@myapihq/cli 2.6.0 → 2.6.2

package/dist/commands/doctor-findings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/doctor-findings.test.js

@@ -0,0 +1,156 @@
+// Regression cover for three doctor findings reported from a live production
+// org, where two of four warnings described healthy things as broken.
+//
+// The shared defect: the check reported a CONCLUSION ("customers may not be
+// able to reach this", "no email inbox configured") where it only had an
+// OBSERVATION ("it answered 401", "the platform's counter said zero"). Each
+// test below pins the observation and refuses the conclusion.
+import { describe, it, expect } from 'vitest';
+import { classifyReachability, _setupSection, _rewriteQuietWebhook } from './doctor.js';
+const ENTITY = { slot: 'container', name: 'skout-engine-prod' };
+describe('classifyReachability', () => {
+    // The finding: two containers behind an auth boundary were reported as
+    // "customers may not be able to reach" them. Both were up. A 401 to an
+    // anonymous probe is the designed answer and proves liveness.
+    it('treats 401 as reachable, not as a warning', () => {
+        const v = classifyReachability({ status: 401 }, ENTITY);
+        expect(v.severity).toBe('ok');
+        expect(v.message).toMatch(/reachable, authentication required/);
+    });
+    it('treats 403 the same way', () => {
+        expect(classifyReachability({ status: 403 }, ENTITY).severity).toBe('ok');
+    });
+    it('never tells the user customers cannot reach a URL that answered', () => {
+        for (const status of [200, 301, 401, 403, 404, 418, 500, 503]) {
+            const v = classifyReachability({ status }, ENTITY);
+            expect(v.hint ?? '').not.toMatch(/may not be able to reach/);
+        }
+    });
+    // Only a probe that got no answer at all is unreachable. That is the one
+    // case where the old wording was right.
+    it('reports a network failure as unreachable, and says why', () => {
+        const v = classifyReachability({ status: null, error: 'ETIMEDOUT' }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/unreachable/);
+        expect(v.hint).toBe('ETIMEDOUT');
+    });
+    it('falls back to a customer-facing hint when there is no error string', () => {
+        const v = classifyReachability({ status: null }, ENTITY);
+        expect(v.hint).toMatch(/nothing answered/);
+    });
+    // Still warns, but distinguishes "the host answered and served nothing"
+    // from "the host is down" — a different problem with a different fix.
+    it('warns on 404 while stating the host answered', () => {
+        const v = classifyReachability({ status: 404 }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/reachable, but nothing is served/);
+    });
+    it('warns on 5xx as an application error, not an outage', () => {
+        const v = classifyReachability({ status: 503 }, ENTITY);
+        expect(v.severity).toBe('warn');
+        expect(v.message).toMatch(/the application is erroring/);
+        expect(v.hint).toMatch(/logs/);
+    });
+    it('handles an entity with no name without printing undefined', () => {
+        const v = classifyReachability({ status: null }, { slot: 'funnel' });
+        expect(v.hint ?? '').not.toMatch(/undefined/);
+    });
+});
+// ── setup gaps ──────────────────────────────────────────────────────────────
+function report(sections) {
+    return {
+        org_id: '11111111-1111-4111-8111-111111111111',
+        sections: sections.map(s => ({ name: '', summary: '', issues: [], ...s })),
+    };
+}
+const ZERO_EMAILS = report([{ name: 'emails', resource_count: 0, issues: [] }]);
+function setupMessages(r, ctx) {
+    return (_setupSection(r, ctx)?.issues ?? []).map(i => ({ message: i.message, hint: i.hint ?? '' }));
+}
+describe('setup gaps are confirmed before they become instructions', () => {
+    // The finding: the platform reported resource_count 0 for an org with two
+    // active mailboxes, one of which had received mail 14 hours earlier. The
+    // doctor turned that into "Create one with: myapi email mailbox create …".
+    it('does not tell you to create a mailbox when we counted some', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 2 });
+        expect(issue.message).toMatch(/but 2 are configured/);
+        expect(issue.hint).toMatch(/Do not create another/);
+        expect(issue.hint).not.toMatch(/mailbox create/);
+    });
+    it('still reports a real gap when our own count agrees', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 0 });
+        expect(issue.message).toBe('No email inbox configured');
+        expect(issue.hint).toMatch(/mailbox create/);
+    });
+    // A failed enumeration is not evidence of absence OR presence, so the
+    // backend's view stands rather than us inventing a disagreement.
+    it('defers to the platform when we could not count', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, {});
+        expect(issue.message).toBe('No email inbox configured');
+    });
+    it('gets the singular right', () => {
+        const [issue] = setupMessages(ZERO_EMAILS, { mailboxCount: 1 });
+        expect(issue.message).toMatch(/but 1 is configured/);
+    });
+    it('applies the same rule to domains', () => {
+        const r = report([{ name: 'domains', resource_count: 0, issues: [] }]);
+        expect(setupMessages(r, { domainCount: 3 })[0].message).toMatch(/but 3 are configured/);
+        expect(setupMessages(r, { domainCount: 0 })[0].hint).toMatch(/domain register/);
+    });
+});
+// ── quiet webhooks ──────────────────────────────────────────────────────────
+const QUIET = {
+    id: 'webhook_quiet/332660b11afb07c8',
+    severity: 'warn',
+    scope: 'webhook/7a56765f164d2db5',
+    entity: { slot: 'webhook', id: '0737f583', name: 'funnel-skout-app' },
+    category: 'activity',
+    message: 'no deliveries in the last 30 days',
+    hint: 'confirm the form/page is reachable and wired to this endpoint',
+};
+describe('quiet-webhook advice is replaced by delivery history', () => {
+    // The reported near-miss: this hint reads as a cleanup instruction, and the
+    // endpoint it fired on was the ingest path for a live marketing site.
+    it('never tells you to go check whether the page is wired up', () => {
+        for (const lifetime of [{ count: 0 }, { count: 3, mostRecent: '2026-07-20T10:00:00Z' }]) {
+            const out = _rewriteQuietWebhook(QUIET, lifetime);
+            expect(out.hint ?? '').not.toMatch(/confirm the form/);
+        }
+    });
+    // "No submissions in 30 days" is the expected state for anything
+    // pre-launch, so it must not imply abandonment.
+    it('reports zero lifetime deliveries as a plain observation, with no hint', () => {
+        const out = _rewriteQuietWebhook(QUIET, { count: 0 });
+        expect(out.message).toBe('no submissions since created');
+        expect(out.hint).toBeUndefined();
+    });
+    it('says quiet-not-unused when deliveries exist', () => {
+        const out = _rewriteQuietWebhook(QUIET, { count: 3, mostRecent: '2026-07-20T10:00:00Z' });
+        expect(out.message).toMatch(/3 received in total, most recent 2026-07-20/);
+        expect(out.hint).toMatch(/quiet, not unused/);
+    });
+    it('omits the date when the API did not supply one', () => {
+        const out = _rewriteQuietWebhook(QUIET, { count: 1 });
+        expect(out.message).toMatch(/1 received in total$/);
+    });
+    // Never invent a cleanup recommendation. The ask was to stop implying
+    // cleanup on a signal that cannot support it — adding a confident orphan
+    // verdict would repeat the mistake in the other direction.
+    it('never suggests deleting anything', () => {
+        for (const lifetime of [{ count: 0 }, { count: 5 }, undefined]) {
+            const out = _rewriteQuietWebhook(QUIET, lifetime);
+            expect(`${out.message} ${out.hint ?? ''}`).not.toMatch(/delet|remov|clean/i);
+        }
+    });
+    // A failed lookup is not evidence, so the backend's finding stands rather
+    // than being softened on no information.
+    it('leaves the finding untouched when the count could not be fetched', () => {
+        expect(_rewriteQuietWebhook(QUIET, undefined)).toEqual(QUIET);
+    });
+    it('preserves id, severity and entity so dedup and rendering still work', () => {
+        const out = _rewriteQuietWebhook(QUIET, { count: 2 });
+        expect(out.id).toBe(QUIET.id);
+        expect(out.severity).toBe('warn');
+        expect(out.entity).toEqual(QUIET.entity);
+    });
+});

