@koda-sl/baker-cli 0.571.0 → 0.572.0-dev.61ba69c66

package/dist/chunk-4WLJYLRL.js

@@ -0,0 +1,544 @@
+import {
+  adFieldPlan,
+  adRows
+} from "./chunk-RJXO66C4.js";
+import {
+  reportError,
+  splitList
+} from "./chunk-6LNCKT6S.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-UUDWZIDC.js";
+import {
+  registerSchema,
+  scopedWinnersSearchRequestSchema,
+  staticFormatPatternSchema,
+  winnerSearchScopeSchema,
+  winnersSortSchema,
+  winningAdNormalizer,
+  writeJson,
+  writeOutput
+} from "./chunk-6V4UAC5I.js";
+
+// src/commands/winning-ads/search.ts
+import { defineCommand } from "citty";
+var FORMAT_PATTERN_DESCRIPTION = `Comma list of static containers, the best proven ads in them from any category (\`winning-ads formats\` ranks them for a segment): ${staticFormatPatternSchema.options.join(", ")}`;
+var STAGE_DESCRIPTION = "Comma list of where the ad is in its life: new (\u22647 days running), testing (\u226421), proven (\u226460), evergreen (longer), killed_early (stopped within 2 weeks: a lost test), retired, unverified (brand not checked recently). What competitors kept: --stage proven,evergreen";
+var SURVIVED_TEST_DESCRIPTION = "Only the version a brand kept after testing it against other versions of the same concept: the strongest public sign it works";
+var PARTNERSHIP_DESCRIPTION = "only = just Meta partnership ads (the brand ran it with a creator or another brand, both named in the ad; each row says who as partner); exclude = drop them, for the brand's own ads";
+var PARTNERSHIP_VALUES = { only: true, exclude: false };
+var LANGUAGE_DESCRIPTION = "Comma list of ISO 639-1 codes (es,en) for the language the ad's copy and voiceover are in; where it ran is --country";
+registerSchema({
+  command: "winning-ads.search",
+  description: "Search the ad-dna corpus of scored winning ads, the company's followed brands first. Returns a lean shortlist (advertiser, summary, scores, days_active/active/winner_category as proof, media_url, visual/container/mechanism, and who the ad was made for: audience_temperature/funnel_stage/advertiser_size/presumes_brand_knowledge, when known) to pick a reference to reproduce. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry. Each row carries its stage (new, testing, proven, evergreen, killed_early, retired, unverified) and survived_test when it is the version its brand kept after testing; --survived-test or --stage proven,evergreen keep only what competitors kept. Only designed pictures and videos come back by default (no Google search, Shopping or app ads); --format text asks for Google search ads (their words), --all-kinds for everything. A value outside a closed list (--platform, --format, --winner-category, --awareness, --audience-temperature, --funnel-stage, --advertiser-size, --format-pattern, --stage, --sort) is refused with error.fix.validValues.",
+  args: {
+    query: { type: "string", description: "Free-text natural-language query", required: false },
+    scope: {
+      type: "string",
+      description: "Which brands to draw from: followed-first (default: followed brands first, topped up from the library when too few clear the relevance floor; the whole library when the company follows nobody), followed (only brands the company follows), all (the whole shared library). Every result carries source: followed|library.",
+      required: false,
+      default: "followed-first"
+    },
+    "ref-ad-id": {
+      type: "string",
+      description: "Find ads similar to this ad id (instead of free text)",
+      required: false
+    },
+    limit: { type: "number", description: "Max results 1-100 (default 10)", required: false, default: 10 },
+    "max-per-advertiser": {
+      type: "number",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "number", description: "Relevance floor 0-1; trims weak matches", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a browse with no query: winner (default, by winner score), longest_running (by days active), newest (by first seen). Ignored when a query is given: a query ranks by relevance blended with winner score.",
+      required: false,
+      default: "winner"
+    },
+    platform: {
+      type: "string",
+      description: "Comma list: meta,linkedin,tiktok,google",
+      required: false
+    },
+    format: { type: "string", description: "Comma list: video,static,carousel,text", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list: winner,scaled_winner,evergreen,rising,untested,dud,\u2026",
+      required: false
+    },
+    awareness: {
+      type: "string",
+      description: "Comma list: unaware,problem_aware,solution_aware,product_aware,most_aware",
+      required: false
+    },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold (strangers), 1_warm_engaged (engaged, not yet visited), 2_hot_visited (visited the site), 3_customer. A cold brief takes 0_cold references.",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads whose copy only works if the viewer already knows the brand (an unexplained logo, mascot, nickname or promise). Ads not judged yet are kept and show no presumes_brand_knowledge. Use it whenever the ad you are making is for viewers who don't know the brand.",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": {
+      type: "string",
+      description: "Restrict to these advertiser ids (browse one brand's winners)",
+      required: false
+    },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand (a reused ad is marked already_adapted instead)",
+      required: false
+    },
+    "first-seen-after": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen after this",
+      required: false
+    },
+    "first-seen-before": {
+      type: "string",
+      description: "ISO date (2026-01-01) or datetime; only ads first seen before this",
+      required: false
+    },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of hook SEEDS (from `winning-ads hooks`) \u2014 narrow to ads on a proven hook pattern",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    partnership: { type: "string", description: PARTNERSHIP_DESCRIPTION, required: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return ads nobody can build a creative on: Google search text, Shopping and app ads. By default a search returns only designed pictures and videos; --format text asks for search ads alone (their words: headlines, claims, offers).",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "Return one varied set (different brands, containers, hooks) instead of rank order: one reference per concept in a single call",
+      required: false,
+      default: false
+    }
+  }
+});
+function setNumber(body, key, value) {
+  if (value !== void 0 && value !== "") {
+    body[key] = Number(value);
+  }
+}
+function setList(target, key, value) {
+  const list = splitList(value);
+  if (list.length) {
+    target[key] = list;
+  }
+}
+function setString(target, key, value) {
+  if (value) {
+    target[key] = value;
+  }
+}
+function buildSearchBody(args) {
+  const body = {};
+  if (args.query) {
+    body.free_text_query = args.query;
+  }
+  if (args.refAdId) {
+    body.ref_ad_id = args.refAdId;
+  }
+  setString(body, "scope", args.scope);
+  setNumber(body, "limit", args.limit);
+  setNumber(body, "max_per_advertiser", args.maxPerAdvertiser);
+  setNumber(body, "min_relevance", args.minRelevance);
+  setString(body, "sort", args.sort);
+  if (args.diverse) {
+    body.diverse = true;
+  }
+  const hardFilters = {};
+  setList(hardFilters, "platform", args.platform);
+  setList(hardFilters, "format", args.format);
+  setList(hardFilters, "winner_category", args.winnerCategory);
+  setList(hardFilters, "awareness_stage", args.awareness);
+  setList(hardFilters, "audience_temperature", args.audienceTemperature);
+  setList(hardFilters, "funnel_stage", args.funnelStage);
+  setList(hardFilters, "advertiser_size", args.advertiserSize);
+  if (args.excludeBrandReliant) {
+    hardFilters.presumes_brand_knowledge = false;
+  }
+  setList(hardFilters, "country", args.country);
+  setList(hardFilters, "language", args.language?.toLowerCase());
+  setList(hardFilters, "advertiser_ids", args.advertiserId);
+  setList(hardFilters, "exclude_advertiser_ids", args.excludeAdvertiser);
+  setList(hardFilters, "hook_archetype_seeds", args.hookArchetype);
+  setList(hardFilters, "static_format_patterns", args.formatPattern);
+  setString(hardFilters, "first_seen_after", args.firstSeenAfter);
+  setString(hardFilters, "first_seen_before", args.firstSeenBefore);
+  setList(hardFilters, "lifecycle_stage", args.stage);
+  if (args.survivedTest) {
+    hardFilters.survived_test = true;
+  }
+  if (args.partnership !== void 0 && args.partnership in PARTNERSHIP_VALUES) {
+    hardFilters.partnership = PARTNERSHIP_VALUES[args.partnership];
+  }
+  if (Object.keys(hardFilters).length) {
+    body.hard_filters = hardFilters;
+  }
+  return body;
+}
+function designedByDefault(body, opts) {
+  const filters = body.hard_filters ?? {};
+  const wantsText = Array.isArray(filters.format) && filters.format.includes("text");
+  if (opts.allKinds || wantsText) return body;
+  return { ...body, hard_filters: { ...filters, design_reference: true } };
+}
+function searchHints(data) {
+  const hints = [];
+  if ((data.following_count ?? 0) === 0) {
+    hints.push(
+      'The company follows no brands, so these references come from brands tracked by others and may be off-market. Follow competitors with `baker winning-ads follow-competitors "<domain,domain>"` to get on-market references, then search with --scope followed-first.'
+    );
+  } else if (data.scope === "followed" && (data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No followed brand has an ad on this brief. Re-run with --scope followed-first to top up from the whole library."
+    );
+  } else if ((data.results?.length ?? 0) === 0) {
+    hints.push(
+      "No reference matched the brief and every filter. Search once more with ONE change: drop the narrowest filter (--country, --audience-temperature or one --awareness stage) or shorten the brief to the product and who it is for. For a container your concept needs, --format-pattern <container> with no query returns the best proven ads in it from any category."
+    );
+  }
+  const kept = keptHint(data.results ?? []);
+  if (kept) hints.push(kept);
+  const adapted = (data.results ?? []).filter(
+    (r) => r?.baker_uses?.ours === true
+  ).length;
+  if (adapted > 0) {
+    hints.push(
+      `${adapted} of these references you already adapted into a creative (already_adapted), so they are listed last. A second creative from the same ad is a variant, not a new concept: pick another unless the user asked for one.`
+    );
+  }
+  return hints;
+}
+var KEPT_STAGES = /* @__PURE__ */ new Set(["proven", "evergreen"]);
+var UNTESTED_STAGES = /* @__PURE__ */ new Set(["new", "testing"]);
+function keptHint(results) {
+  const rows = results.map((r) => r ?? {});
+  const kept = rows.filter((r) => r.survived_test === true || KEPT_STAGES.has(String(r.stage))).length;
+  if (kept > 0 && kept < rows.length) {
+    return `${kept} of these are what competitors kept after testing (survived_test, or stage proven/evergreen): prefer them as references; a new or testing ad may still be cut.`;
+  }
+  if (kept === 0 && rows.some((r) => UNTESTED_STAGES.has(String(r.stage)))) {
+    return "None of these has outlived a test yet (stage new/testing): to reference what competitors kept, search once more with --survived-test or --stage proven,evergreen.";
+  }
+  return null;
+}
+var UNKNOWN_COUNTRY_RE = /Unknown country code\(s\): ([^.]+)\. Countries with ads: ([^.]+)\./;
+function unknownCountryFix(message) {
+  const match = UNKNOWN_COUNTRY_RE.exec(message);
+  if (!match) {
+    return null;
+  }
+  const unknownCountries = splitList(match[1]);
+  const validCountries = splitList(match[2]);
+  if (unknownCountries.length === 0 || validCountries.length === 0) {
+    return null;
+  }
+  return {
+    action: "retry_with_a_valid_country",
+    explanation: `${unknownCountries.join(", ")} is not a country the winning-ads library holds ads for. Re-run with codes from \`validCountries\`, or drop --country to search every market.`,
+    unknownCountries,
+    validCountries
+  };
+}
+function searchErrorFix(code, message) {
+  if (code === "UNAVAILABLE") {
+    return {
+      action: "retry_narrower_once",
+      explanation: "The library did not answer this search in time. Retry once with a shorter brief, a lower --limit or fewer filters. If it fails again, continue without a reference and say so; do not stop the creative work."
+    };
+  }
+  return unknownCountryFix(message);
+}
+function reportSearchError(err) {
+  const fix = err instanceof ApiError ? searchErrorFix(err.code, err.message) : null;
+  if (err instanceof ApiError && fix) {
+    writeJson({ ok: false, error: { code: err.code, message: err.message, fix } });
+    process.exit(1);
+  }
+  reportError(err);
+}
+var FLAG_FOR_FIELD = {
+  limit: "--limit",
+  max_per_advertiser: "--max-per-advertiser",
+  min_relevance: "--min-relevance",
+  platform: "--platform",
+  format: "--format",
+  winner_category: "--winner-category",
+  awareness_stage: "--awareness",
+  audience_temperature: "--audience-temperature",
+  funnel_stage: "--funnel-stage",
+  advertiser_size: "--advertiser-size",
+  static_format_patterns: "--format-pattern",
+  first_seen_after: "--first-seen-after",
+  first_seen_before: "--first-seen-before",
+  lifecycle_stage: "--stage"
+};
+function flagFor(path) {
+  const field = String(path[0] === "hard_filters" ? path[1] : path[0]);
+  return FLAG_FOR_FIELD[field] ?? field;
+}
+function schemaRejection(body) {
+  const parsed = scopedWinnersSearchRequestSchema.safeParse(body, { reportInput: true });
+  if (parsed.success) {
+    return null;
+  }
+  const [first] = parsed.error.issues;
+  if (!first) {
+    return { message: "Invalid search" };
+  }
+  const flag = flagFor(first.path);
+  if (first.code === "invalid_value") {
+    const sameFlag = parsed.error.issues.filter((i) => i.code === "invalid_value" && flagFor(i.path) === flag);
+    const invalidValues = sameFlag.map((i) => String(i.input));
+    const validValues = first.values.map(String);
+    return {
+      message: `Unknown ${flag} value${invalidValues.length > 1 ? "s" : ""} ${invalidValues.map((v) => `"${v}"`).join(", ")}.`,
+      fix: {
+        action: "retry_with_valid_values",
+        explanation: `Re-run with values from \`validValues\` for ${flag}, or drop the flag.`,
+        flag,
+        invalidValues,
+        validValues
+      }
+    };
+  }
+  return { message: first.path.length > 0 ? `${flag}: ${first.message}` : first.message };
+}
+var NUMERIC_FLAGS = [
+  ["--limit", "limit"],
+  ["--max-per-advertiser", "maxPerAdvertiser"],
+  ["--min-relevance", "minRelevance"]
+];
+function searchRejection(args, body) {
+  if (args.scope !== void 0 && !winnerSearchScopeSchema.safeParse(args.scope).success) {
+    return { message: `Unknown --scope "${args.scope}". Use one of: ${winnerSearchScopeSchema.options.join(", ")}.` };
+  }
+  if (args.sort !== void 0 && !winnersSortSchema.safeParse(args.sort).success) {
+    return { message: `Unknown --sort "${args.sort}". Use one of: ${winnersSortSchema.options.join(", ")}.` };
+  }
+  if (args.partnership !== void 0 && !(args.partnership in PARTNERSHIP_VALUES)) {
+    return { message: `Unknown --partnership "${args.partnership}". Use one of: only, exclude.` };
+  }
+  for (const [flag, key] of NUMERIC_FLAGS) {
+    const value = args[key];
+    if (value !== void 0 && value !== "" && Number.isNaN(Number(value))) {
+      return { message: `${flag} must be a number, got "${value}".` };
+    }
+  }
+  if (!("free_text_query" in body || "ref_ad_id" in body || "hard_filters" in body)) {
+    return { message: "Provide a query, --ref-ad-id, or a filter flag" };
+  }
+  return schemaRejection(body);
+}
+function writeSearchResult(data, opts) {
+  const rawResults = Array.isArray(data?.results) ? data.results : [];
+  const hints = searchHints(data ?? {});
+  const withHints = hints.length > 0 ? { hints } : {};
+  if (opts.output === "json") {
+    const results = adRows(rawResults, opts);
+    writeJson({
+      ok: true,
+      data: {
+        results,
+        scope: data?.scope ?? null,
+        following_count: data?.following_count ?? null,
+        pool_size: data?.pool_size ?? null,
+        match_confidence: data?.match_confidence ?? null,
+        below_floor_count: data?.below_floor_count ?? null,
+        country_coverage: data?.country_coverage ?? null
+      },
+      ...withHints
+    });
+    return;
+  }
+  writeOutput({ ok: true, data: rawResults, ...withHints }, opts.output, opts.fields, opts.full, winningAdNormalizer);
+}
+var SEARCH_TIMEOUT_MS = 12e4;
+var searchCommand = defineCommand({
+  meta: {
+    name: "search",
+    description: "Search winning reference ads, the company's followed brands first. Start here: baker winning-ads search 'B2B SaaS before/after AI automation' --platform meta --format static --exclude-advertiser adv_123 --output md. A set of references for N concepts in one call: add --diverse --limit N. The best proven ad in one container from any category: --format-pattern comparison_table (no query needed; add --sort longest_running to order by staying power). References for viewers who don't know the brand: --audience-temperature 0_cold --exclude-brand-reliant. What competitors kept after testing: --survived-test. What competitors run through creators: --partnership only. Each search is a paid reranker + judge call: one strong search, at most one adjusted retry."
+  },
+  args: {
+    query: { type: "positional", description: "Free-text search query", required: false },
+    scope: {
+      type: "string",
+      description: "followed-first (default) | followed | all. followed-first = the company's followed brands first, topped up from the whole library (the whole library when it follows nobody)",
+      required: false
+    },
+    "ref-ad-id": { type: "string", description: "Find ads similar to this ad id", required: false },
+    limit: {
+      type: "string",
+      description: "Max results 1-100 (default 10 \u2014 a shortlist)",
+      required: false,
+      default: "10"
+    },
+    "max-per-advertiser": {
+      type: "string",
+      description: "Spread per advertiser by default: each brand's best 3 first, the rest after the other brands, none dropped. Set 1-50 to drop past N (1 = one reference per brand), 0 for rank order",
+      required: false
+    },
+    "min-relevance": { type: "string", description: "Relevance floor 0-1", required: false },
+    sort: {
+      type: "string",
+      description: "Order of a no-query browse: winner (default) | longest_running | newest. Ignored when a query is given",
+      required: false
+    },
+    platform: {
+      type: "string",
+      description: "Comma list of platforms (meta,linkedin,tiktok,google) \u2014 search one or several",
+      required: false
+    },
+    format: { type: "string", description: "Comma list of formats (video,static,carousel,text)", required: false },
+    "winner-category": {
+      type: "string",
+      description: "Comma list of winner categories (default: all)",
+      required: false
+    },
+    awareness: { type: "string", description: "Comma list of awareness stages", required: false },
+    "audience-temperature": {
+      type: "string",
+      description: "Comma list of who the ad was made for: 0_cold | 1_warm_engaged | 2_hot_visited | 3_customer (a cold brief takes 0_cold)",
+      required: false
+    },
+    "funnel-stage": { type: "string", description: "Comma list: TOF,MOF,BOF", required: false },
+    "advertiser-size": { type: "string", description: "Comma list: solo,smb,mid,enterprise", required: false },
+    "exclude-brand-reliant": {
+      type: "boolean",
+      description: "Drop ads that only work if the viewer already knows the brand (ads not judged yet are kept). Use it when making ads for viewers who don't know the brand",
+      required: false,
+      default: false
+    },
+    country: {
+      type: "string",
+      description: "Comma list of ISO country codes (US,GB): ads known to run there, plus ads with no country data (every Meta ad) in that country's main language. An unknown code is refused with the codes that have ads",
+      required: false
+    },
+    language: { type: "string", description: LANGUAGE_DESCRIPTION, required: false },
+    "advertiser-id": { type: "string", description: "Restrict to these advertiser ids", required: false },
+    "exclude-advertiser": {
+      type: "string",
+      description: "Drop these advertiser ids, usually your own brand",
+      required: false
+    },
+    "first-seen-after": { type: "string", description: "ISO date or datetime lower bound", required: false },
+    "first-seen-before": { type: "string", description: "ISO date or datetime upper bound", required: false },
+    "hook-archetype": {
+      type: "string",
+      description: "Comma list of proven hook seeds (from `winning-ads hooks`) to narrow the search",
+      required: false
+    },
+    "format-pattern": {
+      type: "string",
+      description: FORMAT_PATTERN_DESCRIPTION,
+      required: false
+    },
+    stage: { type: "string", description: STAGE_DESCRIPTION, required: false },
+    "survived-test": { type: "boolean", description: SURVIVED_TEST_DESCRIPTION, required: false, default: false },
+    partnership: { type: "string", description: PARTNERSHIP_DESCRIPTION, required: false },
+    "all-kinds": {
+      type: "boolean",
+      description: "Also return Google search text, Shopping and app ads (default: designed pictures and videos only)",
+      required: false,
+      default: false
+    },
+    diverse: {
+      type: "boolean",
+      description: "One varied set (different brands, containers, hooks): a reference per concept in one call",
+      required: false,
+      default: false
+    },
+    output: { type: "string", description: "Output format: json|files|md", required: false, default: "json" },
+    fields: { type: "string", description: "Comma-separated field names to include", required: false },
+    full: {
+      type: "boolean",
+      description: "Include DNA detail (angle, persona, hook, awareness, industry) + reach and media kind; mechanism, days_active, active, winner_category, audience_temperature, funnel_stage, advertiser_size and presumes_brand_knowledge are in the default output",
+      required: false,
+      default: false
+    }
+  },
+  run: async ({ args }) => {
+    try {
+      const searchArgs = {
+        query: args.query,
+        scope: args.scope,
+        refAdId: args["ref-ad-id"],
+        limit: args.limit,
+        maxPerAdvertiser: args["max-per-advertiser"],
+        minRelevance: args["min-relevance"],
+        sort: args.sort,
+        platform: args.platform,
+        format: args.format,
+        winnerCategory: args["winner-category"],
+        awareness: args.awareness,
+        audienceTemperature: args["audience-temperature"],
+        funnelStage: args["funnel-stage"],
+        advertiserSize: args["advertiser-size"],
+        excludeBrandReliant: args["exclude-brand-reliant"],
+        country: args.country,
+        language: args.language,
+        advertiserId: args["advertiser-id"],
+        excludeAdvertiser: args["exclude-advertiser"],
+        firstSeenAfter: args["first-seen-after"],
+        firstSeenBefore: args["first-seen-before"],
+        hookArchetype: args["hook-archetype"],
+        formatPattern: args["format-pattern"],
+        stage: args.stage,
+        survivedTest: args["survived-test"],
+        partnership: args.partnership,
+        diverse: args.diverse
+      };
+      const fieldPlan = adFieldPlan(args.fields, args.full);
+      const body = designedByDefault(buildSearchBody(searchArgs), { allKinds: args["all-kinds"] });
+      const rejection = searchRejection(searchArgs, body);
+      if (rejection) {
+        writeJson({ ok: false, error: { code: "VALIDATION_ERROR", ...rejection } });
+        process.exit(1);
+      }
+      const data = await apiPost("/api/ad-library/winners/search", body, {
+        timeoutMs: SEARCH_TIMEOUT_MS
+      });
+      writeSearchResult(data, { output: args.output || "json", ...fieldPlan });
+    } catch (err) {
+      reportSearchError(err);
+    }
+  }
+});
+
+export {
+  buildSearchBody,
+  designedByDefault,
+  searchHints,
+  unknownCountryFix,
+  searchErrorFix,
+  searchRejection,
+  searchCommand
+};
+//# sourceMappingURL=chunk-4WLJYLRL.js.map

