From 1dbaead397f50444e3d86ee433578c81f3abdc9d Mon Sep 17 00:00:00 2001
From: Kush <kshah@bandwidth.com>
Date: Thu, 20 Aug 2026 14:47:28 -0400
Subject: [PATCH 1/2] copy: replace "Blocker" with "No direct equivalent"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Blocker" reads to a developer as "requires some dev work," but to a
non-technical reader it lands as a red flag about Bandwidth's capabilities.
The tier means something narrower and more neutral: this Twilio verb has no
BXML counterpart, so it needs a redesign rather than a translation.

The tool already had softer vocabulary for exactly this concept — the
playground pill says "No equivalent" and its summary line says "have no
direct equivalent" — so this aligns the remaining labels with wording the
UI was already using.

Display strings only. Internal identifiers (the Bucket union, counts.blocker,
the blockers array, coverage.json's blockers key) are untouched, so nothing
parsing the machine-readable output breaks.

- Playground: tile label and section heading
- Compatibility Check report: section heading, score-formula text
- BXML Generator report: section heading, document summary line
- README, web/README: the works-as-is / heads-up / blocker triad
- Section emoji 🛑 -> 🔧, so the icon de-escalates with the word
---
 README.md                         | 4 ++--
 examples/full-pv-app/server.js    | 2 +-
 src/bxml-generator/report.ts      | 4 ++--
 src/compatibility-check/report.ts | 4 ++--
 web/README.md                     | 2 +-
 web/app.ts                        | 4 ++--
 6 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index cdc651d..dfeca99 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ Same concepts, different words — like British vs. American English. Roughly 80
 
 **What it does:** Scans a customer's existing codebase and checks how their TwiML and Twilio SDK usage maps to Bandwidth's BXML.
 
-**Outcome:** Size the migration effort and identify blockers **without writing a line of code**. You get a migration-complexity score and a per-feature *works-as-is / heads-up / blocker* breakdown.
+**Outcome:** Size the migration effort and identify what needs a redesign **without writing a line of code**. You get a migration-complexity score and a per-feature *works-as-is / heads-up / no direct equivalent* breakdown.
 
 ```bash
 npm install
@@ -56,7 +56,7 @@ npm run bxml-generator -- <in-dir> <out-dir>     # writes out/bxml/*, out/MIGRAT
 
 ## Try the Compatibility Check in your browser — no command needed
 
-The **Migration Compatibility Check** is a single, self-contained HTML file a sales engineer can double-click and present to a prospect. Paste a customer's TwiML (or pick a curated example) and it shows — live — a migration-complexity score, a *works-as-is / heads-up / blocker* verdict, the translated BXML, and a forwardable report.
+The **Migration Compatibility Check** is a single, self-contained HTML file a sales engineer can double-click and present to a prospect. Paste a customer's TwiML (or pick a curated example) and it shows — live — a migration-complexity score, a *works-as-is / heads-up / no direct equivalent* verdict, the translated BXML, and a forwardable report.
 
 ```bash
 npm install
diff --git a/examples/full-pv-app/server.js b/examples/full-pv-app/server.js
index 0ec5aec..a6ec1c6 100644
--- a/examples/full-pv-app/server.js
+++ b/examples/full-pv-app/server.js
@@ -1,7 +1,7 @@
 // "Full PV" demo — a Twilio voice app that exercises EVERYTHING Bandwidth
 // Programmable Voice supports (verified against dev.bandwidth.com via Context7).
 // Deliberately stays inside the supported surface, so the whole app translates
-// clean through the adapter: no blockers, only expected heads-up notes.
+// clean through the adapter: nothing lacking a direct equivalent, only expected heads-up notes.
 //
 // Supported BW PV surface covered here (Twilio verb -> BXML verb):
 //   Say (+SSML, voice)        -> SpeakSentence
diff --git a/src/bxml-generator/report.ts b/src/bxml-generator/report.ts
index 1c10725..393e83b 100644
--- a/src/bxml-generator/report.ts
+++ b/src/bxml-generator/report.ts
@@ -22,7 +22,7 @@ export function renderMigration(result: GenerateResult): string {
     "# Twilio → Bandwidth migration — generated BXML",
     "",
     `Translated **${docs.length}** TwiML document${docs.length === 1 ? "" : "s"} to native BXML` +
-      ` (${clean} clean, ${withBlockers} with blockers).`,
+      ` (${clean} clean, ${withBlockers} with verbs that have no direct equivalent).`,
     "",
     "Generated BXML is written under `bxml/`. Action/redirect URLs are preserved",
     "exactly as your Twilio app used them — point those endpoints at your migrated",
@@ -37,7 +37,7 @@ export function renderMigration(result: GenerateResult): string {
     if (errors.length === 0 && warnings.length === 0)
       lines.push("✅ Translated cleanly.", "");
     if (errors.length) {
-      lines.push("### 🛑 Blockers — need a human", "");
+      lines.push("### 🔧 No direct equivalent — needs a human", "");
       for (const f of errors)
         lines.push(`- **${f.verb}** — ${f.message}${f.docsUrl ? ` ([docs](${f.docsUrl}))` : ""}`);
       lines.push("");
diff --git a/src/compatibility-check/report.ts b/src/compatibility-check/report.ts
index e805d36..397d1dd 100644
--- a/src/compatibility-check/report.ts
+++ b/src/compatibility-check/report.ts
@@ -13,7 +13,7 @@ export function renderReport(analyses: FileAnalysis[]): string {
   const lines: string[] = [
     "# Twilio → Bandwidth migration — Compatibility Check",
     "",
-    `**Migration complexity: ${score}/10** (1 + warnings + 3×blockers, capped at 10)`,
+    `**Migration complexity: ${score}/10** (1 + heads-up + 3× no-equivalent, capped at 10)`,
     "",
     `Files with Twilio voice usage: ${relevant.length}`,
     "",
@@ -25,7 +25,7 @@ export function renderReport(analyses: FileAnalysis[]): string {
     if (errors.length === 0 && warnings.length === 0)
       lines.push("✅ Runs through the translator as-is.", "");
     if (errors.length) {
-      lines.push("### 🛑 Blockers", "");
+      lines.push("### 🔧 No direct equivalent", "");
       for (const f of errors)
         lines.push(`- **${f.verb}** — ${f.message}${f.docsUrl ? ` ([docs](${f.docsUrl}))` : ""}`);
       lines.push("");
diff --git a/web/README.md b/web/README.md
index 4cdcaff..5b1694a 100644
--- a/web/README.md
+++ b/web/README.md
@@ -1,6 +1,6 @@
 # Migration Compatibility Check playground
 
-A single, self-contained HTML file a sales engineer can **double-click** and present to a prospect. Paste a customer's TwiML (or pick a curated example) and it shows — live — how much of that Twilio voice app runs on Bandwidth unchanged: a works-as-is / heads-up / blocker verdict, a migration-complexity score, the translated BXML, and a forwardable report.
+A single, self-contained HTML file a sales engineer can **double-click** and present to a prospect. Paste a customer's TwiML (or pick a curated example) and it shows — live — how much of that Twilio voice app runs on Bandwidth unchanged: a works-as-is / heads-up / no direct equivalent verdict, a migration-complexity score, the translated BXML, and a forwardable report.
 
 No server, no install, no network. It works offline on a plane.
 
diff --git a/web/app.ts b/web/app.ts
index 2d4eb46..8c1784c 100644
--- a/web/app.ts
+++ b/web/app.ts
@@ -79,7 +79,7 @@ function renderVerdict(v: PreflightView): string {
         <div class="pf-tiles">
           ${tile("clean", v.counts.clean, "Clean")}
           ${tile("warn", v.counts.headsUp, "Heads-up")}
-          ${tile("block", v.counts.blocker, "Blocker")}
+          ${tile("block", v.counts.blocker, "No direct equivalent")}
         </div>
       </div>
     </section>`;
@@ -106,7 +106,7 @@ function tile(kind: "clean" | "warn" | "block", n: number, label: string): strin
 // ---- Findings ----
 function renderFindings(v: PreflightView): string {
   const groups: Array<[string, "block" | "warn" | "clean", VerbCard[]]> = [
-    ["Blockers", "block", v.blockers],
+    ["No direct equivalent", "block", v.blockers],
     ["Heads-up", "warn", v.headsUp],
     ["Clean", "clean", v.clean],
   ];

From 70f4f7e4590a44dfc1206a6c3220fdff0933dbc3 Mon Sep 17 00:00:00 2001
From: Kush <kshah@bandwidth.com>
Date: Thu, 20 Aug 2026 14:59:59 -0400
Subject: [PATCH 2/2] =?UTF-8?q?copy:=20keep=20the=20=F0=9F=9B=91=20emoji?=
 =?UTF-8?q?=20on=20the=20no-direct-equivalent=20section?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The word was the problem, not the icon. "No direct equivalent" already
reframes the tier as a difference rather than a verdict on Bandwidth, and
a loud stop sign still matches how the rest of the tool signals "this one
needs a human." Reverts the 🔧 swap from the previous commit.
---
 src/bxml-generator/report.ts      | 2 +-
 src/compatibility-check/report.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/bxml-generator/report.ts b/src/bxml-generator/report.ts
index 393e83b..faecf30 100644
--- a/src/bxml-generator/report.ts
+++ b/src/bxml-generator/report.ts
@@ -37,7 +37,7 @@ export function renderMigration(result: GenerateResult): string {
     if (errors.length === 0 && warnings.length === 0)
       lines.push("✅ Translated cleanly.", "");
     if (errors.length) {
-      lines.push("### 🔧 No direct equivalent — needs a human", "");
+      lines.push("### 🛑 No direct equivalent — needs a human", "");
       for (const f of errors)
         lines.push(`- **${f.verb}** — ${f.message}${f.docsUrl ? ` ([docs](${f.docsUrl}))` : ""}`);
       lines.push("");
diff --git a/src/compatibility-check/report.ts b/src/compatibility-check/report.ts
index 397d1dd..a48593b 100644
--- a/src/compatibility-check/report.ts
+++ b/src/compatibility-check/report.ts
@@ -25,7 +25,7 @@ export function renderReport(analyses: FileAnalysis[]): string {
     if (errors.length === 0 && warnings.length === 0)
       lines.push("✅ Runs through the translator as-is.", "");
     if (errors.length) {
-      lines.push("### 🔧 No direct equivalent", "");
+      lines.push("### 🛑 No direct equivalent", "");
       for (const f of errors)
         lines.push(`- **${f.verb}** — ${f.message}${f.docsUrl ? ` ([docs](${f.docsUrl}))` : ""}`);
       lines.push("");