sizmo 0.4.0

package/INSTALL.md

@@ -0,0 +1,127 @@
+# Installation
+
+> Not affiliated with, endorsed by, or supported by HighLevel.
+
+## Requirements
+
+- Node.js 20 or later (`node --version` to check)
+- A GoHighLevel Private Integration Token (PIT) with at minimum `contacts.read`, `conversations.read`, `opportunities.read`, `calendars.read`, `invoices.read`, and `payments.read` scopes
+
+## Step 1 — clone and link
+
+```sh
+git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli
+cd sizmo-ghl-cli
+bash install.sh
+```
+
+`install.sh` does exactly three things (verified against the actual script):
+
+1. Creates `~/.local/bin` if it does not exist
+2. Symlinks `<repo>/bin/sizmo.mjs` → `~/.local/bin/sizmo`
+3. `chmod +x`s the bin entry point
+4. Warns if `~/.local/bin` is not in `$PATH`
+
+If the PATH warning appears, add to your shell profile:
+
+```sh
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # zsh
+# or
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # bash
+source ~/.zshrc   # reload
+```
+
+Confirm the link works:
+
+```sh
+sizmo --version
+# 0.4.0
+```
+
+## Step 2 — get a PIT from GoHighLevel
+
+1. Open GoHighLevel → Settings → Integrations → Private Integrations
+2. Create a new integration — give it a name like "sizmo-read"
+3. Grant read-only scopes: `contacts.read`, `conversations.read`, `opportunities.read`, `calendars.read`, `invoices.read`, `payments.read`, `transactions.read`
+4. Copy the token (starts with `pit-`)
+
+Never store the PIT in a shell command or history. Always pass via stdin.
+
+## Step 3 — configure a profile
+
+```sh
+echo "pit-yourtoken..." | sizmo config set --profile myclient --loc YOUR_LOCATION_ID --pit-stdin
+```
+
+- `--profile` — a name for this credential set (e.g. the client's name)
+- `--loc` — your GoHighLevel Location ID (found in Settings > Business Profile)
+- `--pit-stdin` — reads the PIT from stdin; never from argv
+
+The profile is saved to `~/.config/sizmo/profiles.json` with permissions `0600`.
+
+## Step 4 — verify auth
+
+```sh
+sizmo auth status
+```
+
+Expected output:
+
+```
+auth source   profile
+location      your-location-id
+PIT           pit-…XXXX  (myclient)
+PIT age       day N of 90
+```
+
+Then do a live probe:
+
+```sh
+sizmo auth check
+```
+
+This makes one real API call (`GET /contacts/?limit=1`) to confirm the PIT is accepted for your location. You need a network connection and a valid PIT for this to pass.
+
+## Multi-client setup
+
+Add a second profile for each additional GoHighLevel location:
+
+```sh
+echo "pit-secondtoken..." | sizmo config set --profile client2 --loc LOC_B --pit-stdin
+sizmo config list         # see all profiles; * marks the default
+sizmo config use client2  # switch default
+```
+
+Pass `--profile <name>` to any command to target a specific client without switching the default.
+
+## Credential storage
+
+Profiles are stored in `~/.config/sizmo/profiles.json`. The file is created with `chmod 0600` — readable only by your user. PITs are stored in plaintext in that file; protect your home directory accordingly.
+
+To remove a profile:
+
+```sh
+sizmo config rm myclient
+```
+
+## PIT rotation
+
+PITs expire after 90 days. `sizmo auth status` shows the age — warnings appear at day 80, the expired-zone at day 90.
+
+To rotate:
+
+```sh
+echo "pit-newtoken..." | sizmo config set --profile myclient --pit-stdin --created $(date +%Y-%m-%d)
+```
+
+`--created` resets the age counter. If omitted, the current date is used automatically when setting a PIT.
+
+## Using environment variables instead of profiles
+
+```sh
+export GHL_PIT=pit-yourtoken...
+export GHL_LOCATION_ID=your-location-id
+sizmo brief
+```
+
+Environment variables take precedence over saved profiles.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sizmo / CJ Salamida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# sizmo
+
+**Unofficial read-only GoHighLevel CLI for coaches and consultants.**
+
+> Not affiliated with, endorsed by, or supported by HighLevel. This is an independent open-source tool.
+
+`sizmo` reads your GoHighLevel location — leads, bookings, pipeline, A/R, money leaks — from the terminal. It never writes, never charges, never sends. Every outward action stays human-triggered.
+
+## Install
+
+Requires Node.js 20+.
+
+**Option A — clone + install (puts `sizmo` on your PATH):**
+
+```sh
+git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli
+cd sizmo-ghl-cli
+bash install.sh
+```
+
+`install.sh` symlinks `bin/sizmo.mjs` into `~/.local/bin/sizmo`. Add `~/.local/bin` to `$PATH` if not already present (the script will warn you if needed).
+
+**Option B — run with no install, straight from GitHub:**
+
+```sh
+npx github:csalamida07-cyber/sizmo-ghl-cli brief
+```
+
+**Option C — clone + run directly:**
+
+```sh
+git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli && cd sizmo-ghl-cli
+node bin/sizmo.mjs brief
+```
+
+> `npx sizmo` (npm install) is coming once the package is published to npm.
+
+Then configure a profile:
+
+```sh
+echo "pit-yourtoken..." | sizmo config set --profile myclient --loc YOUR_LOCATION_ID --pit-stdin
+```
+
+PIT = Private Integration Token. Find it under GoHighLevel Settings > Integrations > Private Integrations. Never pass it as a command-line argument — always pipe it via stdin.
+
+Verify auth:
+
+```sh
+sizmo auth status
+sizmo auth check
+```
+
+## Commands
+
+Command list generated from `sizmo schema` (authoritative — pulled directly from the code):
+
+| Command | Summary | Key flags |
+|---------|---------|-----------|
+| `sizmo brief` | Morning brief — numbers + NEEDS YOU TODAY | `--days N` (default 7) |
+| `sizmo snapshot` | Monday card — 6 metrics, one screen | `--days N` (default 7) |
+| `sizmo triage` | Who is waiting on a reply, longest first | `--top N` (default 10), `--days N` (default 30) |
+| `sizmo pipeline` | Pipeline health — value by stage + stuck deal sweep | `--stuck-days N` (default 7), `--top N` (default 100) |
+| `sizmo noshow` | No-show recovery — who to re-book | `--days N` (default 30), `--top N` (default 15) |
+| `sizmo receivables` | A/R — who owes, how much, how old | `--top N` (default 20) |
+| `sizmo reconcile` | Money reconciliation — collected by source, flags, recurring | `--days N` (default 30), `--top N` (default 20) |
+| `sizmo booked-not-paid` | Sessions with no invoice or payment — the money leak | `--days N` (default 30), `--top N` (default 15) |
+| `sizmo focus` | One ranked to-do queue by money at stake | `--top N` (default 15), `--stuck-days N` (default 7) |
+| `sizmo segment` | Find contacts by criteria — tag, phone, age, etc. | `--tag X`, `--without-tag X`, `--no-tags`, `--created-days N`, `--has-phone`, `--no-phone`, `--top N` (default 20) |
+
+### Utility commands
+
+```sh
+sizmo schema            # machine-readable command tree (JSON)
+sizmo auth status       # show credential source, location, masked PIT, rotation age
+sizmo auth check        # probe live API to verify PIT scopes
+sizmo config list       # list all saved profiles
+sizmo config use <name> # switch default profile
+sizmo config set --profile <name> --loc <id> --pit-stdin
+sizmo config rm <name>  # remove a profile
+sizmo api /path         # raw GET escape hatch (--paginate --max-pages N)
+```
+
+### Global flags (work with every command)
+
+```
+--profile <name>   use a named credential profile
+--json             machine-readable output (stable JSON envelope)
+--fresh            bypass 60-second read cache — re-fetches live data
+--no-cache         alias for --fresh
+```
+
+## JSON envelope
+
+Every command supports `--json`. The envelope shape is stable:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "brief",
+  "location": "LOC_ID",
+  "data": { ... },
+  "degraded": false,
+  "warnings": [],
+  "cacheAgeMs": 0
+}
+```
+
+`degraded: true` means at least one data source was blocked (scope or auth). Read `warnings`. A blocked source is not zero — treat it as unknown.
+
+## Read-only + safety promise
+
+- **Never writes to GoHighLevel.** No contacts created, no messages sent, no invoices issued, no payments charged.
+- **Money is always human-triggered.** The CLI reads; humans approve every action that has a dollar attached.
+- **PIT never in argv.** Credentials are passed via stdin (`--pit-stdin`) or env var (`--pit-env VAR`). Never logged, never echoed raw.
+- **60-second read cache.** Repeated calls within 60s return cached data. `cacheAgeMs` in the envelope tells you how old. Use `--fresh` to bypass.
+
+## Honest limitations
+
+- **Rate-limit cap: 5 concurrent requests.** The pool is capped at 5 to avoid hammering the GHL API.
+- **Cache TTL: 60 seconds.** Stale data possible within that window. Use `--fresh` when you need live.
+- **No-show / booked-not-paid calendar truncation.** GHL's `/calendars/events` endpoint has no pagination cursor. If a calendar returns >= 100 events the result may be silently truncated. A `degraded: true` warning is emitted in that case.
+- **Pipeline currency.** GHL opportunity monetary values carry no currency field — they inherit pipeline config. The CLI renders them as-is; cross-currency totals are never summed.
+- **No workflow writes.** This tool has no workflow-authoring capability. Workflow creation stays in GoHighLevel's UI.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | OK |
+| 1 | API error |
+| 2 | Usage error (bad flag / unknown command) |
+| 3 | Auth error / no location resolved |
+| 4 | Not found |
+
+## Multi-client
+
+```sh
+sizmo config set --profile clientA --loc LOC_A --pit-stdin
+sizmo config set --profile clientB --loc LOC_B --pit-stdin
+sizmo brief --profile clientA
+sizmo brief --profile clientB
+```
+
+See `docs/how-to/multi-client.md` for full workflow.
+
+## License
+
+MIT. See LICENSE.
+
+---
+
+Built by Sizmo — productized GHL systems for coaches & consultants. Unofficial; not affiliated with HighLevel.

package/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: sizmo
+description: Use to read a GoHighLevel location's state — leads, bookings, who's waiting, pipeline, A/R, money-leaks — via the read-only CLI. Never writes; money is always human-triggered.
+---
+
+# Driving the GoHighLevel Read-Only CLI
+
+Read-only GoHighLevel ops. Every command takes `--json` (stable envelope: `{schemaVersion,command,location,data,degraded,warnings}`) and `--profile <name>` for multi-client. Run `sizmo schema` for the machine-readable command tree before composing.
+
+## Recipes (the jobs)
+- `sizmo brief` — the morning screen: numbers + prioritized "needs you today". Start here.
+- `sizmo snapshot [days]` — 6-metric card (leads/bookings/show-rate/collected/reply-rate/pipeline).
+- `sizmo triage --top N` — who's waiting on a reply, longest first.
+- `sizmo pipeline --stuck-days N` — value by stage + stuck-deal sweep.
+- `sizmo noshow --days N` — no-shows to re-book.
+- `sizmo receivables` — who owes, how old, how much.
+- `sizmo reconcile --days N` — money collected by source + flags.
+- `sizmo booked-not-paid --days N` — sessions with no invoice/payment (the money leak).
+- `sizmo segment --tag X --no-phone` — find contacts by criteria.
+
+## Auth
+`sizmo config set --profile <client> --loc <id> --pit-stdin` (paste PIT to stdin — never argv). `sizmo auth status` shows source + PIT age (rotate at 90d). `sizmo auth check` probes scopes.
+
+## Gotchas
+- READ-ONLY. The CLI never writes to GoHighLevel. To act (send, invoice, tag), the specialist agents draft; the human approves; money is always human-triggered.
+- `degraded:true` in the envelope ≠ zero — a source was blocked (scope/auth). Read `warnings`. Never treat a blocked read as "0".
+- Exit codes: 0 ok · 1 API · 2 usage · 3 auth/no-location · 4 not found. Branch on these.
+- No location resolved → exit 3. Pass `--profile` or set `GHL_LOCATION_ID`; there is no default location.
+
+---
+Built by Sizmo — productized GHL systems for coaches & consultants. Unofficial; not affiliated with HighLevel.

package/bin/sizmo.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../lib/cli.mjs';
+run(process.argv.slice(2)).then(code => process.exit(code ?? 0));

package/commands/booked-not-paid.mjs

@@ -0,0 +1,242 @@
+// commands/booked-not-paid.mjs — Money-leak detector: sessions × invoices × payments.
+// Trust-fix #1: LOC from ctx.cfg.loc.
+// Trust-fix #2 (critical): transactions paginate to completion — fixes false-accusation bug
+//   where single-page limit:100 missed paid contacts → now exhausts all pages.
+// READ-ONLY. Never messages, invoices, or charges.
+import { paginate } from '../lib/paginate.mjs';
+
+export const meta = {
+  name: 'booked-not-paid',
+  summary: 'Sessions with no invoice or payment — the money leak',
+  flags: [
+    { name: '--days', type: 'int', default: 30, desc: 'session lookback window' },
+    { name: '--top', type: 'int', default: 15, desc: 'max rows to show per bucket' },
+  ],
+  readOnly: true,
+};
+
+const SYM = { PHP: '₱', USD: '$', EUR: '€', GBP: '£' };
+const money = (n, c = 'PHP') => (SYM[c] || c + ' ') + Number(n || 0).toLocaleString('en-PH', { maximumFractionDigits: 0 });
+const UNPAID = new Set(['sent', 'overdue', 'partially_paid', 'partially paid', 'payment_processing', 'viewed', 'due']);
+// Must match reconcile.mjs SUCCESS set exactly — any status in this set means the contact paid.
+const SUCCESS = new Set(['succeeded', 'success', 'paid', 'completed', 'captured']);
+
+// I-2 truncation cap: GHL's /calendars/events has no pagination cursor.
+// If a calendar returns >= CAP events it is likely truncated (silently under-reports).
+// Full fix = date-window splitting; tracked as follow-up. Cheap mitigation: warn + degrade.
+const EVENTS_CAP = 100;
+
+export async function collect(args, ctx) {
+  const DAYS = args.days ?? 30;
+  const TOP = args.top ?? 15;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const START = NOW - DAYS * 86400000;
+  const PAY_LOOKBACK = START - 60 * 86400000;
+
+  // ── 1. CALENDARS: who had a session in the window ──
+  const cr = await ctx.http.get('/calendars/', { query: { locationId: LOC }, version: '2021-04-15' });
+  if (!cr.ok) {
+    ctx.out.warn(`can't see calendars → HTTP ${cr.code}`, { degraded: true });
+    return { location: LOC, days: DAYS, calendars: 0, contactsWithSessions: 0, neverBilled: [], billedUnpaid: [], billedUnpaidTotal: 0, currency: 'PHP', settled: 0, caveat: 'calendars blocked' };
+  }
+  const cals = cr.j.calendars || [];
+  const byContact = new Map();
+  let skippedCalendars = 0;
+  for (const cal of cals) {
+    const ev = await ctx.http.get('/calendars/events', {
+      query: { locationId: LOC, calendarId: cal.id, startTime: String(START), endTime: String(NOW) },
+      version: '2021-04-15',
+    });
+    if (!ev.ok) {
+      skippedCalendars++;
+      ctx.out.warn(`calendar "${cal.name || cal.id}" events unreadable (HTTP ${ev.code})`, { degraded: true });
+      continue;
+    }
+    const evList = ev.j.events || ev.j.appointments || [];
+    // I-2: truncation mitigation — no cursor available; warn if at cap
+    if (evList.length >= EVENTS_CAP) {
+      ctx.out.warn(`calendar "${cal.name || cal.id}" returned ${evList.length} events — may be truncated (no pagination cursor available); counts for this calendar may under-report`, { degraded: true });
+    }
+    for (const e of evList) {
+      const s = (e.appointmentStatus || e.status || '').toLowerCase();
+      if (['noshow', 'no-show', 'no_show', 'cancelled', 'canceled', 'invalid'].includes(s)) continue;
+      const t = Date.parse(e.startTime || e.startTimeISO || e.appointmentStartTime) || 0;
+      if (t > NOW) continue;
+      if (!e.contactId) continue;
+      const rec = byContact.get(e.contactId) ?? { name: e.title || e.contactName || '(unknown)', sessions: [] };
+      rec.sessions.push({ when: t, status: s === 'showed' ? 'showed' : 'unmarked', cal: cal.name });
+      byContact.set(e.contactId, rec);
+    }
+  }
+
+  if (!byContact.size) {
+    return {
+      location: LOC, days: DAYS, calendars: cals.length,
+      ...(skippedCalendars > 0 && { skippedCalendars }),
+      contactsWithSessions: 0, invoicesScanned: 0, neverBilled: [], billedUnpaid: [],
+      billedUnpaidTotal: 0, currency: 'PHP', settled: 0,
+      caveat: 'contact-level matching; payments lookback window+60d; prepaid clients older than that may flag falsely',
+    };
+  }
+
+  // ── 2. INVOICES: who got billed ──
+  const inv = [];
+  let invBlocked = null;
+  for await (const item of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/invoices/', {
+        query: { altId: LOC, altType: 'location', limit: 100, offset },
+      });
+      if (!r.ok) return { _err: r.code, invoices: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { invBlocked = `HTTP ${resp._err}`; return []; }
+      return resp.invoices || resp.data || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 500,
+    startCursor: 0,
+  })) {
+    inv.push(item);
+  }
+
+  const billing = new Map();
+  for (const i of inv) {
+    const cid = i.contactDetails?.id || i.contactDetails?._id || i.contactId;
+    if (!cid) continue;
+    const st = String(i.status || '').toLowerCase();
+    if (st === 'draft' || st === 'void' || st === 'cancelled' || st === 'canceled') continue;
+    const b = billing.get(cid) ?? { billed: false, due: 0, cur: (i.currency || 'PHP').toUpperCase() };
+    b.billed = true;
+    if (UNPAID.has(st)) {
+      const due = Number(i.total ?? i.amount ?? 0) - Number(i.amountPaid ?? i.totalPaid ?? 0);
+      if (due > 0.0001) b.due += due;
+    }
+    billing.set(cid, b);
+  }
+
+  // ── 3. PAYMENTS: paginate to completion (trust-fix #2 — the false-accusation fix) ──
+  const paidContacts = new Set();
+  let payBlocked = null;
+  for await (const t of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/payments/transactions', {
+        query: {
+          altId: LOC, altType: 'location', limit: 100, offset,
+          startAt: new Date(PAY_LOOKBACK).toISOString().slice(0, 10),
+        },
+      });
+      if (!r.ok) return { _err: r.code, data: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { payBlocked = `HTTP ${resp._err}`; return []; }
+      return resp.data || resp.transactions || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 500,
+    startCursor: 0,
+  })) {
+    if (!SUCCESS.has(String(t.status || '').toLowerCase())) continue;
+    const cid = t.contactId || t.contactDetails?.id;
+    if (cid) paidContacts.add(cid);
+  }
+
+  // Emit machine-readable degraded warnings for blocked sources (visible in --json, not just TTY).
+  // invBlocked: can't tell billed from not → neverBilled bucket unreliable.
+  // payBlocked: can't see outside-invoice payments → neverBilled bucket unreliable (may over-accuse).
+  if (invBlocked) ctx.out.warn(`can't see invoices (${invBlocked}) — NEVER-BILLED bucket suppressed, can't tell billed from not`, { degraded: true });
+  if (payBlocked) ctx.out.warn(`can't see payments (${payBlocked}) — outside-invoice payments invisible; NEVER-BILLED bucket suppressed to avoid false accusations`, { degraded: true });
+
+  // ── 4. Cross-check ──
+  const neverBilled = [], billedUnpaid = [];
+  let settled = 0;
+  for (const [cid, rec] of byContact) {
+    const b = billing.get(cid);
+    const paidAnyRoute = paidContacts.has(cid);
+    const last = Math.max(...rec.sessions.map(s => s.when));
+    const row = {
+      name: rec.name, contactId: cid, sessions: rec.sessions.length,
+      lastSession: new Date(last).toISOString(), lastSessionTs: last,
+      attended: rec.sessions.some(s => s.status === 'showed') ? 'showed' : 'unmarked',
+    };
+    if (b?.due > 0.0001) billedUnpaid.push({ ...row, due: b.due, cur: b.cur });
+    // neverBilled suppressed when invBlocked (can't see invoices) OR payBlocked (can't see all payments)
+    else if (!b?.billed && !paidAnyRoute && !invBlocked && !payBlocked) neverBilled.push(row);
+    else settled++;
+  }
+  neverBilled.sort((a, b) => b.lastSessionTs - a.lastSessionTs);
+  billedUnpaid.sort((a, b) => b.due - a.due);
+  const dueSum = billedUnpaid.reduce((s, x) => s + x.due, 0);
+  const cur = billedUnpaid[0]?.cur || 'PHP';
+
+  return {
+    location: LOC,
+    days: DAYS,
+    calendars: cals.length,
+    ...(skippedCalendars > 0 && { skippedCalendars }),
+    contactsWithSessions: byContact.size,
+    invoicesScanned: inv.length,
+    ...(invBlocked && { invoicesBlocked: invBlocked }),
+    ...(payBlocked && { paymentsBlocked: payBlocked }),
+    neverBilled: neverBilled.slice(0, TOP),
+    billedUnpaid: billedUnpaid.slice(0, TOP),
+    billedUnpaidTotal: dueSum,
+    currency: cur,
+    settled,
+    caveat: 'contact-level matching; payments lookback window+60d; prepaid clients older than that may flag falsely',
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  ctx.out.data(data);
+
+  const DAYS = args.days ?? 30;
+  const TOP = args.top ?? 15;
+  const cur = data.currency;
+  const fmt = (t) =>
+    new Date(t).toLocaleString('en-US', { timeZone: 'Asia/Manila', month: 'short', day: 'numeric' });
+
+  ctx.out.card(() => {
+    ctx.out.line(`\n  BOOKED-NOT-PAID — last ${DAYS}d · ${data.contactsWithSessions} contact(s) with sessions · loc ${data.location}`);
+    ctx.out.line('  ' + '─'.repeat(72));
+    if (data.invoicesBlocked) ctx.out.line(`  ⚠ can't see invoices (${data.invoicesBlocked}) — NEVER-BILLED bucket suppressed, can't tell billed from not`);
+    if (data.paymentsBlocked) ctx.out.line(`  ⚠ can't see payments (${data.paymentsBlocked}) — outside-invoice payments invisible, may over-flag`);
+    if (!data.neverBilled?.length && !data.billedUnpaid?.length) {
+      ctx.out.line(`  No leaks — every session contact is billed or settled (${data.settled} clean). ✅\n`);
+      return;
+    }
+    if (data.neverBilled?.length) {
+      ctx.out.line(`  NEVER BILLED — ${data.neverBilled.length} contact(s) had sessions, zero invoice, zero payment on file:`);
+      data.neverBilled.slice(0, TOP).forEach((x, i) => {
+        ctx.out.line(`  ${String(i + 1).padStart(2)}. ${(x.name || '?').slice(0, 26).padEnd(26)} ${String(x.sessions) + ' session(s)'} · last ${fmt(x.lastSessionTs)} · ${x.attended}`);
+        ctx.out.line(`      contact ${x.contactId}`);
+      });
+      if (data.neverBilled.length > TOP) ctx.out.line(`  … +${data.neverBilled.length - TOP} more`);
+      ctx.out.line('');
+    }
+    if (data.billedUnpaid?.length) {
+      ctx.out.line(`  BILLED, UNPAID — ${money(data.billedUnpaidTotal, cur)} due from ${data.billedUnpaid.length} session contact(s):`);
+      data.billedUnpaid.slice(0, TOP).forEach((x, i) => {
+        ctx.out.line(`  ${String(i + 1).padStart(2)}. ${(x.name || '?').slice(0, 26).padEnd(26)} ${money(x.due, x.cur).padStart(11)} · ${x.sessions} session(s) · last ${fmt(x.lastSessionTs)}`);
+        ctx.out.line(`      contact ${x.contactId}`);
+      });
+      if (data.billedUnpaid.length > TOP) ctx.out.line(`  … +${data.billedUnpaid.length - TOP} more`);
+      ctx.out.line('');
+    }
+    ctx.out.line('  ' + '─'.repeat(72));
+    ctx.out.line(`  ${data.settled} contact(s) billed/settled — skipped. Matching is contact-level (v1); prepaid >${DAYS + 60}d ago may flag.`);
+    ctx.out.line('  → never-billed: ghl-invoices drafts the invoice · unpaid: ghl-conversations drafts the nudge.');
+    ctx.out.line('  You approve every invoice and every message. Money stays you, always.\n');
+  });
+  return 0;
+}