sizmo 0.4.0

package/commands/snapshot.mjs

@@ -0,0 +1,256 @@
+// commands/snapshot.mjs — Monday card: 6 metrics, one screen.
+// Trust-fix #1: LOC from ctx.cfg.loc (no baked default).
+// Trust-fix #2: leads() and revenue() paginate to completion.
+// Trust-fix #3: revenue tracks per-currency (never cross-sums).
+import { paginate } from '../lib/paginate.mjs';
+import { mapLimit } from '../lib/pool.mjs';
+
+export const meta = {
+  name: 'snapshot',
+  summary: 'Monday card — 6 metrics, one screen',
+  flags: [{ name: '--days', type: 'int', default: 7, desc: 'window in days' }],
+  readOnly: true,
+};
+
+const SYM = { PHP: '₱', USD: '$', EUR: '€', GBP: '£', AUD: 'A$', CAD: 'C$' };
+const money = (n, cur = 'PHP') =>
+  (n == null || !Number.isFinite(Number(n))) ? '—' : (SYM[cur] || cur + ' ') + Number(n).toLocaleString('en-PH', { maximumFractionDigits: 0 });
+const fmtManila = (ms) =>
+  new Date(ms).toLocaleString('en-US', { timeZone: 'Asia/Manila', month: 'short', day: 'numeric' });
+const metric = (label, value, { note = '', blocked = false, blocker = '' } = {}) =>
+  ({ label, value, note, blocked, blocker });
+
+export async function collect(args, ctx) {
+  const DAYS = args.days != null ? args.days : (Number(args._?.[0]) || 7);
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const START = NOW - DAYS * 24 * 60 * 60 * 1000;
+  const startISO = new Date(START).toISOString();
+  const inWindow = (v) => {
+    const t = typeof v === 'number' ? (v < 1e12 ? v * 1000 : v) : Date.parse(v);
+    return Number.isFinite(t) && t >= START && t <= NOW;
+  };
+
+  // ── LEADS: paginate contacts newest→older, stop past window ──
+  async function leads() {
+    let count = 0, pages = 0, oldest = null;
+    let startAfter, startAfterId, done = false;
+    for await (const c of paginate({
+      fetchPage: async (cursor) => {
+        const q = { locationId: LOC, limit: 100 };
+        if (cursor) { q.startAfter = cursor.startAfter; q.startAfterId = cursor.startAfterId; }
+        const r = await ctx.http.get('/contacts/', { query: q });
+        if (!r.ok) return { _err: r.code, contacts: [] };
+        return r.j;
+      },
+      getItems: (resp) => {
+        if (resp._err) return [];
+        const arr = resp.contacts || resp.data || [];
+        if (!arr.length) done = true;
+        for (const c of arr) {
+          const da = c.dateAdded || c.createdAt;
+          const t = Date.parse(da);
+          if (Number.isFinite(t)) { oldest = t; if (t < START) done = true; }
+        }
+        pages++;
+        const last = arr[arr.length - 1];
+        startAfter = last?.dateAdded ? Date.parse(last.dateAdded) : undefined;
+        startAfterId = last?.id;
+        return arr;
+      },
+      nextCursor: (resp, items) => {
+        if (done || items.length < 100 || resp._err) return null;
+        return { startAfter, startAfterId };
+      },
+      maxPages: 200,
+    })) {
+      const da = c.dateAdded || c.createdAt;
+      const t = Date.parse(da);
+      if (Number.isFinite(t) && t >= START && t <= NOW) count++;
+    }
+    if (pages === 0) return metric('Leads', null, { blocked: true, blocker: 'contacts read failed' });
+    return metric('Leads', count, { note: `new contacts · ${pages} page(s) scanned` });
+  }
+
+  // ── BOOKINGS + SHOW RATE ──
+  // 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;
+  async function bookings() {
+    const cr = await ctx.http.get('/calendars/', { query: { locationId: LOC }, version: '2021-04-15' });
+    if (!cr.ok) return [
+      metric('Bookings', null, { blocked: true, blocker: `calendars list HTTP ${cr.code}` }),
+      metric('Show rate', null, { blocked: true, blocker: 'no calendars' }),
+    ];
+    const cals = cr.j.calendars || [];
+    let booked = 0, showed = 0, noshow = 0, calsHit = 0, skippedCalendars = 0;
+    // Parallel fan-out, capped at 5 concurrent (GHL rate-limit-safe: 100 req/10s; 5 concurrent is well under).
+    // ONLY the independent per-calendar fetches are parallelized — pagination pages stay sequential.
+    const evResults = await mapLimit(cals, 5, async (cal) => {
+      const ev = await ctx.http.get('/calendars/events', {
+        query: { locationId: LOC, calendarId: cal.id, startTime: String(START), endTime: String(NOW) },
+        version: '2021-04-15',
+      });
+      return { cal, ev };
+    });
+    for (const { cal, ev } of evResults) {
+      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 });
+      }
+      calsHit++;
+      for (const e of evList) {
+        const st = e.startTime || e.startTimeISO || e.appointmentStartTime;
+        if (!inWindow(st)) continue;
+        booked++;
+        const s = (e.appointmentStatus || e.status || '').toLowerCase();
+        if (s === 'showed' || s === 'shown') showed++;
+        else if (s === 'noshow' || s === 'no-show' || s === 'no_show') noshow++;
+      }
+    }
+    const rated = showed + noshow;
+    const showRate = rated > 0 ? Math.round(showed / rated * 100) : null;
+    return [
+      metric('Bookings', booked, { note: `appointments · ${calsHit}/${cals.length} calendars${skippedCalendars > 0 ? ` · ${skippedCalendars} skipped` : ''}`, ...(skippedCalendars > 0 && { skippedCalendars }) }),
+      showRate == null
+        ? metric('Show rate', null, { blocked: true, blocker: 'no completed (showed/noshow) appts in window yet' })
+        : metric('Show rate', showRate + '%', { note: `${showed} showed / ${rated} completed` }),
+    ];
+  }
+
+  // ── REVENUE: paginate transactions to completion (trust-fix #2), per-currency (trust-fix #3) ──
+  async function revenue() {
+    const byCur = {}; // { PHP: { sum, n }, ... }
+    let firstErr = null, totalScanned = 0;
+    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 },
+        });
+        if (!r.ok) return { _err: r.code, data: [] };
+        return r.j;
+      },
+      getItems: (resp) => {
+        if (resp._err) { firstErr = 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: 200,
+      startCursor: 0,
+    })) {
+      totalScanned++;
+      const when = t.createdAt || t.created_at || t.dateAdded;
+      const ok = (t.status || t.paymentStatus || '').toLowerCase();
+      if (inWindow(when) && (ok === 'succeeded' || ok === 'success' || ok === 'paid' || ok === 'completed' || ok === 'captured')) {
+        const cur = (t.currency || 'PHP').toUpperCase();
+        byCur[cur] = byCur[cur] || { sum: 0, n: 0 };
+        byCur[cur].sum += Number(t.amount) || 0;
+        byCur[cur].n++;
+      }
+    }
+    if (firstErr && totalScanned === 0)
+      return metric('Collected', null, { blocked: true, blocker: `transactions HTTP ${firstErr}` });
+    // If only one currency, match original format; multi-currency → list all
+    const entries = Object.entries(byCur);
+    if (entries.length === 0)
+      return metric('Collected', money(0, 'PHP'), { note: `0 payment(s) · ${totalScanned} txns scanned` });
+    if (entries.length === 1) {
+      const [cur, { sum, n }] = entries[0];
+      return metric('Collected', money(sum, cur), { note: `${n} payment(s) · ${totalScanned} txns scanned` });
+    }
+    const summary = entries.map(([c, { sum, n }]) => `${money(sum, c)} (${n})`).join(' + ');
+    const totalN = entries.reduce((s, [, { n }]) => s + n, 0);
+    return metric('Collected', summary, { note: `${totalN} payment(s) · ${totalScanned} txns scanned · multi-currency` });
+  }
+
+  // ── PIPELINE VALUE ──
+  async function pipelineValue() {
+    let sum = 0, n = 0;
+    for await (const o of paginate({
+      fetchPage: async (page = 1) => {
+        const r = await ctx.http.get('/opportunities/search', {
+          query: { location_id: LOC, status: 'open', limit: 100, page },
+        });
+        if (!r.ok) return { _err: r.code, opportunities: [] };
+        return r.j;
+      },
+      getItems: (resp) => resp._err ? [] : (resp.opportunities || resp.data || []),
+      nextCursor: (resp, items, page = 1) => {
+        if (resp._err || items.length < 100) return null;
+        return page + 1;
+      },
+      maxPages: 20,
+      startCursor: 1,
+    })) {
+      sum += Number(o.monetaryValue || o.monetary_value || 0) || 0;
+      n++;
+    }
+    return metric('Pipeline value', money(sum), { note: `${n} open deal(s)` });
+  }
+
+  // ── REPLY RATE ──
+  async function replyRate() {
+    const r = await ctx.http.get('/conversations/search', { query: { locationId: LOC, limit: 100 } });
+    if (!r.ok)
+      return metric('Reply rate', null, { blocked: true, blocker: `conversations HTTP ${r.code}` });
+    const convos = r.j.conversations || r.j.data || [];
+    let waiting = 0, total = 0;
+    for (const c of convos) {
+      const when = c.lastMessageDate || c.dateUpdated;
+      if (!inWindow(when)) continue;
+      total++;
+      if ((c.unreadCount || 0) > 0) waiting++;
+    }
+    if (total === 0)
+      return metric('Reply rate', null, { blocked: true, blocker: 'no conversation activity in window' });
+    const replied = total - waiting;
+    return metric('Reply rate', Math.round(replied / total * 100) + '%', { note: `${waiting} thread(s) still waiting on you` });
+  }
+
+  const [bk, sr] = await bookings();
+  const rows = await Promise.all([leads(), Promise.resolve(bk), Promise.resolve(sr), revenue(), replyRate(), pipelineValue()]);
+  return {
+    location: LOC,
+    window: { days: DAYS, startISO, endISO: new Date(NOW).toISOString() },
+    metrics: rows,
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  ctx.out.data(data);
+
+  const DAYS = args.days != null ? args.days : (Number(args._?.[0]) || 7);
+  const NOW = ctx.now;
+  const START = NOW - DAYS * 24 * 60 * 60 * 1000;
+  ctx.out.card(() => {
+    const W = 58;
+    const winLabel = `${fmtManila(START)} – ${fmtManila(NOW)} (last ${DAYS}d, Manila)`;
+    const line = (l, v) => '│ ' + l.padEnd(16) + ' ' + String(v).padEnd(W - 20) + '│';
+    ctx.out.line('┌' + '─'.repeat(W - 2) + '┐');
+    ctx.out.line(line('SNAPSHOT', winLabel.slice(0, W - 20)));
+    ctx.out.line('├' + '─'.repeat(W - 2) + '┤');
+    for (const m of data.metrics) {
+      if (m.blocked) {
+        ctx.out.line(line(m.label, "⚠ can't see"));
+        ctx.out.line('│ ' + ' '.repeat(16) + ' ' + ('→ ' + m.blocker).slice(0, W - 20).padEnd(W - 20) + '│');
+      } else {
+        ctx.out.line(line(m.label, m.value));
+        if (m.note) ctx.out.line('│ ' + ' '.repeat(16) + ' ' + ('· ' + m.note).slice(0, W - 20).padEnd(W - 20) + '│');
+      }
+    }
+    ctx.out.line('└' + '─'.repeat(W - 2) + '┘');
+    ctx.out.line('loc ' + data.location + '  ·  read-only  ·  numbers are counts, never fabricated');
+  });
+  return 0;
+}

