Add plain-English sales doc

docs/sales/instagram_dm_revenue_plan_plain_english.md

@@ -0,0 +1,190 @@
+# Instagram DM Revenue Plan (Plain English)
+
+**Inbox:** `@socialmediatorr`  
+**Time zone used in this document:** CET  
+**Purpose:** turn more DM interest into paid outcomes, without lowering trust
+
+---
+
+## The Short Version
+
+Most people who write to you are asking for one of a small set of things. The biggest one is the book.
+
+If we answer those repeat questions fast, clearly, and in the person’s language, you should get more sales and more booked calls from the same message volume.
+
+We can prove this safely by running a “draft only” test first: the new system writes the reply, but never sends it. We then compare it to what the current system actually sent.
+
+---
+
+## What We Measured (From Your Export)
+
+This is what was in the Instagram export we scanned. It is a count of patterns, not a money ledger.
+
+| Item | Count |
+|---|---:|
+| Total messages | 54,069 |
+| Messages you sent | 43,607 |
+| Messages people sent you | 10,462 |
+| Messages that look like a question or request | 2,715 |
+| Time window covered | 2024-10-20 → 2025-12-22 |
+
+---
+
+## The Main Business Signal
+
+People keep asking for the same thing. The biggest topic is the book.
+
+| Rank | What people ask for (simple wording) | Count |
+|---:|---|---:|
+| 1 | “Book” (often just one word) | 1,857 |
+| 2 | “What is this?” | 203 |
+| 3 | “Send the video” | 189 |
+| 4 | Other question | 118 |
+| 5 | “Can you help me?” | 74 |
+
+This is the split:
+
+```mermaid
+pie title Questions/Requests: Book vs Everything Else
+  "Book" : 1893
+  "Everything else" : 822
+```
+
+Why this matters: if a person writes “book”, they are already close to taking a next step. Slow or unclear replies at this moment lose money.
+
+---
+
+## When Replies Arrive (CET)
+
+Most inbound messages arrive in two time blocks. This is when fast replies matter most.
+
+| Time block (CET) | Messages from people |
+|---|---:|
+| 00:00–05:59 | 2,113 |
+| 06:00–11:59 | 1,274 |
+| 12:00–17:59 | 2,333 |
+| 18:00–23:59 | 4,742 |
+
+```mermaid
+pie title Messages From People by Time of Day (CET)
+  "00:00-05:59" : 2113
+  "06:00-11:59" : 1274
+  "12:00-17:59" : 2333
+  "18:00-23:59" : 4742
+```
+
+Practical meaning: if you can cover **12:00–17:59** and **18:00–23:59**, you will catch most of the “book” and “link” requests while they still care.
+
+---
+
+## Language Reality (What People Actually Write In)
+
+People mostly write in English and Spanish, with some French and a small amount of Catalan.
+
+Many messages are too short (one word, emoji, or “book”), so we do not try to guess the language for those.
+
+Rule we should follow:
+
+- Reply in the same language the person used in their last clear message.
+- If the message is too short to tell, keep the last known language in that thread.
+- If still unclear, ask one short question: “English or Spanish?” (or include French/Catalan if needed).
+
+---
+
+## What We Will Change (In Simple Terms)
+
+This is not “more messages”. It is better answers at the moments that matter.
+
+### 1) Fast answers for the Top 20 questions
+
+We already wrote 20 ready-made answers (English/Spanish/French/Catalan) for the most common questions.
+
+Result: fewer people asking twice, and fewer “where is it?” messages.
+
+### 2) A clean “book” path
+
+When someone says “book”, the system should:
+
+1) confirm what they want (book link or video first)  
+2) send the correct link  
+3) ask one short next question  
+
+Result: more people finish the step instead of stalling.
+
+### 3) A simple follow-up when people go silent
+
+If there is no reply after 24–48 hours, send one short follow-up (not a long paragraph).
+
+Result: you recover sales that would otherwise die in silence.
+
+---
+
+## What We Will Not Automate
+
+This protects trust and reduces risk.
+
+- Anything that looks like crisis or self-harm.
+- Anything that needs clinical nuance in DMs.
+- Anything involving sensitive personal data.
+- Anything that turns into an argument.
+
+In these cases, the system should stop and ask you to take over (or move it to a call).
+
+---
+
+## How We Prove It Without Replying to Real Clients
+
+We run a “draft only” test first.
+
+The new system writes a draft reply, stores it, and does not send it. Then we compare it to what the current system actually sent.
+
+```mermaid
+flowchart LR
+  A1["A new DM arrives"] --> A2["Current system sends its reply (unchanged)"]
+  A1 --> B1["New system writes a draft reply (not sent)"]
+  A2 --> C1["We save the real reply"]
+  B1 --> C2["We save the draft reply"]
+  C1 --> D1["We compare both in a table"]
+  C2 --> D1
+```
+
+The comparison table can include:
+
+- time (CET)
+- message topic (book / link / price / video / other)
+- the reply the person actually got
+- the draft reply we would have sent
+- a simple quality score (clear? short? correct language? correct next step?)
+
+---
+
+## The Money Question (A Clean Way to Estimate It)
+
+We should not guess revenue from message keywords alone. The right way is:
+
+1) tag links we send (so we can see if they were used)  
+2) match payments/bookings back to the DM thread (so we can see what actually worked)  
+
+Until we wire that up, here is a conservative estimate framework you can fill in:
+
+| Scenario | Extra people who buy/book per month | Average value per sale/call (€) | Extra revenue per month (€) |
+|---|---:|---:|---:|
+| Conservative | 10 |  |  |
+| Expected | 30 |  |  |
+| Strong | 70 |  |  |
+
+How to fill it in:
+
+- “Extra people who buy/book” should come from the “draft only” test + a small controlled rollout.
+- “Average value” depends on whether the outcome is mainly book sales, calls, or a mix.
+
+---
+
+## What I Need From You (To Finish This Properly)
+
+- the exact book link you want to use
+- the “video link” you want to use
+- the pricing you want quoted in DMs (if any)
+- whether you want “book” to go to book-first, video-first, or a choice
+- what you consider a “win” (book sale, call booked, paid program, etc.)
+

tools/verify_mermaid.mjs

@@ -61,7 +61,7 @@ function detectDiagramType(code) {
 
 async function main() {
   const args = process.argv.slice(2);
-  const roots = args.length ? args : ["reports"];
+  const roots = args.length ? args : ["reports", "docs"];
 
   let ok = true;
   let total = 0;