package/dist/chunk-55AX6DOP.js

@@ -0,0 +1,86 @@
+// src/engine/copy-tells/questions.ts
+var ANY_LANGUAGE = "The copy may be in any language; judge the construction, not the words.";
+var TELL_QUESTIONS = [
+  {
+    id: "rhetorical-opener",
+    question: `Does \`sentence\` open with a fake-candid pause before an ordinary claim, such as "Honestly?", "Here's the thing:", "Look,", "Let's be real", "La verdad es que", "Seamos sinceros"? A sentence that simply starts with its claim does not count. ${ANY_LANGUAGE}`,
+    threshold: 0.75
+  },
+  {
+    id: "negation-pivot",
+    question: `Is \`sentence\` built as a negative parallelism that denies a smaller framing to assert a bigger one, such as "It's not just a CRM, it's a growth engine", "Not only X but also Y", "No se trata solo de X, sino de Y", or a short "Not a tool." answered by "A partner." (\`before\` is the sentence before it, for that two-sentence form)? A plain negative fact ("No setup fee", "We don't sell your data") does not count. ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  },
+  {
+    id: "participle-tail",
+    question: `Does \`sentence\` end with a participle or gerund phrase hung off a comma to add vague significance, such as ", ensuring nothing slips through", ", fostering growth", ", permitiendo cerrar el mes antes"? A sentence that opens with such a word does not count. ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  },
+  {
+    id: "copula-avoidance",
+    question: `Does \`sentence\` use an inflated verb where a plain "is" or "has" would do, such as "serves as", "stands as", "boasts", "se erige como", "cuenta con"? ${ANY_LANGUAGE}`,
+    threshold: 0.6
+  },
+  {
+    id: "authority-trope",
+    question: `Does \`sentence\` claim to reveal what is "really" at stake, with a phrase like "The real question is", "At its core", "What really matters is", "The heart of the matter", "En el fondo", "Lo que realmente importa"? Candid openers ("Honestly", "To be fair"), contrasts ("not just X, but Y") and filler words are other tells and do not count here. ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  },
+  {
+    id: "signposting",
+    question: `Does \`sentence\` announce what the text is about to explain instead of saying it, such as "Let's dive in", "Here's what you need to know", "Let's break it down", "Vamos a ver c\xF3mo funciona"? Presenting the offer itself ("Here is a plan for every team size", "Aqu\xED tienes nuestras tarifas") and an assistant handing over a summary are not this. ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  },
+  {
+    id: "chat-artifact",
+    question: `Is \`sentence\` an AI assistant talking to the person who asked it for the text, pasted into the page by mistake, such as "I hope this helps!", "Let me know if you want changes", "Here is an overview of the plan", "Would you like me to", "Aqu\xED tienes el resumen"? Copy that speaks to the page's own visitor ("Here are our three plans", "Tell us what you need") does not count. ${ANY_LANGUAGE}`,
+    threshold: 0.62
+  },
+  {
+    id: "vague-attribution",
+    question: `Does \`sentence\` credit a claim to unnamed authorities, such as "Experts agree", "Studies show", "Research shows", "Los expertos coinciden", without naming who? ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  },
+  {
+    id: "hollow-conclusion",
+    question: `Is \`sentence\` a vague upbeat ending that asserts nothing, such as "The future looks bright", "The possibilities are endless", "El cielo es el l\xEDmite"? ${ANY_LANGUAGE}`,
+    threshold: 0.65
+  },
+  {
+    id: "filler-phrase",
+    question: `Does \`sentence\` contain a wordy filler phrase that carries no meaning, such as "in order to", "due to the fact that", "it is worth noting that", "cabe destacar"? ${ANY_LANGUAGE}`,
+    threshold: 0.75
+  },
+  {
+    id: "aphorism-formula",
+    question: `Is \`sentence\` an aphorism of the form "X is the <abstract noun> of Y", such as "Trust is the currency of every deal", "Data is the language of growth", "Los datos son la columna vertebral de tu negocio"? Other contrasts and slogans do not count. ${ANY_LANGUAGE}`,
+    threshold: 0.7
+  },
+  {
+    id: "false-range",
+    question: `Does \`sentence\` use a "from X to Y" range whose two ends are not points on one scale, such as "from onboarding to retention", "from startups to enterprises", "desde la captaci\xF3n hasta la fidelizaci\xF3n"? A real range of numbers, prices or dates ("from $9 to $99") does not count. ${ANY_LANGUAGE}`,
+    threshold: 0.5
+  }
+];
+function tellQuestionsFor(sentence) {
+  return TELL_QUESTIONS.map((t) => ({
+    instructions: {
+      sentence: sentence.text,
+      ...t.id === "negation-pivot" && sentence.before ? { before: sentence.before } : {},
+      question: t.question
+    }
+  }));
+}
+var SAME_CLAIM_QUESTION = `\`a\` and \`b\` are two headlines of the same ad. Are they the same claim reworded, a synonym or a swapped verb apart ("Boost Your Sales Fast" and "Increase Your Sales Fast"), rather than two different claims (a price, a guarantee, a delivery time, a rating)? ${ANY_LANGUAGE}`;
+var SAME_CLAIM_HELD = 0.5;
+function sameClaimQuestion(a, b) {
+  return { instructions: { a, b, question: SAME_CLAIM_QUESTION } };
+}
+
+export {
+  TELL_QUESTIONS,
+  tellQuestionsFor,
+  SAME_CLAIM_HELD,
+  sameClaimQuestion
+};
+//# sourceMappingURL=chunk-55AX6DOP.js.map