package/dist/commands/doctor.d.ts

@@ -14,6 +14,23 @@ export declare function _tallyTotals(sections: sdkHq.DoctorSection[]): DoctorTot
 export declare function sanitizeHint(hint: string | undefined): string | undefined;
 export interface SetupContext {
     mailingAddress?: string | null;
+    mailboxCount?: number;
+    domainCount?: number;
 }
 export declare function _setupSection(report: sdkHq.DoctorReport, ctx?: SetupContext): sdkHq.DoctorSection | null;
+export declare function _rewriteQuietWebhook(issue: sdkHq.DoctorIssue, lifetime: {
+    count: number;
+    mostRecent?: string;
+} | undefined): sdkHq.DoctorIssue;
+export declare function classifyReachability(probe: {
+    status: number | null;
+    error?: string;
+}, entity: {
+    slot: string;
+    name?: string;
+}): {
+    severity: 'ok' | 'warn';
+    message: string;
+    hint?: string;
+};
 export declare function run(_subcommand: string | undefined, _args: string[], flags: Flags): Promise<void>;

package/dist/commands/doctor.js

@@ -17,7 +17,7 @@
 // interleave with the backend's findings.
 import { promises as dns } from 'node:dns';
 import { createHash } from 'node:crypto';
-import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel } from '@myapihq/sdk';
+import { hq as sdkHq, container as sdkContainer, funnel as sdkFunnel, domain as sdkDomain, email as sdkEmail, webhook as sdkWebhook } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { info, error, printJson } from '../output.js';
 import { requireOrg } from '../helpers.js';
