@tritard/waterbrother 0.10.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -33,6 +33,9 @@ import { runBuildWorkflow, startFeatureTask, runChallengeWorkflow } from "./work
 import { createPanelRenderer, buildPanelState } from "./panel.js";
 import { deriveTaskNameFromPrompt, nextActionsForState, routeNaturalInput } from "./router.js";
 import { compressEpisode, compressSessionEpisode, saveEpisode, loadRecentEpisodes, findRelevantEpisodes, buildEpisodicMemoryBlock, buildReminderBlock } from "./episodic.js";
+import { createProduct, loadProduct, saveProduct, hasProduct, generateBlueprint, buildProductContext, detectProductRequest, parseProductIntent, addSurface, createCampaign, getActiveCampaign, matchTemplate, applyTemplate, startPreview, killPreview } from "./product.js";
+import { runQualityChecks, formatQualityFindings, buildQualityFixPrompt } from "./quality.js";
+import { scanForInitiatives, formatInitiatives, buildInitiativeFixPrompt } from "./initiative.js";
 import { formatPlanForDisplay } from "./planner.js";
 import { parseCharterFromGoal, runExperimentLoop, formatExperimentSummary, gitReturnToBranch } from "./experiment.js";
 
@@ -4762,20 +4765,44 @@ async function promptLoop(agent, session, context) {
     context.runtime.projectMemory = await readProjectMemory(context.cwd);
   }
 
-  // Load episodic memory and combine with project memory
+  // Load episodic memory and product state, combine with project memory
   try {
     const recentEpisodes = await loadRecentEpisodes({ cwd: context.cwd, limit: 5 });
     if (recentEpisodes.length > 0) {
-      const episodicBlock = buildEpisodicMemoryBlock(recentEpisodes);
-      context.runtime.episodicMemory = episodicBlock;
-      const fullMemory = [
-        context.runtime.projectMemory?.promptText || "",
-        episodicBlock
-      ].filter(Boolean).join("\n\n");
-      agent.setMemory(fullMemory);
+      context.runtime.episodicMemory = buildEpisodicMemoryBlock(recentEpisodes);
     }
   } catch {}
 
