@donotdev/cli 0.0.17 → 0.0.18

package/dist/bin/dndev.js

@@ -49,7 +49,7 @@ Usage: dndev <command>[:<app>] [options]
 
 Commands:
   init, create-project    Create a new DoNotDev project
-  create-app [name]       Add app (--builder vite|next, --functions, --project <id>)
+  create-app [name]       Add app (--builder, --host, --functions, --backend)
   dev [app]               Start development server
   build [app]             Build for production
   preview [app]           Preview production build
@@ -74,9 +74,10 @@ Options:
 Examples:
   dndev init my-project   Create a new project
   dndev create-app        Interactive app creation
-  dndev create-app my-app Create 'my-app' with defaults (vite, no functions)
-  dndev create-app my-app --builder next --functions  Next.js + functions
-  dndev create-app my-app --functions --project my-fb-id  Set Firebase project (2-min setup)
+  dndev create-app my-app Create 'my-app' with defaults (vite, frontend-only)
+  dndev create-app my-app --builder next --host vercel  Next.js + Vercel hosting
+  dndev create-app my-app --functions firebase --backend firebase  Full Firebase stack
+  dndev create-app my-app --backend supabase --project my-fb-id  Supabase + custom project
   dndev dev               Start dev server
   dndev dev:web           Start dev server for 'web' app
   dndev agent             Configure MCP for all AI agents
@@ -101,14 +102,16 @@ program.command("init [name]").alias("create-project").description("Create a new
   const { main } = await import("./commands/create-project.js");
   await main({ projectName: name });
 });
