sizmo 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # sizmo
 
-**Unofficial read-only GoHighLevel CLI for coaches and consultants.**
+**Unofficial read-only GoHighLevel CLI.** Your GoHighLevel CRM — leads, bookings, pipeline, receivables, payments, and a money-ranked to-do list — from the terminal, in one command.
 
 > Not affiliated with, endorsed by, or supported by HighLevel. This is an independent open-source tool.
 
@@ -10,7 +10,16 @@
 
 Requires Node.js 20+.
 
-**Option A — clone + install (puts `sizmo` on your PATH):**
+**Option A — npm (recommended):**
+
+```sh
+npx sizmo brief            # run with no install
+# or install globally:
+npm install -g sizmo
+sizmo brief
+```
+
+**Option B — clone + install (puts `sizmo` on your PATH from source):**
 
 ```sh
 git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli
@@ -20,12 +29,6 @@ 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
@@ -33,8 +36,6 @@ 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
@@ -43,6 +44,17 @@ echo "pit-yourtoken..." | sizmo config set --profile myclient --loc YOUR_LOCATIO
 
 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.
 
+When creating the Private Integration, grant these scopes for the full `brief`:
+
+```
+contacts.readonly · conversations.readonly · opportunities.readonly
+calendars.readonly · invoices.readonly · payments/transactions.readonly
+```
+
+Granting fewer is fine — missing scopes show as ⚠ in affected metrics rather than failing the whole command. Run `sizmo auth check` after setup to see a per-lane scope report.
+
+**Auth: PIT vs MCP** — `sizmo` uses a Private Integration Token (PIT), not the GoHighLevel MCP server. See [`docs/how-to/auth-pit-vs-mcp.md`](docs/how-to/auth-pit-vs-mcp.md) for the comparison and when you'd want each.
+
 Verify auth:
 
 ```sh