@@ -29,6 +29,8 @@ export const EXPOSES = [
     'GET /funnel/orgs/{org_id}/funnels/{funnel_id}/pages',
     // Best-effort read for the setup-gap mailing_address check (CAN-SPAM).
     'GET /hq/account/mailing-address',
+    // Lifetime delivery counts, to replace the 30-day 'quiet webhook' advice.
+    'GET /webhook/orgs/{org_id}/deliveries',
 ];
 export const SCHEMA = {};
 const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -116,6 +118,32 @@ function isZeroState(section) {
         return section.resource_count === 0;
     return section.issues.length === 0;
 }
+// Emits the "you have not set this up" warning ONLY when our own count agrees
+// with the backend's. When we counted resources the backend says do not
+// exist, the disagreement replaces the advice — it is both true and more
+// useful, and it never sends anyone to recreate something that already
+// exists. When we did not count (`counted` undefined), the backend's view
+// stands, since a missing check is not evidence either way.
+function confirmedGap(o) {
+    if (typeof o.counted === 'number' && o.counted > 0) {
+        return {
+            id: localIssueId(`${o.idKey}_disagreement`, o.orgId),
+            severity: 'warn',
+            scope: o.scope,
+            category: 'setup',
+            message: `Platform reports no ${o.noun} for this org, but ${o.counted} ${o.counted === 1 ? 'is' : 'are'} configured`,
+            hint: `This is a reporting bug, not a setup gap — your ${o.noun}${o.counted === 1 ? '' : 'es'} ${o.counted === 1 ? 'is' : 'are'} fine. Do not create another.`,
+        };
+    }
+    return {
+        id: localIssueId(o.idKey, o.orgId),
+        severity: 'warn',
+        scope: o.scope,
+        category: 'setup',
+        message: o.absent,
+        hint: o.hint,
+    };
+}
 export function _setupSection(report, ctx = {}) {
     const byName = new Map();
     for (const s of report.sections)
@@ -123,25 +151,27 @@ export function _setupSection(report, ctx = {}) {
     const issues = [];
     const dom = byName.get('domains');
     if (dom && isZeroState(dom)) {
-        issues.push({
-            id: localIssueId('setup_no_domain', report.org_id),
-            severity: 'warn',
+        issues.push(confirmedGap({
+            orgId: report.org_id,
+            idKey: 'setup_no_domain',
             scope: 'setup/domain',
-            category: 'setup',
-            message: 'No domain registered for this org',
+            counted: ctx.domainCount,
+            noun: 'domain',
+            absent: 'No domain registered for this org',
             hint: 'Register one with: myapi domain register <domain> && myapi domain assign <domain>',
-        });
+        }));
     }
     const em = byName.get('emails');
     if (em && isZeroState(em)) {
-        issues.push({
-            id: localIssueId('setup_no_mailbox', report.org_id),
-            severity: 'warn',
+        issues.push(confirmedGap({
+            orgId: report.org_id,
+            idKey: 'setup_no_mailbox',
             scope: 'setup/email-inbox',
-            category: 'setup',
-            message: 'No email inbox configured',
+            counted: ctx.mailboxCount,
+            noun: 'email inbox',
+            absent: 'No email inbox configured',
             hint: 'Create one with: myapi email mailbox create <username>@<your-domain>',
-        });
+        }));
     }
     // Account-scoped (so use report.org_id only for the dedup id, not as
     // entity scope). Hard-gates every transactional `email send` —
@@ -253,17 +283,30 @@ async function httpProbeSection(apiKey, orgId) {
     }
     catch { /* augmentation is best-effort — skip the slot if enumeration fails */ }
     // Funnels: probe every published page URL.
+    //
+    // And probe the funnel's own subdomain when the page list comes back empty.
+    // A funnel serving a live site can report an empty inventory — verified
+    // 2026-07-28 on a funnel answering 200 with real content on both its
+    // subdomain and a bound custom domain while `GET .../pages` returned
+    // `{"pages":[]}`. Trusting that list meant the org's public landing page,
+    // the single most customer-visible URL it has, was silently dropped from
+    // the probe. A check that quietly narrows its own scope is worse than one
+    // that fails, so fall back rather than skip.
     try {
         const funnels = await sdkFunnel.listFunnels(apiKey, orgId);
         await Promise.all(funnels.map(async (f) => {
+            const name = f.name || f.id;
+            let pageUrls = [];
             try {
                 const pages = await sdkFunnel.listFunnelPages(apiKey, orgId, f.id);
-                for (const p of pages) {
-                    if (p.url)
-                        targets.push({ url: p.url, entity: { slot: 'funnel', id: f.id, name: f.name || f.id } });
-                }
+                pageUrls = pages.map(p => p.url).filter((u) => !!u);
+            }
+            catch { /* fall through to the subdomain */ }
+            if (pageUrls.length === 0 && f.subdomain_url)
+                pageUrls = [f.subdomain_url];
+            for (const url of pageUrls) {
+                targets.push({ url, entity: { slot: 'funnel', id: f.id, name } });
             }
-            catch { /* skip this funnel */ }
         }));
     }
     catch { /* skip the slot */ }
@@ -272,29 +315,163 @@ async function httpProbeSection(apiKey, orgId) {
     const issues = [];
     await Promise.all(targets.map(async ({ url, entity }) => {
         const probe = await fetchStatus(url);
-        // 2xx/3xx = reachable. 4xx, 5xx and network failures are all `warn`.
-        const ok = probe.status != null && probe.status < 400;
+        const verdict = classifyReachability(probe, entity);
         issues.push({
-            id: localIssueId(ok ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
-            severity: ok ? 'ok' : 'warn',
+            id: localIssueId(verdict.severity === 'ok' ? 'http_ok' : 'http_unreachable', `${entity.slot}/${entity.id}/${url}`),
+            severity: verdict.severity,
             scope: `local/${url}`,
             entity,
             category: 'network',
-            message: ok
-                ? `${url} responded ${probe.status}`
-                : `${url} ${probe.status != null ? `returned ${probe.status}` : 'is unreachable'}`,
-            hint: ok ? undefined : (probe.error || `customers may not be able to reach ${entity.slot} "${entity.name}"`),
+            message: `${url} ${verdict.message}`,
+            hint: verdict.hint,
         });
     }));
-    const warns = issues.filter(i => i.severity === 'warn').length;
+    // Only a probe that got NO response means unreachable. Everything else
+    // answered, so the summary must not call it unreachable — see
+    // classifyReachability.
+    const unreachable = issues.filter(i => i.severity === 'warn').length;
     return {
         name: 'reachability',
-        summary: warns
-            ? `${warns} of ${issues.length} URL${issues.length === 1 ? '' : 's'} unreachable`
+        summary: unreachable
+            ? `${unreachable} of ${issues.length} URL${issues.length === 1 ? '' : 's'} need attention`
             : `${issues.length} URL${issues.length === 1 ? '' : 's'} reachable`,
         issues,
     };
 }
+// The backend flags a webhook that has had "no deliveries in the last 30 days"
+// and hints "confirm the form/page is reachable and wired to this endpoint".
+//
+// That hint reads as a cleanup instruction, and a user came within one command
+// of deleting the endpoint behind their live marketing site because of it. The
+// 30-day window cannot support the implication: a pre-launch product has no
+// traffic by definition, which is the normal state for most forms on a
+// platform aimed at people building something new. The signal cannot tell
+// "abandoned" from "not launched".
+//
+// It is also not correlated with the thing it implies. In the reported org the
+// endpoint holding three real waitlist signups was NOT flagged, while the one
+// serving the live landing page was.
+//
+// Lifetime deliveries can tell those apart, and we can count them. So the
+// window stays as the observation, and the count replaces the advice:
+//
+//   received > 0  → quiet, not abandoned. Never imply cleanup.
+//   received = 0  → "no submissions since created" — the expected pre-launch
+//                   state. Still no directive.
+//
+// Deliberately absent: any suggestion to DELETE. The ask was to stop implying
+// cleanup on a signal that cannot support it, and inventing a
+// confident-sounding orphan verdict would repeat the mistake in the other
+// direction. State what is true and let the operator decide.
+export function _rewriteQuietWebhook(issue, lifetime) {
+    // No evidence gathered — leave the backend's finding untouched rather than
+    // soften something we did not check.
+    if (!lifetime)
+        return issue;
+    if (lifetime.count > 0) {
+        const when = lifetime.mostRecent ? `, most recent ${lifetime.mostRecent.slice(0, 10)}` : '';
+        return {
+            ...issue,
+            message: `no deliveries in the last 30 days — ${lifetime.count} received in total${when}`,
+            hint: 'quiet, not unused — this endpoint has received real submissions',
+        };
+    }
+    return {
+        ...issue,
+        message: 'no submissions since created',
+        hint: undefined,
+    };
+}
+// Walks the report's `webhook_quiet` findings and replaces the directive with
+// what the delivery history actually shows. Best-effort: any failure leaves
+// the backend's original finding in place.
+async function enrichQuietWebhooks(apiKey, orgId, report) {
+    const quiet = [];
+    for (const s of report.sections) {
+        for (const i of s.issues) {
+            if (i.id?.startsWith('webhook_quiet/') && i.entity?.id)
+                quiet.push(i);
+        }
+    }
+    if (quiet.length === 0)
+        return;
+    const byEndpoint = new Map();
+    await Promise.all([...new Set(quiet.map(i => i.entity.id))].map(async (endpointId) => {
+        try {
+            const page = await sdkWebhook.listDeliveries(apiKey, orgId, { endpointId, limit: 100 });
+            const items = page.deliveries ?? [];
+            byEndpoint.set(endpointId, {
+                // `has_more` means we counted a floor, not a total — which is fine,
+                // because every use of this number only needs "more than zero".
+                count: items.length,
+                mostRecent: items[0]?.received_at,
+            });
+        }
+        catch {
+            byEndpoint.set(endpointId, undefined);
+        }
+    }));
+    for (const s of report.sections) {
+        s.issues = s.issues.map(i => (i.id?.startsWith('webhook_quiet/') && i.entity?.id)
+            ? _rewriteQuietWebhook(i, byEndpoint.get(i.entity.id))
+            : i);
+    }
+}
+// What an HTTP status actually tells you about reachability.
+//
+// This check used to treat any status >= 400 as "unreachable" with the hint
+// "customers may not be able to reach <name>". A user ran it against a
+// healthy production org and got two such warnings, both for containers
+// behind an auth boundary that were answering 401 exactly as designed.
+//
+// The advice was backwards. A 401 is positive evidence: something answered,
+// and its auth boundary works. As they put it, if one of those URLs ever
+// answered 200 to an unauthenticated probe, THAT would be the emergency —
+// and the old check would have called it healthy.
+//
+// The cost of a false warning is not neutral. Two of them in one run teaches
+// the reader to skim past warnings, which is where the real ones live.
+//
+// So: reachability is about whether anything answered. Only a network
+// failure or timeout is unreachable. Statuses that answered but suggest a
+// problem are still reported — as what was observed, not as a conclusion
+// about customers.
+export function classifyReachability(probe, entity) {
+    const { status } = probe;
+    if (status == null) {
+        return {
+            severity: 'warn',
+            message: 'is unreachable',
+            hint: probe.error || `nothing answered — customers may not be able to reach ${entity.slot} "${entity.name ?? '(unnamed)'}"`,
+        };
+    }
+    // Answered and served.
+    if (status < 400)
+        return { severity: 'ok', message: `responded ${status}` };
+    // Answered and refused the anonymous probe. This is the designed behaviour
+    // of anything sitting behind auth, and it proves both liveness and that the
+    // boundary holds.
+    if (status === 401 || status === 403) {
+        return { severity: 'ok', message: `responded ${status} — reachable, authentication required` };
+    }
+    // Answered, but nothing is published at that path.
+    if (status === 404 || status === 410) {
+        return {
+            severity: 'warn',
+            message: `returned ${status} — reachable, but nothing is served at this URL`,
+            hint: `the host answers, so this is a routing or publish problem rather than an outage`,
+        };
+    }
+    if (status >= 500) {
+        return {
+            severity: 'warn',
+            message: `returned ${status} — reachable, but the application is erroring`,
+            hint: `check \`myapi ${entity.slot} logs\``,
+        };
+    }
+    // Any other 4xx: report the fact, draw no conclusion.
+    return { severity: 'warn', message: `returned ${status} — reachable` };
+}
 export async function run(_subcommand, _args, flags) {
     if (flags.help) {
         info(HELP);
@@ -330,9 +507,41 @@ export async function run(_subcommand, _args, flags) {
     catch {
         mailingAddress = undefined;
     }
-    const setup = _setupSection(report, { mailingAddress });
+    // Count mailboxes and domains ourselves before any "you have not set this
+    // up" advice goes out. Both are cheap list calls, and both are the
+    // difference between a true finding and an instruction to duplicate live
+    // infrastructure. `undefined` on failure means "not checked" — the backend
+    // view then stands, because a failed check is not evidence.
+    //
+    // Mailboxes are scoped per registered domain, so this walks the org's
+    // domains rather than asking for a bare list.
+    let mailboxCount;
+    let domainCount;
+    try {
+        // NOT filter:'all' — that is account-wide and spans every org, which
+        // would count another org's mailboxes against this one. The default
+        // filter is org-scoped, which is the only correct basis for a claim
+        // about "this org".
+        const domains = await sdkDomain.listDomains(apiKey, orgId);
+        domainCount = domains.length;
+        const perDomain = await Promise.all(domains.map(async (d) => {
+            try {
+                return (await sdkEmail.listMailboxes(apiKey, { domain: d.domain })).length;
+            }
+            catch {
+                return 0;
+            }
+        }));
+        mailboxCount = perDomain.reduce((a, b) => a + b, 0);
+    }
+    catch {
+        mailboxCount = undefined;
+        domainCount = undefined;
+    }
+    const setup = _setupSection(report, { mailingAddress, mailboxCount, domainCount });
     if (setup)
         report.sections.push(setup);
+    await enrichQuietWebhooks(apiKey, orgId, report);
     const localSection = await dnsProbeSection(report);
     if (localSection)
         report.sections.push(localSection);

package/dist/commands/funnel.js

@@ -173,6 +173,39 @@ export async function del(id, flags) {
     await sdkFunnel.deleteFunnel(config.api_key, orgId, id);
     success(`Funnel ${id} deleted (org ${orgId})`);
 }
+// Returns the funnel's own URL when it answers with a non-empty body, else
+// null. Used only to contradict an empty page inventory, so every failure
+// mode — no URL, network error, timeout, 404, empty body — resolves to null
+// and lets the normal "no pages" message stand. A probe that cannot reach the
+// funnel is not evidence that the funnel is serving.
+async function probeFunnelOrigin(apiKey, orgId, funnelId) {
+    let url;
+    try {
+        const funnels = await sdkFunnel.listFunnels(apiKey, orgId);
+        const f = funnels.find(x => x.id === funnelId);
+        url = f?.domain_url || f?.subdomain_url;
+    }
+    catch {
+        return null;
+    }
+    if (!url)
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8000);
+    try {
+        const res = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+        if (!res.ok)
+            return null;
+        const body = await res.text();
+        return body.trim().length > 0 ? url : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 // List the pages currently published to a funnel. Resolves the funnel id
 // from positional arg, --funnel flag, or the user's default funnel.
 export async function pages(funnelArg, flags) {
@@ -182,6 +215,31 @@ export async function pages(funnelArg, flags) {
     if (!funnelId)
         error('Missing funnel id. Pass it as a positional arg, --funnel <id>, or set: myapi config set-funnel <id>');
     const list = await sdkFunnel.listFunnelPages(config.api_key, orgId, funnelId);
+    // An empty inventory is not proof the funnel is empty. Verified 2026-07-28:
+    // a funnel answering 200 with real content on both its subdomain and a bound
+    // custom domain reported `{"pages":[]}`. Someone auditing what is deployed
+    // reads "No pages published" as "safe to remove", and that is how a live
+    // site gets deleted by a person being careful.
+    //
+    // So when the list is empty, ask the funnel itself before agreeing it is
+    // empty. Only on the empty path — the common case costs nothing extra.
+    //
+    // This runs BEFORE the --json branch on purpose. An agent is more likely to
+    // use --json than a human is, and handing it `[]` with exit 0 is precisely
+    // the silent wrong answer. The JSON shape stays an array so existing parsers
+    // keep working; the contradiction goes to stderr and the exit code turns
+    // non-zero, so anything checking either one is protected.
+    const serving = list.length === 0
+        ? await probeFunnelOrigin(config.api_key, orgId, funnelId)
+        : null;
+    if (serving) {
+        if (flags.json)
+            printJson(list);
+        error(`Inventory reports no pages, but ${serving} is serving content right now.\n\n` +
+            'This is a reporting bug, not an empty funnel. Do NOT delete this funnel on the\n' +
+            'strength of an empty page list — confirm with curl first.');
+        return;
+    }
     if (flags.json) {
         printJson(list);
         return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.6.0",
+  "version": "2.6.2",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -40,7 +40,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.6.0"
+    "@myapihq/sdk": "^2.6.2"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",