@koda-sl/baker-cli 0.158.2 → 0.160.0

package/dist/cli.js

@@ -3501,7 +3501,7 @@ registerSchema({
     name: { type: "string", description: "Action name (short, action-verb, \u22646 words)", required: true },
     description: {
       type: "string",
-      description: "Context-complete description: what / why / where / done-when",
+      description: "Context-complete description in markdown: what / why / where / done-when. Use `##` headings for those sections, `-` bullets for lists of items, and `**bold**` for the figures that drive the decision. Anything longer than a couple of sentences needs headings \u2014 it is read in a narrow panel.",
       required: false
     },
     tags: {
@@ -4154,7 +4154,11 @@ registerSchema({
   args: {
     id: { type: "string", description: "Action ID or tempId (temp_*) of a task staged in this chat", required: true },
     name: { type: "string", description: "New name", required: false },
-    description: { type: "string", description: "New description", required: false },
+    description: {
+      type: "string",
+      description: "New description, in markdown \u2014 `##` headings per section, `-` bullets, `**bold**` for the decisive figures. REPLACES the whole description, so carry over anything still true.",
+      required: false
+    },
     tags: {
       type: "string",
       description: "Comma-separated tag slugs \u2014 REPLACES existing tags ('' clears)",
@@ -4176,7 +4180,7 @@ var updateCommand = defineCommand17({
     id: { type: "positional", description: "Action ID or tempId (temp_*)", required: false },
     "action-id": { type: "string", description: "Action ID or tempId (temp_*)", required: false },
     name: { type: "string", description: "New name", required: false },
-    description: { type: "string", description: "New description", required: false },
+    description: { type: "string", description: "New description (markdown)", required: false },
     tags: { type: "string", description: "Comma-separated tag slugs \u2014 REPLACES existing ('' clears)", required: false },
     priority: { type: "string", description: `Priority: ${ACTION_PRIORITIES.join("|")}|none`, required: false }
   },
@@ -4840,7 +4844,10 @@ var callAdSchema = z13.object({
 var appAdSchema = z13.object({
   format: z13.literal("app"),
   headlines: z13.array(z13.object({ text: z13.string().min(1).max(30) })).min(1),
-  descriptions: z13.array(z13.object({ text: z13.string().min(1).max(90) })).min(1)
+  descriptions: z13.array(z13.object({ text: z13.string().min(1).max(90) })).min(1),
+  // An App campaign ad carries its images on its own content (`AppAdInfo.images`), not as
+  // campaign-level asset links — same shape as a responsive display ad's marketing images.
+  images: z13.array(refSchema).optional()
 });
 var videoAdSchema = z13.object({
   format: z13.literal("video"),
@@ -6179,6 +6186,443 @@ import { defineCommand as defineCommand22 } from "citty";
 // src/commands/ads/google/write-shared.ts
 import { readFileSync as readFileSync2 } from "fs";
 
+// src/engine/copy-tells/patterns.ts
+var PHRASE_TELLS = {
+  // §33 — the fake-candid pause before an ordinary claim. The single loudest
+  // tell in AI-written Meta primary text. Anchored to a sentence start by the
+  // detector, so "take a look at" and "honestly, I agree" mid-sentence are safe.
+  "rhetorical-opener": [
+    "honestly\\?",
+    "honestly,",
+    "here's the thing",
+    "here is the thing",
+    "the thing is",
+    "let's be honest",
+    "let's be real",
+    "real talk",
+    "look,",
+    "listen,",
+    "la verdad es que",
+    "sinceramente,",
+    "seamos honestos",
+    "seamos sinceros",
+    "mira,",
+    "escucha,",
+    "te lo digo claro"
+  ],
+  // §9 — negative parallelism. Our landing doctrine already names this in prose;
+  // this is the detector that was missing.
+  "negation-pivot": [
+    "it's not just",
+    "it is not just",
+    "it's not merely",
+    "not only .{3,40} but also",
+    "less about .{3,40} more about",
+    "isn't about .{3,40} it's about",
+    "no se trata solo de",
+    "no se trata \xFAnicamente de",
+    "no solo .{3,40} sino",
+    "no es solo .{3,40} es",
+    "m\xE1s que .{3,40}, es"
+  ],
+  // §3 — present participle hung off a comma to fake depth. Detector requires
+  // the preceding comma, so a sentence-initial participle is not a tell.
+  "participle-tail": [
+    "ensuring",
+    "highlighting",
+    "underscoring",
+    "emphasizing",
+    "showcasing",
+    "fostering",
+    "empowering",
+    "reflecting",
+    "symbolizing",
+    "contributing to",
+    "encompassing",
+    "cultivating",
+    "permitiendo",
+    "garantizando",
+    "impulsando",
+    "reflejando",
+    "consolidando",
+    "potenciando"
+  ],
+  // §8 — elaborate constructions standing in for "is" and "has".
+  "copula-avoidance": [
+    "serves as",
+    "stands as",
+    "boasts",
+    "represents a",
+    "marks a",
+    "se erige como",
+    "se posiciona como",
+    "cuenta con",
+    "se consolida como",
+    "constituye un"
+  ],
+  // §27 — pretending to cut through noise before restating an ordinary point.
+  "authority-trope": [
+    "the real question is",
+    "at its core",
+    "what really matters",
+    "the heart of the matter",
+    "the deeper issue",
+    "in reality,",
+    "la verdadera pregunta",
+    "en el fondo,",
+    "lo que realmente importa",
+    "en esencia,"
+  ],
+  // §28 — announcing the writing instead of doing it.
+  signposting: [
+    "let's dive in",
+    "let's dive into",
+    "let's explore",
+    "let's break (?:this|it) down",
+    "here's what you need to know",
+    "here is what you need to know",
+    "now let's look at",
+    "without further ado",
+    "vamos a ver",
+    "vamos a analizar",
+    "profundicemos",
+    "esto es lo que necesitas saber",
+    "te lo explicamos paso a paso"
+  ],
+  // §20 — chatbot correspondence pasted in as content. Always a defect: it means
+  // the agent shipped its own conversational frame into client-facing copy.
+  //
+  // This is the only tell the landing gate fires at ONE occurrence, so every
+  // entry has to be unambiguous. The delivery openers are therefore bound to the
+  // noun the assistant hands over ("here is a summary", "aquí tienes el
+  // resumen"): a bare "here is a…" / "aquí tienes…" is ordinary marketing copy.
+  "chat-artifact": [
+    "i hope this helps",
+    "let me know if",
+    "would you like me to",
+    "want me to",
+    "here (?:is|are) (?:an? |the )?(?:overview|summary|breakdown|rundown|outline|draft|revised version)",
+    "here's (?:an? |the )?(?:overview|summary|breakdown|rundown|outline|draft|revised version)",
+    "certainly!",
+    "great question",
+    "you're absolutely right",
+    "espero que (?:te sirva|esto ayude)",
+    "av\xEDsame si",
+    "\xBFquieres que",
+    "aqu\xED tienes (?:un |una |el |la |los |las )?(?:resumen|listado|desglose|borrador|esquema|propuesta|versi\xF3n)",
+    "por supuesto!"
+  ],
+  // §5 — opinions attributed to nobody in particular.
+  "vague-attribution": [
+    "experts agree",
+    "experts say",
+    "experts argue",
+    "studies show",
+    "research shows",
+    "industry reports",
+    "observers have",
+    "some critics",
+    "it is believed that",
+    "los expertos coinciden",
+    "los expertos afirman",
+    "los estudios demuestran",
+    "seg\xFAn varios informes",
+    "se cree que"
+  ],
+  // §25 — vague upbeat endings that assert nothing.
+  "hollow-conclusion": [
+    "the future looks bright",
+    "exciting times",
+    "a step in the right direction",
+    "the possibilities are endless",
+    "the sky's the limit",
+    "el futuro es prometedor",
+    "las posibilidades son infinitas",
+    "un paso en la direcci\xF3n correcta",
+    "el cielo es el l\xEDmite"
+  ],
+  // §23 — words that carry no load.
+  "filler-phrase": [
+    "in order to",
+    "due to the fact that",
+    "at this point in time",
+    "has the ability to",
+    "have the ability to",
+    "it is important to note",
+    "it is worth noting",
+    "con el fin de",
+    "debido al hecho de que",
+    "en este momento del tiempo",
+    "tiene la capacidad de",
+    "cabe destacar",
+    "cabe se\xF1alar",
+    "es importante se\xF1alar"
+  ],
+  // §32 — ordinary claims dressed as reusable aphorisms.
+  "aphorism-formula": [
+    "the language of",
+    "the currency of",
+    "the architecture of",
+    "the backbone of",
+    "el lenguaje de",
+    "la moneda de",
+    "la columna vertebral de"
+  ]
+};
+var SENTENCE_INITIAL_TELLS = /* @__PURE__ */ new Set(["rhetorical-opener"]);
+var COMMA_ANCHORED_TELLS = /* @__PURE__ */ new Set(["participle-tail"]);
+var STACCATO_MAX_WORDS = 4;
+var STACCATO_RUN = 3;
+var SYNONYM_OVERLAP = 0.6;
+var HEADLINE_SET_FLOOR = 3;
+var CYCLED_VERBS = [
+  ["boost", "increase", "grow", "raise", "lift", "improve", "enhance", "maximize", "drive"],
+  ["cut", "reduce", "lower", "slash", "shrink", "minimize", "decrease"],
+  ["get", "obtain", "receive", "secure", "unlock", "claim"],
+  ["fast", "quick", "rapid", "swift", "speedy", "instant"],
+  ["aumenta", "incrementa", "mejora", "impulsa", "potencia", "maximiza", "multiplica"],
+  ["reduce", "recorta", "baja", "disminuye", "minimiza"],
+  ["consigue", "obt\xE9n", "logra", "alcanza", "desbloquea"],
+  ["r\xE1pido", "veloz", "inmediato", "al instante"]
+];
+
+// src/engine/copy-tells/detect.ts
+var SAMPLE_MAX = 60;
+function sample(text) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  return clean.length <= SAMPLE_MAX ? clean : `${clean.slice(0, SAMPLE_MAX)}\u2026`;
+}
+var DELIBERATE_REGEX = /\.\{\d+,\d+\}|\(\?:[^()]*\)|\\?\?/g;
+function escapeLiteral(text) {
+  return text.replace(/[.*+^$?()|[\]{}\\]/g, (ch) => `\\${ch}`);
+}
+function toPattern(phrase) {
+  let out = "";
+  let last = 0;
+  for (const m of phrase.matchAll(DELIBERATE_REGEX)) {
+    const start = m.index ?? 0;
+    out += escapeLiteral(phrase.slice(last, start)) + m[0];
+    last = start + m[0].length;
+  }
+  return out + escapeLiteral(phrase.slice(last));
+}
+var WORD_START = "(?<![\\p{L}\\p{N}])";
+function matcherFor(id, phrase) {
+  const body = toPattern(phrase);
+  if (SENTENCE_INITIAL_TELLS.has(id)) return new RegExp(`(?:^|[.!?\xBF\xA1]\\s+|\\n)\\s*${body}`, "giu");
+  if (COMMA_ANCHORED_TELLS.has(id)) return new RegExp(`,\\s+${body}\\b`, "giu");
+  return new RegExp(`${WORD_START}${body}`, "giu");
+}
+var FALSE_RANGE_PATTERNS = [
+  /\bfrom\s+([^,.;]{3,30}?)\s+to\s+([^,.;]{3,30}?)(?=[,.;]|$)/gi,
+  /\bdesde\s+([^,.;]{3,30}?)\s+hasta\s+([^,.;]{3,30}?)(?=[,.;]|$)/gi
+];
+function countFalseRanges(text) {
+  let count = 0;
+  let first = "";
+  for (const re of FALSE_RANGE_PATTERNS) {
+    for (const m of text.matchAll(re)) {
+      const left = m[1] ?? "";
+      const right = m[2] ?? "";
+      if (/\d/.test(left) || /\d/.test(right)) continue;
+      count++;
+      if (!first) first = m[0] ?? "";
+    }
+  }
+  return { count, first };
+}
+function countStaccato(text) {
+  const sentences = text.split(/(?<=[.!?])\s+/).map((s) => s.trim()).filter(Boolean);
+  let run = 0;
+  let count = 0;
+  let first = "";
+  let runStart = 0;
+  for (const [i, s] of sentences.entries()) {
+    const words2 = s.split(/\s+/).filter(Boolean).length;
+    if (words2 > 0 && words2 <= STACCATO_MAX_WORDS) {
+      if (run === 0) runStart = i;
+      run++;
+      if (run === STACCATO_RUN) {
+        count++;
+        if (!first) first = sentences.slice(runStart, i + 1).join(" ");
+      }
+    } else {
+      run = 0;
+    }
+  }
+  return { count, first };
+}
+function countTitleCaseHeadings(text) {
+  let count = 0;
+  let first = "";
+  for (const m of text.matchAll(/^\s{0,3}#{1,6}\s+(.+)$/gm)) {
+    const heading = (m[1] ?? "").trim();
+    const words2 = heading.split(/\s+/).filter((w) => new RegExp("\\p{L}", "u").test(w));
+    if (words2.length < 4) continue;
+    const capitalized = words2.filter((w) => new RegExp("^\\p{Lu}", "u").test(w)).length;
+    if (capitalized / words2.length < 0.8) continue;
+    count++;
+    if (!first) first = heading;
+  }
+  return { count, first };
+}
+function countInlineHeaderList(text) {
+  const matches = [...text.matchAll(/^\s*(?:[-*+]|\d+\.)\s+\*\*[^*\n]{2,40}:?\*\*:?\s/gm)];
+  if (matches.length < 3) return { count: 0, first: "" };
+  return { count: matches.length, first: (matches[0]?.[0] ?? "").trim() };
+}
+var EMOJI = /[\u{1F300}-\u{1FAFF}]|[\u{2600}-\u{27BF}]|[\u{1F000}-\u{1F2FF}]|\u{FE0F}/gu;
+var CURLY = /[‘’“”]/g;
+function countPhraseTell(text, id, phrases) {
+  let count = 0;
+  let first = "";
+  for (const phrase of phrases) {
+    for (const m of text.matchAll(matcherFor(id, phrase))) {
+      count++;
+      if (!first) first = m[0] ?? "";
+    }
+  }
+  return { count, first };
+}
+function countPattern(text, re) {
+  const matches = text.match(re) ?? [];
+  return { count: matches.length, first: matches.join("") };
+}
+function detectCopyTells(text) {
+  if (!text.trim()) return [];
+  const results = [
+    ...Object.entries(PHRASE_TELLS).map(([id, phrases]) => [
+      id,
+      countPhraseTell(text, id, phrases)
+    ]),
+    ["false-range", countFalseRanges(text)],
+    ["staccato-drama", countStaccato(text)],
+    ["title-case-heading", countTitleCaseHeadings(text)],
+    ["inline-header-list", countInlineHeaderList(text)],
+    ["curly-quote", countPattern(text, CURLY)],
+    ["emoji", countPattern(text, EMOJI)]
+  ];
+  return results.filter(([, result]) => result.count > 0).map(([id, result]) => ({ id, count: result.count, sample: sample(result.first) }));
+}
+function words(headline) {
+  return headline.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").split(/\s+/).filter(Boolean);
+}
+function canonical(word) {
+  for (const [i, group] of CYCLED_VERBS.entries()) if (group.includes(word)) return `group:${i}`;
+  return word;
+}
+function overlap(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let shared = 0;
+  for (const w of a) if (b.has(w)) shared++;
+  return shared / Math.max(a.size, b.size);
+}
+function detectHeadlineSetTells(headlines) {
+  const usable = headlines.map((h) => h.trim()).filter(Boolean);
+  if (usable.length < HEADLINE_SET_FLOOR) return [];
+  const sets = usable.map((h) => new Set(words(h).map(canonical)));
+  const cycled = [];
+  for (let i = 0; i < sets.length; i++) {
+    for (let j = i + 1; j < sets.length; j++) {
+      if (overlap(sets[i] ?? /* @__PURE__ */ new Set(), sets[j] ?? /* @__PURE__ */ new Set()) >= SYNONYM_OVERLAP) {
+        cycled.push(`"${usable[i]}" / "${usable[j]}"`);
+      }
+    }
+  }
+  if (cycled.length === 0) return [];
+  return [{ id: "synonym-cycling", count: cycled.length, sample: sample(cycled[0] ?? "") }];
+}
+
+// src/commands/ads/copy-hints.ts
+var NOT_APPLICABLE_TO_ADS = /* @__PURE__ */ new Set([
+  "title-case-heading",
+  "staccato-drama",
+  "emoji",
+  "curly-quote",
+  "inline-header-list"
+]);
+var COPY_KEYS = /* @__PURE__ */ new Set([
+  "headline",
+  "headlines",
+  "longheadline",
+  "longheadlines",
+  "shortheadline",
+  "shortheadlines",
+  "description",
+  "descriptions",
+  "primarytext",
+  "primarytexts",
+  "message",
+  "messages",
+  "commentary",
+  "body",
+  "bodies",
+  "text",
+  "calltoaction",
+  "linkdescription",
+  "sitelinktext",
+  "callout",
+  "callouts",
+  "introtext"
+]);
+var HEADLINE_SET_KEYS = /* @__PURE__ */ new Set(["headlines", "longheadlines", "shortheadlines"]);
+var MAX_HINTS = 5;
+var SYNONYM_PAIR_FLOOR = 2;
+function asStrings(value) {
+  const one = (v) => {
+    const text = typeof v === "string" ? v : v !== null && typeof v === "object" ? v.text : "";
+    return typeof text === "string" && text.trim() ? text : void 0;
+  };
+  const values = Array.isArray(value) ? value : [value];
+  return values.map(one).filter((v) => v !== void 0);
+}
+function collectCopy(value, depth = 0) {
+  const texts = [];
+  const headlineSets = [];
+  if (depth > 4 || value === null || typeof value !== "object") return { texts, headlineSets };
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const nested = collectCopy(item, depth + 1);
+      texts.push(...nested.texts);
+      headlineSets.push(...nested.headlineSets);
+    }
+    return { texts, headlineSets };
+  }
+  for (const [key, raw] of Object.entries(value)) {
+    const normalized = key.toLowerCase().replace(/[_-]/g, "");
+    const strings = COPY_KEYS.has(normalized) ? asStrings(raw) : [];
+    if (strings.length > 0) {
+      texts.push(...strings);
+      if (HEADLINE_SET_KEYS.has(normalized) && strings.length > 1) headlineSets.push(strings);
+      continue;
+    }
+    const nested = collectCopy(raw, depth + 1);
+    texts.push(...nested.texts);
+    headlineSets.push(...nested.headlineSets);
+  }
+  return { texts, headlineSets };
+}
+function hintFor(tell) {
+  if (tell.id === "synonym-cycling") {
+    return `AI COPY TELL \u2014 ${tell.count} headline pairs are the same claim reworded (${tell.sample}). A cycled set gives the auction nothing to choose between: make each headline a different claim, not a different verb.`;
+  }
+  return `AI COPY TELL (${tell.id}) \u2014 "${tell.sample}". This construction reads as machine-written; rewrite it as a plain, specific claim before publishing.`;
+}
+function adCopyHints(payload) {
+  const { texts, headlineSets } = collectCopy(payload);
+  if (texts.length === 0) return [];
+  const tells = detectCopyTells(texts.join("\n")).filter((t) => !NOT_APPLICABLE_TO_ADS.has(t.id));
+  for (const set of headlineSets) {
+    for (const tell of detectHeadlineSetTells(set)) {
+      if (tell.count >= SYNONYM_PAIR_FLOOR) tells.push(tell);
+    }
+  }
+  tells.sort(
+    (a, b) => (b.id === "synonym-cycling" ? 1 : 0) - (a.id === "synonym-cycling" ? 1 : 0) || b.count - a.count
+  );
+  return tells.slice(0, MAX_HINTS).map(hintFor);
+}
+
 // src/commands/ads/google/draft-status.ts
 var OPERATION_LABELS = {
   create: "Creating",
@@ -6450,7 +6894,7 @@ async function stageGoogleOp(raw, hints) {
   try {
     const chatId = requireChatId();
     const response = await apiPost("/api/ads/google/draft/stage", { chatId, op: preflight.data });
-    const allHints = [...noopHints(response.data), ...hints ?? []];
+    const allHints = [...noopHints(response.data), ...hints ?? [], ...adCopyHints(preflight.data)];
     writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleGoogleError(err);
@@ -6492,15 +6936,16 @@ async function stageGoogleOps(rawOps, hints) {
       ...skipped.length > 0 ? [
         `${skipped.length} of ${ops.length} op(s) NOT STAGED \u2014 already in the requested state: ${skipped.map((s) => s.reason).join("; ")}`
       ] : [],
-      ...hints ?? []
+      ...hints ?? [],
+      ...adCopyHints(ops)
     ];
     writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleGoogleError(err);
   }
 }
-async function stageUpdate(kind, customerId, target, payload) {
-  await stageGoogleOp({ kind, customerId, target, payload });
+async function stageUpdate(kind, customerId, target, payload, hints) {
+  await stageGoogleOp({ kind, customerId, target, payload }, hints);
 }
 async function stageTarget(kind, customerId, target) {
   await stageGoogleOp({ kind, customerId, target });
@@ -8377,6 +8822,25 @@ function demandGenContentFromFlags(args, base) {
   }
   return content;
 }
+function appContentFromFlags(args, base) {
+  const content = {
+    format: "app",
+    ...base !== null && typeof base === "object" && !Array.isArray(base) ? base : {}
+  };
+  const headlines = listFlag(args.headlines);
+  if (headlines) {
+    content.headlines = headlines.map((text) => ({ text }));
+  }
+  const descriptions = listFlag(args.descriptions);
+  if (descriptions) {
+    content.descriptions = descriptions.map((text) => ({ text }));
+  }
+  const images = listFlag(args["image-assets"]);
+  if (images) {
+    content.images = images;
+  }
+  return content;
+}
 function adContentFromFlags(args, format, fileContent) {
   if (format === "responsiveSearch") {
     return fileContent ?? rsaContentFromFlags(args);
@@ -8390,8 +8854,48 @@ function adContentFromFlags(args, format, fileContent) {
   if (format === "demandGen") {
     return demandGenContentFromFlags(args, fileContent);
   }
+  if (format === "app") {
+    return appContentFromFlags(args, fileContent);
+  }
   return fileContent ?? failWriteValidation(`--format ${format} needs --file with the ad content`);
 }
+var adContentArgs = {
+  format: {
+    type: "string",
+    description: "responsiveSearch (default) | responsiveDisplay | call | app | video | demandGen"
+  },
+  headlines: { type: "string", description: "Comma-separated headlines (RSA/RDA/demandGen/app)" },
+  descriptions: { type: "string", description: "Comma-separated descriptions (RSA/RDA/demandGen/app)" },
+  path1: { type: "string" },
+  path2: { type: "string" },
+  "long-headline": { type: "string", description: "Long headline (responsiveDisplay)" },
+  "business-name": { type: "string", description: "Business name (responsiveDisplay/demandGen)" },
+  "marketing-images": {
+    type: "string",
+    description: "Comma-separated marketing image asset refs (responsiveDisplay)"
+  },
+  "square-marketing-images": {
+    type: "string",
+    description: "Comma-separated square marketing image asset refs (responsiveDisplay)"
+  },
+  "logo-images": { type: "string", description: "Comma-separated logo image asset refs (responsiveDisplay)" },
+  "video-assets": {
+    type: "string",
+    description: `Comma-separated video asset refs (video format) \u2014 stage the YouTube video as an asset first (assets create --file '{"type":"youtubeVideo",\u2026}')`
+  },
+  "image-assets": { type: "string", description: "Comma-separated image asset refs (demandGen/app)" },
+  "square-image-assets": { type: "string", description: "Comma-separated square image asset refs (demandGen)" },
+  "logo-image-assets": { type: "string", description: "Comma-separated logo image asset refs (demandGen)" },
+  "final-url": { type: "string", description: "Comma-separated final URLs" }
+};
+function assertNoContentFlags(args) {
+  const passed = Object.keys(adContentArgs).filter((flag) => flag !== "format" && args[flag] !== void 0);
+  if (passed.length > 0) {
+    failWriteValidation(
+      `${passed.map((flag) => `--${flag}`).join(", ")} only build an ad's content alongside --format (responsiveSearch | responsiveDisplay | call | app | video | demandGen) \u2014 add it, or pass --file with the complete content`
+    );
+  }
+}
 var adsCommand = defineCommand30({
   meta: { name: "ads", description: "Stage ad create/update/pause/resume/remove" },
   subCommands: {
@@ -8404,33 +8908,7 @@ var adsCommand = defineCommand30({
         ...customerIdArg,
         ...fileArg,
         "ad-group-ref": { type: "string", description: "Ad group ref" },
-        format: {
-          type: "string",
-          description: "responsiveSearch (default) | responsiveDisplay | call | app | video | demandGen"
-        },
-        headlines: { type: "string", description: "Comma-separated headlines (RSA/RDA/demandGen)" },
-        descriptions: { type: "string", description: "Comma-separated descriptions (RSA/RDA/demandGen)" },
-        path1: { type: "string" },
-        path2: { type: "string" },
-        "long-headline": { type: "string", description: "Long headline (responsiveDisplay)" },
-        "business-name": { type: "string", description: "Business name (responsiveDisplay/demandGen)" },
-        "marketing-images": {
-          type: "string",
-          description: "Comma-separated marketing image asset refs (responsiveDisplay)"
-        },
-        "square-marketing-images": {
-          type: "string",
-          description: "Comma-separated square marketing image asset refs (responsiveDisplay)"
-        },
-        "logo-images": { type: "string", description: "Comma-separated logo image asset refs (responsiveDisplay)" },
-        "video-assets": {
-          type: "string",
-          description: `Comma-separated video asset refs (video format) \u2014 stage the YouTube video as an asset first (assets create --file '{"type":"youtubeVideo",\u2026}')`
-        },
-        "image-assets": { type: "string", description: "Comma-separated image asset refs (demandGen)" },
-        "square-image-assets": { type: "string", description: "Comma-separated square image asset refs (demandGen)" },
-        "logo-image-assets": { type: "string", description: "Comma-separated logo image asset refs (demandGen)" },
-        "final-url": { type: "string", description: "Comma-separated final URLs" },
+        ...adContentArgs,
         status: { type: "string" }
       },
       run: async ({ args }) => {
@@ -8446,17 +8924,27 @@ var adsCommand = defineCommand30({
       }
     }),
     update: defineCommand30({
-      meta: { name: "update", description: "Stage an ad update" },
-      args: { ...customerIdArg, ...fileArg, status: { type: "string" } },
+      meta: {
+        name: "update",
+        description: "Stage an ad update. Any content change needs --format plus EVERY required field of that format (or --file with the complete content) \u2014 a field you send replaces its current value wholesale, so a list you pass must already include the entries you want to keep. Optional asset lists you omit entirely are left untouched on the ad. Status-only changes need neither --format nor content flags."
+      },
+      args: { ...customerIdArg, ...fileArg, ...adContentArgs, status: { type: "string" } },
       run: async ({ args }) => {
         const customerId = requireCustomerId(args);
         const file = loadJsonFileArg(args.file);
-        await stageUpdate(
-          "google.ad.update",
-          customerId,
-          requireTarget(args, "ad"),
-          mergePayload(file, { status: args.status })
-        );
+        const format = args.format;
+        if (!format) {
+          assertNoContentFlags(args);
+        }
+        const payload = mergePayload(file, {
+          status: args.status,
+          ...format ? { content: adContentFromFlags(args, format, file.content) } : {}
+        });
+        await stageUpdate("google.ad.update", customerId, requireTarget(args, "ad"), payload, [
+          ...payload.content !== void 0 ? [
+            "Each content field you sent replaces its current value wholesale at publish \u2014 re-check that every headline, description, final URL and asset you want to KEEP is in this payload, not just the ones you changed."
+          ] : []
+        ]);
       }
     }),
     pause: statusCommand2("google.ad.pause", "ad"),
@@ -10535,7 +11023,7 @@ async function stageOp(raw, hints) {
       chatId,
       op: preflight.data
     });
-    const allHints = [...batchNudge(response.data), ...hints ?? []];
+    const allHints = [...batchNudge(response.data), ...hints ?? [], ...adCopyHints(preflight.data)];
     writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleLinkedinError(err);
@@ -10562,7 +11050,8 @@ async function stageLinkedinOps(rawOps, hints) {
   try {
     const chatId = requireChatId();
     const response = await apiPost("/api/ads/linkedin/draft/stage-batch", { chatId, ops });
-    writeJsonEnvelope(hints && hints.length > 0 ? { ...response, hints } : response);
+    const allHints = [...hints ?? [], ...adCopyHints(ops)];
+    writeJsonEnvelope(allHints.length > 0 ? { ...response, hints: allHints } : response);
   } catch (err) {
     handleLinkedinError(err);
   }
@@ -13648,7 +14137,8 @@ async function stageOp2(raw) {
   try {
     const chatId = requireChatId();
     const response = await apiPost("/api/ads/meta/draft/stage", { chatId, op: preflight.data });
-    writeJsonEnvelope(response);
+    const copyHints = adCopyHints(preflight.data);
+    writeJsonEnvelope(copyHints.length > 0 ? { ...response, hints: copyHints } : response);
   } catch (err) {
     handleMetaError(err);
   }
@@ -17507,10 +17997,10 @@ function estSpeechS(text) {
 var OBSERVED_WPS_MIN = 1;
 var OBSERVED_WPS_MAX = 6;
 function estSpeechWindowS(text, startS, endS) {
-  const words = wordCount(text);
+  const words2 = wordCount(text);
   const window = (endS ?? 0) - (startS ?? 0);
-  if (words > 0 && window > 0.3) {
-    const wps = words / window;
+  if (words2 > 0 && window > 0.3) {
+    const wps = words2 / window;
     if (wps >= OBSERVED_WPS_MIN && wps <= OBSERVED_WPS_MAX) return window;
   }
   return estSpeechS(text);
@@ -18362,10 +18852,10 @@ function scrubFloatSentences(text, floatDescs) {
   if (floatDescs.length === 0 || !text) return text;
   const tokenSets = floatDescs.map((d) => new Set(floatTokens(d)));
   const kept = text.split(/(?<=[.!?])\s+/).filter((sentence) => {
-    const words = new Set(floatTokens(sentence));
+    const words2 = new Set(floatTokens(sentence));
     return !tokenSets.some((ts) => {
       let hits = 0;
-      for (const w of words) if (ts.has(w)) hits++;
+      for (const w of words2) if (ts.has(w)) hits++;
       return hits >= 2;
     });
   }).join(" ").trim();
@@ -19095,10 +19585,10 @@ function isOnCameraSpeaker(speaker, casts, cameraOn) {
   if (NARRATOR_SPEAKERS.has(speaker.toLowerCase())) return false;
   return casts.has(speaker);
 }
-function makePresenterPresent(slots, canonical, opts = {}) {
+function makePresenterPresent(slots, canonical2, opts = {}) {
   const personSlots = slots.filter((s) => s.type.toLowerCase() === "person");
   const bySpeaker = /* @__PURE__ */ new Map();
-  for (const slot of personSlots) if (slot.castId) bySpeaker.set(canonical(slot.castId), slot.presence);
+  for (const slot of personSlots) if (slot.castId) bySpeaker.set(canonical2(slot.castId), slot.presence);
   const solePerson = !opts.strict && personSlots.length === 1 ? personSlots[0].presence : null;
   return (speaker, sceneIndex) => {
     const presence = bySpeaker.get(speaker) ?? solePerson;
@@ -19130,17 +19620,17 @@ function joinDialogueTexts(texts) {
     }
     const prevWords = prev.split(/\s+/).filter(Boolean);
     const nextWords = text.split(/\s+/).filter(Boolean);
-    let overlap = 0;
+    let overlap2 = 0;
     const maxK = Math.min(JOIN_DEDUP_MAX_WORDS, prevWords.length, nextWords.length);
     for (let k = maxK; k >= 1; k--) {
       const tail = prevWords.slice(-k).map(joinKey).join(" ");
       const head = nextWords.slice(0, k).map(joinKey).join(" ");
       if (tail && tail === head) {
-        overlap = k;
+        overlap2 = k;
         break;
       }
     }
-    const rest = nextWords.slice(overlap).join(" ");
+    const rest = nextWords.slice(overlap2).join(" ");
     if (rest) out.push(rest);
   }
   return out.join(" ");
@@ -19158,13 +19648,13 @@ function collapseVoiceover(blueprint) {
   const presenter = [...presenters][0];
   return (speaker) => NARRATOR_SPEAKERS.has(speaker.toLowerCase()) ? presenter : speaker;
 }
-function multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict) {
+function multiSpeakerScenes(blueprint, casts, cameraOn, canonical2, presentStrict) {
   const multiSpeaker = /* @__PURE__ */ new Set();
   blueprint.scenes.forEach((scene, i) => {
     const onCamAll = new Set(
       (scene.dialogue ?? []).map((l) => l.speaker ?? "voiceover").filter((sp) => isOnCameraSpeaker(sp, casts, cameraOn))
     );
-    const onCamPresent = [...onCamAll].filter((sp) => presentStrict(canonical(sp), i));
+    const onCamPresent = [...onCamAll].filter((sp) => presentStrict(canonical2(sp), i));
     const effective = onCamPresent.length > 0 ? new Set(onCamPresent) : onCamAll;
     if (effective.size >= 2) multiSpeaker.add(i);
   });
@@ -19195,14 +19685,14 @@ function dialogueLines(blueprint, ctx) {
     });
   }).sort((a, b) => a.start - b.start);
 }
-function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict) {
+function buildPhrases(blueprint, canonical2, compositeScenes, presenterPresent, presentStrict) {
   const casts = castIdSet(blueprint);
   const cameraOn = onCameraDialogue(blueprint);
-  const multiSpeaker = multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict);
+  const multiSpeaker = multiSpeakerScenes(blueprint, casts, cameraOn, canonical2, presentStrict);
   const lines = dialogueLines(blueprint, {
     compositeScenes,
     multiSpeaker,
-    canonical,
+    canonical: canonical2,
     casts,
     cameraOn,
     presenterPresent
@@ -19251,12 +19741,12 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
   flush();
   return phrases;
 }
-function makeVoiceFactory(blueprint, canonical, nodes) {
+function makeVoiceFactory(blueprint, canonical2, nodes) {
   const bySpeaker = /* @__PURE__ */ new Map();
   const describe = (speaker) => {
     for (const scene of blueprint.scenes)
       for (const line of scene.dialogue ?? [])
-        if (canonical(line.speaker ?? "voiceover") === speaker && line.voice_description) return line.voice_description;
+        if (canonical2(line.speaker ?? "voiceover") === speaker && line.voice_description) return line.voice_description;
     const cast = blueprint.global?.cast?.find((c) => c.id === speaker);
     return cast?.description ?? blueprint.global?.voiceover?.voice_description ?? `${speaker} voice`;
   };
@@ -19443,15 +19933,15 @@ function emitPhraseTts(phrase, voiceNode, idx, used, clock, nodes, out, language
     speaker: phrase.speaker
   });
 }
-function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical, ensureVoiceNode, usedVoIds, nodes, out) {
+function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical2, ensureVoiceNode, usedVoIds, nodes, out) {
   const present2 = slotsForScene(env.slots, i);
   const onCam = (scene.dialogue ?? []).filter(
     (l) => Boolean(l.line?.trim()) && isOnCameraSpeaker(l.speaker ?? "voiceover", env.casts, env.cameraOn)
   );
-  const distinctSpeakers = new Set(onCam.map((l) => canonical(l.speaker ?? "voiceover")));
+  const distinctSpeakers = new Set(onCam.map((l) => canonical2(l.speaker ?? "voiceover")));
   let nativeTurn;
   if (onCam.length > 0 && distinctSpeakers.size === 1) {
-    const speaker = canonical(onCam[0]?.speaker ?? "voiceover");
+    const speaker = canonical2(onCam[0]?.speaker ?? "voiceover");
     const voiceNode = ensureVoiceNode(speaker);
     const start = onCam[0]?.start_s ?? scene.start_s ?? 0;
     const end = onCam[onCam.length - 1]?.end_s ?? scene.end_s ?? start;
@@ -19496,7 +19986,7 @@ function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical, en
       onCam,
       scene,
       i,
-      canonical,
+      canonical2,
       ensureVoiceNode,
       usedVoIds,
       env.clock,
@@ -19506,10 +19996,10 @@ function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical, en
     );
   }
 }
-function emitCompositeMultiSpeakerVoice(onCam, scene, i, canonical, ensureVoiceNode, usedVoIds, clock, nodes, out, languageCode) {
+function emitCompositeMultiSpeakerVoice(onCam, scene, i, canonical2, ensureVoiceNode, usedVoIds, clock, nodes, out, languageCode) {
   const bySpeaker = /* @__PURE__ */ new Map();
   for (const l of onCam) {
-    const speaker = canonical(l.speaker ?? "voiceover");
+    const speaker = canonical2(l.speaker ?? "voiceover");
     const text = l.line.trim();
     const start = l.start_s ?? scene.start_s ?? 0;
     const end = l.end_s ?? start + estSpeechS(text);
@@ -19662,8 +20152,8 @@ function buildTimeline(blueprint, slots, opts, nodes) {
       if (layeredComposition(s, uiRouted.has(i))) compositeScenes.add(i);
     });
   }
-  const canonical = collapseVoiceover(blueprint);
-  const ensureVoiceNode = makeVoiceFactory(blueprint, canonical, nodes);
+  const canonical2 = collapseVoiceover(blueprint);
+  const ensureVoiceNode = makeVoiceFactory(blueprint, canonical2, nodes);
   const aspect = resolveAspect(blueprint.source?.aspect_ratio, opts.aspect, genAspectsFor(opts.videoModel));
   const env = {
     blueprint,
@@ -19690,9 +20180,9 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     nativeSegments: [],
     sceneSlice: /* @__PURE__ */ new Map()
   };
-  const presenterPresent = makePresenterPresent(slots, canonical);
-  const presentStrict = makePresenterPresent(slots, canonical, { strict: true });
-  const phrases = buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict);
+  const presenterPresent = makePresenterPresent(slots, canonical2);
+  const presentStrict = makePresenterPresent(slots, canonical2, { strict: true });
+  const phrases = buildPhrases(blueprint, canonical2, compositeScenes, presenterPresent, presentStrict);
   const usedVoIds = /* @__PURE__ */ new Set();
   const claimed = /* @__PURE__ */ new Set();
   phrases.forEach((phrase, k) => {
@@ -19716,7 +20206,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
         i,
         i === lastIndex,
         env,
-        canonical,
+        canonical2,
         ensureVoiceNode,
         usedVoIds,
         nodes,
@@ -28521,6 +29011,24 @@ var BUZZWORDS = [
   "drive results",
   "harness the power"
 ];
+var COPY_TELL_GATES = {
+  "chat-artifact": { minCount: 1, severity: "warn" },
+  "rhetorical-opener": { minCount: 2, severity: "warn" },
+  "negation-pivot": { minCount: 2, severity: "warn" },
+  "vague-attribution": { minCount: 2, severity: "warn" },
+  "participle-tail": { minCount: 2, severity: "advisory" },
+  "copula-avoidance": { minCount: 2, severity: "advisory" },
+  "authority-trope": { minCount: 2, severity: "advisory" },
+  signposting: { minCount: 2, severity: "advisory" },
+  "hollow-conclusion": { minCount: 2, severity: "advisory" },
+  "filler-phrase": { minCount: 2, severity: "advisory" },
+  "aphorism-formula": { minCount: 2, severity: "advisory" },
+  "false-range": { minCount: 2, severity: "advisory" },
+  "staccato-drama": { minCount: 2, severity: "advisory" },
+  "title-case-heading": { minCount: 2, severity: "advisory" },
+  "inline-header-list": { minCount: 3, severity: "advisory" },
+  emoji: { minCount: 3, severity: "advisory" }
+};
 var AUTONOMY_CLAIMS = [
   "fully autonomous",
   "completely autonomous",
@@ -28678,6 +29186,86 @@ var RULE_META = {
     severity: "warn",
     note: "Dense em-dashes are an AI cadence tell (and brand copy bans them). Recast with commas, colons, or full stops."
   },
+  "chat-artifact": {
+    family: "copy",
+    severity: "warn",
+    note: "Chatbot framing ('Here is an overview\u2026', 'av\xEDsame si') leaked into the page. Delete it and state the claim directly."
+  },
+  "rhetorical-opener": {
+    family: "copy",
+    severity: "warn",
+    note: "Fake-candid openers ('Honestly?', 'La verdad es que') manufacture intimacy before an ordinary claim. Just say the thing."
+  },
+  "negation-pivot": {
+    family: "copy",
+    severity: "warn",
+    note: "'It's not just X, it's Y' / 'no se trata solo de' is now a louder AI tell than any single word. Cut the setup, keep the claim."
+  },
+  "vague-attribution": {
+    family: "copy",
+    severity: "warn",
+    note: "'Experts agree' / 'los estudios demuestran' attributes to nobody. Name the source and the year, or drop the claim."
+  },
+  "participle-tail": {
+    family: "copy",
+    severity: "advisory",
+    note: "Participles hung off a comma (', ensuring\u2026', ', permitiendo\u2026') fake depth. End the sentence, or make it a real clause."
+  },
+  "copula-avoidance": {
+    family: "copy",
+    severity: "advisory",
+    note: "'serves as' / 'cuenta con' dodges plain 'is' and 'has'. Use the simple verb \u2014 it reads as confidence, not flatness."
+  },
+  "authority-trope": {
+    family: "copy",
+    severity: "advisory",
+    note: "'At its core' / 'en el fondo' pretends to reach a deeper truth before restating an ordinary point. Make the point once."
+  },
+  signposting: {
+    family: "copy",
+    severity: "advisory",
+    note: "Announcing the writing ('Let's dive in', 'vamos a ver') instead of doing it. Delete the announcement, keep the content."
+  },
+  "hollow-conclusion": {
+    family: "copy",
+    severity: "advisory",
+    note: "'The future looks bright' / 'las posibilidades son infinitas' asserts nothing. End on a concrete next step or a number."
+  },
+  "filler-phrase": {
+    family: "copy",
+    severity: "advisory",
+    note: "Filler ('in order to', 'cabe destacar que') costs words and says nothing. Cut to the verb."
+  },
+  "aphorism-formula": {
+    family: "copy",
+    severity: "advisory",
+    note: "'X is the currency of Y' sounds profound without adding precision. Replace it with the concrete claim it gestures at."
+  },
+  "false-range": {
+    family: "copy",
+    severity: "advisory",
+    note: "'From onboarding to retention' pairs ends that aren't on a scale. List what you actually cover."
+  },
+  "staccato-drama": {
+    family: "copy",
+    severity: "advisory",
+    note: "A run of very short sentences manufactures drama. One clipped line lands; three in a row read as engineered."
+  },
+  "title-case-heading": {
+    family: "copy",
+    severity: "advisory",
+    note: "Title Case headings are an AI tell \u2014 and in Spanish the convention doesn't exist at all. Use sentence case."
+  },
+  "inline-header-list": {
+    family: "copy",
+    severity: "advisory",
+    note: "'**Speed:** it is fast' bullets are AI list shape. Write the sentence, or let the bullet carry the content directly."
+  },
+  emoji: {
+    family: "copy",
+    severity: "advisory",
+    note: "Emoji-decorated copy is a chatbot habit. Let the words and the layout carry the emphasis."
+  },
   "dark-glow": {
     family: "borders_depth",
     severity: "warn",
@@ -28880,6 +29468,14 @@ function includesPhraseAtWordStart(haystack, phrase) {
 function stripHtmlToText(html) {
   return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ");
 }
+function stripHtmlPreservingHeadings(html) {
+  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(
+    /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi,
+    (_all, _lvl, inner) => `
+## ${String(inner).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim()}
+`
+  ).replace(/<\/(?:p|div|section|li|tr|br)>|<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n");
+}
 function blankAstroFrontmatter(text) {
   if (!text.startsWith("---")) return text;
   const lines = text.split("\n");
@@ -29064,6 +29660,23 @@ var ANALYZERS = [
       return [{ id: "aphoristic-cadence", snippet: `${count} aphoristic constructions: "${firstSample}"`, file }];
     }
   },
+  // Shared AI copy tells (engine/copy-tells) — the Wikipedia "Signs of AI
+  // writing" set, English and Spanish. Page-scope: every gate here is a count
+  // threshold, and a landing is always split across small components, so
+  // measuring per file would dilute a page-wide habit into nothing.
+  {
+    scope: "page",
+    run: (text, file) => {
+      const body = stripHtmlPreservingHeadings(text);
+      const out = [];
+      for (const tell of detectCopyTells(body)) {
+        const gate = COPY_TELL_GATES[tell.id];
+        if (!gate || tell.count < gate.minCount) continue;
+        out.push({ id: tell.id, snippet: `${tell.count}\xD7 \u2014 "${tell.sample}"`, file });
+      }
+      return out;
+    }
+  },
   // Gradient text in authored CSS. A rule block spans lines, so this scans a
   // ±6-line window around each `background-clip: text` instead of one line
   // (the Tailwind class form stays a line matcher above).
@@ -29494,6 +30107,20 @@ function parseScope(raw) {
 function actingUserId() {
   return getEnv().BAKER_ACTING_USER_ID;
 }
+function customEntry(server) {
+  const failed = server.health && !server.health.ok;
+  const problem = server.health?.message ?? "This server's address is not serving tools.";
+  return {
+    name: server.name,
+    scope: server.scope,
+    enabled: server.enabled,
+    ...failed && !server.health?.transient ? { usable: false, problem } : {},
+    ...failed && server.health?.transient ? { lastCheck: "failed", problem } : {},
+    ...failed && server.health?.suggestedUrl ? { suggestedAddress: server.health.suggestedUrl } : {}
+  };
+}
+var BROKEN_SERVER_HINT = "A server marked usable=false will NOT answer: its tools are absent from this turn. Say plainly that the tool is not working and relay `problem`; never claim its tools are loading, coming next message, or temporarily unavailable. Fixing it needs a person: the user updates its address in the dashboard (Brain \u2192 Integrations \u2192 MCPs). If `suggestedAddress` is present, that is the address to use.";
+var LAST_CHECK_FAILED_HINT = "A server with lastCheck=failed was unreachable or erroring when it was last checked \u2014 that may already have passed, and its tools ARE loaded this turn. Try the tool; if it works, say nothing about the check. If it fails, report `problem` as what happened rather than guessing.";
 function parseHeaders(raw) {
   const list = raw === void 0 ? [] : Array.isArray(raw) ? raw : [raw];
   const headers = {};
@@ -29540,8 +30167,14 @@ A tool the user names that is NOT listed here is simply not connected yet.`
         ...c.accountLabel ? { account: c.accountLabel } : {},
         ...c.readOnly ? { readOnly: true } : {}
       }));
-      const custom = data.custom.map((s) => ({ name: s.name, scope: s.scope, enabled: s.enabled }));
+      const custom = data.custom.map(customEntry);
       const hints = [];
+      if (data.custom.some((s) => s.health && !s.health.ok && !s.health.transient)) {
+        hints.push(BROKEN_SERVER_HINT);
+      }
+      if (data.custom.some((s) => s.health && !s.health.ok && s.health.transient)) {
+        hints.push(LAST_CHECK_FAILED_HINT);
+      }
       if (data.managedDisabled) {
         hints.push("Managed integrations are disabled for this company \u2014 only custom MCP servers load.");
       }
@@ -29577,7 +30210,15 @@ var listCommand13 = defineCommand139({
         "/api/mcp/custom",
         user ? { actingUserId: user } : void 0
       );
-      writeJson({ ok: true, data: data.servers });
+      writeJson({
+        ok: true,
+        // Detail view: the full row (address included) plus the usability verdict.
+        // `health` itself is folded into `usable`/`problem` by `customEntry`.
+        data: data.servers.map((server) => ({ ...server, health: void 0, ...customEntry(server) })),
+        ...data.servers.some((s) => s.health && !s.health.ok) ? {
+          hints: data.servers.some((s) => s.health && !s.health.ok && !s.health.transient) ? [BROKEN_SERVER_HINT] : [LAST_CHECK_FAILED_HINT]
+        } : {}
+      });
     } catch (err) {
       fail6(err);
     }
@@ -29588,7 +30229,11 @@ registerSchema({
   description: "Register a custom MCP server. Tools appear as mcp__<name>__* on the next message. URL must be HTTPS. Scope: company (default, all chats) | org (org admin key) | user (only the current sender).",
   args: {
     name: { type: "string", description: "Server name \u2192 tools appear as mcp__<name>__*", required: true },
-    url: { type: "string", description: "HTTPS MCP endpoint", required: true },
+    url: {
+      type: "string",
+      description: "Full HTTPS MCP endpoint (commonly ends in /mcp, not just the domain)",
+      required: true
+    },
     scope: { type: "string", description: "user | user_org | company | org (default company)", required: false },
     header: { type: "string", description: 'Auth header "Key: Value" (repeatable)', required: false }
   }
@@ -29607,7 +30252,11 @@ Examples:
   },
   args: {
     name: { type: "string", description: "Server name (mcp__<name>__*)", required: true },
-    url: { type: "string", description: "HTTPS MCP endpoint", required: true },
+    url: {
+      type: "string",
+      description: "Full HTTPS MCP endpoint (commonly ends in /mcp, not just the domain)",
+      required: true
+    },
     scope: { type: "string", description: "user | user_org | company | org (default company)", required: false },
     header: { type: "string", description: 'Auth header "Key: Value" (repeatable)', required: false }
   },
@@ -29623,7 +30272,14 @@ Examples:
         ...user ? { actingUserId: user } : {},
         ...headers ? { headers } : {}
       });
-      writeJson({ ok: true, data });
+      writeJson({
+        ok: true,
+        data,
+        hints: [
+          "The address must be the full MCP endpoint (commonly ending in /mcp), not just the domain \u2014 a domain on its own usually answers sign-in and then serves no tools.",
+          "The address is checked in the background. Run `baker mcp connected` on the next message to confirm it serves tools before promising the user anything."
+        ]
+      });
     } catch (err) {
       fail6(err);
     }