@productbrain/cli 0.1.0-beta.41 → 0.1.0-beta.4100

package/dist/commands/admin/inspect.d.ts

@@ -4,9 +4,27 @@
  * Command names mirror `convex/admin/commandManifest.ts` — behavior is server-side (STD-101).
  */
 import { Command } from 'commander';
-/** Session or explicit `--workspace-id` (same contract as seed S3). */
-export declare function resolveWorkspaceArg(explicit?: string): string | undefined;
-export declare function requireWorkspaceArg(explicit?: string): string;
+/**
+ * Resolve an explicit workspace arg (slug or raw Convex ID) to a workspace _id.
+ *
+ * Resolution order:
+ *   1. If no explicit arg, fall back to the active session's workspaceId.
+ *   2. If arg looks like a raw Convex ID (alphanum, 20+ chars, no hyphens) — use as-is.
+ *   3. Otherwise treat as a slug and resolve via the admin endpoint.
+ *
+ * Resolves TEN-1333 — previously only raw _id values were accepted.
+ */
+export declare function resolveWorkspaceArg(explicit?: string): Promise<string | undefined>;
+export declare function requireWorkspaceArg(explicit?: string): Promise<string>;
+/**
+ * Resolve an email address to a Clerk user ID.
+ *
+ * Calls inspect:resolve-user and returns the clerkUserId string,
+ * or throws CLIError(VALIDATION_FAILED) if not found.
+ *
+ * Chain: WP-324 S1 — E4 Email-to-User Resolution (FEAT-1021)
+ */
+export declare function resolveUserArg(email: string): Promise<string>;
 /** Attach inspect subcommands to the `inspect` Commander node. */
 export declare function attachInspectCommands(inspect: Command): void;
 //# sourceMappingURL=inspect.d.ts.map

package/dist/commands/admin/inspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../src/commands/admin/inspect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAS7D;AA4HD,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuJ5D"}
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../src/commands/admin/inspect.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkBxF;AAED,wBAAsB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5E;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE;AAmXD,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqQ5D"}

package/dist/commands/admin/inspect.js

@@ -4,25 +4,106 @@
  * Command names mirror `convex/admin/commandManifest.ts` — behavior is server-side (STD-101).
  */
 import { adminCall } from '../../lib/client.js';
-import { getConfig } from '../../lib/config.js';
+import { resolveAdminConfig } from '../../lib/config.js';
 import { CLIError, ErrorCode } from '../../lib/errors.js';
+import { ask, intro, isInteractive, log, outro, select } from '../../lib/prompts.js';
 import { readSession } from '../../lib/session.js';
 import { isJsonMode } from '../../lib/runner.js';
 import { withSpinner } from '../../lib/spinner.js';
