sizmo 0.4.0 → 0.5.0

package/commands/reconcile.mjs

@@ -2,8 +2,11 @@
 // Trust-fix #1: LOC from ctx.cfg.loc.
 // Trust-fix #2: transactions + subscriptions paginate to completion.
 // Trust-fix #3: collected-by-source per currency (never cross-sums).
+// v0.5.0: default currency from CRM model location (not hardcoded PHP).
+// v0.6.0 (C2): modelMeta emitted in JSON envelope; TTY staleness note.
 // READ-ONLY. NEVER charges, refunds, or collects.
 import { paginate } from '../lib/paginate.mjs';
+import { ENTITY_SPECS } from '../lib/model.mjs';
 
 export const meta = {
   name: 'reconcile',
@@ -33,6 +36,34 @@ export async function collect(args, ctx) {
     return t >= START && t <= NOW;
   };
 
+  // Location currency from CRM model (fallback PHP if model missing/blocked)
+  let locationCurrency = 'PHP';
+  let _reconcileModelLoaded = null;
+  let modelMeta = null;
+  if (ctx.ensureModel) {
+    try {
+      _reconcileModelLoaded = await ctx.ensureModel();
+      const locCur = _reconcileModelLoaded?.entities?.location?.item?.business?.currency
+        || _reconcileModelLoaded?.entities?.location?.item?.currency;
+      if (locCur) locationCurrency = locCur.toUpperCase();
+    } catch { /* use default */ }
+  } else if (ctx.cfg.currency) {
+    locationCurrency = ctx.cfg.currency;
+  }
+  // Build modelMeta for the JSON envelope (C2)
+  if (_reconcileModelLoaded) {
+    const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+    const locEnt = _reconcileModelLoaded.entities?.location;
+    const locSpec = specMap.location;
+    const locStale = locEnt && locSpec ? (NOW - (locEnt.fetchedAt ?? 0)) > locSpec.ttlMs : false;
+    modelMeta = {
+      syncedAt: _reconcileModelLoaded.syncedAt,
+      ageMs: NOW - _reconcileModelLoaded.syncedAt,
+      stale: locStale,
+      offline: !!(_reconcileModelLoaded.offline),
+    };
+  }
+
   // transactions paginated to completion (trust-fix #2)
   const txns = [];
   let txnErr = null;
@@ -61,7 +92,7 @@ export async function collect(args, ctx) {
   if (txnErr && txns.length === 0) {
     ctx.out.warn(`can't see transactions → HTTP ${txnErr}`, { degraded: true });
     return {
-      location: LOC, days: DAYS, scanned: 0, inWindow: 0, collected: 0, currency: 'PHP',
+      location: LOC, days: DAYS, scanned: 0, inWindow: 0, collected: 0, currency: locationCurrency,
       bySource: {}, byStatus: {}, flags: { refunds: 0, failed: 0, orphans: 0 }, subscriptions: null,
     };
   }
@@ -78,7 +109,7 @@ export async function collect(args, ctx) {
     const st = (t.status || t.paymentStatus || '').toLowerCase();
     byStatus[st] = (byStatus[st] || 0) + 1;
     const amt = Number(t.amount) || 0;
-    const cur = (t.currency || 'PHP').toUpperCase();
+    const cur = (t.currency || locationCurrency).toUpperCase();
     if (SUCCESS.has(st)) {
       const s = srcOf(t);
       byCur[cur] ??= { bySource: {}, total: 0 };
@@ -97,7 +128,7 @@ export async function collect(args, ctx) {
   // flatten for output — single currency → backward-compat flat shape; multi → byCurrency map
   const currencies = Object.keys(byCur);
   const isSingle = currencies.length <= 1;
-  const currency = isSingle ? (currencies[0] || 'PHP') : (currencies[0] || 'PHP');
+  const currency = isSingle ? (currencies[0] || locationCurrency) : (currencies[0] || locationCurrency);
   const collected = isSingle ? (byCur[currency]?.total ?? 0) : null;
   const byCurrency = isSingle ? null : Object.fromEntries(currencies.map(c => [c, byCur[c].total]));
   // bySource: when single currency keep flat {src:{c,v}} for backward compat; multi-currency not surfaced at top level
@@ -136,7 +167,7 @@ export async function collect(args, ctx) {
     // MRR per-currency — same treatment as transactions (never cross-sum currencies)
     const mrrByCur = {};
     for (const x of active) {
-      const cur = (x.currency || 'PHP').toUpperCase();
+      const cur = (x.currency || locationCurrency).toUpperCase();
       mrrByCur[cur] = (mrrByCur[cur] || 0) + (Number(x.amount) || 0);
     }
     const mrrCurrencies = Object.keys(mrrByCur);
@@ -164,6 +195,7 @@ export async function collect(args, ctx) {
     byStatus,
     flags: { refunds: refunds.length, failed: failed.length, orphans: orphans.length },
     subscriptions: subs,
+    ...(modelMeta ? { modelMeta } : {}),
   };
 }
 
@@ -179,6 +211,16 @@ export async function run(args, ctx) {
 
   ctx.out.card(() => {
     ctx.out.line(`\n  RECONCILE — ${collectedLine} collected · last ${data.days}d · ${data.inWindow} txn in window · loc ${data.location}`);
+    // C2: model staleness note
+    if (data.modelMeta) {
+      const mm = data.modelMeta;
+      if (mm.offline) {
+        ctx.out.line(`  · CRM model OFFLINE — currency from cache`);
+      } else if (mm.stale) {
+        const ageD = Math.round(mm.ageMs / 86400000);
+        ctx.out.line(`  · CRM model ${ageD}d old — run sizmo sync`);
+      }
+    }
     ctx.out.line('  ' + '─'.repeat(64));
     ctx.out.line('  BY SOURCE (succeeded)');
     const srcs = Object.entries(data.bySource).sort((a, b) => b[1].v - a[1].v);

package/commands/snapshot.mjs

@@ -2,8 +2,11 @@
 // 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).
+// v0.5.0: calendar list from CRM model; location currency from model.
+// v0.6.0 (C2): modelMeta emitted in JSON envelope; TTY staleness note.
 import { paginate } from '../lib/paginate.mjs';
 import { mapLimit } from '../lib/pool.mjs';
+import { ENTITY_SPECS } from '../lib/model.mjs';
 
 export const meta = {
   name: 'snapshot',
@@ -31,6 +34,35 @@ export async function collect(args, ctx) {
     return Number.isFinite(t) && t >= START && t <= NOW;
   };
 
+  // Location currency from CRM model (fallback PHP if model missing/blocked)
+  let locationCurrency = 'PHP';
+  let _snapshotModelLoaded = null;
+  let modelMeta = null;
+  if (ctx.ensureModel) {
+    try {
+      _snapshotModelLoaded = await ctx.ensureModel();
+      const locCur = _snapshotModelLoaded?.entities?.location?.item?.business?.currency
+        || _snapshotModelLoaded?.entities?.location?.item?.currency;
+      if (locCur) locationCurrency = locCur.toUpperCase();
+    } catch { /* use default */ }
+  } else if (ctx.cfg.currency) {
+    locationCurrency = ctx.cfg.currency;
+  }
+  // Build modelMeta for the JSON envelope (C2)
+  if (_snapshotModelLoaded) {
+    const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+    // Check calendars staleness (the main model-sourced entity in snapshot)
+    const calEnt = _snapshotModelLoaded.entities?.calendars;
+    const calSpec = specMap.calendars;
+    const calStale = calEnt && calSpec ? (NOW - (calEnt.fetchedAt ?? 0)) > calSpec.ttlMs : false;
+    modelMeta = {
+      syncedAt: _snapshotModelLoaded.syncedAt,
+      ageMs: NOW - _snapshotModelLoaded.syncedAt,
+      stale: calStale,
+      offline: !!(_snapshotModelLoaded.offline),
+    };
+  }
+
   // ── LEADS: paginate contacts newest→older, stop past window ──
   async function leads() {
     let count = 0, pages = 0, oldest = null;
@@ -78,12 +110,27 @@ export async function collect(args, ctx) {
   // 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 || [];
+    // Get calendar list from the CRM model if available; fall back to live fetch.
+    // Use _snapshotModelLoaded already loaded above — no second ensureModel call.
+    let cals = null;
+    if (_snapshotModelLoaded?.entities?.calendars && !_snapshotModelLoaded.entities.calendars.blocked && !_snapshotModelLoaded.entities.calendars.networkError) {
+      cals = _snapshotModelLoaded.entities.calendars.items ?? [];
+    } else if (!_snapshotModelLoaded && ctx.ensureModel) {
+      try {
+        const model = await ctx.ensureModel();
+        if (model?.entities?.calendars && !model.entities.calendars.blocked && !model.entities.calendars.networkError) {
+          cals = model.entities.calendars.items ?? [];
+        }
+      } catch { /* fall through to live fetch */ }
+    }
+    if (cals === null) {
+      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' }),
+      ];
+      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.
@@ -152,7 +199,7 @@ export async function collect(args, ctx) {
       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();
+        const cur = (t.currency || locationCurrency).toUpperCase();
         byCur[cur] = byCur[cur] || { sum: 0, n: 0 };
         byCur[cur].sum += Number(t.amount) || 0;
         byCur[cur].n++;
@@ -163,7 +210,7 @@ export async function collect(args, ctx) {
     // 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` });
+      return metric('Collected', money(0, locationCurrency), { 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` });
@@ -195,7 +242,7 @@ export async function collect(args, ctx) {
       sum += Number(o.monetaryValue || o.monetary_value || 0) || 0;
       n++;
     }
-    return metric('Pipeline value', money(sum), { note: `${n} open deal(s)` });
+    return metric('Pipeline value', money(sum, locationCurrency), { note: `${n} open deal(s)` });
   }
 
   // ── REPLY RATE ──
@@ -223,6 +270,7 @@ export async function collect(args, ctx) {
     location: LOC,
     window: { days: DAYS, startISO, endISO: new Date(NOW).toISOString() },
     metrics: rows,
+    ...(modelMeta ? { modelMeta } : {}),
   };
 }
 
@@ -239,6 +287,16 @@ export async function run(args, ctx) {
     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)));
+    // C2: model staleness note
+    if (data.modelMeta) {
+      const mm = data.modelMeta;
+      if (mm.offline) {
+        ctx.out.line(line('· model', 'OFFLINE — calendar list from cache'));
+      } else if (mm.stale) {
+        const ageD = Math.round(mm.ageMs / 86400000);
+        ctx.out.line(line('· model', `${ageD}d old — run sizmo sync`));
+      }
+    }
     ctx.out.line('├' + '─'.repeat(W - 2) + '┤');
     for (const m of data.metrics) {
       if (m.blocked) {

package/commands/sync.mjs

@@ -0,0 +1,84 @@
+// commands/sync.mjs — force-refresh the local CRM model.
+// Fetches all 6 structure entities (or a subset) and stores the blob.
+// READ-ONLY. Only writes to the local model file; never writes to GoHighLevel.
+import { syncModel, ENTITY_SPECS, DEFAULT_MODEL_DIR } from '../lib/model.mjs';
+
+export const meta = {
+  name: 'sync',
+  summary: 'Refresh the local CRM model (pipelines, calendars, tags, fields, users, location)',
+  flags: [],
+  readOnly: true,
+};
+
+export async function run(args, ctx) {
+  const dir = ctx._modelDir ?? DEFAULT_MODEL_DIR;
+  const loc = ctx.cfg.loc;
+  const now = typeof ctx.now === 'function' ? ctx.now : () => ctx.now;
+
+  // Optional: sync only one entity — `sizmo sync tags`
+  const entityArg = args._?.[0];
+  const validNames = ENTITY_SPECS.map(s => s.name);
+  // Also accept 'fields' as alias for 'customFields'
+  const alias = { fields: 'customFields' };
+  const resolvedArg = entityArg ? (alias[entityArg] ?? entityArg) : null;
+  const only = resolvedArg ? [resolvedArg] : null;
+
+  if (resolvedArg && !validNames.includes(resolvedArg)) {
+    ctx.out.warn(`unknown entity "${entityArg}" — valid: ${validNames.join(', ')}`);
+    return 1;
+  }
+
+  let model;
+  try {
+    model = await syncModel({ http: ctx.http, loc, dir, now, only });
+  } catch (e) {
+    if (e.offline) {
+      ctx.out.warn("⚠ OFFLINE — can't reach GoHighLevel — check your connection; run `sizmo sync` when online");
+      return 1;
+    }
+    // Write failure (disk full, permissions, etc.)
+    ctx.out.warn(`sync failed — model not written: ${e.message}`);
+    return 1;
+  }
+
+  // Count results
+  let synced = 0, blocked = 0, networkErrors = 0;
+  for (const [, ent] of Object.entries(model.entities)) {
+    if (ent.networkError) networkErrors++;
+    else if (ent.blocked) blocked++;
+    else synced++;
+  }
+
+  ctx.out.data({ synced, blocked, networkErrors: networkErrors || undefined, offline: model.offline || undefined,
+    locationId: loc, syncedAt: model.syncedAt, entities: Object.fromEntries(
+    Object.entries(model.entities).map(([name, ent]) => [
+      name,
+      ent.networkError
+        ? { networkError: true, error: ent.error }
+        : ent.blocked
+          ? { blocked: true, scope: ent.scope }
+          : { fetchedAt: ent.fetchedAt, count: ent.items ? ent.items.length : (ent.item ? 1 : 0) },
+    ])
+  )});
+
+  ctx.out.card(() => {
+    const blockedNote = blocked > 0 ? ` (${blocked} scope-blocked)` : '';
+    const netNote = networkErrors > 0 ? ` (${networkErrors} network-error — check connection)` : '';
+    ctx.out.line(`synced ${synced} of ${synced + blocked + networkErrors} entities${blockedNote}${netNote} · loc ${loc}`);
+    for (const [name, ent] of Object.entries(model.entities)) {
+      if (ent.networkError) {
+        ctx.out.line(`  ⚠ ${name.padEnd(14)} couldn't reach GHL`);
+      } else if (ent.blocked) {
+        ctx.out.line(`  ✖ ${name.padEnd(14)} needs ${ent.scope}`);
+      } else {
+        const count = ent.items ? ent.items.length : (ent.item ? 1 : 0);
+        ctx.out.line(`  ✔ ${name.padEnd(14)} ${count} item(s)`);
+      }
+    }
+    if (model.offline) {
+      ctx.out.line('  ⚠ some entities could not be reached — model may be partially stale');
+    }
+  });
+
+  return 0;
+}

package/docs/how-to/auth-pit-vs-mcp.md

@@ -0,0 +1,77 @@
+# Auth: PIT vs GoHighLevel MCP
+
+Two ways to authenticate with GoHighLevel from external tooling. `sizmo` uses one; here is why, and when you might want the other.
+
+---
+
+## What sizmo uses: PIT (Private Integration Token)
+
+A Private Integration Token is a scoped API credential you create inside your GoHighLevel account under **Settings → Integrations → Private Integrations**. When you create one you choose exactly which API scopes it carries. The token is a long string starting with `pit-`.
+
+Why `sizmo` uses it:
+
+- **Precise scope control.** You decide which scopes are granted — `sizmo` requests read-only scopes only (`contacts.readonly`, `conversations.readonly`, etc.). The token cannot do anything beyond what you explicitly allowed.
+- **Deterministic.** The token is stable and usable in any headless environment — scripts, cron jobs, CI, terminal aliases. No browser, no interactive login flow, no per-session refresh.
+- **Least-privilege.** A read-only PIT cannot create contacts, send messages, charge invoices, or modify workflows. If the token is ever compromised, the blast radius is limited to read access.
+- **No token server required.** The CLI resolves the token from a local profile file or an environment variable. There is no OAuth callback server to run.
+
+**PIT = more control** over what the credential can do.
+
+---
+
+## GoHighLevel also offers an official MCP server
+
+GoHighLevel provides an official MCP (Model Context Protocol) server — the LeadConnector MCP server — as a sanctioned, public feature you can enable inside your GoHighLevel account. Once enabled, MCP clients (such as AI assistants like Claude) can connect to it and perform CRM operations through the MCP protocol.
+
+Key characteristics of GHL's MCP server:
+
+- It is OAuth-connected. Authorization goes through GoHighLevel's standard OAuth flow.
+- It is designed for AI agent and LLM use cases — giving an AI assistant the ability to read and write CRM data through natural language requests.
+- It exposes a broader surface area of CRM operations compared to a scoped read-only PIT.
+
+For information on enabling GoHighLevel's MCP server, refer to [GoHighLevel's official MCP documentation](https://help.gohighlevel.com) (search for "MCP" or "Model Context Protocol" in their help center).
+
+---
+
+## When to use which
+
+| | PIT (what sizmo uses) | GHL MCP server |
+|---|---|---|
+| **Use case** | CLI tools, shell scripts, cron jobs, precise read-only reporting | AI assistants / LLM agents that need to read or write CRM data via natural language |
+| **Auth mechanism** | Static token in local profile or env var | OAuth flow |
+| **Scope control** | Explicit, per-scope — grant only what you need | Managed by the MCP server and OAuth grant |
+| **Headless / scriptable** | Yes — no browser required | Requires initial OAuth browser flow |
+| **Write operations** | Not applicable for sizmo (read-only tool) | Yes — MCP can expose write operations |
+| **Setup** | Create PIT in GHL settings, save with `sizmo config set` | Enable MCP in GHL settings, connect an MCP-capable client |
+
+**Use a PIT** when you want a CLI tool, shell automation, or any situation where you need deterministic, headless, read-only access with explicit scope control. That is what `sizmo auth check` validates.
+
+**Use GHL's MCP server** when you are wiring GoHighLevel into an AI assistant or agent that communicates via the MCP protocol and you want the AI to be able to interact with your CRM through natural language.
+
+The two are not mutually exclusive — you can use `sizmo` for terminal-based reporting alongside an MCP-connected AI assistant in the same GoHighLevel location.
+
+---
+
+## Checking which scopes your PIT has
+
+After setting up a profile, run:
+
+```sh
+sizmo auth check
+```
+
+This probes all six read lanes and reports which scopes are present and which are missing:
+
+```
+auth check: probing 6 GoHighLevel API scopes...
+  ✅ contacts
+  ✅ conversations
+  ✖ opportunities — add scope opportunities.readonly
+  ✅ calendars
+  ✅ invoices
+  ✅ payments
+
+5/6 lanes readable — `brief` will show ⚠ on opportunities until you add: opportunities.readonly
+```
+
+Add the missing scope in your GoHighLevel Private Integration settings, then re-run `sizmo auth check` to confirm.

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

@@ -4,7 +4,20 @@ A profile stores a PIT (Private Integration Token) and Location ID under a name.
 
 ## Step 1 — get your PIT
 
-In GoHighLevel: Settings → Integrations → Private Integrations → Create. Grant read-only scopes. Copy the token (starts with `pit-`).
+In GoHighLevel: Settings → Integrations → Private Integrations → Create. Copy the token (starts with `pit-`).
+
+Grant the following scopes when creating the integration (minimum set for a full `brief`):
+
+```
+contacts.readonly
+conversations.readonly
+opportunities.readonly
+calendars.readonly
+invoices.readonly
+payments/transactions.readonly
+```
+
+Grant all six for the complete `brief`. Granting fewer is fine — any missing scope shows as ⚠ in the affected metric rather than hard-failing. Run `sizmo auth check` after setup to see exactly which lanes are readable and which scopes are still needed.
 
 ## Step 2 — find your Location ID
 

package/docs/how-to/crm-model.md

@@ -0,0 +1,105 @@
+# CRM model — how it works
+
+`sizmo` keeps a local copy of your CRM's structure — pipelines + stages, calendars, tags, custom fields, users, and location info. Recipes read from this cache instead of re-fetching on every run.
+
+## What is cached
+
+| Entity | Endpoint | TTL | Key fields |
+|--------|----------|-----|-----------|
+| pipelines + stages | `GET /opportunities/pipelines` | 24h | pipeline `{id,name}`, stages `[{id,name,position}]` |
+| calendars | `GET /calendars/` | 24h | `{id,name,calendarType,isActive}` |
+| tags | `GET /locations/{loc}/tags` | 12h | `{id,name}` |
+| customFields | `GET /locations/{loc}/customFields` | 12h | `{id,name,fieldKey,dataType}` |
+| users | `GET /users/` | 24h | `{id,firstName,lastName,email}` |
+| location | `GET /locations/{loc}` | 24h | `{name,timezone,currency,country}` |
+
+Stored at `~/.config/sizmo/model/<locationId>.json`. Written atomically (temp + rename), permissions 0600.
+
+## First run
+
+The model is synced automatically the first time a command needs it. Nothing to do.
+
+## Keeping the model fresh
+
+Run `sizmo sync` after:
+- Adding or renaming a pipeline stage
+- Adding or removing a calendar
+- Adding custom fields or tags
+- Onboarding a new user
+
+```sh
+sizmo sync              # full refresh (6 single-page calls, rate-safe)
+sizmo sync tags         # refresh one entity
+sizmo sync customFields
+```
+
+Valid entity names: `pipelines`, `calendars`, `tags`, `customFields` (or `fields`), `users`, `location`.
+
+## Querying the model
+
+```sh
+sizmo crm                   # overview: count + age per entity
+sizmo crm pipelines         # list pipelines + stages
+sizmo crm calendars         # list calendars
+sizmo crm tags              # list tags (first 20)
+sizmo crm tags --all        # list all tags
+sizmo crm fields            # list custom fields
+sizmo crm users             # list users
+sizmo crm location          # timezone / currency / country
+
+# Machine output:
+sizmo crm pipelines --json  # includes _meta with source/syncedAt/ageMs/stale
+```
+
+## Honest staleness
+
+Every model read shows the age of the data. Stale means the entity has passed its TTL (24h or 12h).
+
+- Fresh (under TTL): no special marker
+- Stale (past TTL): `⚠ STALE — run sizmo sync` banner; served anyway
+- Blocked (scope missing): `✖ needs <scope>`; other entities still served
+
+The CLI **never** auto-syncs mid-recipe when stale — it serves the cache and warns. This avoids surprise network calls and rate-limit hits. Use `sizmo sync` to force a refresh.
+
+The `--json` output includes `_meta` so agents can branch without parsing prose:
+
+```json
+{
+  "_meta": {
+    "source": "cache",
+    "syncedAt": 1718000000000,
+    "ageMs": 3600000,
+    "stale": false,
+    "offline": false
+  }
+}
+```
+
+## Name resolution
+
+Recipes use names (not IDs) in output when the model is available. If an ID is not found in the model (renamed stage, deleted calendar), the output shows:
+
+```
+<unknown:<id> — run sizmo sync>
+```
+
+This is the resolver's miss path. It never fabricates a name. Run `sizmo sync` to refresh the model after structural changes.
+
+## Partial sync (missing scopes)
+
+A 401 or 403 on one entity marks it blocked and stores what succeeded. `sizmo crm` shows blocked entities with `✖ needs <scope>`. Other entities are unaffected.
+
+Required scopes for a full sync:
+
+```
+opportunities.readonly
+calendars.readonly
+locations/tags.readonly
+locations/customFields.readonly
+users.readonly
+locations.readonly
+```
+
+## Schema versioning
+
+The model blob has a `schemaVersion` field. A format change bumps this version and invalidates the cached file (treated as missing, triggering a re-sync on next use).

package/lib/cli.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { registry } from './registry.mjs';
 import { resolve, loadProfiles, saveProfiles, validateToken, mask, pitAgeDays } from './config.mjs';
 import { makeHttp } from './http.mjs';
+import { mapLimit } from './pool.mjs';
 import { buildCtx } from './context.mjs';
 import { buildSchema } from './schema.mjs';
 import { GhlError, EXIT } from './errors.mjs';
@@ -92,24 +93,77 @@ async function routerVerb(cmd, args, io) {
   // ── auth ────────────────────────────────────────────────────────────────────
   if (cmd === 'auth') {
     if (verb === 'check') {
-      // auth check: verify PIT scopes by probing the API directly
+      // auth check: per-lane scope diagnostic — probes all fleet read lanes concurrently.
+      // Rule: 401/403 = scope MISSING; 200 or 4xx param error (400/422) = scope PRESENT.
+      // Exit 0 if contacts lane is readable (tool is usable); per-lane ✖ lines guide the user.
       const creds = resolve(profile);
       if (!creds.pit) return die('no credentials found', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
       if (!creds.loc) return die('no location resolved', EXIT.AUTH, 'pass --profile <name>, or set GHL_LOCATION_ID');
-      write('auth check: probing GoHighLevel API scopes...\n');
+
+      const loc = creds.loc;
+      const LANES = [
+        { name: 'contacts',      scope: 'contacts.readonly',             path: `/contacts/?locationId=${loc}&limit=1` },
+        { name: 'conversations', scope: 'conversations.readonly',        path: `/conversations/search?locationId=${loc}&limit=1` },
+        { name: 'opportunities', scope: 'opportunities.readonly',        path: `/opportunities/search?location_id=${loc}&limit=1` },
+        { name: 'calendars',     scope: 'calendars.readonly',            path: `/calendars/?locationId=${loc}` },
+        { name: 'invoices',      scope: 'invoices.readonly',             path: `/invoices/?altId=${loc}&altType=location&limit=1` },
+        { name: 'payments',      scope: 'payments/transactions.readonly', path: `/payments/transactions?altId=${loc}&altType=location&limit=1` },
+      ];
+
+      if (!json) write(`auth check: probing ${LANES.length} GoHighLevel API scopes...\n`);
+
+      let lanes;
       try {
         const http = makeHttp({ pit: creds.pit });
-        const result = await validateToken(http, creds.loc);
-        if (!result.ok) {
-          writeErr(`WARN: token check failed — ${result.reason}\n`);
-          return EXIT.AUTH;
-        }
-        write(`auth check: PIT accepted for location ${creds.loc}\n`);
-        return EXIT.OK;
+        lanes = await mapLimit(LANES, 5, async (lane) => {
+          try {
+            const r = await http.get(lane.path);
+            // 401/403 = scope blocked; 200 or param-error (400/422) = authorized
+            const ok = r.code !== 401 && r.code !== 403;
+            return { name: lane.name, scope: lane.scope, ok, code: r.code };
+          } catch (e) {
+            return { name: lane.name, scope: lane.scope, ok: false, code: 0, error: e?.message ?? 'error' };
+          }
+        });
       } catch (e) {
         writeErr(`auth check: could not reach GoHighLevel (${e?.message ?? 'error'})\n`);
         return EXIT.API;
       }
+
+      const okCount = lanes.filter(l => l.ok).length;
+      const total = lanes.length;
+
+      if (json) {
+        const contactsOk = lanes.find(l => l.name === 'contacts')?.ok ?? false;
+        write(JSON.stringify({
+          schemaVersion: 1,
+          location: loc,
+          lanes: lanes.map(l => ({ name: l.name, scope: l.scope, ok: l.ok, httpCode: l.code })),
+          summary: `${okCount}/${total} lanes readable`,
+          usable: contactsOk,
+        }) + '\n');
+        return contactsOk ? EXIT.OK : EXIT.AUTH;
+      }
+
+      // human output — per-lane lines then summary
+      for (const l of lanes) {
+        if (l.ok) {
+          write(`  ✅ ${l.name}\n`);
+        } else {
+          writeErr(`  ✖ ${l.name} — add scope ${l.scope}\n`);
+        }
+      }
+
+      const missing = lanes.filter(l => !l.ok).map(l => l.scope);
+      if (missing.length === 0) {
+        write(`\n${okCount}/${total} lanes readable — full brief available\n`);
+      } else {
+        const missingNames = lanes.filter(l => !l.ok).map(l => l.name).join(', ');
+        writeErr(`\n${okCount}/${total} lanes readable — \`brief\` will show ⚠ on ${missingNames} until you add: ${missing.join(', ')}\n`);
+      }
+
+      const contactsOk = lanes.find(l => l.name === 'contacts')?.ok ?? false;
+      return contactsOk ? EXIT.OK : EXIT.AUTH;
     }
     if (verb !== 'status') return die('usage: sizmo auth status|check', EXIT.USAGE);
 

package/lib/context.mjs

@@ -3,6 +3,8 @@ import { makeHttp } from './http.mjs';
 import { makeOut } from './output.mjs';
 import { makeCache } from './cache.mjs';
 import { GhlError, EXIT } from './errors.mjs';
+import { loadModel, syncModel, DEFAULT_MODEL_DIR } from './model.mjs';
+import { makeResolver } from './resolver.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { env as processEnv } from 'node:process';
@@ -29,5 +31,38 @@ export function buildCtx({ creds, globals, now = Date.now(), httpFactory = makeH
       return r;
     },
   };
-  return { http, cfg: creds, out, now };
+
+  // CRM model — lazy, loaded once per ctx. Auto-syncs if missing.
+  // Recipes read ctx.model (the raw blob) and ctx.resolve (the resolver).
+  // We expose a lazy getter so commands that don't need the model pay nothing.
+  let _model = undefined; // undefined = not yet loaded; null = load attempted, none found + sync ran
+  let _resolver = undefined;
+
+  async function ensureModel() {
+    if (_model !== undefined) return _model;
+    _model = loadModel(creds.loc, DEFAULT_MODEL_DIR);
+    if (!_model) {
+      // Auto-sync on first use (model missing)
+      try {
+        _model = await syncModel({ http: rawHttp, loc: creds.loc, now: () => now });
+      } catch {
+        _model = null;
+      }
+    }
+    _resolver = makeResolver(_model, { now: () => now });
+    return _model;
+  }
+
+  return {
+    http,
+    cfg: creds,
+    out,
+    now,
+    // Expose model access for recipes
+    get model() { return _model; },
+    // ensureModel() → async lazy-loads + returns model
+    ensureModel,
+    // resolve(kind, id) → sync resolver call (after ensureModel was awaited)
+    get resolve() { return _resolver; },
+  };
 }