package/commands/triage.mjs

@@ -0,0 +1,142 @@
+// commands/triage.mjs — Who's waiting on a reply, longest first.
+// Trust-fix #1: LOC from ctx.cfg.loc (no baked default).
+// Trust-fix #2: conversations paginate to completion — --top N caps final sorted list only.
+// READ-ONLY. Never sends. Agent drafts, human approves.
+import { paginate } from '../lib/paginate.mjs';
+
+export const meta = {
+  name: 'triage',
+  summary: 'Who is waiting on a reply, longest first',
+  flags: [
+    { name: '--top', type: 'int', default: 10, desc: 'max threads to show' },
+    { name: '--days', type: 'int', default: 30, desc: 'lookback window' },
+  ],
+  readOnly: true,
+};
+
+const CHAN = {
+  TYPE_SMS: 'SMS', TYPE_EMAIL: 'Email', TYPE_PHONE: 'Call', TYPE_FB: 'FB',
+  TYPE_IG: 'IG', TYPE_WHATSAPP: 'WhatsApp', TYPE_GMB: 'GMB',
+  TYPE_LIVE_CHAT: 'Chat', TYPE_NO_SHOW: '(no-show)',
+};
+
+export async function collect(args, ctx) {
+  const TOP = args.top ?? 10;
+  const DAYS = args.days ?? 30;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const START = NOW - DAYS * 24 * 60 * 60 * 1000;
+  const ago = (ms) => {
+    const d = Math.floor((NOW - ms) / 86400000);
+    if (d >= 1) return d + 'd';
+    const h = Math.floor((NOW - ms) / 3600000);
+    if (h >= 1) return h + 'h';
+    return Math.max(1, Math.floor((NOW - ms) / 60000)) + 'm';
+  };
+
+  // paginate conversations to completion — limit:100 per page, offset-based (trust-fix #2)
+  const convos = [];
+  let convErr = null;
+  for await (const c of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/conversations/search', {
+        query: { locationId: LOC, limit: 100, offset },
+        version: '2021-04-15',
+      });
+      if (!r.ok) return { _err: r.code, conversations: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { convErr = resp._err; return []; }
+      return resp.conversations || resp.data || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 200,
+    startCursor: 0,
+  })) {
+    convos.push(c);
+  }
+
+  if (convErr && convos.length === 0) {
+    ctx.out.warn(`can't see conversations → HTTP ${convErr}`, { degraded: true });
+    return { location: LOC, scanned: 0, waiting: 0, shown: 0, threads: [] };
+  }
+
+  const waiting = convos
+    .filter(c => (c.unreadCount || 0) > 0 && (c.lastMessageDate || 0) >= START)
+    .sort((a, b) => (a.lastMessageDate || 0) - (b.lastMessageDate || 0));
+  const top = waiting.slice(0, TOP);
+
+  // fetch last inbound snippet for context (top-N only, cheap)
+  async function lastInbound(convId) {
+    const r = await ctx.http.get(`/conversations/${convId}/messages`, {
+      query: { limit: 20 },
+      version: '2021-04-15',
+    });
+    if (!r.ok) return '';
+    const msgs = r.j.messages?.messages || r.j.messages || r.j.data || [];
+    const inb = msgs.find(m => (m.direction || '').toLowerCase() === 'inbound');
+    const b = (inb?.body || inb?.message || '').replace(/\s+/g, ' ').trim();
+    return b.slice(0, 90);
+  }
+
+  for (const c of top) { c._snippet = await lastInbound(c.id); }
+
+  return {
+    location: LOC,
+    scanned: convos.length,
+    waiting: waiting.length,
+    shown: top.length,
+    threads: top.map(c => ({
+      rank: 0,
+      name: c.contactName || c.fullName,
+      channel: CHAN[c.lastMessageType] || c.type,
+      waiting: ago(c.lastMessageDate),
+      unread: c.unreadCount,
+      snippet: c._snippet,
+      conversationId: c.id,
+      contactId: c.contactId,
+      email: c.email,
+    })),
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  ctx.out.data(data);
+
+  const TOP = args.top ?? 10;
+  const DAYS = args.days ?? 30;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const ago = (ms) => {
+    const d = Math.floor((NOW - ms) / 86400000);
+    if (d >= 1) return d + 'd';
+    const h = Math.floor((NOW - ms) / 3600000);
+    if (h >= 1) return h + 'h';
+    return Math.max(1, Math.floor((NOW - ms) / 60000)) + 'm';
+  };
+
+  ctx.out.card(() => {
+    ctx.out.line(`\n  TRIAGE — ${data.waiting} thread(s) waiting on you  ·  showing top ${data.shown}  ·  last ${DAYS}d  ·  loc ${LOC}`);
+    ctx.out.line('  ' + '─'.repeat(72));
+    if (!data.threads.length) {
+      ctx.out.line('  Inbox clear — nobody waiting on a reply. ✅\n');
+      return;
+    }
+    // reconstruct display from convos in data — thread ordering preserved
+    data.threads.forEach((t, i) => {
+      const name = (t.name || '(no name)').slice(0, 22);
+      const chan = (t.channel || '?').replace('TYPE_', '');
+      ctx.out.line(`  ${String(i + 1).padStart(2)}. ${name.padEnd(22)} ${chan.padEnd(7)} waiting ${(t.waiting || '?').padEnd(4)} · ${t.unread} unread`);
+      if (t.snippet) ctx.out.line(`      "${t.snippet}"`);
+      ctx.out.line(`      conv ${t.conversationId} · contact ${t.contactId}`);
+    });
+    ctx.out.line('  ' + '─'.repeat(72));
+    ctx.out.line('  → I draft a reply per thread; you approve each before it sends (L2, human-gated).\n');
+  });
+  return 0;
+}