package/dist/chunk-55AX6DOP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/engine/copy-tells/questions.ts"],"sourcesContent":["/**\n * The AI copy tells that are a reading of the words, asked of the decision model (Jev) one\n * sentence at a time, in whatever language the copy is written.\n *\n * The observation set is Wikipedia's \"Signs of AI writing\" (WikiProject AI Cleanup), via the\n * `humanizer` skill (MIT, github.com/blader/humanizer): which constructions models over-produce.\n * It used to be phrase lists in English and Spanish, so a Portuguese, German or French page passed\n * clean and a paraphrase of a listed phrase did too. The examples in each question are examples:\n * Jev reads the construction, not the words. Thresholds were measured on\n * scripts/copy-tells-evals (docs/decision-model.md).\n *\n * The tells that are a shape rather than a reading (a run of very short sentences, Title Case in\n * a heading, emoji, curly quotes, an inline-header list) stay in code: `detect.ts`.\n */\nimport type { NoulQuestion } from \"../lib/remembered-nouls.ts\";\n\nexport type JudgedTellId =\n  | \"rhetorical-opener\"\n  | \"negation-pivot\"\n  | \"participle-tail\"\n  | \"copula-avoidance\"\n  | \"authority-trope\"\n  | \"signposting\"\n  | \"chat-artifact\"\n  | \"vague-attribution\"\n  | \"hollow-conclusion\"\n  | \"filler-phrase\"\n  | \"aphorism-formula\"\n  | \"false-range\";\n\ntype TellQuestion = {\n  id: JudgedTellId;\n  question: string;\n  /** At or above this, the sentence carries the tell. Measured per question. */\n  threshold: number;\n};\n\nconst ANY_LANGUAGE = \"The copy may be in any language; judge the construction, not the words.\";\n\nexport const TELL_QUESTIONS: readonly TellQuestion[] = [\n  {\n    id: \"rhetorical-opener\",\n    question: `Does \\`sentence\\` open with a fake-candid pause before an ordinary claim, such as \"Honestly?\", \"Here's the thing:\", \"Look,\", \"Let's be real\", \"La verdad es que\", \"Seamos sinceros\"? A sentence that simply starts with its claim does not count. ${ANY_LANGUAGE}`,\n    threshold: 0.75,\n  },\n  {\n    id: \"negation-pivot\",\n    question: `Is \\`sentence\\` built as a negative parallelism that denies a smaller framing to assert a bigger one, such as \"It's not just a CRM, it's a growth engine\", \"Not only X but also Y\", \"No se trata solo de X, sino de Y\", or a short \"Not a tool.\" answered by \"A partner.\" (\\`before\\` is the sentence before it, for that two-sentence form)? A plain negative fact (\"No setup fee\", \"We don't sell your data\") does not count. ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n  {\n    id: \"participle-tail\",\n    question: `Does \\`sentence\\` end with a participle or gerund phrase hung off a comma to add vague significance, such as \", ensuring nothing slips through\", \", fostering growth\", \", permitiendo cerrar el mes antes\"? A sentence that opens with such a word does not count. ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n  {\n    id: \"copula-avoidance\",\n    question: `Does \\`sentence\\` use an inflated verb where a plain \"is\" or \"has\" would do, such as \"serves as\", \"stands as\", \"boasts\", \"se erige como\", \"cuenta con\"? ${ANY_LANGUAGE}`,\n    threshold: 0.6,\n  },\n  {\n    id: \"authority-trope\",\n    question: `Does \\`sentence\\` claim to reveal what is \"really\" at stake, with a phrase like \"The real question is\", \"At its core\", \"What really matters is\", \"The heart of the matter\", \"En el fondo\", \"Lo que realmente importa\"? Candid openers (\"Honestly\", \"To be fair\"), contrasts (\"not just X, but Y\") and filler words are other tells and do not count here. ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n  {\n    id: \"signposting\",\n    question: `Does \\`sentence\\` announce what the text is about to explain instead of saying it, such as \"Let's dive in\", \"Here's what you need to know\", \"Let's break it down\", \"Vamos a ver cómo funciona\"? Presenting the offer itself (\"Here is a plan for every team size\", \"Aquí tienes nuestras tarifas\") and an assistant handing over a summary are not this. ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n  {\n    id: \"chat-artifact\",\n    question: `Is \\`sentence\\` an AI assistant talking to the person who asked it for the text, pasted into the page by mistake, such as \"I hope this helps!\", \"Let me know if you want changes\", \"Here is an overview of the plan\", \"Would you like me to\", \"Aquí tienes el resumen\"? Copy that speaks to the page's own visitor (\"Here are our three plans\", \"Tell us what you need\") does not count. ${ANY_LANGUAGE}`,\n    threshold: 0.62,\n  },\n  {\n    id: \"vague-attribution\",\n    question: `Does \\`sentence\\` credit a claim to unnamed authorities, such as \"Experts agree\", \"Studies show\", \"Research shows\", \"Los expertos coinciden\", without naming who? ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n  {\n    id: \"hollow-conclusion\",\n    question: `Is \\`sentence\\` a vague upbeat ending that asserts nothing, such as \"The future looks bright\", \"The possibilities are endless\", \"El cielo es el límite\"? ${ANY_LANGUAGE}`,\n    threshold: 0.65,\n  },\n  {\n    id: \"filler-phrase\",\n    question: `Does \\`sentence\\` contain a wordy filler phrase that carries no meaning, such as \"in order to\", \"due to the fact that\", \"it is worth noting that\", \"cabe destacar\"? ${ANY_LANGUAGE}`,\n    threshold: 0.75,\n  },\n  {\n    id: \"aphorism-formula\",\n    question: `Is \\`sentence\\` an aphorism of the form \"X is the <abstract noun> of Y\", such as \"Trust is the currency of every deal\", \"Data is the language of growth\", \"Los datos son la columna vertebral de tu negocio\"? Other contrasts and slogans do not count. ${ANY_LANGUAGE}`,\n    threshold: 0.7,\n  },\n  {\n    id: \"false-range\",\n    question: `Does \\`sentence\\` use a \"from X to Y\" range whose two ends are not points on one scale, such as \"from onboarding to retention\", \"from startups to enterprises\", \"desde la captación hasta la fidelización\"? A real range of numbers, prices or dates (\"from $9 to $99\") does not count. ${ANY_LANGUAGE}`,\n    threshold: 0.5,\n  },\n];\n\n/** One sentence of copy, and the one before it in the same block, when there is one. */\nexport type CopySentence = { text: string; before?: string };\n\n/** The tell questions for one sentence, in `TELL_QUESTIONS` order. Pure. */\nexport function tellQuestionsFor(sentence: CopySentence): NoulQuestion[] {\n  return TELL_QUESTIONS.map((t) => ({\n    instructions: {\n      sentence: sentence.text,\n      ...(t.id === \"negation-pivot\" && sentence.before ? { before: sentence.before } : {}),\n      question: t.question,\n    },\n  }));\n}\n\n/**\n * Synonym cycling (§11): headlines of one ad that are one claim reworded with a swapped verb. Both\n * an AI tell and a real Google Ads defect, since a cycled set gives the auction nothing to choose\n * between. Asked of each pair of a set; it replaced a table of English and Spanish verb synonyms.\n */\nexport const SAME_CLAIM_QUESTION = `\\`a\\` and \\`b\\` are two headlines of the same ad. Are they the same claim reworded, a synonym or a swapped verb apart (\"Boost Your Sales Fast\" and \"Increase Your Sales Fast\"), rather than two different claims (a price, a guarantee, a delivery time, a rating)? ${ANY_LANGUAGE}`;\nexport const SAME_CLAIM_HELD = 0.5;\n\nexport function sameClaimQuestion(a: string, b: string): NoulQuestion {\n  return { instructions: { a, b, question: SAME_CLAIM_QUESTION } };\n}\n"],"mappings":";AAqCA,IAAM,eAAe;AAEd,IAAM,iBAA0C;AAAA,EACrD;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,qPAAqP,YAAY;AAAA,IAC3Q,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,maAAma,YAAY;AAAA,IACzb,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,sQAAsQ,YAAY;AAAA,IAC5R,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,2JAA2J,YAAY;AAAA,IACjL,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,6VAA6V,YAAY;AAAA,IACnX,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,kWAA4V,YAAY;AAAA,IAClX,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,+XAA4X,YAAY;AAAA,IAClZ,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,qKAAqK,YAAY;AAAA,IAC3L,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,+JAA4J,YAAY;AAAA,IAClL,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,uKAAuK,YAAY;AAAA,IAC7L,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,2PAA2P,YAAY;AAAA,IACjR,WAAW;AAAA,EACb;AAAA,EACA;AAAA,IACE,IAAI;AAAA,IACJ,UAAU,iSAA2R,YAAY;AAAA,IACjT,WAAW;AAAA,EACb;AACF;AAMO,SAAS,iBAAiB,UAAwC;AACvE,SAAO,eAAe,IAAI,CAAC,OAAO;AAAA,IAChC,cAAc;AAAA,MACZ,UAAU,SAAS;AAAA,MACnB,GAAI,EAAE,OAAO,oBAAoB,SAAS,SAAS,EAAE,QAAQ,SAAS,OAAO,IAAI,CAAC;AAAA,MAClF,UAAU,EAAE;AAAA,IACd;AAAA,EACF,EAAE;AACJ;AAOO,IAAM,sBAAsB,uQAAuQ,YAAY;AAC/S,IAAM,kBAAkB;AAExB,SAAS,kBAAkB,GAAW,GAAyB;AACpE,SAAO,EAAE,cAAc,EAAE,GAAG,GAAG,UAAU,oBAAoB,EAAE;AACjE;","names":[]}