-program.command("create-app [name]").description("Add a new app to existing project").option("--name <name>", "App name (non-interactive)").option("--builder <builder>", "Framework: vite or next (default: vite)").option("--functions", "Include Firebase functions").option("--project <id>", "Firebase project ID (default: app name)").option("--region <region>", "Firebase region (default: europe-west1)").action(async (name, options) => {
+program.command("create-app [name]").description("Add a new app to existing project").option("--name <name>", "App name (non-interactive)").option("--builder <builder>", "Framework: vite, next, or expo (default: vite)").option("--host <host>", "Hosting: none, vercel, or firebase (default: none)").option("--functions <runtime>", "Functions: none, vercel, firebase, or supabase (default: none)").option("--backend <backend>", "BaaS: none, firebase, or supabase (default: none)").option("--project <id>", "Firebase project ID (default: app name)").option("--region <region>", "Firebase region (default: europe-west1)").action(async (name, options) => {
   const { main } = await import("./commands/create-app.js");
   const appName = name || options.name;
   if (appName) {
     await main({
       name: appName,
       builder: options.builder,
+      host: options.host,
       functions: options.functions,
+      backend: options.backend,
       firebaseProjectId: options.project,
       firebaseRegion: options.region
     });
@@ -252,7 +255,7 @@ program.command("wai").alias("wai-way").description("Output WAI-WAY activation p
 function preprocessArgs(args2) {
   if (args2.length === 0) return args2;
   const firstArg = args2[0];
-  const appCommands = ["dev", "build", "preview", "emu", "deploy", "staging"];
+  const appCommands = ["dev", "build", "preview", "emu", "deploy", "staging", "tc", "type-check", "cacheout", "co"];
   if (firstArg && firstArg.includes(":")) {
     const colonIndex = firstArg.indexOf(":");
     const command = firstArg.substring(0, colonIndex);

package/dist/bin/donotdev.js

@@ -49,7 +49,7 @@ Usage: dndev <command>[:<app>] [options]
 
 Commands:
   init, create-project    Create a new DoNotDev project
-  create-app [name]       Add app (--builder vite|next, --functions, --project <id>)
+  create-app [name]       Add app (--builder, --host, --functions, --backend)
   dev [app]               Start development server
   build [app]             Build for production
   preview [app]           Preview production build
@@ -74,9 +74,10 @@ Options:
 Examples:
   dndev init my-project   Create a new project
   dndev create-app        Interactive app creation
-  dndev create-app my-app Create 'my-app' with defaults (vite, no functions)
-  dndev create-app my-app --builder next --functions  Next.js + functions
-  dndev create-app my-app --functions --project my-fb-id  Set Firebase project (2-min setup)
+  dndev create-app my-app Create 'my-app' with defaults (vite, frontend-only)
+  dndev create-app my-app --builder next --host vercel  Next.js + Vercel hosting
+  dndev create-app my-app --functions firebase --backend firebase  Full Firebase stack
+  dndev create-app my-app --backend supabase --project my-fb-id  Supabase + custom project
   dndev dev               Start dev server
   dndev dev:web           Start dev server for 'web' app
   dndev agent             Configure MCP for all AI agents
@@ -101,14 +102,16 @@ program.command("init [name]").alias("create-project").description("Create a new
   const { main } = await import("./commands/create-project.js");
   await main({ projectName: name });
 });
-program.command("create-app [name]").description("Add a new app to existing project").option("--name <name>", "App name (non-interactive)").option("--builder <builder>", "Framework: vite or next (default: vite)").option("--functions", "Include Firebase functions").option("--project <id>", "Firebase project ID (default: app name)").option("--region <region>", "Firebase region (default: europe-west1)").action(async (name, options) => {
+program.command("create-app [name]").description("Add a new app to existing project").option("--name <name>", "App name (non-interactive)").option("--builder <builder>", "Framework: vite, next, or expo (default: vite)").option("--host <host>", "Hosting: none, vercel, or firebase (default: none)").option("--functions <runtime>", "Functions: none, vercel, firebase, or supabase (default: none)").option("--backend <backend>", "BaaS: none, firebase, or supabase (default: none)").option("--project <id>", "Firebase project ID (default: app name)").option("--region <region>", "Firebase region (default: europe-west1)").action(async (name, options) => {
   const { main } = await import("./commands/create-app.js");
   const appName = name || options.name;
   if (appName) {
     await main({
       name: appName,
       builder: options.builder,
+      host: options.host,
       functions: options.functions,
+      backend: options.backend,
       firebaseProjectId: options.project,
       firebaseRegion: options.region
     });
@@ -252,7 +255,7 @@ program.command("wai").alias("wai-way").description("Output WAI-WAY activation p
 function preprocessArgs(args2) {
   if (args2.length === 0) return args2;
   const firstArg = args2[0];
-  const appCommands = ["dev", "build", "preview", "emu", "deploy", "staging"];
+  const appCommands = ["dev", "build", "preview", "emu", "deploy", "staging", "tc", "type-check", "cacheout", "co"];
   if (firstArg && firstArg.includes(":")) {
     const colonIndex = firstArg.indexOf(":");
     const command = firstArg.substring(0, colonIndex);

package/dist/index.js

@@ -18617,34 +18617,67 @@ var APP_QUESTIONNAIRE = [
     ]
   },
   {
-    id: "needsBackend",
-    question: "Include backend functions?",
-    type: "confirm",
-    defaultValue: false
+    id: "host",
+    question: "Where will you host?",
+    type: "select",
+    condition: (answers) => answers.framework !== "expo",
+    defaultValue: (answers) => {
+      return answers.framework === "nextjs" ? "vercel" : "none";
+    },
+    choices: [
+      { title: "None \u2014 no hosting config", value: "none" },
+      { title: "Vercel \u2014 edge CDN + serverless", value: "vercel" },
+      { title: "Firebase Hosting \u2014 Google CDN", value: "firebase" }
+    ]
+  },
+  {
+    id: "functions",
+    question: "Serverless functions?",
+    type: "select",
+    defaultValue: "none",
+    // Choices filtered dynamically based on host
+    choices: [
+      { title: "None", value: "none" },
+      { title: "Vercel Functions \u2014 edge + node.js", value: "vercel" },
+      { title: "Firebase Functions \u2014 Google Cloud", value: "firebase" },
+      { title: "Supabase Edge Functions \u2014 Deno", value: "supabase" }
+    ],
+    choicesFilter: (answers) => {
+      const host = answers.host ?? "none";
+      const framework = answers.framework;
+      if (framework === "expo") return ["none", "firebase", "supabase"];
+      if (host === "firebase") return ["none", "firebase"];
+      if (host === "vercel") return ["none", "vercel", "supabase"];
+      return ["none", "vercel", "firebase", "supabase"];
+    }
   },
   {
-    id: "backendPlatform",
-    question: "Which backend platform?",
+    id: "backend",
+    question: "Backend / BaaS provider?",
     type: "select",
-    dependsOn: "needsBackend",
-    condition: (answers) => answers.needsBackend === true,
     defaultValue: (answers) => {
-      return answers.framework === "nextjs" ? "vercel" : "firebase";
+      if (answers.functions === "firebase") return "firebase";
+      if (answers.functions === "supabase") return "supabase";
+      return "none";
     },
     choices: [
+      { title: "None \u2014 frontend only", value: "none" },
       {
-        title: "Firebase \u2014 Full-stack platform (hosting + functions + auth + firestore)",
+        title: "Firebase \u2014 Auth + Firestore + Storage",
         value: "firebase"
       },
-      {
-        title: "Vercel \u2014 Serverless functions (edge + node.js)",
-        value: "vercel"
-      },
       {
         title: "Supabase \u2014 Postgres + Auth + Storage",
         value: "supabase"
       }
-    ]
+    ],
+    choicesFilter: (answers) => {
+      const functions = answers.functions ?? "none";
+      if (functions === "firebase") return ["none", "firebase"];
+      if (functions === "supabase") return ["none", "supabase"];
+      if (functions === "vercel") return ["none"];
+      return ["none", "firebase", "supabase"];
+    }
   }
 ];
 var PROJECT_QUESTIONNAIRE = [
@@ -18662,12 +18695,13 @@ var PROJECT_QUESTIONNAIRE = [
   }
 ];
 function aggregateRequirements(answers) {
+  const hasBackend = answers.backend && answers.backend !== "none" || answers.functions && answers.functions !== "none";
   const requirements = {
     entities: [],
     // Entities created in apps/<app>/entities/ (v1), root entities/ for v2
     billing: true,
     // Always on (useStripeBillingSafe handles missing package)
-    backend: answers.needsBackend || false,
+    backend: hasBackend,
     features: [],
     template: "vite",
     // Only Vite for now
@@ -18691,6 +18725,10 @@ async function runQuestionnaire(questions, initialAnswers, showWIP, askFor) {
         if (!showWIP) {
           choices = choices.filter((choice) => !choice.wip);
         }
+        if (question.choicesFilter) {
+          const allowed = question.choicesFilter(answers);
+          choices = choices.filter((c) => allowed.includes(c.value));
+        }
         if (choices.length === 0) continue;
         answer = await askFor.selection(question.question, choices);
         break;
@@ -20114,120 +20152,22 @@ init_pathResolver();
 
 // packages/tooling/src/scaffolding/scaffold-matrix.ts
 init_utils();
-var MATRIX = [
-  {
-    builder: "vite",
-    backend: "none",
-    baseTemplate: "app-vite",
-    overlay: null,
-    deployConfig: null,
-    functionsTemplate: null
-  },
-  {
-    builder: "vite",
-    backend: "firebase",
-    baseTemplate: "app-vite",
-    overlay: "overlay-firebase",
-    deployConfig: "firebase",
-    functionsTemplate: "functions-firebase"
-  },
-  {
-    builder: "vite",
-    backend: "supabase",
-    baseTemplate: "app-vite",
-    overlay: "overlay-supabase",
-    deployConfig: "vercel-supabase",
-    functionsTemplate: "functions-supabase"
-  },
-  {
-    builder: "vite",
-    backend: "vercel",
-    baseTemplate: "app-vite",
-    overlay: "overlay-vercel",
-    deployConfig: "vercel-vercel",
-    functionsTemplate: "functions-vercel"
-  },
-  {
-    builder: "nextjs",
-    backend: "none",
-    baseTemplate: "app-next",
-    overlay: null,
-    deployConfig: null,
-    functionsTemplate: null
-  },
-  {
-    builder: "nextjs",
-    backend: "firebase",
-    baseTemplate: "app-next",
-    overlay: "overlay-firebase",
-    deployConfig: "firebase",
-    functionsTemplate: "functions-firebase"
-  },
-  {
-    builder: "nextjs",
-    backend: "supabase",
-    baseTemplate: "app-next",
-    overlay: "overlay-supabase",
-    deployConfig: "vercel-supabase",
-    functionsTemplate: "functions-supabase"
-  },
-  {
-    builder: "nextjs",
-    backend: "vercel",
-    baseTemplate: "app-next",
-    overlay: "overlay-vercel",
-    deployConfig: "vercel-vercel",
-    functionsTemplate: "functions-vercel"
-  },
-  {
-    builder: "expo",
-    backend: "none",
-    baseTemplate: "app-expo",
-    overlay: null,
-    deployConfig: null,
-    functionsTemplate: null
-  },
-  {
-    builder: "expo",
-    backend: "firebase",
-    baseTemplate: "app-expo",
-    overlay: "overlay-firebase",
-    deployConfig: null,
-    functionsTemplate: "functions-firebase"
-  },
-  {
-    builder: "expo",
-    backend: "supabase",
-    baseTemplate: "app-expo",
-    overlay: "overlay-supabase",
-    deployConfig: null,
-    functionsTemplate: "functions-supabase"
-  },
-  {
-    builder: "demo",
-    backend: "none",
-    baseTemplate: "app-demo",
-    overlay: null,
-    deployConfig: null,
-    functionsTemplate: null
-  }
-];
-function comboKey(builder, backend) {
-  return `${builder}-${backend}`;
-}
-var ROWS_BY_KEY = /* @__PURE__ */ new Map();
-for (const row of MATRIX) {
-  ROWS_BY_KEY.set(comboKey(row.builder, row.backend), row);
+function resolveDeployConfig(host, backend) {
+  if (host === "none") return null;
+  if (host === "firebase") return "firebase";
+  if (backend === "supabase") return "vercel-supabase";
+  return "vercel-vercel";
 }
-function getScaffoldRow(builder, backend) {
-  const key = comboKey(builder, backend);
-  const row = ROWS_BY_KEY.get(key);
-  if (!row) {
-    throw new Error(
-      `Unsupported scaffold combo: ${key}. Supported: ${[...ROWS_BY_KEY.keys()].join(", ")}`
-    );
-  }
-  return row;
+function getScaffoldParts(builder, host, functions, backend) {
+  const baseTemplate = builder === "nextjs" ? "app-next" : builder === "demo" ? "app-demo" : `app-${builder}`;
+  return {
+    builder,
+    backend,
+    baseTemplate,
+    overlay: backend !== "none" ? `overlay-${backend}` : null,
+    deployConfig: resolveDeployConfig(host, backend),
+    functionsTemplate: functions !== "none" ? `functions-${functions}` : null
+  };
 }
 
 // packages/tooling/src/scaffolding/create-app.ts
@@ -20267,11 +20207,15 @@ async function createApp(appName, appConfig, workspaceRoot, templatesRoot) {
       input: askForInput
     });
     const requirements = aggregateRequirements(answers);
-    const defaultPlatform = answers.framework === "nextjs" ? "vercel" : "firebase";
+    const framework = answers.framework || "vite";
+    const host2 = answers.host || "none";
+    const functions2 = answers.functions || "none";
+    const backend2 = answers.backend || "none";
     appConfig = {
-      template: answers.framework || "vite",
-      needsBackend: answers.needsBackend || false,
-      backendPlatform: answers.needsBackend ? answers.backendPlatform || defaultPlatform : void 0,
+      template: framework,
+      host: host2,
+      functions: functions2,
+      backend: backend2,
       needsCRUD: true,
       // Always on
       selectedEntities: [],
@@ -20317,12 +20261,14 @@ async function createApp(appName, appConfig, workspaceRoot, templatesRoot) {
   s.start(`Creating app: ${appName}`);
   await ensureDir(appDir);
   const builder = appTemplate;
-  const backend = appConfig.needsBackend && appConfig.backendPlatform ? appConfig.backendPlatform : "none";
-  const row = getScaffoldRow(builder, backend);
+  const host = appConfig.host ?? "none";
+  const functions = appConfig.functions ?? "none";
+  const backend = appConfig.backend ?? "none";
+  const row = getScaffoldParts(builder, host, functions, backend);
   const templateDir = row.baseTemplate;
   const firebaseProjectId = (appConfig?.firebaseProjectId ?? "").trim() || appName.toLowerCase().replace(/\s+/g, "-");
   const firebaseRegion = appConfig?.firebaseRegion ?? "europe-west1";
-  const backendPlatform = appConfig.backendPlatform ?? "firebase";
+  const backendPlatform = backend !== "none" ? backend : "firebase";
   const deployConfig = row.deployConfig;
   const replacements = {
     projectName: appName,
@@ -20660,11 +20606,13 @@ Happy coding!`,
 }
 async function main8(options) {
   try {
-    const hasExplicitFlags = options?.builder !== void 0 || options?.functions !== void 0;
+    const hasExplicitFlags = options?.builder !== void 0 || options?.host !== void 0 || options?.functions !== void 0 || options?.backend !== void 0;
     if (hasExplicitFlags && options?.name) {
       const appName = options.name;
       const builder = options.builder || "vite";
-      const includeFunctions = options.functions ?? false;
+      const hostOpt = options.host ?? "none";
+      const functionsOpt = options.functions ?? "none";
+      const backendOpt = options.backend ?? "none";
       if (!isValidFileName(appName)) {
         throw new Error(
           `Invalid app name "${appName}". Use only letters, numbers, dashes (-), and underscores (_).`
@@ -20677,8 +20625,9 @@ async function main8(options) {
       }
       const appConfig = {
         template: builder === "next" ? "nextjs" : builder === "expo" ? "expo" : "vite",
-        needsBackend: includeFunctions,
-        backendPlatform: includeFunctions ? "firebase" : void 0,
+        host: hostOpt,
+        functions: functionsOpt,
+        backend: backendOpt,
         needsCRUD: true,
         selectedEntities: [],
         userAuth: "social",
@@ -20710,12 +20659,11 @@ async function collectAppConfig(appName) {
     input: askForInput
   });
   const framework = answers.framework || "vite";
-  const needsBackend = answers.needsBackend || false;
-  const defaultPlatform = framework === "nextjs" ? "vercel" : "firebase";
   return {
     template: framework,
-    needsBackend,
-    backendPlatform: needsBackend ? answers.backendPlatform || defaultPlatform : void 0,
+    host: answers.host || "none",
+    functions: answers.functions || "none",
+    backend: answers.backend || "none",
     needsCRUD: false,
     selectedEntities: [],
     userAuth: "none",
@@ -20862,7 +20810,7 @@ async function main9(options) {
       Me(`Configuring "${trimmedName}"...`, "\u2699\uFE0F");
       const config = await collectAppConfig(trimmedName);
       appConfigs[trimmedName] = config;
-      if (config.needsBackend) anyAppNeedsBackend = true;
+      if (config.backend !== "none" || config.functions !== "none") anyAppNeedsBackend = true;
     }
     let installDemoApp = await askForConfirmation(
       "Would you like to install the demo app? (component showcase)",
@@ -20938,8 +20886,9 @@ async function main9(options) {
         log.warn(`Missing config for app "${appName}", using defaults`);
         appConfigs[appName] = {
           template: "vite",
-          needsBackend: false,
-          backendPlatform: void 0,
+          host: "none",
+          functions: "none",
+          backend: "none",
           needsCRUD: false,
           selectedEntities: [],
           userAuth: "none",
@@ -20987,7 +20936,7 @@ async function main9(options) {
         overwrite: true
       });
       const relativeMonorepoPath = executionMode === "development" ? calculateRelativePath(projectDirNormalized, monorepoRoot) : "";
-      const primaryPlatform = Object.values(appConfigs).find((c) => c.backendPlatform)?.backendPlatform ?? "firebase";
+      const primaryPlatform = Object.values(appConfigs).find((c) => c.backend !== "none")?.backend ?? "firebase";
       const rootPackageJson = generatePackageJson(
         "consumer-root",
         executionMode,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donotdev/cli",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "description": "Command-line interface for DoNotDev Framework",
   "type": "module",
   "private": false,

package/templates/root-consumer/.claude/commands/brainstorm.md.example

@@ -41,6 +41,14 @@ description: Extract requirements and generate complete HLD through conversation
 
 ## Process
 
+### Step 0: Start Phase (MANDATORY — DO THIS FIRST)
+
+**BEFORE asking any questions or doing any work**, call:
+```
+start_phase(0)
+```
+This activates Phase 0: BRAINSTORM and loads the blueprint, persona, context, and lessons learned from previous sessions. **Do NOT proceed without this call.**
+
 ### Step 1: Activate EXTRACTOR Agent
 
 **Deploy:** `/agents extractor` (BMAD EXTRACTOR persona)
@@ -87,7 +95,7 @@ EXTRACTOR generates `HLD.md` with:
 
 ---
 
-## Validation Gate
+## Validation Gate & Phase Completion (MANDATORY)
 
 **Before proceeding to `/design`:**
 - [ ] HLD is complete (no empty sections or TBDs)
@@ -97,6 +105,12 @@ EXTRACTOR generates `HLD.md` with:
 - [ ] Native vs custom analysis complete
 - [ ] User has validated HLD
 
+**When HLD is complete**, write the filled-out spec to `docs/HLD.md` (the template at `guides/wai-way/spec_template.md` stays untouched as reference). Then call:
+```
+complete_phase({ files: ["docs/HLD.md"], summary: "HLD complete — N entities, N pages, N features" })
+```
+Then wait for the user to call `approve_phase()` before moving to `/design`.
+
 **Quality Over Speed:** Take as long as needed. A complete HLD that takes 4 hours is better than an incomplete one that takes 20 minutes.
 
 ---

package/templates/root-consumer/.claude/commands/build.md.example

@@ -36,6 +36,14 @@ description: Two-agent workflow: Prompt Engineer → Coder (AFTER /design)
 
 ## Process
 
+### Step 0: Start Phase (MANDATORY — DO THIS FIRST)
+
+**BEFORE writing any code**, call:
+```
+start_phase(3)
+```
+This activates Phase 3: COMPOSE and loads the blueprint, persona, context, and lessons. **Do NOT write code without this call.**
+
 ### Step 1: Activate FORGER Agent
 
 **Deploy:** `/agents builder` (BMAD FORGER persona)
@@ -54,10 +62,19 @@ description: Two-agent workflow: Prompt Engineer → Coder (AFTER /design)
    - Phase 6: Integration (wire everything together)
 4. Use framework defaults ONLY (no styling, no customization)
 5. Hardcode all strings (no i18n yet)
-6. Validate each phase before proceeding
+6. Run `dndev tc` after every file change — type errors must be fixed immediately
+7. Validate each phase before proceeding
 
 **Output:** Working app (functional MVP, no styling)
 
+### Phase Completion (MANDATORY)
+
+When all pages are built and `dndev tc` passes, call:
+```
+complete_phase({ files: ["src/pages/...all page files..."], summary: "N pages composed, all type-checking" })
+```
+Wait for user to call `approve_phase()` before moving to `/polish`.
+
 ---
 
 ## Alternative: Two-Agent Workflow
@@ -79,10 +96,15 @@ For complex builds, you can use:
 - **Builder (FORGER):** Implements exactly what's in LLD, uses framework defaults only
 - **Framework defaults ONLY:** No styling, no customization (deferred to /polish)
 - **Hardcode strings:** No i18n yet (deferred to /polish)
-- **MCP required:** Use lookup_symbol for ALL components
 - **Phase by phase:** Complete each phase before proceeding
 - **User:** Reviews output, proceeds to /polish when functional
 
+## STOP — lookup_symbol Before Every Component (Repeated Here On Purpose)
+
+**STOP before writing ANY `@donotdev` import.** Call `lookup_symbol({ symbol: "Name" })` first. Do NOT guess props, hooks, or APIs. Do NOT proceed without verification. `complete_phase` will reject un-looked-up symbols.
+
+**Import convention:** Always `@donotdev/<package>` — never sub-paths. No `@donotdev/ui/routing`, no `@donotdev/components/card`. The only exceptions are `@donotdev/core/server`, `@donotdev/core/vite`, `@donotdev/core/next`, `@donotdev/core/functions`.
+
 ## Mode Detection
 
 **CRITICAL:** Check working mode first.

package/templates/root-consumer/.claude/commands/design.md.example

@@ -36,6 +36,21 @@ description: Design workflow: Architect → Design Document (BEFORE /build)
 
 ## Process
 
+### Step 0: Start Phase (MANDATORY — DO THIS FIRST)
+
+**BEFORE doing any design work**, call the appropriate phase:
+```
+start_phase(1)   # for SCAFFOLD (routes, page stubs)
+start_phase(2)   # for ENTITIES (data models, fields, access)
+```
+This loads the blueprint, persona, context, and lessons. **Do NOT proceed without this call.**
+
+When design work is complete, call:
+```
+complete_phase({ files: ["...affected files..."], summary: "Description of what was designed" })
+```
+Wait for user to call `approve_phase()` before moving on.
+
 ### Step 1: Architect Phase
 
 **Deploy:** `/agents architect` (WAI-WAY architect role)
@@ -102,6 +117,8 @@ UNRESOLVED:
 - **ALWAYS reference framework architecture** - stay aligned
 - **ALWAYS identify impacts** - what breaks if we change this?
 - **ALWAYS prepare for /build** - design should be actionable
+- **ALWAYS use `lookup_symbol`** when referencing @donotdev components in your design — verify the API exists before putting it in the plan
+- **Import convention:** Always `@donotdev/<package>` top-level, never sub-paths. The only exceptions are `@donotdev/core/server`, `@donotdev/core/vite`, `@donotdev/core/next`, `@donotdev/core/functions`
 
 ## Integration with WAI-WAY & BMAD
 

package/templates/root-consumer/.claude/commands/polish.md.example

@@ -42,6 +42,14 @@ description: Generate tests, firestore rules, CI/CD, config, fix bugs, i18n (Pha
 
 ## Process
 
+### Step 0: Start Phase (MANDATORY — DO THIS FIRST)
+
+**BEFORE any polish work**, call:
+```
+start_phase(4)
+```
+This activates Phase 4: CONFIGURE and loads the blueprint, persona, context, and lessons. **Do NOT proceed without this call.**
+
 ### Step 1: Activate Polisher Agent
 
 **Deploy:** `/agents polisher` (Phase 4 Polisher persona)
@@ -112,6 +120,7 @@ Extract strings to `src/locales/`, replace with `useTranslation()`.
 ## Ship Readiness
 
 App is ready to ship when:
+- ✅ `dndev tc` passes
 - ✅ `bun test` passes
 - ✅ `firestore.rules` generated
 - ✅ `.github/workflows/ci.yml` created
@@ -121,6 +130,14 @@ App is ready to ship when:
 - ✅ Configuration complete
 - ✅ (Optional) i18n added
 
+## Phase Completion (MANDATORY)
+
+When all ship readiness checks pass, call:
+```
+complete_phase({ files: ["...all test/config files..."], summary: "Tests passing, config complete, ready to ship" })
+```
+Wait for user to call `approve_phase()`.
+
 ---
 
 ## Next Step