@@ -66,6 +78,8 @@ Command list generated from `sizmo schema` (authoritative — pulled directly fr
 | `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) |
+| `sizmo crm` | Query the local CRM model — counts, lists, staleness | `--all` (show all items) |
+| `sizmo sync` | Refresh the local CRM model (pipelines, calendars, tags, fields, users, location) | `[entity]` (sync one) |
 
 ### Utility commands
 
@@ -107,6 +121,42 @@ Every command supports `--json`. The envelope shape is stable:
 
 `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.
 
+## Your CRM model
+
+`sizmo` caches the slow-changing structure of your CRM — pipelines + stages, calendars, tags, custom fields, users, and location — in a local file (`~/.config/sizmo/model/<locationId>.json`). Recipes read from this cache instead of re-fetching structure on every run.
+
+**What it stores:** pipeline/stage names + IDs, calendar list, tag list, custom fields, user roster, and location info (timezone, currency, country). Structure only — no contacts, no conversations, no payments.
+
+**Sync once, read fast.** The model is synced automatically on first use. After that, recipes use the cached copy. Run `sizmo sync` after you change your pipeline stages or add calendars:
+
+```sh
+sizmo sync                # full refresh (all 6 entities)
+sizmo sync tags           # refresh one entity only
+```
+
+**Age is always shown.** `sizmo crm` shows how old each entity is. Stale entries (past TTL: 24h for pipelines/calendars/users/location; 12h for tags/fields) show a warning. The CLI never silently serves stale structure as current.
+
+**Model never auto-syncs when stale.** It serves the cached data with a loud age banner. This avoids surprise network calls mid-recipe. Use `sizmo sync` or `--fresh` to force a refresh.
+
+```sh
+sizmo crm                 # overview: counts + age per entity
+sizmo crm pipelines       # list pipelines + stages
+sizmo crm calendars       # list calendars
+sizmo crm tags [--all]    # list tags (truncated at 20 by default)
+sizmo crm fields          # list custom fields
+sizmo crm users           # list users
+sizmo crm location        # timezone / currency / country
+sizmo crm pipelines --json  # machine output with _meta.source/syncedAt/ageMs/stale
+```
+
+The JSON `_meta` block in every `crm` response lets agents branch on staleness without parsing prose:
+
+```json
+"_meta": { "source": "cache", "syncedAt": 1718000000000, "ageMs": 3600000, "stale": false, "offline": false }
+```
+
+**Scope requirements** for a full sync: `opportunities.readonly`, `calendars.readonly`, `locations/tags.readonly`, `locations/customFields.readonly`, `users.readonly`, `locations.readonly`. A 401/403 on one entity marks it blocked; the rest still store. `sizmo crm` shows `✖ needs <scope>` for blocked entities.
+
 ## Read-only + safety promise
 
 - **Never writes to GoHighLevel.** No contacts created, no messages sent, no invoices issued, no payments charged.
@@ -149,4 +199,4 @@ MIT. See LICENSE.
 
 ---
 
-Built by Sizmo — productized GHL systems for coaches & consultants. Unofficial; not affiliated with HighLevel.
+Built by [Sizmo](https://github.com/csalamida07-cyber/sizmo-ghl-cli) — GHL CRM systems & automation. Unofficial; not affiliated with HighLevel.

package/SKILL.md

@@ -28,4 +28,4 @@ Read-only GoHighLevel ops. Every command takes `--json` (stable envelope: `{sche
 - 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.
+Built by Sizmo — GHL CRM systems & automation. Unofficial; not affiliated with HighLevel.

package/commands/crm.mjs

@@ -0,0 +1,258 @@
+// commands/crm.mjs — query surface for the local CRM model.
+// Overview counts + per-entity lists. Honest staleness on every read.
+// Missing model → auto-sync once (first run). Stale → serve + banner, no auto-sync.
+// READ-ONLY. No writes to GoHighLevel.
+import { loadModel, syncModel, isStale, ageMs, ENTITY_SPECS, DEFAULT_MODEL_DIR } from '../lib/model.mjs';
+
+export const meta = {
+  name: 'crm',
+  summary: 'Query the local CRM model — counts, lists, staleness',
+  flags: [
+    { name: '--all', type: 'bool', desc: 'show all items (overrides high-cardinality truncation)' },
+  ],
+  readOnly: true,
+};
+
+const TRUNCATE_ABOVE = 20; // default max items for high-cardinality entities (tags, fields)
+
+// Alias map for subcommands
+const ALIAS = { fields: 'customFields' };
+const VALID_SUBS = ['pipelines', 'calendars', 'tags', 'fields', 'users', 'location'];
+
+export async function run(args, ctx) {
+  const dir = ctx._modelDir ?? DEFAULT_MODEL_DIR;
+  const loc = ctx.cfg.loc;
+  const nowMs = typeof ctx.now === 'function' ? ctx.now() : ctx.now;
+  const showAll = !!(args.all || args['--all']);
+
+  // Sub-command from positional args
+  const sub = args._?.[0] || null;
+
+  // 1. Load model (auto-sync if missing)
+  let model = loadModel(loc, dir);
+  if (!model) {
+    // First run — auto-sync. syncModel throws if cold+offline.
+    ctx.out.warn('model not found — running first-time sync...');
+    try {
+      model = await syncModel({ http: ctx.http, loc, dir, now: typeof ctx.now === 'function' ? ctx.now : () => ctx.now });
+    } catch (e) {
+      if (e.offline) {
+        ctx.out.warn("⚠ OFFLINE — can't reach GoHighLevel — check your connection; run `sizmo sync` when online");
+        return 1;
+      }
+      throw e;
+    }
+  }
+
+  // 2. Build overall model meta
+  const modelAgeMs = nowMs - model.syncedAt;
+  // Determine overall staleness: any entity past its TTL
+  const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+  let anyStale = false;
+  for (const [name, ent] of Object.entries(model.entities)) {
+    if (!ent.blocked && !ent.networkError && specMap[name] && isStale(ent, nowMs, specMap[name].ttlMs)) {
+      anyStale = true;
+    }
+  }
+
+  // Determine offline: model was last sync'd while offline, OR the model itself has the offline flag.
+  // Also detect if a model exists but a refresh just failed (model.offline = true from the last sync).
+  const offline = !!(model.offline);
+  const meta = { source: 'cache', syncedAt: model.syncedAt, ageMs: modelAgeMs, stale: anyStale, offline };
+
+  // 3. Warn if offline (showing stale/cached data) or just stale
+  if (offline) {
+    const cacheAge = fmtAge(modelAgeMs);
+    ctx.out.warn(`⚠ OFFLINE — showing cache from ${new Date(model.syncedAt).toISOString()} (${cacheAge} old) — run \`sizmo sync\` when online`);
+  } else if (anyStale) {
+    ctx.out.warn(`⚠ model is stale (${fmtAge(modelAgeMs)} old) — run sizmo sync to refresh`);
+  }
+
+  // 4. Dispatch sub-command or overview
+  if (!sub) {
+    return overview(model, meta, nowMs, specMap, ctx);
+  }
+
+  const resolved = ALIAS[sub] ?? sub;
+  if (!VALID_SUBS.includes(sub) && !VALID_SUBS.includes(resolved)) {
+    ctx.out.warn(`unknown crm subcommand "${sub}" — valid: ${VALID_SUBS.join(', ')}`);
+    return 1;
+  }
+
+  if (resolved === 'location') return locationCmd(model, meta, ctx);
+  return entityList(resolved, model, meta, nowMs, specMap, showAll, ctx);
+}
+
+// ── overview ──────────────────────────────────────────────────────────────────
+
+function overview(model, modelMeta, nowMs, specMap, ctx) {
+  const counts = {};
+  const blocked = {};
+  const networkErrors = {};
+  for (const spec of ENTITY_SPECS) {
+    const ent = model.entities[spec.name];
+    if (!ent) { counts[spec.name] = 0; continue; }
+    if (ent.networkError) {
+      counts[spec.name] = null;
+      networkErrors[spec.name] = ent.error ?? 'network error';
+    } else if (ent.blocked) {
+      counts[spec.name] = null;
+      blocked[spec.name] = ent.scope;
+    } else if (spec.name === 'location') {
+      counts[spec.name] = ent.item ? 1 : 0;
+    } else {
+      counts[spec.name] = Array.isArray(ent.items) ? ent.items.length : 0;
+    }
+  }
+
+  // Build human-friendly output structure
+  const data = {
+    pipelines: counts.pipelines,
+    calendars: counts.calendars,
+    tags: counts.tags,
+    customFields: counts.customFields,
+    users: counts.users,
+    location: counts.location,
+    _meta: modelMeta,
+  };
+  // Add blocked/networkError flags so agents can branch
+  for (const [name, scope] of Object.entries(blocked)) {
+    data[`${name}Blocked`] = true;
+    data[`${name}Scope`] = scope;
+  }
+  for (const [name] of Object.entries(networkErrors)) {
+    data[`${name}NetworkError`] = true;
+  }
+
+  ctx.out.data(data);
+
+  ctx.out.card(() => {
+    const age = fmtAge(modelMeta.ageMs);
+    const staleNote = modelMeta.offline ? ` ⚠ OFFLINE` : (modelMeta.stale ? ` ⚠ STALE — run sizmo sync` : '');
+    ctx.out.line(`\n  CRM MODEL  ·  loc ${model.locationId}  ·  synced ${age}${staleNote}`);
+    ctx.out.line('  ' + '─'.repeat(50));
+    for (const spec of ENTITY_SPECS) {
+      if (spec.name === 'location') continue; // shown separately
+      const ent = model.entities[spec.name];
+      if (!ent) { ctx.out.line(`  ${spec.name.padEnd(16)} 0`); continue; }
+      if (ent.networkError) {
+        ctx.out.line(`  ${spec.name.padEnd(16)} ⚠ couldn't reach GHL`);
+      } else if (ent.blocked) {
+        ctx.out.line(`  ${spec.name.padEnd(16)} ✖ needs ${ent.scope}`);
+      } else {
+        const count = Array.isArray(ent.items) ? ent.items.length : 0;
+        const entAge = ageMs(ent, nowMs);
+        const entStale = isStale(ent, nowMs, specMap[spec.name]?.ttlMs ?? Infinity);
+        const ageNote = entAge !== null ? ` · ${fmtAge(entAge)}${entStale ? ' ⚠' : ''}` : '';
+        ctx.out.line(`  ${spec.name.padEnd(16)} ${count}${ageNote}`);
+      }
+    }
+    // Location line
+    const locEnt = model.entities.location;
+    if (locEnt && !locEnt.blocked && locEnt.item) {
+      const loc = locEnt.item;
+      const cur = loc.business?.currency || loc.currency || 'PHP';
+      ctx.out.line(`  ${'location'.padEnd(16)} ${loc.name || model.locationId}  ·  ${cur}  ·  ${loc.timezone || ''}`);
+    }
+    ctx.out.line('  ' + '─'.repeat(50));
+    ctx.out.line('  sizmo crm <pipelines|calendars|tags|fields|users|location>  for details\n');
+  });
+
+  return 0;
+}
+
+// ── entity list ───────────────────────────────────────────────────────────────
+
+function entityList(entityName, model, modelMeta, nowMs, specMap, showAll, ctx) {
+  const ent = model.entities[entityName];
+  const spec = specMap[entityName];
+
+  if (ent?.networkError) {
+    ctx.out.warn(`⚠ ${entityName} — couldn't reach GHL during last sync`);
+    ctx.out.data({ entity: entityName, networkError: true, _meta: modelMeta });
+    return 1;
+  }
+
+  if (!ent || ent.blocked) {
+    const scope = ent?.scope ?? 'unknown';
+    ctx.out.warn(`✖ ${entityName} blocked — needs ${scope}`);
+    ctx.out.data({ entity: entityName, blocked: true, scope, _meta: modelMeta });
+    return 1;
+  }
+
+  const items = Array.isArray(ent.items) ? ent.items : [];
+  const entAge = ageMs(ent, nowMs);
+  const stale = spec ? isStale(ent, nowMs, spec.ttlMs) : false;
+  const entMeta = { ...modelMeta, entityFetchedAt: ent.fetchedAt, entityAgeMs: entAge, entityStale: stale };
+
+  // High-cardinality truncation (tags, customFields)
+  const highCard = entityName === 'tags' || entityName === 'customFields';
+  const shown = (highCard && !showAll) ? items.slice(0, TRUNCATE_ABOVE) : items;
+  const truncated = shown.length < items.length;
+
+  ctx.out.data({ entity: entityName, items: shown, total: items.length, truncated, _meta: entMeta });
+
+  ctx.out.card(() => {
+    const ageNote = entAge !== null ? `synced ${fmtAge(entAge)} ago` : '';
+    const staleNote = stale ? ' ⚠ STALE' : '';
+    ctx.out.line(`\n  ${entityName.toUpperCase()}  ·  ${items.length} item(s)  ·  ${ageNote}${staleNote}`);
+    ctx.out.line('  ' + '─'.repeat(50));
+    if (entityName === 'pipelines') {
+      for (const pl of shown) {
+        ctx.out.line(`  ${(pl.name || pl.id).slice(0, 40)}`);
+        for (const s of (pl.stages || [])) {
+          ctx.out.line(`    [${String(s.position ?? '').padStart(2)}] ${(s.name || s.id).slice(0, 36)}`);
+        }
+      }
+    } else if (entityName === 'users') {
+      for (const u of shown) {
+        const name = [u.firstName, u.lastName].filter(Boolean).join(' ') || u.name || u.id;
+        ctx.out.line(`  ${name.slice(0, 30).padEnd(30)} ${(u.email || '').slice(0, 36)}`);
+      }
+    } else {
+      for (const item of shown) {
+        const label = item.name || item.id;
+        const extra = item.fieldKey ? `  key: ${item.fieldKey}` : (item.calendarType ? `  ${item.calendarType}` : '');
+        ctx.out.line(`  ${label.slice(0, 40)}${extra}`);
+      }
+    }
+    if (truncated) ctx.out.line(`  … ${items.length - shown.length} more — --all to show all`);
+    ctx.out.line('  ' + '─'.repeat(50) + '\n');
+  });
+
+  return 0;
+}
+
+// ── location subcommand ───────────────────────────────────────────────────────
+
+function locationCmd(model, modelMeta, ctx) {
+  const ent = model.entities.location;
+  if (!ent || ent.blocked) {
+    const scope = ent?.scope ?? 'locations.readonly';
+    ctx.out.warn(`✖ location blocked — needs ${scope}`);
+    ctx.out.data({ blocked: true, scope, _meta: modelMeta });
+    return 1;
+  }
+  const item = ent.item ?? {};
+  ctx.out.data({ item, location: item, _meta: modelMeta });
+  ctx.out.card(() => {
+    ctx.out.line(`\n  LOCATION  ·  ${item.name || model.locationId}`);
+    ctx.out.line('  ' + '─'.repeat(40));
+    ctx.out.line(`  id        ${item.id || model.locationId}`);
+    ctx.out.line(`  timezone  ${item.timezone || '—'}`);
+    ctx.out.line(`  currency  ${item.business?.currency || item.currency || '—'}`);
+    ctx.out.line(`  country   ${item.country || '—'}`);
+    ctx.out.line('  ' + '─'.repeat(40) + '\n');
+  });
+  return 0;
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function fmtAge(ms) {
+  if (ms == null || ms < 0) return '?';
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h`;
+  return `${Math.round(ms / 86_400_000)}d`;
+}

package/commands/noshow.mjs

@@ -1,7 +1,10 @@
 // commands/noshow.mjs — No-show recovery: surfaces who no-showed to re-book.
 // Trust-fix #1: LOC from ctx.cfg.loc (no baked default).
+// v0.5.0: calendar list from CRM model (no per-run /calendars/ re-fetch); events still live.
+// v0.6.0 (C2): modelMeta emitted in JSON envelope; staleness note in TTY.
 // READ-ONLY. Never messages, never books.
 import { mapLimit } from '../lib/pool.mjs';
+import { ENTITY_SPECS } from '../lib/model.mjs';
 export const meta = {
   name: 'noshow',
   summary: 'No-show recovery — who to re-book',
@@ -24,12 +27,39 @@ export async function collect(args, ctx) {
   const NOW = ctx.now;
   const START = NOW - DAYS * 24 * 60 * 60 * 1000;
 
-  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, calendars: 0, noshows: 0, shown: 0, list: [] };
+  // Get calendar list from the CRM model if available; fall back to live fetch.
+  let cals = null;
+  let modelLoaded = null;
+  let modelMeta = null;
+  if (ctx.ensureModel) {
+    try {
+      modelLoaded = await ctx.ensureModel();
+      if (modelLoaded?.entities?.calendars && !modelLoaded.entities.calendars.blocked && !modelLoaded.entities.calendars.networkError) {
+        cals = modelLoaded.entities.calendars.items ?? [];
+      }
+    } catch { /* fall through to live fetch */ }
+  }
+  // Build modelMeta for the JSON envelope (C2)
+  if (modelLoaded) {
+    const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+    const calEnt = modelLoaded.entities?.calendars;
+    const calSpec = specMap.calendars;
+    const calStale = calEnt && calSpec ? (NOW - (calEnt.fetchedAt ?? 0)) > calSpec.ttlMs : false;
+    modelMeta = {
+      syncedAt: modelLoaded.syncedAt,
+      ageMs: NOW - modelLoaded.syncedAt,
+      stale: calStale,
+      offline: !!(modelLoaded.offline),
+    };
+  }
+  if (cals === null) {
+    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, calendars: 0, noshows: 0, shown: 0, list: [], ...(modelMeta ? { modelMeta } : {}) };
+    }
+    cals = cr.j.calendars || [];
   }
-  const cals = cr.j.calendars || [];
   const noshows = [];
   let skippedCalendars = 0;
   // Parallel fan-out, capped at 5 concurrent (GHL rate-limit-safe: 100 req/10s; 5 concurrent is well under).
@@ -82,6 +112,7 @@ export async function collect(args, ctx) {
       when: new Date(n.when).toISOString(),
       calendar: n.cal,
     })),
+    ...(modelMeta ? { modelMeta } : {}),
   };
 }
 
@@ -100,6 +131,16 @@ export async function run(args, ctx) {
 
   ctx.out.card(() => {
     ctx.out.line(`\n  NO-SHOW RECOVERY — ${data.noshows} no-show(s) · last ${DAYS}d · ${data.calendars} calendars · loc ${data.location}`);
+    // C2: staleness note when model is old/offline
+    if (data.modelMeta) {
+      const mm = data.modelMeta;
+      if (mm.offline) {
+        ctx.out.line(`  · CRM model OFFLINE — calendar list 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(70));
     if (!data.list.length) {
       ctx.out.line('  No no-shows in window. ✅\n');

package/commands/pipeline.mjs

@@ -1,8 +1,12 @@
 // commands/pipeline.mjs — Pipeline health: value by stage + stuck sweep.
 // Trust-fix #1: LOC from ctx.cfg.loc.
 // Trust-fix #2: opps paginate to completion.
+// v0.5.0: stage/pipeline names sourced from ctx CRM model (no per-run structure re-fetch).
+// v0.6.0 (C2): names resolved via ctx.resolve (never fabricated); modelMeta emitted with staleness signal.
+//              I1 fix: stage sort uses model position (not undefined .sid).
 // READ-ONLY.
 import { paginate } from '../lib/paginate.mjs';
+import { ENTITY_SPECS } from '../lib/model.mjs';
 
 export const meta = {
   name: 'pipeline',
@@ -31,19 +35,75 @@ export async function collect(args, ctx) {
     return d >= 1 ? d + 'd' : Math.max(1, Math.floor((NOW - t) / 3600000)) + 'h';
   };
 
-  // pipelines → stage id→name map
-  const p = await ctx.http.get('/opportunities/pipelines', { query: { locationId: LOC } });
-  if (!p.ok) {
-    ctx.out.warn(`can't see pipelines → HTTP ${p.code}`, { degraded: true });
-    return { location: LOC, totalValue: 0, openCount: 0, pipelines: [], stuck: [] };
+  // Build stage/pipeline name resolution from the CRM model (no per-run structure re-fetch).
+  // Falls back to a live fetch only when model is genuinely unavailable.
+  // C2: names go through ctx.resolve when available — miss → '<unknown:id — run sizmo sync>'
+  // I1: stagePosition map keyed by stage-id carries model position (not a discarded .sid).
+
+  let modelLoaded = null; // the raw model blob (for modelMeta)
+  let resolver = null;    // ctx.resolve (makeResolver instance)
+  const stagePosition = {}; // sid → model position (for sort)
+  const stageName = {}, pipeName = {}; // fallback maps (live-fetch path)
+
+  // Try model first (via ctx.ensureModel / ctx.resolve)
+  const usingModelPath = !!(ctx.ensureModel || ctx.resolve);
+  if (usingModelPath) {
+    try {
+      if (ctx.ensureModel) modelLoaded = await ctx.ensureModel();
+      resolver = ctx.resolve ?? null;
+      // Build stagePosition from model for sort (I1 fix)
+      if (modelLoaded?.entities?.pipelines && !modelLoaded.entities.pipelines.blocked && !modelLoaded.entities.pipelines.networkError) {
+        for (const pl of (modelLoaded.entities.pipelines.items ?? [])) {
+          for (const s of (pl.stages || [])) {
+            stagePosition[s.id] = s.position ?? 0;
+          }
+        }
+      }
+    } catch { /* fall through to live fetch */ }
   }
-  const pipelines = p.j.pipelines || [];
-  const stageName = {}, pipeName = {}, stageOrder = {};
-  for (const pl of pipelines) {
-    pipeName[pl.id] = pl.name;
-    (pl.stages || []).forEach((s, i) => { stageName[s.id] = s.name; stageOrder[s.id] = i; });
+
+  // modelMeta for staleness signal (C2)
+  const specMap = Object.fromEntries(ENTITY_SPECS.map(s => [s.name, s]));
+  let modelMeta = null;
+  if (modelLoaded) {
+    const plEnt = modelLoaded.entities?.pipelines;
+    const plSpec = specMap.pipelines;
+    const plFetchedAt = plEnt?.fetchedAt ?? null;
+    const plAgeMs = plFetchedAt != null ? NOW - plFetchedAt : null;
+    const plStale = plEnt && plSpec ? (NOW - (plEnt.fetchedAt ?? 0)) > plSpec.ttlMs : false;
+    modelMeta = {
+      syncedAt: modelLoaded.syncedAt,
+      ageMs: NOW - modelLoaded.syncedAt,
+      stale: plStale,
+      offline: !!(modelLoaded.offline),
+    };
+  }
+
+  if (!resolver) {
+    // Fallback: live fetch (model genuinely unavailable)
+    const p = await ctx.http.get('/opportunities/pipelines', { query: { locationId: LOC } });
+    if (!p.ok) {
+      ctx.out.warn(`can't see pipelines → HTTP ${p.code}`, { degraded: true });
+      return { location: LOC, totalValue: 0, openCount: 0, pipelines: [], stuck: [], modelMeta };
+    }
+    const pipelines = p.j.pipelines || [];
+    for (const pl of pipelines) {
+      pipeName[pl.id] = pl.name;
+      (pl.stages || []).forEach((s) => { stageName[s.id] = s.name; stagePosition[s.id] = s.position ?? 0; });
+    }
   }
 
+  // Helper: resolve pipeline name (via resolver or fallback map)
+  const resolvePipeName = (pid) => {
+    if (resolver) return resolver.label('pipeline', pid);
+    return pipeName[pid] || pid;
+  };
+  // Helper: resolve stage name (via resolver or fallback map)
+  const resolveStageName = (sid) => {
+    if (resolver) return resolver.label('stage', sid);
+    return stageName[sid] || sid;
+  };
+
   // all open opps paginated to completion (trust-fix #2)
   const opps = [];
   let firstOppErr = null;
@@ -98,19 +158,22 @@ export async function collect(args, ctx) {
     totalValue: total,
     openCount: opps.length,
     pipelines: Object.entries(byPipe).map(([pid, stages]) => ({
-      pipeline: pipeName[pid] || pid,
+      pipeline: resolvePipeName(pid),
+      // I1 fix: carry sid onto mapped object; sort by model stagePosition (never undefined)
       stages: Object.entries(stages)
-        .map(([sid, v]) => ({ stage: stageName[sid] || sid, ...v }))
-        .sort((a, b) => (stageOrder[a.sid] || 0) - (stageOrder[b.sid] || 0)),
+        .map(([sid, v]) => ({ sid, stage: resolveStageName(sid), position: stagePosition[sid] ?? Infinity, ...v }))
+        .sort((a, b) => a.position - b.position)
+        .map(({ sid: _sid, position: _pos, ...rest }) => rest), // strip internal keys from output
     })),
     stuck: stuck.map(x => ({
       name: x.o.name,
       value: x.o.monetaryValue,
-      stage: stageName[x.o.pipelineStageId] || '',
+      stage: resolveStageName(x.o.pipelineStageId || x.o.stageId || ''),
       idle: ago(x.t),
       oppId: x.o.id,
       contactId: x.o.contactId,
     })),
+    ...(modelMeta ? { modelMeta } : {}),
   };
 }
 
@@ -124,6 +187,16 @@ export async function run(args, ctx) {
 
   ctx.out.card(() => {
     ctx.out.line(`\n  PIPELINE HEALTH  ·  ${money2(data.totalValue)} across ${data.openCount} open deal(s)  ·  loc ${data.location}`);
+    // C2: staleness note when model is old/offline
+    if (data.modelMeta) {
+      const mm = data.modelMeta;
+      if (mm.offline) {
+        ctx.out.line(`  · CRM model OFFLINE — stage names from cache`);
+      } else if (mm.stale) {
+        const ageD = Math.round(mm.ageMs / 86400000);
+        ctx.out.line(`  · CRM model ${ageD}d old — run sizmo sync`);
+      }
+    }
     for (const pl of data.pipelines) {
       ctx.out.line(`\n  ${pl.pipeline}`);
       for (const s of pl.stages) {