-import { adminBanner, bold, dim, green, heading, hint, icons, red } from '../../lib/style.js';
-/** Session or explicit `--workspace-id` (same contract as seed S3). */
-export function resolveWorkspaceArg(explicit) {
-    if (explicit)
+import { adminBanner, bold, cyan, dim, formatCheck, green, heading, hint, icons, red, yellow, } from '../../lib/style.js';
+// ---------------------------------------------------------------------------
+// Workspace arg helpers (same contract as seed S3)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an explicit workspace arg (slug or raw Convex ID) to a workspace _id.
+ *
+ * Resolution order:
+ *   1. If no explicit arg, fall back to the active session's workspaceId.
+ *   2. If arg looks like a raw Convex ID (alphanum, 20+ chars, no hyphens) — use as-is.
+ *   3. Otherwise treat as a slug and resolve via the admin endpoint.
+ *
+ * Resolves TEN-1333 — previously only raw _id values were accepted.
+ */
+export async function resolveWorkspaceArg(explicit) {
+    if (!explicit) {
+        return readSession()?.workspaceId;
+    }
+    // Looks like a raw Convex ID (alphanumeric, no hyphens, ≥20 chars) — use as-is
+    if (/^[a-z0-9]{20,}$/i.test(explicit)) {
         return explicit;
-    return readSession()?.workspaceId;
+    }
+    // Treat as a slug — resolve via admin endpoint
+    try {
+        const result = await adminCall('inspect:resolve-workspace', { slugOrId: explicit });
+        if (result && result._id)
+            return result._id;
+    }
+    catch {
+        // Resolution failed — return the original value and let the backend validate
+    }
+    return explicit;
 }
-export function requireWorkspaceArg(explicit) {
-    const id = resolveWorkspaceArg(explicit);
+export async function requireWorkspaceArg(explicit) {
+    const id = await resolveWorkspaceArg(explicit);
     if (!id) {
         throw new CLIError('Workspace id required — pass --workspace-id or run `pb session start` in this project.', { code: ErrorCode.VALIDATION_FAILED, category: 'validation' });
     }
     return id;
 }
+/**
+ * Resolve an email address to a Clerk user ID.
+ *
+ * Calls inspect:resolve-user and returns the clerkUserId string,
+ * or throws CLIError(VALIDATION_FAILED) if not found.
+ *
+ * Chain: WP-324 S1 — E4 Email-to-User Resolution (FEAT-1021)
+ */
+export async function resolveUserArg(email) {
+    try {
+        const result = await adminCall('inspect:resolve-user', { email });
+        if (result && result.found)
+            return result.clerkUserId;
+    }
+    catch (err) {
+        throw new CLIError(`Could not resolve user "${email}": ${err}`, { code: ErrorCode.VALIDATION_FAILED, category: 'validation' });
+    }
+    throw new CLIError(`No user found for email "${email}". Check the email address and try again.`, { code: ErrorCode.VALIDATION_FAILED, category: 'validation' });
+}
+function renderReadinessSummary(r) {
+    if (!r)
+        return dim('—');
+    const total = r.total ?? 0;
+    const pending = r.toMigrate ?? 0;
+    if (pending === 0)
+        return `${green(icons.pass)} ${total} collections — config current`;
+    return `${yellow(icons.warn)} ${total} collections — ${yellow(String(pending))} pending migration`;
+}
+function renderConsistencySummary(c) {
+    if (!c || c.error)
+        return dim(c?.error ?? '—');
+    const checked = c.totalChecked ?? 0;
+    const invalid = c.invalidCount ?? 0;
+    const unvalidated = (c.unvalidated ?? []).reduce((a, u) => a + u.entryCount, 0);
+    const gaps = (c.purposeGaps ?? []).length;
+    const main = invalid === 0
+        ? `${green(icons.pass)} ${checked} checked — ${green('clean')}`
+        : `${red(icons.fail)} ${checked} checked — ${red(`${invalid} invalid`)}`;
+    const extras = [];
+    if (unvalidated > 0)
+        extras.push(`${unvalidated} unvalidated`);
+    if (gaps > 0)
+        extras.push(`${gaps} purpose gaps`);
+    return extras.length > 0 ? `${main}  ${dim(extras.join(', '))}` : main;
+}
+function renderDraftsSummary(d) {
+    if (!d || d.error)
+        return dim(d?.error ?? '—');
+    const count = d.totalDraftCount ?? 0;
+    if (count === 0)
+        return `${green(icons.pass)} No uncommitted drafts`;
+    const oldest = d.oldestDraftAgeDays != null ? `  ${dim(`oldest: ${d.oldestDraftAgeDays}d`)}` : '';
+    return `${yellow(icons.warn)} ${bold(String(count))} drafts${oldest}`;
+}
 function filterCompletenessForWorkspace(completeness, workspaceId) {
     if (!completeness || typeof completeness !== 'object') {
         return { global: completeness, workspaceFindings: [] };
@@ -33,76 +114,285 @@ function filterCompletenessForWorkspace(completeness, workspaceId) {
     return { global: completeness, workspaceFindings };
 }
 function printHealthDashboard(data) {
-    adminBanner(getConfig().siteUrl);
-    process.stdout.write(`${bold('Admin inspect — health dashboard')}\n\n`);
+    process.stdout.write(`${bold('Health dashboard')}\n\n`);
+    const r = data.readiness;
     process.stdout.write(`${heading('Readiness config')}\n`);
-    process.stdout.write(dim(JSON.stringify(data.readiness, null, 2)) + '\n\n');
+    process.stdout.write(`  ${renderReadinessSummary(r)}\n`);
+    if (r?.toMigrate && r.toMigrate > 0) {
+        hint('pb admin seed run readiness-config   Apply pending migration');
+        process.stdout.write(`  ${cyan('→ Suggested next action:')} ${bold('Migrate readiness config')}  ${dim('pb admin seed run readiness-config')}\n`);
+    }
+    process.stdout.write('\n');
     if (!data.workspaceId) {
-        process.stdout.write(dim('Workspace-scoped panels skipped — pass --workspace-id (or use an active session).\n'));
+        process.stdout.write(dim('  Workspace panels require --workspace-id (or an active session).\n\n'));
+        hint('pb session start                    Start session with workspace context');
+        process.stdout.write('\n');
         return;
     }
+    // Collections
     process.stdout.write(`${heading('Collections')}\n`);
-    process.stdout.write(dim(JSON.stringify(data.collections, null, 2)) + '\n\n');
+    const cols = data.collections;
+    if (cols?.workspace) {
+        process.stdout.write(`  ${bold(cols.workspace.name)} ${dim(`(${cols.workspace.slug})`)}  ${dim(`${cols.totalCollections ?? 0} collections, ${(cols.totalEntries ?? 0).toLocaleString()} entries`)}\n`);
+        // Show completeness overview if available
+        const { workspaceFindings } = filterCompletenessForWorkspace(data.collections, data.workspaceId);
+        const withGaps = workspaceFindings.filter((f) => f.missing.length > 0);
+        if (withGaps.length > 0) {
+            process.stdout.write(`  ${yellow(icons.warn)} ${withGaps.length} collections with completeness gaps\n`);
+        }
+        else {
+            process.stdout.write(`  ${green(icons.pass)} All collections complete\n`);
+        }
+    }
+    else {
+        process.stdout.write(`  ${dim('—')}\n`);
+    }
+    process.stdout.write('\n');
+    // Data consistency
     process.stdout.write(`${heading('Data consistency')}\n`);
-    process.stdout.write(dim(JSON.stringify(data.consistency, null, 2)) + '\n\n');
+    process.stdout.write(`  ${renderConsistencySummary(data.consistency)}\n\n`);
+    // Drafts
     process.stdout.write(`${heading('Draft debt')}\n`);
-    process.stdout.write(dim(JSON.stringify(data.drafts, null, 2)) + '\n');
-    hint('Read-only — no confirmation required.');
+    process.stdout.write(`  ${renderDraftsSummary(data.drafts)}\n\n`);
+    hint('pb admin inspect collections --workspace-id <id>   Collection detail + gaps');
+    hint('pb admin inspect drafts --workspace-id <id>        Draft breakdown');
+    hint('pb admin inspect data-consistency --workspace-id <id>');
+    process.stdout.write('\n');
 }
 function printCollectionsMerged(workspaceId, collection, completeness, workspaceFindings) {
-    adminBanner(getConfig().siteUrl);
     process.stdout.write(`${bold('Collections + completeness')}\n`);
     process.stdout.write(dim(`workspaceId: ${workspaceId}`) + '\n\n');
     if (collection && typeof collection === 'object' && 'collections' in collection) {
         const c = collection;
-        process.stdout.write(`${c.workspace.name} (${c.workspace.slug}) — ${c.totalCollections} collections, ${c.totalEntries} entries\n\n`);
+        const ws = c.workspace;
+        process.stdout.write(`${bold(ws.name)} ${dim(`(${ws.slug})`)}  ${dim(`${c.totalCollections} collections, ${(c.totalEntries ?? 0).toLocaleString()} entries`)}\n\n`);
         const missingBySlug = new Map();
         for (const f of workspaceFindings) {
             missingBySlug.set(f.slug, f.missing);
         }
         const wSlug = 24;
         const wCount = 8;
-        process.stdout.write(`${bold('Slug'.padEnd(wSlug))}  ${bold('Entries'.padStart(wCount))}  ${bold('Completeness gaps')}\n`);
+        process.stdout.write(`${bold('Slug'.padEnd(wSlug))}  ${bold('Entries'.padStart(wCount))}  ${bold('Completeness')}\n`);
+        process.stdout.write(dim('─'.repeat(wSlug + wCount + 20)) + '\n');
         for (const row of c.collections) {
             const gaps = missingBySlug.get(row.slug);
             const gapStr = gaps && gaps.length > 0 ? red(gaps.join(', ')) : green(icons.pass + ' ok');
-            process.stdout.write(`${row.slug.padEnd(wSlug)}  ${String(row.entryCount).padStart(wCount)}  ${gapStr}\n`);
+            process.stdout.write(`${cyan(row.slug.padEnd(wSlug))}  ${String(row.entryCount).padStart(wCount)}  ${gapStr}\n`);
         }
+        process.stdout.write('\n');
     }
     else {
         process.stdout.write(dim(JSON.stringify(collection, null, 2)) + '\n');
     }
-    process.stdout.write(`\n${heading('Global completeness summary (platform)')}\n`);
-    process.stdout.write(dim(JSON.stringify(completeness, null, 2)) + '\n');
-    hint('inspect:collection-completeness is platform-wide; rows above filter findings to this workspace.');
+    if (workspaceFindings.length > 0) {
+        const withGaps = workspaceFindings.filter((f) => f.missing.length > 0);
+        process.stdout.write(`${heading('Completeness gaps for this workspace')}  ${dim(`(${withGaps.length} collections)`)}\n`);
+        for (const f of withGaps.slice(0, 10)) {
+            process.stdout.write(`  ${red(icons.fail)} ${f.slug.padEnd(24)} ${dim(f.missing.join(', '))}\n`);
+        }
+        if (withGaps.length > 10) {
+            process.stdout.write(`  ${dim(`... ${withGaps.length - 10} more`)}\n`);
+        }
+        process.stdout.write('\n');
+    }
+    hint('inspect:collection-completeness is platform-wide; results above are filtered to this workspace.');
 }
 function printPeopleDuplicates(workspaceId, duplicates) {
-    adminBanner(getConfig().siteUrl);
     if (!Array.isArray(duplicates)) {
         process.stdout.write(dim(JSON.stringify(duplicates, null, 2)) + '\n');
         return;
     }
     const forWs = duplicates.filter((d) => String(d.workspaceId) === String(workspaceId));
-    process.stdout.write(`${bold('People duplicates')}\n`);
-    process.stdout.write(dim(`workspaceId: ${workspaceId}`) + '\n\n');
+    process.stdout.write(`${bold('People duplicates')} ${dim(`— workspaceId: ${workspaceId}`)}\n\n`);
     if (forWs.length === 0) {
-        process.stdout.write(`${green(icons.pass)} No duplicate (workspaceId, clerkUserId) pairs for this workspace.\n`);
+        process.stdout.write(`  ${formatCheck('pass', 'Duplicates', 'None found for this workspace.')}\n`);
         return;
     }
-    process.stdout.write(`${red(icons.fail)} ${forWs.length} duplicate group(s):\n\n`);
+    process.stdout.write(`  ${red(icons.fail)} ${forWs.length} duplicate group(s):\n\n`);
     for (const d of forWs) {
         process.stdout.write(dim(JSON.stringify(d, null, 2)) + '\n\n');
     }
 }
+function printWorkspaceDiagnostic(data) {
+    if (!data || typeof data !== 'object' || 'error' in data) {
+        const msg = data?.error ?? 'Unknown error';
+        process.stdout.write(`${red(icons.fail)} ${msg}\n`);
+        return;
+    }
+    const d = data;
+    process.stdout.write(`${bold('Workspace')} ${dim('—')} ${bold(d.workspace.name)} ${dim(`(${d.workspace.slug})`)}\n\n`);
+    for (const [slug, info] of Object.entries(d.targetCollections)) {
+        const status = info.exists ? 'pass' : 'fail';
+        const detail = info.exists ? `${info.entryCount} entries` : 'missing';
+        process.stdout.write(`  ${formatCheck(status, slug, detail)}\n`);
+    }
+    process.stdout.write('\n');
+    process.stdout.write(`  ${d.totalCollections} total collections\n`);
+    const slugList = d.allCollectionSlugs.join(', ');
+    const truncated = slugList.length > 100 ? slugList.slice(0, 100) + '...' : slugList;
+    process.stdout.write(`  ${dim(truncated)}\n`);
+    // Surface actionable next command when target collections are missing
+    const missingCount = Object.values(d.targetCollections).filter((v) => !v.exists).length;
+    if (missingCount > 0) {
+        process.stdout.write('\n');
+        process.stdout.write(`  ${cyan('→ Suggested next action:')} ${bold('Seed id prefixes')}  ${dim('pb admin seed run seed:id-prefixes')}\n`);
+    }
+}
+function printDataConsistency(data) {
+    if (!data || typeof data !== 'object' || 'error' in data) {
+        const msg = data?.error ?? 'Unknown error';
+        process.stdout.write(`${red(icons.fail)} ${msg}\n`);
+        return;
+    }
+    const d = data;
+    process.stdout.write(`${bold('Data consistency')} ${dim(`— ${d.workspace.name} (${d.workspace.slug})`)}\n\n`);
+    const checked = d.totalChecked ?? 0;
+    const invalid = d.invalidCount ?? 0;
+    const unvalidatedEntries = (d.unvalidated ?? []).reduce((a, u) => a + u.entryCount, 0);
+    const purposeGapCount = (d.purposeGaps ?? []).length;
+    process.stdout.write(`  ${formatCheck(invalid === 0 ? 'pass' : 'fail', `${checked} checked`, invalid === 0 ? 'clean' : `${invalid} invalid`)}\n`);
+    if (unvalidatedEntries > 0) {
+        process.stdout.write(`  ${formatCheck('warn', `${unvalidatedEntries} unvalidated`, `(${(d.unvalidated ?? []).length} schemaless collections)`)}\n`);
+    }
+    if (purposeGapCount > 0) {
+        process.stdout.write(`  ${formatCheck('warn', `${purposeGapCount} purpose gaps`, '(collection purpose < 20 chars)')}\n`);
+    }
+    if (d.invalid && d.invalid.length > 0) {
+        process.stdout.write(`\n${heading('Invalid entries')}\n`);
+        for (const e of d.invalid.slice(0, 10)) {
+            process.stdout.write(`  ${red(icons.fail)} ${e.entryId.padEnd(12)} ${dim(e.collectionSlug.padEnd(20))} ${dim(e.errors[0] ?? '')}\n`);
+        }
+        if (d.invalid.length > 10) {
+            process.stdout.write(`  ${dim(`... ${d.invalid.length - 10} more`)}\n`);
+        }
+    }
+    if ((d.unvalidated ?? []).length > 0) {
+        process.stdout.write(`\n${heading('Schemaless collections')}\n`);
+        for (const u of d.unvalidated ?? []) {
+            process.stdout.write(`  ${cyan(u.collectionSlug.padEnd(26))} ${dim(String(u.entryCount))} entries\n`);
+        }
+    }
+    if (purposeGapCount > 0) {
+        process.stdout.write(`\n${heading('Purpose gaps')}\n`);
+        for (const g of d.purposeGaps ?? []) {
+            process.stdout.write(`  ${cyan(g.collectionSlug.padEnd(26))} ${dim(`${g.purposeLength} chars`)}\n`);
+        }
+    }
+    process.stdout.write('\n');
+}
+function printDraftDebt(data) {
+    if (!data || typeof data !== 'object' || 'error' in data) {
+        const msg = data?.error ?? 'Unknown error';
+        process.stdout.write(`${red(icons.fail)} ${msg}\n`);
+        return;
+    }
+    const d = data;
+    process.stdout.write(`${bold('Draft debt')} ${dim(`— ${d.workspace.name} (${d.workspace.slug})`)}\n\n`);
+    const total = d.totalDraftCount ?? 0;
+    if (total === 0) {
+        process.stdout.write(`  ${formatCheck('pass', 'Drafts', 'None — all entries committed.')}\n`);
+        return;
+    }
+    const oldestStr = d.oldestDraftAgeDays != null ? `  ${dim(`oldest: ${d.oldestDraftAgeDays}d`)}` : '';
+    process.stdout.write(`  ${yellow(icons.warn)} ${bold(String(total))} uncommitted drafts${oldestStr}\n\n`);
+    const byCol = d.byCollection ?? {};
+    const sorted = Object.entries(byCol).sort(([, a], [, b]) => b.count - a.count);
+    const wSlug = Math.max(12, ...sorted.map(([s]) => s.length));
+    process.stdout.write(`${bold('Collection'.padEnd(wSlug))}  ${bold('Count')}  ${bold('Oldest')}\n`);
+    process.stdout.write(dim('─'.repeat(wSlug + 20)) + '\n');
+    for (const [slug, bucket] of sorted) {
+        const oldest = bucket.entries[0]?.ageDays;
+        const oldestLabel = oldest != null ? `${oldest}d` : '—';
+        process.stdout.write(`${cyan(slug.padEnd(wSlug))}  ${String(bucket.count).padStart(5)}  ${dim(oldestLabel)}\n`);
+    }
+    process.stdout.write('\n');
+    hint('pb capture "..."    Commit or kill drafts to clear debt');
+}
+// ---------------------------------------------------------------------------
+// Attach inspect subcommands
+// ---------------------------------------------------------------------------
 /** Attach inspect subcommands to the `inspect` Commander node. */
 export function attachInspectCommands(inspect) {
+    const INSPECT_CMDS = [
+        { name: 'health', description: 'Combined dashboard — readiness + collections + consistency + drafts' },
+        { name: 'workspace', description: 'Target collection health (roles, teams, principles, ...)' },
+        { name: 'collections', description: 'Entry counts + completeness signals per collection' },
+        { name: 'users', description: 'Duplicate (workspaceId, clerkUserId) people entries' },
+        { name: 'data-consistency', description: 'Schema validation — invalid and unvalidated entries' },
+        { name: 'drafts', description: 'Uncommitted draft debt — counts and age' },
+    ];
+    // Default action when `pb admin inspect` is invoked with no subcommand.
+    inspect.action(async () => {
+        if (isJsonMode()) {
+            process.stdout.write(JSON.stringify({ commands: INSPECT_CMDS }, null, 2) + '\n');
+            return;
+        }
+        let siteUrl = '';
+        try {
+            siteUrl = resolveAdminConfig().siteUrl;
+        }
+        catch { /* not configured */ }
+        if (siteUrl)
+            adminBanner(siteUrl);
+        if (isInteractive()) {
+            intro('Inspect — Workspace Diagnostics');
+            const choice = await select({
+                message: 'Which diagnostic would you like to run?',
+                options: [
+                    ...INSPECT_CMDS.map((cmd) => ({
+                        value: cmd.name,
+                        label: cmd.name,
+                        hint: cmd.description,
+                    })),
+                    { value: '__exit', label: 'Exit', hint: 'No action' },
+                ],
+            });
+            if (choice === '__exit') {
+                outro('Use pb admin inspect <command> --workspace-id <id> to run directly');
+                return;
+            }
+            // Try session workspace first, then prompt
+            const sessionWsId = readSession()?.workspaceId;
+            let workspaceId;
+            if (sessionWsId) {
+                workspaceId = sessionWsId;
+                log.info(`Using session workspace: ${dim(sessionWsId)}`);
+            }
+            else {
+                workspaceId = await ask({
+                    message: 'Workspace ID:',
+                    validate: (v) => v.trim() ? undefined : 'Workspace ID is required',
+                });
+            }
+            outro(`→ run: pb admin inspect ${choice} --workspace-id ${workspaceId}`);
+            return;
+        }
+        // Non-interactive (non-JSON) fallback — existing static listing
+        process.stdout.write(`${heading('Inspect commands')}\n\n`);
+        const wName = Math.max(...INSPECT_CMDS.map((c) => c.name.length));
+        for (const cmd of INSPECT_CMDS) {
+            process.stdout.write(`  ${cyan(cmd.name.padEnd(wName))}  ${dim(cmd.description)}\n`);
+        }
+        process.stdout.write('\n');
+        process.stdout.write(`  ${dim('All read-only — no confirmation required.')}\n\n`);
+        process.stdout.write(`  ${cyan('pb admin inspect health --workspace-id <id>')}\n`);
+        process.stdout.write(`  ${cyan('pb admin inspect collections --workspace-id <id>')}\n`);
+        process.stdout.write('\n');
+    });
     inspect
         .command('health')
         .description('Combined dashboard: readiness + collection counts + consistency + draft debt')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = resolveWorkspaceArg(options.workspaceId);
-        const payload = await withSpinner('Loading admin health', async () => {
+        const ws = await resolveWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: health');
+        }
+        const payload = await withSpinner('Loading health dashboard', async () => {
             if (!ws) {
                 const readiness = await adminCall('inspect:readiness-config', {});
                 return {
@@ -113,13 +403,23 @@ export function attachInspectCommands(inspect) {
                     workspaceId: null,
                 };
             }
-            const [readiness, collections, consistency, drafts] = await Promise.all([
-                adminCall('inspect:readiness-config', {}),
-                adminCall('inspect:collection', { workspaceId: ws }),
-                adminCall('diagnose:data-consistency', { workspaceId: ws }),
-                adminCall('diagnose:draft-debt', { workspaceId: ws }),
-            ]);
-            return { readiness, collections, consistency, drafts, workspaceId: ws };
+            try {
+                const [readiness, collections, consistency, drafts] = await Promise.all([
+                    adminCall('inspect:readiness-config', {}),
+                    adminCall('inspect:collection', { workspaceId: ws }),
+                    adminCall('diagnose:data-consistency', { workspaceId: ws }),
+                    adminCall('diagnose:draft-debt', { workspaceId: ws }),
+                ]);
+                return { readiness, collections, consistency, drafts, workspaceId: ws };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/v\.id\("workspaces"\)/.test(msg) || /does not match.*validator/.test(msg)) {
+                    throw new CLIError('The --workspace-id value must be a workspaces table ID. You may have passed an ID from a different table.\n' +
+                        '  Run `pb session start` to auto-resolve your workspace ID, or find the correct ID in the Convex dashboard under the workspaces table.', { code: ErrorCode.VALIDATION_FAILED, category: 'validation' });
+                }
+                throw err;
+            }
         });
         if (isJsonMode()) {
             process.stdout.write(JSON.stringify({
@@ -137,27 +437,42 @@ export function attachInspectCommands(inspect) {
             drafts: payload.drafts,
             workspaceId: payload.workspaceId ?? null,
         });
+        outro('Read-only inspection complete');
     });
     inspect
         .command('workspace')
-        .description('Workspace health diagnostic (diagnose:workspace)')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .description('Target collection health — roles, teams, principles, policies, business-rules, glossary')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = requireWorkspaceArg(options.workspaceId);
+        const ws = await requireWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: workspace');
+        }
         const data = await withSpinner('Diagnosing workspace', () => adminCall('diagnose:workspace', { workspaceId: ws }));
         if (isJsonMode()) {
             process.stdout.write(JSON.stringify(data, null, 2) + '\n');
             return;
         }
-        adminBanner(getConfig().siteUrl);
-        process.stdout.write(dim(JSON.stringify(data, null, 2)) + '\n');
+        printWorkspaceDiagnostic(data);
+        outro('Read-only inspection complete');
     });
     inspect
         .command('collections')
-        .description('Collection entry counts + completeness signals (inspect:collection + inspect:collection-completeness)')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .description('Collection entry counts + completeness signals')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = requireWorkspaceArg(options.workspaceId);
+        const ws = await requireWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: collections');
+        }
         const [collection, completeness] = await withSpinner('Inspecting collections', () => Promise.all([
             adminCall('inspect:collection', { workspaceId: ws }),
             adminCall('inspect:collection-completeness', { limit: 500 }),
@@ -168,13 +483,21 @@ export function attachInspectCommands(inspect) {
             return;
         }
         printCollectionsMerged(ws, collection, completeness, workspaceFindings);
+        outro('Read-only inspection complete');
     });
     inspect
         .command('users')
-        .description('Duplicate people entries for a workspace (inspect:people-duplicates, filtered)')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .description('Duplicate people entries (workspaceId + clerkUserId pairs)')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = requireWorkspaceArg(options.workspaceId);
+        const ws = await requireWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: users');
+        }
         const duplicates = await withSpinner('Checking people duplicates', () => adminCall('inspect:people-duplicates', {}));
         if (isJsonMode()) {
             const list = Array.isArray(duplicates)
@@ -184,34 +507,49 @@ export function attachInspectCommands(inspect) {
             return;
         }
         printPeopleDuplicates(ws, duplicates);
+        outro('Read-only inspection complete');
     });
     inspect
         .command('data-consistency')
-        .description('Data consistency diagnostic (diagnose:data-consistency)')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .description('Schema validation — invalid entries, unvalidated collections, purpose gaps')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = requireWorkspaceArg(options.workspaceId);
+        const ws = await requireWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: data-consistency');
+        }
         const data = await withSpinner('Running data consistency check', () => adminCall('diagnose:data-consistency', { workspaceId: ws }));
         if (isJsonMode()) {
             process.stdout.write(JSON.stringify(data, null, 2) + '\n');
             return;
         }
-        adminBanner(getConfig().siteUrl);
-        process.stdout.write(dim(JSON.stringify(data, null, 2)) + '\n');
+        printDataConsistency(data);
+        outro('Read-only inspection complete');
     });
     inspect
         .command('drafts')
-        .description('Draft debt report (diagnose:draft-debt)')
-        .option('--workspace-id <id>', 'Workspace id (defaults to session workspace when set)')
+        .description('Uncommitted draft debt — total, breakdown by collection, oldest age')
+        .option('--workspace-id <id>', 'Convex workspaces table _id (not a slug or ID from another table)')
         .action(async (options) => {
-        const ws = requireWorkspaceArg(options.workspaceId);
+        const ws = await requireWorkspaceArg(options.workspaceId);
+        if (!isJsonMode()) {
+            try {
+                adminBanner(resolveAdminConfig().siteUrl);
+            }
+            catch { /* not configured */ }
+            intro('Inspect: drafts');
+        }
         const data = await withSpinner('Checking draft debt', () => adminCall('diagnose:draft-debt', { workspaceId: ws }));
         if (isJsonMode()) {
             process.stdout.write(JSON.stringify(data, null, 2) + '\n');
             return;
         }
-        adminBanner(getConfig().siteUrl);
-        process.stdout.write(dim(JSON.stringify(data, null, 2)) + '\n');
+        printDraftDebt(data);
+        outro('Read-only inspection complete');
     });
 }
 //# sourceMappingURL=inspect.js.map