@whisperr/wizard 0.1.9 → 0.1.11

package/dist/index.js

@@ -7,7 +7,7 @@ import * as p from "@clack/prompts";
 // src/core/config.ts
 var DEFAULT_API_BASE = "https://api.whisperr.net";
 var DEFAULT_MODEL = "claude-sonnet-4-6";
-var DEFAULT_EFFORT = "medium";
+var DEFAULT_EFFORT = "high";
 var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 function resolveEffort() {
   const raw = (process.env.WHISPERR_WIZARD_EFFORT ?? "").toLowerCase();
@@ -995,6 +995,58 @@ in the code. You will NOT find everything \u2014 some events live server-side or
 aren't in this codebase at all. That is expected and fine. Get what is here, get
 it right, report the rest. Know exactly what you're doing; never hunt blindly.
 
+WHO COUNTS AS "THE USER" \u2014 decide this BEFORE you place anything:
+Whisperr models churn for the product's END USERS: the customers/consumers who
+use the app and could leave. identify() and EVERY event must key to that person.
+Internal actors are NOT the user and must never be instrumented \u2014 doing so fills
+the churn model with the wrong people and is a serious miss:
+  admins \xB7 staff \xB7 operators \xB7 support / back-office agents \xB7 superusers \xB7
+  sellers/merchants/partners (unless the product is FOR them) \xB7 CMS / management
+  / admin-panel consoles.
+Real apps usually have SEVERAL auth/identity paths. Before wiring identify(),
+enumerate them (grep for login / signup / register / authenticate / session
+handlers) and pick the END-USER one. Treat any of these in a path, route,
+namespace, class, guard, model, or table name as a strong "WRONG subject \u2014 skip
+it" signal:
+  admin \xB7 adminpanel \xB7 backoffice \xB7 internal \xB7 staff \xB7 operator \xB7 seller \xB7
+  merchant \xB7 partner \xB7 cms \xB7 manage/management \xB7 console \xB7 dashboard \xB7 support \xB7
+  superuser \xB7 a dedicated admin guard/middleware (e.g. Laravel \`auth:admin\`) or
+  a separate Admin/Staff user model or table.
+If the only auth you can see sits on such a path, the real end-user auth is
+almost certainly elsewhere (a customer-facing API, the mobile backend, an SSO
+callback) \u2014 keep looking instead of settling for it. Only treat an operator as
+the user when the product itself is genuinely for operators (an internal tool).
+
+CONSISTENCY CHECK: identify() and the signup/login events (e.g. account_created)
+describe the SAME person, so they belong on the SAME surface. If you wired
+account_created into one controller and are about to put identify() in a
+different one, stop \u2014 that's the tell you've split the subject. Co-locate them.
+
+WHAT THE EVENT MEANS \u2014 place by SEMANTICS, not by keyword. This is where most
+mistakes happen. An event names a SPECIFIC moment, not "something happened
+nearby." For each event, before you place it:
+- Model the exact transition. \`subscription_started\` is the FIRST subscription,
+  NOT every payment \u2014 renewals, retries, and reactivations are DIFFERENT events.
+  Firing one event on a path that also handles the other cases is a real bug.
+- Read the control flow and find the branch that separates look-alike cases.
+  Payment/callback handlers routinely route initial vs recurring/renewal, success
+  vs retry, trial vs paid through ONE function. Key the event to the right branch
+  (e.g. a \`RENEW_CARD\` / \`is_recurring\` / \`type\` check), or branch yourself and
+  emit the correct event per case. Do not drop one event on the shared success
+  line and move on \u2014 open the function and see which cases it actually covers.
+- Read the codebase's own flags literally. A field like \`type: promo|standard\`
+  is pricing tier, not lifecycle \u2014 confirm what a flag means before keying on it.
+- Capture the discriminators as properties. The fields that tell cases apart \u2014
+  charge_type, is_recurring, payment_source/gateway, amount, plan, currency \u2014 are
+  exactly what makes the event usable for churn (a failed RENEWAL is a churn
+  signal; a failed first charge is not). If the code sets such a field right
+  there (e.g. \`type => 'initial'\`), pass it. A billing event without them is
+  half-blind.
+- Cover the whole lifecycle. Two gateways each with an initial and a recurring
+  path is FOUR call sites \u2014 instrument all of them. A recurring/secondary
+  callback with no events is a churn blind spot. If you deliberately skip a path,
+  say so in the summary.
+
 Every step costs time and the user is watching. Work FAST and DECISIVELY.
 
 EFFICIENCY \u2014 non-negotiable:
@@ -1010,6 +1062,10 @@ DECISIVENESS:
 - If you can't find a clear place for something within ~2 searches, STOP looking.
   Leave a one-line \`// TODO(whisperr): ...\` only if an obvious spot exists,
   otherwise just note it as a follow-up. Do not keep hunting.
+- ONE exception: choosing the correct user/subject (see WHO COUNTS AS "THE
+  USER") is worth a few extra searches. Do not grab the first thing named
+  "login" \u2014 confirm it's the end-user path first. Getting the subject wrong is
+  far more costly than a missed event.
 
 PROPERTY CAPTURE (this is the craft):
 - For each event you place, look at what's in scope AT THAT CALL SITE \u2014 function
@@ -1025,6 +1081,9 @@ CORRECTNESS:
 - Match the app's existing conventions (imports, state management, file layout).
 - Use the EXACT snake_case event names given. Never invent or rename events.
 - Only place an event where you're confident the user action truly happens.
+- Before writing a call, confirm the id in scope is the END-USER's \u2014 not an
+  admin/staff/operator/seller id. An admin acting on a user's behalf is still an
+  admin action; instrument where the end user themselves acts.
 
 FINAL SUMMARY (this is shown verbatim to a non-technical customer in a
 dashboard \u2014 write for a human, not a changelog):
@@ -1122,12 +1181,18 @@ async function runIntegrationAgent(opts) {
     "Do exactly these, then stop:",
     `1. Add the Whisperr SDK dependency and install it (${playbook.packageRef}).`,
     "2. Initialize it once at app startup with the key + base URL below.",
-    "3. Wire identify() at the PRIMARY place the user becomes authenticated",
-    "   (after a successful login) and on session restore at app startup; call",
-    "   reset() on logout. Do NOT enumerate every auth method \u2014 one primary",
-    "   login path plus session restore is enough. Keep channels minimal: pass",
-    "   email if it's readily at hand; phone/push are optional, skip them if not",
-    "   obvious. Do not go hunting through every auth file.",
+    "3. Wire identify() for the END USER \u2014 the paying customer/consumer, NEVER an",
+    '   admin, staff, operator, seller, or partner (see WHO COUNTS AS "THE USER"',
+    "   in your instructions). This app likely has several auth paths: enumerate",
+    "   them first (grep login/signup/register/authenticate) and instrument the",
+    '   end-user one \u2014 do NOT just take the first thing named "login". A path',
+    "   under admin/backoffice/staff/seller/cms is the wrong subject. Sanity",
+    "   check: identify() belongs on the SAME surface as account_created \u2014 if",
+    "   they'd land in different controllers, you've picked the wrong login.",
+    "   Wire it at the primary end-user login success and on session restore at",
+    "   startup; call reset() on logout. One end-user login path plus session",
+    "   restore is enough. Keep channels minimal: email if readily at hand;",
+    "   phone/push optional.",
     "",
     "This is a real app \u2014 be quick and decisive, aim to finish in ~15 steps.",
     "Do NOT instrument product events yet \u2014 that is a separate step. Do not run",
@@ -1157,10 +1222,12 @@ ${core.summary}`);
       "initialized, and identify() is wired. Now instrument the product events",
       "below with track().",
       "",
-      "Work in importance order. Place each event at its real call site and",
-      "attach the properties you can source from what's in scope there (see the",
-      "property-capture rule in your instructions). Skip fast when an event has",
-      "no clear client-side trigger \u2014 spend steps placing events, not exploring.",
+      "Work in importance order. Place each event at the real call site where the",
+      "END USER performs the action (not an admin/staff path \u2014 see WHO COUNTS AS",
+      `"THE USER"), and attach the properties you can source from what's in scope`,
+      "there (see the property-capture rule). These events describe the same",
+      "person identify() did, so they live on the same end-user surface. Skip fast",
+      "when an event has no clear trigger here \u2014 spend steps placing, not exploring.",
       "Stop once the events that clearly exist in this app are wired.",
       "",
       "----- EVENTS -----",
@@ -1180,6 +1247,44 @@ ${core.summary}`);
     eventsComplete = !events.maxedOut;
     if (events.summary) summaries.push(`Events:
 ${events.summary}`);
+  }
+  if (core.ok) {
+    progress?.onPhase?.("Reviewing & correcting placements");
+    const reviewPrompt = [
+      `You wired the Whisperr ${playbook.target.displayName} SDK into this repo.`,
+      "Now AUDIT YOUR OWN WORK and fix mistakes before finishing.",
+      `Project root: ${repoPath}`,
+      "",
+      "Run `git diff` and read the surrounding code to see exactly what you added.",
+      "For every identify() and track() call, verify \u2014 and FIX in place:",
+      "1. Subject \u2014 keys to the END USER, never an admin/staff/operator/seller.",
+      "   identify() sits on the SAME surface as account_created (same person).",
+      "2. Lifecycle \u2014 the event fires ONLY on its real moment. A 'first time'",
+      "   event (e.g. subscription_started) must NOT fire on a renewal/recurring",
+      "   path; look for RENEW_CARD / is_recurring / type branches in the SAME",
+      "   handler. If one path handles both cases, branch and emit the right",
+      "   event per case.",
+      "3. Discriminators \u2014 billing/subscription events carry the properties that",
+      "   tell cases apart when the code exposes them (charge_type / is_recurring",
+      "   / payment_source / amount / plan). Add the ones you missed.",
+      "4. Coverage \u2014 every gateway/callback path that should emit an event does;",
+      "   no recurring or secondary path left as a dead zone.",
+      "Change ONLY what is genuinely wrong or incomplete \u2014 do not churn correct",
+      "calls or re-explore the whole repo. Be surgical. End with a one-line,",
+      "plain-text note of what you corrected, or 'No corrections needed.'."
+    ].join("\n");
+    const review = await runPass({
+      prompt: reviewPrompt,
+      systemPrompt: systemPrompt9,
+      repoPath,
+      model: config.model,
+      effort: config.effort,
+      maxTurns: 25,
+      progress
+    });
+    costUsd += review.costUsd;
+    if (review.summary) summaries.push(`Review:
+${review.summary}`);
   }
   return {
     summary: summaries.join("\n\n"),
@@ -1785,7 +1890,7 @@ async function main() {
     return;
   }
   if ("version" in parsed) {
-    console.log("0.1.9");
+    console.log("0.1.11");
     return;
   }
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Whisperr Wizard — one command to integrate the Whisperr SDK into your app. Authenticates with your onboarded account and uses an AI coding agent to wire up identify() and your business events automatically.",
   "license": "UNLICENSED",
   "private": false,