+  // Load product if it exists
+  try {
+    const product = await loadProduct(context.cwd);
+    if (product) {
+      context.runtime.product = product;
+      // Show product context and run initiative scan
+      const hasBuilt = product.surfaces.some((s) => s.status === "built");
+      if (hasBuilt) {
+        console.log(dim(`product: ${product.name}`));
+        try {
+          const initiatives = await scanForInitiatives({ cwd: context.cwd });
+          if (initiatives.length > 0) {
+            context.runtime.pendingInitiatives = initiatives;
+            console.log(formatInitiatives(initiatives));
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // Combine all memory sources
+  const memoryParts = [
+    context.runtime.projectMemory?.promptText || "",
+    context.runtime.episodicMemory || "",
+    context.runtime.product ? buildProductContext(context.runtime.product) : ""
+  ].filter(Boolean);
+  if (memoryParts.length > 0) {
+    agent.setMemory(memoryParts.join("\n\n"));
+  }
+
   if (!Array.isArray(context.runtime.lastSearchResults)) {
     context.runtime.lastSearchResults = [];
   }
@@ -4982,6 +5009,326 @@ async function promptLoop(agent, session, context) {
   }
 
   async function handleNaturalInput(line) {
+    // Product builder intake: detect "I want a recipe app" in any mode
+    if (detectProductRequest(line)) {
+      const intent = parseProductIntent(line);
+      const spinner = createProgressSpinner("understanding your product...");
+
+      try {
+        // Ask the model to extract product details via structured JSON
+        const { createJsonCompletion } = await import("./grok-client.js");
+        const model = context.runtime.plannerModel || agent.getModel();
+        const completion = await createJsonCompletion({
+          apiKey: context.runtime.apiKey,
+          baseUrl: context.runtime.baseUrl,
+          model,
+          messages: [
+            { role: "system", content: `You are a product strategist. Extract a product brief from the user's request. Respond with JSON only:
+{
+  "name": "short product name",
+  "description": "one-sentence description",
+  "audience": "who is this for",
+  "type": "web|mobile|api|cli|desktop",
+  "surfaces": ["Landing", "Login", "Dashboard", "Settings"],
+  "stack": { "framework": "Next.js", "styling": "Tailwind", "backend": "Supabase", "auth": "email", "deploy": "Vercel" },
+  "taste": "visual style in 3-5 words",
+  "features": ["feature 1", "feature 2"]
+}
+Infer reasonable defaults. Keep it practical.` },
+            { role: "user", content: line }
+          ],
+          temperature: 0.3
+        });
+
+        spinner.stop();
+        const brief = completion.json;
+        if (!brief) { return false; }
+
+        // Create the product
+        const product = createProduct({
+          name: brief.name || intent.name || "My Product",
+          description: brief.description || line,
+          audience: brief.audience || "",
+          type: brief.type || intent.type
+        });
+
+        // Apply template if detected
+        const templateType = matchTemplate(line);
+        if (templateType) {
+          applyTemplate(product, templateType);
+        }
+
+        // Fill in details from the brief (overrides template defaults)
+        if (brief.stack) {
+          product.stack = { ...product.stack, ...brief.stack };
+        }
+        if (brief.taste) product.qualityBar.taste = brief.taste;
+        if (Array.isArray(brief.surfaces)) {
+          for (const s of brief.surfaces) {
+            addSurface(product, { name: s, type: "page", status: "planned" });
+          }
+        }
+
+        // Create initial campaign
+        createCampaign(product, { name: "Launch V1", goal: `Ship MVP: ${brief.description || product.description}` });
+
+        // Save and display
+        await saveProduct(context.cwd, product);
+        context.runtime.product = product;
+
+        // Inject product context into agent memory
+        const productCtx = buildProductContext(product);
+        const fullMemory = [
+          context.runtime.projectMemory?.promptText || "",
+          context.runtime.episodicMemory || "",
+          productCtx
+        ].filter(Boolean).join("\n\n");
+        agent.setMemory(fullMemory);
+
+        console.log(generateBlueprint(product));
+
+      } catch (error) {
+        spinner.stop();
+        console.log(`product intake failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      return true;
+    }
+
+    // Product builder actions: "build", "deploy", "adjust", "show surfaces"
+    const product = context.runtime.product || await loadProduct(context.cwd);
+    if (product) {
+      context.runtime.product = product;
+      const lower = line.trim().toLowerCase();
+
+      if (/^(build|build it|build the product|scaffold|go)$/.test(lower)) {
+        const productCtx = buildProductContext(product);
+        const planned = product.surfaces.filter((s) => s.status === "planned").map((s) => s.name);
+
+        const spinner = createProgressSpinner("building product...");
+        try {
+          const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+          agent.toolRuntime.setAutonomyMode("auto");
+
+          // Phase 1: Scaffold foundation (package.json, config, shared components)
+          const scaffoldPrompt = `${productCtx}\n\nFirst, set up the project foundation:\n1. Create package.json with all dependencies\n2. Create config files (tailwind, next.config, etc.)\n3. Create shared layout/components (nav, footer)\n4. Set up auth if needed\n5. Run npm install\n\nDo NOT build individual pages yet — just the skeleton.`;
+
+          spinner.setLabel("scaffolding...");
+          await agent.runTurn(scaffoldPrompt, {
+            onAssistantDelta() {},
+            onToolStart(tc) { spinner.setLabel(`${tc?.function?.name || "tool"}...`); },
+            onToolEnd() { spinner.setLabel("scaffolding..."); }
+          });
+          await agent.toolRuntime.completeTurn({});
+
+          // Phase 2: Build each surface individually
+          for (let i = 0; i < planned.length; i++) {
+            const surface = planned[i];
+            spinner.setLabel(`building ${surface} (${i + 1}/${planned.length})...`);
+            const surfacePrompt = `${productCtx}\n\nBuild the "${surface}" page/flow. Create all components needed for this surface. Make it complete and polished — real content, proper styling, working interactions. Follow the product's style: ${product.qualityBar.taste || "clean and modern"}.`;
+            await agent.runTurn(surfacePrompt, {
+              onAssistantDelta() {},
+              onToolStart(tc) { spinner.setLabel(`${surface}: ${tc?.function?.name || "tool"}...`); },
+              onToolEnd() { spinner.setLabel(`building ${surface}...`); }
+            });
+            await agent.toolRuntime.completeTurn({});
+            console.log(dim(`  ✓ ${surface}`));
+          }
+
+          agent.toolRuntime.setAutonomyMode(prevAutonomy);
+          spinner.stop();
+
+          // Quality checks
+          try {
+            const findings = await runQualityChecks({ cwd: context.cwd });
+            const qualityOutput = formatQualityFindings(findings);
+            if (qualityOutput) {
+              console.log("");
+              console.log(qualityOutput);
+            }
+          } catch {}
+
+          // Mark surfaces as built
+          for (const s of product.surfaces) {
+            s.status = "built";
+          }
+          await saveProduct(context.cwd, product);
+
+          // Start preview server and open browser
+          console.log("");
+          console.log("PREVIEW ▸ ready");
+          const builtSurfaces = product.surfaces.filter((s) => s.status === "built").map((s) => s.name);
+          if (builtSurfaces.length > 0) console.log(`  ${builtSurfaces.join(", ")}`);
+
+          try {
+            const preview = await startPreview(context.cwd);
+            if (preview.ok) {
+              console.log(`  ${preview.url}`);
+              context.runtime.previewPid = preview.pid;
+            } else {
+              console.log("  http://localhost:3000 (start dev server manually)");
+            }
+          } catch {
+            console.log("  http://localhost:3000 (start dev server manually)");
+          }
+
+          console.log("");
+          console.log(dim("  refine · add feature · deploy"));
+
+        } catch (error) {
+          spinner.stop();
+          console.log(`build failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+      }
+
+      if (/^(show surfaces|surfaces|pages|show pages)$/.test(lower)) {
+        console.log(generateBlueprint(product));
+        return true;
+      }
+
+      if (/^(adjust|change|modify)$/.test(lower)) {
+        console.log(generateBlueprint(product));
+        console.log("\nDescribe what to adjust (e.g. 'add a settings page' or 'change auth to Google')");
+        return true;
+      }
+
+      // Deploy with milestone gate
+      if (/^(deploy|ship|publish|launch)$/.test(lower)) {
+        const deployTarget = product.stack.deploy || "Vercel";
+        try {
+          const confirm = await promptYesNo(`Deploy to ${deployTarget}?`, { input: process.stdin, output: process.stdout });
+          if (!confirm) {
+            console.log("deploy canceled");
+            return true;
+          }
+        } catch {
+          console.log("deploy canceled");
+          return true;
+        }
+
+        const spinner = createProgressSpinner(`deploying to ${deployTarget}...`);
+        try {
+          const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+          agent.toolRuntime.setAutonomyMode("auto");
+          await agent.runTurn(
+            `Deploy this project to ${deployTarget}. Run the necessary CLI commands (e.g. vercel, netlify deploy, gh-pages). If not set up, initialize it first.`,
+            { onAssistantDelta() {}, onToolStart() { spinner.setLabel("deploying..."); }, onToolEnd() {} }
+          );
+          await agent.toolRuntime.completeTurn({});
+          agent.toolRuntime.setAutonomyMode(prevAutonomy);
+          spinner.stop();
+          console.log(`\nSHIP ▸ deployed`);
+          console.log(dim("  share link · add feature · view code"));
+        } catch (error) {
+          spinner.stop();
+          console.log(`deploy failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+      }
+
+      // Refine: natural language changes to a built product
+      if (/^(fix these|fix quality|fix initiatives|fix product)$/.test(lower) && !context.runtime.activeTask) {
+        // Only handle product fixes when no task is active — otherwise let router handle "fix these" for task reviews
+        if (context.runtime.pendingInitiatives?.length > 0) {
+          const spinner = createProgressSpinner("fixing product gaps...");
+          try {
+            const fixPrompt = buildInitiativeFixPrompt(context.runtime.pendingInitiatives);
+            const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+            agent.toolRuntime.setAutonomyMode("auto");
+            const productCtx = buildProductContext(product);
+            await agent.runTurn(`${productCtx}\n\n${fixPrompt}`, {
+              onAssistantDelta() {}, onToolStart() { spinner.setLabel("fixing..."); }, onToolEnd() {}
+            });
+            await agent.toolRuntime.completeTurn({});
+            agent.toolRuntime.setAutonomyMode(prevAutonomy);
+            spinner.stop();
+            context.runtime.pendingInitiatives = [];
+            console.log("product gaps addressed");
+            console.log(dim("  refine · add feature · deploy"));
+          } catch (error) {
+            spinner.stop();
+            console.log(`fix failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+          return true;
+        }
+      }
+
+      if (/^(fix these|fix quality)$/.test(lower) && !context.runtime.activeTask) {
+        const spinner = createProgressSpinner("fixing quality issues...");
+        try {
+          const findings = await runQualityChecks({ cwd: context.cwd });
+          const fixPrompt = buildQualityFixPrompt(findings);
+          if (!fixPrompt) { spinner.stop(); console.log("no quality issues to fix"); return true; }
+          const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+          agent.toolRuntime.setAutonomyMode("auto");
+          const productCtx = buildProductContext(product);
+          await agent.runTurn(`${productCtx}\n\n${fixPrompt}`, {
+            onAssistantDelta() {}, onToolStart() { spinner.setLabel("fixing..."); }, onToolEnd() {}
+          });
+          await agent.toolRuntime.completeTurn({});
+          agent.toolRuntime.setAutonomyMode(prevAutonomy);
+          spinner.stop();
+          console.log("quality issues addressed");
+          console.log(dim("  refine · add feature · deploy"));
+        } catch (error) {
+          spinner.stop();
+          console.log(`fix failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return true;
+      }
+
+      // Refine: any other refinement when product has built surfaces
+      const hasBuilt = product.surfaces.some((s) => s.status === "built");
+      if (hasBuilt && !lower.startsWith("/") && !context.runtime.activeTask) {
+        // Negative gate: exclude things that look like new product requests or work requests
+        const isNewProduct = detectProductRequest(line);
+        const isWorkRequest = /^(add|build|create|implement|fix|refactor|wire|debug)\b/.test(lower) && /\b(to the|for the|in the|api|endpoint|middleware|service|module|auth|database)\b/.test(lower);
+        // Positive gate: must reference visual/UI elements or the existing product
+        const isRefinement = !isNewProduct && !isWorkRequest && /\b(make|change|update|prettier|simpler|bigger|smaller|darker|lighter|color|font|style|dark\s*mode|light\s*mode|resize|move|header|footer|nav|button|logo|image|background|padding|margin|spacing|border|rounded|shadow|gradient|animation|hover|responsive|mobile|desktop|center|align|layout)\b/i.test(lower);
+        if (isRefinement) {
+          const spinner = createProgressSpinner("refining...");
+          try {
+            const productCtx = buildProductContext(product);
+
+            // Check if adding a new surface
+            const addMatch = lower.match(/add\s+(?:a\s+)?(.+?)(?:\s+page|\s+screen|\s+section)?$/);
+            if (addMatch) {
+              const surfaceName = addMatch[1].trim().replace(/^(a|an|the)\s+/i, "");
+              addSurface(product, { name: surfaceName, type: "page", status: "planned" });
+              await saveProduct(context.cwd, product);
+            }
+
+            const prevAutonomy = agent.toolRuntime.getAutonomyMode();
+            agent.toolRuntime.setAutonomyMode("auto");
+            await agent.runTurn(
+              `${productCtx}\n\nRefine the product: ${line}\n\nMake the change while keeping the existing product quality and style consistent.`,
+              {
+                onAssistantDelta() {},
+                onToolStart(tc) { spinner.setLabel(`${tc?.function?.name || "editing"}...`); },
+                onToolEnd() { spinner.setLabel("refining..."); }
+              }
+            );
+            await agent.toolRuntime.completeTurn({});
+            agent.toolRuntime.setAutonomyMode(prevAutonomy);
+            spinner.stop();
+
+            // Mark any new surfaces as built
+            for (const s of product.surfaces) {
+              if (s.status === "planned") s.status = "built";
+            }
+            await saveProduct(context.cwd, product);
+
+            console.log("refined");
+            console.log(dim("  refine · add feature · deploy"));
+          } catch (error) {
+            spinner.stop();
+            console.log(`refine failed: ${error instanceof Error ? error.message : String(error)}`);
+          }
+          return true;
+        }
+      }
+    }
+
     const routed = routeNaturalInput(line, { task: context.runtime.activeTask });
     if (!routed || routed.kind === "none" || routed.kind === "chat") return false;
 
@@ -6976,6 +7323,9 @@ async function promptLoop(agent, session, context) {
     }
   }
 
+  // Kill any running preview server
+  killPreview();
+
   // Save CC-mode session episode on exit (if any files were touched)
   if (!context.runtime.activeTask) {
     try {

package/src/initiative.js

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const IGNORE_DIRS = new Set(["node_modules", ".git", ".waterbrother", "dist", "build", ".next", ".nuxt"]);
+
+async function fileExists(filePath) {
+  try { await fs.access(filePath); return true; } catch { return false; }
+}
+
+async function findFiles(dir, pattern, maxDepth = 4, depth = 0) {
+  if (depth > maxDepth) return [];
+  const matches = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        matches.push(...await findFiles(full, pattern, maxDepth, depth + 1));
+      } else if (pattern.test(entry.name)) {
+        matches.push(full);
+      }
+    }
+  } catch {}
+  return matches;
+}
+
+async function grepFiles(dir, textPattern, extensions, maxDepth = 4) {
+  const files = await findFiles(dir, new RegExp(`\\.(${extensions.join("|")})$`), maxDepth);
+  const matches = [];
+  for (const f of files) {
+    try {
+      const content = await fs.readFile(f, "utf8");
+      if (textPattern.test(content)) matches.push(path.relative(dir, f).replace(/\\/g, "/"));
+    } catch {}
+  }
+  return matches;
+}
+
+const INITIATIVES = [
+  {
+    id: "no-404",
+    label: "No 404 page",
+    check: async (cwd) => {
+      const has404 = await findFiles(cwd, /404\.(jsx?|tsx?|html|vue|svelte)$/);
+      return has404.length === 0;
+    },
+    suggestion: "Add a 404 page so users see a friendly message on broken links"
+  },
+  {
+    id: "no-favicon",
+    label: "No favicon",
+    check: async (cwd) => {
+      const hasFavicon = await fileExists(path.join(cwd, "public", "favicon.ico"))
+        || await fileExists(path.join(cwd, "public", "favicon.svg"))
+        || await fileExists(path.join(cwd, "app", "favicon.ico"));
+      return !hasFavicon;
+    },
+    suggestion: "Add a favicon — it's the first thing users notice in their browser tab"
+  },
+  {
+    id: "no-meta-tags",
+    label: "Missing SEO meta tags",
+    check: async (cwd) => {
+      const htmlFiles = await findFiles(cwd, /\.(html|jsx|tsx)$/);
+      for (const f of htmlFiles) {
+        try {
+          const content = await fs.readFile(f, "utf8");
+          if (/meta.*description/i.test(content) || /metadata/i.test(content)) return false;
+        } catch {}
+      }
+      return htmlFiles.length > 0;
+    },
+    suggestion: "Add meta description tags for SEO — helps your site show up in search"
+  },
+  {
+    id: "no-loading-states",
+    label: "No loading indicators",
+    check: async (cwd) => {
+      const hasLoading = await grepFiles(cwd, /loading|spinner|skeleton|isLoading|isPending/i, ["jsx", "tsx", "vue", "svelte"]);
+      return hasLoading.length === 0;
+    },
+    suggestion: "Add loading states to async content — prevents blank screens while data loads"
+  },
+  {
+    id: "no-error-handling",
+    label: "Forms without error handling",
+    check: async (cwd) => {
+      const forms = await grepFiles(cwd, /<form|onSubmit|handleSubmit/i, ["jsx", "tsx", "vue", "svelte"]);
+      if (forms.length === 0) return false;
+      const errorHandling = await grepFiles(cwd, /error|catch|validation|invalid/i, ["jsx", "tsx", "vue", "svelte"]);
+      return errorHandling.length === 0;
+    },
+    suggestion: "Add error handling to forms — show validation messages and handle failures"
+  },
+  {
+    id: "no-responsive",
+    label: "No responsive design hints",
+    check: async (cwd) => {
+      const hasResponsive = await grepFiles(cwd, /@media|sm:|md:|lg:|xl:|responsive|mobile/i, ["css", "scss", "jsx", "tsx", "html"]);
+      return hasResponsive.length === 0;
+    },
+    suggestion: "Add responsive breakpoints — your app should look good on phones"
+  }
+];
+
+export async function scanForInitiatives({ cwd }) {
+  const found = [];
+  for (const initiative of INITIATIVES) {
+    try {
+      const applies = await initiative.check(cwd);
+      if (applies) {
+        found.push({
+          id: initiative.id,
+          label: initiative.label,
+          suggestion: initiative.suggestion
+        });
+      }
+    } catch {}
+  }
+  return found;
+}
+
+export function formatInitiatives(initiatives) {
+  if (!initiatives || initiatives.length === 0) return "";
+  const lines = ["Product improvements available:"];
+  for (const init of initiatives.slice(0, 5)) {
+    lines.push(`  → ${init.suggestion}`);
+  }
+  lines.push("\n  fix these · ignore");
+  return lines.join("\n");
+}
+
+export function buildInitiativeFixPrompt(initiatives) {
+  const lines = ["Fix these product quality gaps:"];
+  for (const init of initiatives) {
+    lines.push(`- ${init.label}: ${init.suggestion}`);
+  }
+  lines.push("\nImplement each fix. Keep changes minimal and focused.");
+  return lines.join("\n");
+}

package/src/product.js

@@ -0,0 +1,452 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const PRODUCT_FILE = "product.json";
+
+function productDir(cwd) {
+  return path.join(cwd, ".waterbrother");
+}
+
+function productPath(cwd) {
+  return path.join(productDir(cwd), PRODUCT_FILE);
+}
+
+/**
+ * Product: the persistent object at the center of builder mode.
+ *
+ * {
+ *   name: "Family Recipe Book",
+ *   description: "A web app for sharing family recipes",
+ *   audience: "My family — 10 people, non-technical",
+ *   type: "web",                    // web | mobile | api | cli | desktop
+ *   stack: {
+ *     framework: "Next.js",
+ *     styling: "Tailwind",
+ *     backend: "Supabase",
+ *     auth: "email magic link",
+ *     deploy: "Vercel"
+ *   },
+ *   surfaces: [
+ *     { name: "Landing", type: "page", status: "built" },
+ *     { name: "Login", type: "flow", status: "built" },
+ *     { name: "Recipe Feed", type: "page", status: "planned" },
+ *     { name: "Create Recipe", type: "form", status: "planned" }
+ *   ],
+ *   qualityBar: {
+ *     taste: "clean, warm, simple",
+ *     trust: ["no broken links", "real content not lorem ipsum"],
+ *     ux: ["mobile-first", "< 3 clicks to core action"],
+ *     performance: ["< 3s load time"]
+ *   },
+ *   tradeoffs: [
+ *     "No real-time features — polling is fine",
+ *     "Email auth only — no OAuth complexity"
+ *   ],
+ *   campaigns: [
+ *     { id: "launch-v1", name: "Launch V1", status: "active", goal: "Ship MVP with 4 core pages" }
+ *   ],
+ *   deployUrl: null,
+ *   repoUrl: null,
+ *   createdAt: "2026-03-15T...",
+ *   updatedAt: "2026-03-15T..."
+ * }
+ */
+
+export function createProduct({ name, description, audience, type }) {
+  return {
+    name: name || "Untitled Product",
+    description: description || "",
+    audience: audience || "",
+    type: type || "web",
+    stack: {
+      framework: null,
+      styling: null,
+      backend: null,
+      auth: null,
+      deploy: null
+    },
+    surfaces: [],
+    qualityBar: {
+      taste: "",
+      trust: [],
+      ux: [],
+      performance: []
+    },
+    tradeoffs: [],
+    campaigns: [],
+    deployUrl: null,
+    repoUrl: null,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  };
+}
+
+export async function loadProduct(cwd) {
+  try {
+    const raw = await fs.readFile(productPath(cwd), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveProduct(cwd, product) {
+  product.updatedAt = new Date().toISOString();
+  await fs.mkdir(productDir(cwd), { recursive: true });
+  await fs.writeFile(productPath(cwd), `${JSON.stringify(product, null, 2)}\n`, "utf8");
+}
+
+export async function hasProduct(cwd) {
+  try {
+    await fs.access(productPath(cwd));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- Surface management ---
+
+export function addSurface(product, { name, type = "page", status = "planned" }) {
+  const existing = product.surfaces.find((s) => s.name.toLowerCase() === name.toLowerCase());
+  if (existing) {
+    existing.status = status;
+    existing.type = type;
+    return existing;
+  }
+  const surface = { name, type, status };
+  product.surfaces.push(surface);
+  return surface;
+}
+
+export function markSurfaceBuilt(product, name) {
+  const surface = product.surfaces.find((s) => s.name.toLowerCase() === name.toLowerCase());
+  if (surface) surface.status = "built";
+  return surface;
+}
+
+export function getPlannedSurfaces(product) {
+  return product.surfaces.filter((s) => s.status === "planned");
+}
+
+export function getBuiltSurfaces(product) {
+  return product.surfaces.filter((s) => s.status === "built");
+}
+
+// --- Campaign management ---
+
+export function createCampaign(product, { name, goal }) {
+  const id = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 40);
+  const campaign = { id, name, status: "active", goal, createdAt: new Date().toISOString() };
+  // Deactivate other campaigns
+  for (const c of product.campaigns) {
+    if (c.status === "active") c.status = "paused";
+  }
+  product.campaigns.push(campaign);
+  return campaign;
+}
+
+export function getActiveCampaign(product) {
+  return product.campaigns.find((c) => c.status === "active") || null;
+}
+
+export function completeCampaign(product, campaignId) {
+  const campaign = product.campaigns.find((c) => c.id === campaignId);
+  if (campaign) campaign.status = "completed";
+  return campaign;
+}
+
+// --- Blueprint generation ---
+
+export function generateBlueprint(product) {
+  const lines = [];
+  const rule = "─".repeat(40);
+
+  lines.push(rule);
+  lines.push(`BLUEPRINT: ${product.name}`);
+  lines.push(rule);
+
+  if (product.description) lines.push(`  ${product.description}`);
+  if (product.audience) lines.push(`  For: ${product.audience}`);
+  lines.push("");
+
+  if (product.surfaces.length > 0) {
+    const planned = product.surfaces.filter((s) => s.status === "planned").map((s) => s.name);
+    const built = product.surfaces.filter((s) => s.status === "built").map((s) => s.name);
+    if (planned.length > 0) lines.push(`  Pages: ${planned.join(", ")}`);
+    if (built.length > 0) lines.push(`  Built: ${built.join(", ")}`);
+  }
+
+  const stack = product.stack;
+  const stackParts = [];
+  if (stack.framework) stackParts.push(stack.framework);
+  if (stack.styling) stackParts.push(stack.styling);
+  if (stack.backend) stackParts.push(stack.backend);
+  if (stackParts.length > 0) lines.push(`  Stack: ${stackParts.join(" + ")}`);
+  if (stack.auth) lines.push(`  Auth: ${stack.auth}`);
+  if (stack.deploy) lines.push(`  Deploy: ${stack.deploy}`);
+
+  if (product.qualityBar.taste) lines.push(`  Style: ${product.qualityBar.taste}`);
+
+  if (product.tradeoffs.length > 0) {
+    lines.push("");
+    for (const t of product.tradeoffs) lines.push(`  ◦ ${t}`);
+  }
+
+  const campaign = getActiveCampaign(product);
+  if (campaign) {
+    lines.push("");
+    lines.push(`  Campaign: ${campaign.name} — ${campaign.goal}`);
+  }
+
+  lines.push("");
+  lines.push("  build · adjust · show surfaces · deploy");
+  lines.push(rule);
+
+  return lines.join("\n");
+}
+
+// --- Product context for system prompt ---
+
+export function buildProductContext(product) {
+  if (!product) return "";
+  const parts = [`Product: ${product.name}`];
+  if (product.description) parts.push(`Description: ${product.description}`);
+  if (product.audience) parts.push(`Audience: ${product.audience}`);
+
+  const stack = product.stack;
+  const stackParts = [];
+  if (stack.framework) stackParts.push(stack.framework);
+  if (stack.styling) stackParts.push(stack.styling);
+  if (stack.backend) stackParts.push(stack.backend);
+  if (stackParts.length > 0) parts.push(`Stack: ${stackParts.join(" + ")}`);
+
+  if (product.qualityBar.taste) parts.push(`Style: ${product.qualityBar.taste}`);
+  if (product.qualityBar.ux.length > 0) parts.push(`UX rules: ${product.qualityBar.ux.join(", ")}`);
+  if (product.qualityBar.trust.length > 0) parts.push(`Trust rules: ${product.qualityBar.trust.join(", ")}`);
+
+  if (product.tradeoffs.length > 0) parts.push(`Tradeoffs: ${product.tradeoffs.join("; ")}`);
+
+  const planned = product.surfaces.filter((s) => s.status === "planned").map((s) => s.name);
+  const built = product.surfaces.filter((s) => s.status === "built").map((s) => s.name);
+  if (planned.length > 0) parts.push(`Planned surfaces: ${planned.join(", ")}`);
+  if (built.length > 0) parts.push(`Built surfaces: ${built.join(", ")}`);
+
+  const campaign = getActiveCampaign(product);
+  if (campaign) parts.push(`Active campaign: ${campaign.name} — ${campaign.goal}`);
+
+  parts.push("You are building this product. Every change should serve the product's goals, audience, and quality bar.");
+
+  return parts.join("\n");
+}
+
+// --- Brief intake: parse natural language into product fields ---
+
+export function detectProductRequest(text) {
+  const lower = text.toLowerCase().trim();
+  return /^(i want|build me|make me|create|i need|can you build|help me build|let's build|we need)\b/.test(lower)
+    && /\b(app|site|website|page|platform|tool|dashboard|store|shop|blog|portfolio|saas|api|bot|game)\b/.test(lower);
+}
+
+export function parseProductIntent(text) {
+  const lower = text.toLowerCase();
+  let type = "web";
+  if (/\b(mobile|ios|android|iphone|phone)\b/.test(lower)) type = "mobile";
+  else if (/\b(api|backend|server|microservice)\b/.test(lower)) type = "api";
+  else if (/\b(cli|command.?line|terminal)\b/.test(lower)) type = "cli";
+  else if (/\b(desktop|electron)\b/.test(lower)) type = "desktop";
+
+  // Extract name hint
+  const nameMatch = text.match(/(?:called?|named?)\s+"?([^"]+)"?/i);
+  const name = nameMatch ? nameMatch[1].trim() : "";
+
+  return { type, name, raw: text };
+}
+
+// --- Templates ---
+
+const TEMPLATES = {
+  "landing-page": {
+    surfaces: [
+      { name: "Landing", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "bold, modern, conversion-focused",
+    qualityBar: { ux: ["single page", "clear CTA above fold", "< 3s load time"], trust: ["real testimonials", "no stock photos"] }
+  },
+  "saas": {
+    surfaces: [
+      { name: "Landing", type: "page" },
+      { name: "Pricing", type: "page" },
+      { name: "Login", type: "flow" },
+      { name: "Signup", type: "flow" },
+      { name: "Dashboard", type: "page" },
+      { name: "Settings", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: "Supabase", auth: "email + OAuth", deploy: "Vercel" },
+    taste: "clean, professional, trustworthy",
+    qualityBar: { ux: ["mobile-first", "onboarding under 60s", "clear pricing"], trust: ["SSL", "privacy policy link", "real company info"] }
+  },
+  "blog": {
+    surfaces: [
+      { name: "Home / Post List", type: "page" },
+      { name: "Post Page", type: "page" },
+      { name: "About", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "readable, minimal, typographic",
+    qualityBar: { ux: ["< 2s load", "good reading experience", "responsive"], trust: ["author info", "real dates"] }
+  },
+  "store": {
+    surfaces: [
+      { name: "Home / Product List", type: "page" },
+      { name: "Product Detail", type: "page" },
+      { name: "Cart", type: "page" },
+      { name: "Checkout", type: "flow" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: "Supabase", auth: "email", deploy: "Vercel" },
+    taste: "clean, trustworthy, product-focused",
+    qualityBar: { ux: ["fast product browsing", "< 3 clicks to checkout"], trust: ["secure checkout badge", "return policy visible"] }
+  },
+  "portfolio": {
+    surfaces: [
+      { name: "Home / Projects Grid", type: "page" },
+      { name: "Project Detail", type: "page" },
+      { name: "About", type: "page" },
+      { name: "Contact", type: "page" }
+    ],
+    stack: { framework: "Next.js", styling: "Tailwind", backend: null, auth: null, deploy: "Vercel" },
+    taste: "creative, visual, spacious",
+    qualityBar: { ux: ["fast image loading", "smooth transitions", "mobile-friendly"], trust: ["real work samples", "contact info visible"] }
+  }
+};
+
+export function matchTemplate(text) {
+  const lower = text.toLowerCase();
+  if (/\b(landing\s*page|one.?page|single.?page|marketing)\b/.test(lower)) return "landing-page";
+  if (/\b(saas|sass|software.?as|subscription|b2b)\b/.test(lower)) return "saas";
+  if (/\b(blog|journal|writing|articles|posts)\b/.test(lower)) return "blog";
+  if (/\b(store|shop|ecommerce|e.?commerce|marketplace|products?\s+for\s+sale)\b/.test(lower)) return "store";
+  if (/\b(portfolio|showcase|gallery|my\s+work|personal\s+site)\b/.test(lower)) return "portfolio";
+  return null;
+}
+
+export function getTemplate(type) {
+  return TEMPLATES[type] || null;
+}
+
+export function applyTemplate(product, templateName) {
+  const template = TEMPLATES[templateName];
+  if (!template) return;
+  for (const s of template.surfaces) {
+    addSurface(product, { name: s.name, type: s.type, status: "planned" });
+  }
+  product.stack = { ...product.stack, ...template.stack };
+  if (template.taste) product.qualityBar.taste = template.taste;
+  if (template.qualityBar?.ux) product.qualityBar.ux = template.qualityBar.ux;
+  if (template.qualityBar?.trust) product.qualityBar.trust = template.qualityBar.trust;
+}
+
+// --- Preview ---
+
+// Track active preview server for cleanup
+let activePreviewServer = null;
+
+export function killPreview() {
+  if (!activePreviewServer) return;
+  try {
+    if (process.platform === "win32") {
+      const { execSync } = require("node:child_process");
+      execSync(`taskkill /PID ${activePreviewServer.pid} /T /F`, { stdio: "ignore" });
+    } else {
+      process.kill(-activePreviewServer.pid);
+    }
+  } catch {}
+  activePreviewServer = null;
+}
+
+function detectPort(cwd) {
+  try {
+    const pkg = JSON.parse(require("node:fs").readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const devScript = pkg.scripts?.dev || "";
+    // Check for --port or -p flags
+    const portMatch = devScript.match(/(?:--port|-p)\s+(\d+)/);
+    if (portMatch) return parseInt(portMatch[1], 10);
+    // Check for PORT env in dev script
+    const envMatch = devScript.match(/PORT=(\d+)/);
+    if (envMatch) return parseInt(envMatch[1], 10);
+  } catch {}
+  return 3000;
+}
+
+async function pollServer(url, maxWaitMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const { request } = await import("node:http");
+      const ok = await new Promise((resolve) => {
+        const req = request(url, { timeout: 1000 }, (res) => { resolve(res.statusCode < 500); });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => { req.destroy(); resolve(false); });
+        req.end();
+      });
+      if (ok) return true;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+export async function startPreview(cwd) {
+  const { spawn } = await import("node:child_process");
+  const pkgPath = path.join(cwd, "package.json");
+  let hasDevScript = false;
+  try {
+    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+    hasDevScript = Boolean(pkg.scripts?.dev);
+  } catch {}
+  if (!hasDevScript) return { ok: false, reason: "no dev script in package.json" };
+
+  // Kill any existing preview server
+  killPreview();
+
+  // Install deps first
+  try {
+    const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+    const install = spawn(npmCmd, ["install"], { cwd, stdio: "ignore" });
+    await new Promise((resolve) => install.on("close", resolve));
+  } catch {}
+
+  // Detect port
+  const port = detectPort(cwd);
+  const url = `http://localhost:${port}`;
+
+  // Start dev server
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const server = spawn(npmCmd, ["run", "dev"], {
+    cwd,
+    stdio: "ignore",
+    detached: process.platform !== "win32"
+  });
+  server.unref();
+  activePreviewServer = server;
+
+  // Poll until server responds (up to 30s)
+  const ready = await pollServer(url);
+
+  if (!ready) {
+    return { ok: true, pid: server.pid, url, warning: "server started but not responding yet — may still be compiling" };
+  }
+
+  // Open browser
+  try {
+    if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", url], { stdio: "ignore" });
+    } else {
+      const openCmd = process.platform === "darwin" ? "open" : "xdg-open";
+      spawn(openCmd, [url], { stdio: "ignore" });
+    }
+  } catch {}
+
+  return { ok: true, pid: server.pid, url: "http://localhost:3000" };
+}

package/src/quality.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CHECKS = [
+  {
+    name: "placeholder-content",
+    severity: "warning",
+    pattern: /lorem ipsum|placeholder|sample text|example\.com|test@test/i,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte", ".md"],
+    message: "Placeholder content found"
+  },
+  {
+    name: "broken-links",
+    severity: "warning",
+    pattern: /href=["']#["']|href=["']["']/,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte"],
+    message: "Broken or empty link"
+  },
+  {
+    name: "missing-alt",
+    severity: "warning",
+    pattern: /<img(?![^>]*alt=)[^>]*>/i,
+    extensions: [".html", ".jsx", ".tsx", ".vue", ".svelte"],
+    message: "Image missing alt text"
+  },
+  {
+    name: "console-log",
+    severity: "info",
+    pattern: /console\.(log|debug|info)\(/,
+    extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte"],
+    message: "console.log left in code"
+  },
+  {
+    name: "todo-fixme",
+    severity: "info",
+    pattern: /\/\/\s*(TODO|FIXME|HACK|XXX)\b/i,
+    extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte", ".css"],
+    message: "TODO/FIXME comment"
+  }
+];
+
+const IGNORE_DIRS = new Set(["node_modules", ".git", ".waterbrother", "dist", "build", ".next", ".nuxt"]);
+
+async function walkFiles(dir, extensions, maxDepth = 5, depth = 0) {
+  if (depth > maxDepth) return [];
+  const files = [];
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...await walkFiles(full, extensions, maxDepth, depth + 1));
+      } else if (extensions.some((ext) => entry.name.endsWith(ext))) {
+        files.push(full);
+      }
+    }
+  } catch {}
+  return files;
+}
+
+export async function runQualityChecks({ cwd }) {
+  const findings = [];
+  const allExtensions = [...new Set(CHECKS.flatMap((c) => c.extensions))];
+  const files = await walkFiles(cwd, allExtensions);
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = await fs.readFile(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const lines = content.split("\n");
+    const rel = path.relative(cwd, filePath).replace(/\\/g, "/");
+
+    for (const check of CHECKS) {
+      if (!check.extensions.some((ext) => filePath.endsWith(ext))) continue;
+      for (let i = 0; i < lines.length; i++) {
+        if (check.pattern.test(lines[i])) {
+          findings.push({
+            check: check.name,
+            severity: check.severity,
+            file: rel,
+            line: i + 1,
+            message: check.message,
+            snippet: lines[i].trim().slice(0, 80)
+          });
+        }
+      }
+    }
+
+    // Check for empty files (< 5 lines of real content)
+    const realLines = lines.filter((l) => l.trim().length > 0 && !l.trim().startsWith("//") && !l.trim().startsWith("/*"));
+    if (realLines.length < 5 && allExtensions.some((ext) => filePath.endsWith(ext))) {
+      findings.push({
+        check: "empty-file",
+        severity: "warning",
+        file: rel,
+        line: 1,
+        message: "File has very little content",
+        snippet: `${realLines.length} non-empty lines`
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function formatQualityFindings(findings) {
+  if (!findings || findings.length === 0) return "";
+  const warnings = findings.filter((f) => f.severity === "warning");
+  const infos = findings.filter((f) => f.severity === "info");
+  const lines = [];
+
+  if (warnings.length > 0) {
+    lines.push(`⚠ ${warnings.length} quality issue${warnings.length > 1 ? "s" : ""}:`);
+    for (const f of warnings.slice(0, 5)) {
+      lines.push(`  ${f.file}:${f.line} — ${f.message}`);
+    }
+    if (warnings.length > 5) lines.push(`  ... and ${warnings.length - 5} more`);
+  }
+  if (infos.length > 0) {
+    lines.push(`ℹ ${infos.length} note${infos.length > 1 ? "s" : ""}: ${[...new Set(infos.map((f) => f.message))].join(", ")}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function buildQualityFixPrompt(findings) {
+  const fixable = findings.filter((f) => f.severity === "warning").slice(0, 10);
+  if (fixable.length === 0) return "";
+  const lines = ["Fix these product quality issues:"];
+  for (const f of fixable) {
+    lines.push(`- ${f.file}:${f.line} — ${f.message} (${f.snippet})`);
+  }
+  lines.push("\nReplace placeholder content with real content. Fix broken links. Add alt text to images.");
+  return lines.join("\n");
+}