package/docs/how-to/booked-not-paid.md

@@ -0,0 +1,54 @@
+# booked-not-paid — the money leak
+
+## What it answers
+
+"Who had a session but was never invoiced or never paid?" Cross-references calendar events (attended appointments) against invoices and payment transactions. Surfaces two buckets: contacts who were never invoiced, and contacts who were invoiced but never paid.
+
+## Command
+
+```sh
+sizmo booked-not-paid
+sizmo booked-not-paid --days 14    # last 14 days
+sizmo booked-not-paid --top 20     # show up to 20 per bucket
+sizmo booked-not-paid --json
+sizmo booked-not-paid --profile myclient
+```
+
+Flags (verified from `meta` in `commands/booked-not-paid.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--days` | int | 30 | Session lookback window |
+| `--top` | int | 15 | Max rows to show per bucket |
+
+## How it works
+
+1. Fetches all attended calendar events within the window (all calendars)
+2. Fetches all invoices for contacts who had sessions
+3. Paginates all payment transactions to completion (critical: the old single-page limit:100 missed paid contacts — this is fixed)
+4. A contact is `neverBilled` if they have an attended session and no invoice at all
+5. A contact is in `invoicedNotPaid` if they have an invoice in an unpaid status and no successful transaction
+
+The transaction pagination is exhaustive to avoid false positives — a contact is only flagged as unpaid if ALL pages of their transactions confirm no successful payment.
+
+**Known limitation:** Same calendar truncation issue as `noshow` — calendars returning >= 100 events may be silently truncated. `degraded: true` warning is emitted.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  NEVER BILLED (had session, no invoice)
+  1. Ana Lim           session 5d ago
+  2. Bong Santos       session 8d ago
+
+  INVOICED NOT PAID
+  1. Juan dela Cruz    ₱25,000   invoice sent 21d ago
+  2. Maria Santos      ₱12,000   invoice viewed 9d ago
+```
+
+*Sample shape only.*
+
+## Notes
+
+- The CLI never creates an invoice or charges a card. Use this list to identify the gap; action stays with you.
+- `neverBilled` contacts show `estValue: 0` in JSON — the value is truly unknown until you decide what to charge.
+- `--top N` caps each bucket independently. All events and transactions are fetched before the cap is applied.

package/docs/how-to/brief.md

@@ -0,0 +1,71 @@
+# brief — morning brief
+
+## What it answers
+
+"What needs my attention today?" Combines snapshot numbers, triage threads, no-shows, stuck deals, and unpaid invoices into a single ranked morning card. The NEEDS YOU TODAY section is ordered by money at stake — highest-value items first, unknown-value items below.
+
+Start here every morning before opening GoHighLevel.
+
+## Command
+
+```sh
+sizmo brief
+sizmo brief --days 14          # widen the snapshot window to 14 days
+sizmo brief --json             # machine-readable envelope
+sizmo brief --profile myclient # target a specific credential profile
+```
+
+Flags (verified from `meta` in `commands/brief.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--days` | int | 7 | Snapshot window in days |
+
+Global flags `--json`, `--profile`, `--fresh` also apply.
+
+## How it works
+
+`brief` fans out five sub-collects in parallel on the same HTTP client and rate-limit pool:
+
+1. `snapshot` — 6 headline metrics
+2. `triage` — unanswered conversation threads (lookback: 30d, cap: 100)
+3. `noshow` — no-shows to re-book (lookback: 30d, cap: 100)
+4. `pipeline` — stuck deals (threshold: 7d, cap: 100)
+5. `receivables` — outstanding invoices (cap: 100)
+
+Each sub-collect is wrapped in a fault-tolerant `safe()` — if one source is blocked (e.g. missing scope), it emits `degraded: true` in the envelope and shows a warning instead of crashing the brief.
+
+NEEDS YOU TODAY is ranked by `rankActions` from `lib/prioritize.mjs` — the same ranker used by `focus`. Money-valued items (stuck deals, invoices) come first in descending dollar order; items with unknown value (waiting threads, no-shows) follow.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  MORNING BRIEF — Monday, Jun 9                                 ║
+║  loc LOC_XXXX  ·  read-only                                    ║
+╚════════════════════════════════════════════════════════════════╝
+
+  THE NUMBERS (last 7d)
+  ────────────────────────────────────────────────────────────────
+  New leads        12
+  Bookings         8
+  Show rate        75%
+  Collected        ₱48,000
+  Reply rate       83%
+  Pipeline         ₱320,000
+
+  NEEDS YOU TODAY
+  ────────────────────────────────────────────────────────────────
+  1. Juan dela Cruz — ₱25,000 invoice (21d overdue)  → sizmo receivables
+  2. Maria Santos — stuck deal ₱18,000 (12d idle)    → sizmo pipeline
+  3. (no-show) Carlo Reyes — 3d ago                  → sizmo noshow
+  ...
+```
+
+*Sample shape only. Actual numbers depend on your GoHighLevel location data.*
+
+## Notes
+
+- `degraded: true` in the JSON envelope means at least one source was blocked. Check `warnings` for detail. Never treat a blocked source as zero.
+- The `--days` flag affects only the snapshot window. Triage, noshow, pipeline, and receivables sub-collects use their own defaults (30d lookback for triage/noshow, 7d stuck threshold for pipeline).
+- To drill into any item, run its recipe: `sizmo receivables`, `sizmo pipeline`, `sizmo triage`, etc.

package/docs/how-to/configure-a-client-profile.md

@@ -0,0 +1,73 @@
+# Configure a client profile
+
+A profile stores a PIT (Private Integration Token) and Location ID under a name. Use one profile per GoHighLevel location.
+
+## Step 1 — get your PIT
+
+In GoHighLevel: Settings → Integrations → Private Integrations → Create. Grant read-only scopes. Copy the token (starts with `pit-`).
+
+## Step 2 — find your Location ID
+
+In GoHighLevel: Settings → Business Profile. The Location ID is in the URL or displayed in the page. It is a long alphanumeric string.
+
+## Step 3 — save the profile
+
+```sh
+echo "pit-yourtoken..." | sizmo config set \
+  --profile myclient \
+  --loc YOUR_LOCATION_ID \
+  --pit-stdin
+```
+
+- `--pit-stdin` reads the PIT from stdin — it never touches command-line history or shell logs
+- The `--` is optional; any order of flags works
+- A `--created` date is set automatically to today (used to track PIT age)
+
+You can also add an optional label:
+
+```sh
+echo "pit-yourtoken..." | sizmo config set \
+  --profile myclient \
+  --loc YOUR_LOCATION_ID \
+  --label "Coaching Client - ABC" \
+  --pit-stdin
+```
+
+## Step 4 — verify
+
+```sh
+sizmo auth status --profile myclient
+sizmo auth check  --profile myclient
+```
+
+`auth status` shows the saved data (source, location, masked PIT, age). `auth check` makes a live API call to confirm the PIT is accepted.
+
+## Update a profile
+
+Re-run `config set` with the same `--profile` name. Fields you specify overwrite; fields you omit are preserved.
+
+```sh
+# Update location ID only
+sizmo config set --profile myclient --loc NEW_LOC_ID
+
+# Rotate PIT only
+echo "pit-newtoken..." | sizmo config set --profile myclient --pit-stdin --created $(date +%Y-%m-%d)
+```
+
+## Remove a profile
+
+```sh
+sizmo config rm myclient
+```
+
+## Using environment variables instead
+
+If you prefer not to use profiles:
+
+```sh
+export GHL_PIT=pit-yourtoken...
+export GHL_LOCATION_ID=YOUR_LOCATION_ID
+sizmo brief
+```
+
+Environment variables take precedence over saved profiles. Neither variable is written to disk by sizmo.

package/docs/how-to/focus.md

@@ -0,0 +1,46 @@
+# focus — ranked to-do queue
+
+## What it answers
+
+"What's the single most important thing I should do right now, ordered by money?" Returns one unified list across all lanes — stuck deals, overdue invoices, never-billed sessions, unanswered threads, and no-shows — ranked by dollar value descending.
+
+Use `focus` when you want the ranked queue without the brief's full morning card layout.
+
+## Command
+
+```sh
+sizmo focus
+sizmo focus --top 10           # show top 10 items
+sizmo focus --stuck-days 14    # widen the stuck-deal threshold
+sizmo focus --json
+sizmo focus --profile myclient
+```
+
+Flags (verified from `meta` in `commands/focus.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--top` | int | 15 | Max items to display |
+| `--stuck-days` | int | 7 | Idle threshold for stuck deals |
+
+## How it works
+
+Same five sub-collects as `brief`, same `rankActions` ranker from `lib/prioritize.mjs`. Output is a flat numbered list — no card headers, no sections. Designed to feed into automation or agent pipelines via `--json`.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  1. Juan dela Cruz — invoice ₱25,000 (21d)      → sizmo receivables
+  2. Maria Santos — stuck deal ₱18,000 (12d)     → sizmo pipeline
+  3. (never billed) Carlo Reyes — session 5d ago → sizmo booked-not-paid
+  4. Ana Reyes — waiting reply (8d)               → sizmo triage
+  ...
+```
+
+*Sample shape only.*
+
+## Notes
+
+- Items with known monetary value (deals, invoices) rank above items with unknown value (threads, no-shows).
+- `--stuck-days` affects how pipeline defines a "stuck" deal. A deal is stuck when it has had no stage change or status update in N days.
+- Use `sizmo brief` if you want the morning card format with headline metrics. Use `focus` for a clean list.