@credda/cli 0.1.0 → 0.1.2

package/dist/cli.js

@@ -7,7 +7,7 @@
  * looks up and offline-verifies EXISTING, already-computed trust facts.
  * `mint`/`revoke` manage a share token (a capability, not a score write).
  */
-export const VERSION = '0.0.1';
+export const VERSION = '0.1.2';
 export const HELP = `credda — portable trust from the terminal
 
 Public (no API key):
@@ -18,22 +18,133 @@ Public (no API key):
                                  export bundle (auto-detected). '-' = stdin.
   credda registry                Federated trust registry
   credda did                     Issuer DID document
+  credda benchmarks              Cohort-benchmark catalog (dimensions + k-anonymity)
+  credda reason-codes            Adverse-action reason-code catalog (ECOA / Reg B)
+  credda badges list             Open Badges 3.0 achievements this issuer signs
+  credda badges get <badgeId>    One achievement definition
+  credda professional-record public <token>
+                                 The professional record behind a share token
+                                 (the subject's own consent to present it)
 
 Platform (needs CREDDA_API_KEY):
   credda score <userId>          Current score
   credda explain <userId>        Factor-level score explanation
   credda components <userId>     Six named 0-100 score components
   credda risk <userId>           Advisory risk signals
-  credda usage [days]            Your platform's metered API usage
+  credda trust-summary <userId> [--narrative]
+                                 Deterministic, evidence-based trust summary
+                                 (explains; never a verdict). --narrative adds an
+                                 advisory AI retelling when the server has AI on.
+  credda benchmark <userId> [--dimension <d>]
+                                 Where a subject sits within its cohort:
+                                 percentile + the cohort distribution
+  credda distribution [--dimension <d>] [--cohort <c>]
+                                 Aggregate, k-anonymised cohort distribution.
+                                 Omit --cohort for every cohort on the dimension.
+  credda users [--score-min <n>] [--score-max <n>] [--band <b>] [--subject-type <PERSON|AGENT>]
+        [--active-since <iso>] [--verified] [--min-verified <n>]
+        [--sort <score|lastActivity|registered|externalId>] [--order <asc|desc>]
+        [--cursor <c>] [--limit <n>]
+                                 Query + export your book of subjects
+  credda usage [days] [--from <date> --to <date>] [--csv <outfile>]
+                                 Your platform's metered API usage. Either a
+                                 trailing [days] window OR an inclusive
+                                 --from/--to date range (YYYY-MM-DD), not both.
+                                 --csv writes the flat CSV statement to a file.
+  credda activity [--action <A>] [--from <t> --to <t>] [--cursor <c>] [--limit <n>]
+                                 Your platform's own activity/audit log,
+                                 newest-first, cursor-paginated
+  credda verified-profile <userId>
+                                 How much of a subject's CLAIMED record
+                                 (education/skills/certifications/employment) is
+                                 third-party verified. Counts whether a claim is
+                                 verified, never how prestigious it is — and it
+                                 can never move the Reliability Score.
+  credda qualify <userId> --category <education|skill|certification|employment>
+        [--label <l>] [--issuer <i>] [--verified-by <witness>]
+                                 Record a qualification claim. Always recorded;
+                                 counts as VERIFIED only with a genuine
+                                 third-party --verified-by witness.
+  credda professional-record get <userId>
+                                 Résumé-shaped summary of a VERIFIED work record.
+                                 Describes a record — not a hiring verdict, a
+                                 background check, or a consumer report.
+  credda professional-record credential <userId> [--ttl <seconds>]
+                                 Mint the signed, offline-verifiable Professional
+                                 Record Credential (+ an "Add to LinkedIn" link)
   credda mint <userId>           Mint a share token for a user
   credda revoke <userId>         Revoke a user's share token
 
+Confirmation requests — the counterparty-confirmation primitive. You PROPOSE an
+outcome and deliver the one-time token to the counterparty over YOUR OWN channel;
+the event is written, verified, only when that distinct party confirms:
+  credda confirmations create --user <externalId> --type <eventType>
+        --counterparty <ref> [--counterparty-name <n>] [--description <d>]
+        [--stake <HIGH|MEDIUM|LOW>] [--value <n>] [--due <iso>] [--completed <iso>]
+        [--return-url <url>] [--expires-in <days>] [--idempotency-key <k>]
+                                 Needs CREDDA_API_KEY. Token shown ONCE.
+  credda confirmations list [--status <s>] [--cursor <c>] [--limit <n>]
+  credda confirmations get <id>
+  credda confirmations cancel <id>
+  credda confirmations preview <id> --token <t>
+                                 What the counterparty is asked to confirm.
+                                 NO API key — the token is the capability.
+  credda confirmations respond <id> --token <t> (--confirm | --decline)
+                                 The counterparty's decision. NO API key.
+                                 --confirm writes the event; --decline writes
+                                 nothing. Single-use either way.
+
+Threshold policies (needs CREDDA_API_KEY) — declarative "tell me when this line
+is crossed"; delivers policy.threshold_crossed through your webhooks. Config
+only: a policy never reads into, blocks, or changes a score:
+  credda policies list [--cursor <c>] [--limit <n>]
+  credda policies get <id>
+  credda policies create --name <n> (--user <externalId> | --all)
+        --metric <score|component|band|verified_events>
+        [--direction <up|down|enter|leave>] [--threshold <n>]
+        [--component <reliability|timeliness|trustworthiness|verification|consistency|momentum>]
+        [--band <b>]
+  credda policies update <id> [--name <n>] [--direction <d>] [--threshold <n>]
+        [--component <c>] [--band <b>] [--activate | --deactivate]
+                                 The metric is immutable — delete + recreate.
+  credda policies delete <id>
+
+Score monitors (needs CREDDA_API_KEY) — edge-triggered watches that deliver
+"monitor.triggered" through your webhooks; notification config only, a
+monitor never affects a score:
+  credda monitors list [--cursor <c>] [--limit <n>]
+  credda monitors get <id>
+  credda monitors create --user <externalId> [--below <score>] [--above <score>] [--band-change]
+                                 At least one condition required. --below fires
+                                 on a downward crossing (and on a first score
+                                 already below it), --above on an upward
+                                 crossing, --band-change on any band change.
+  credda monitors delete <id>
+
+Bulk screenings (needs CREDDA_API_KEY) — async batch score reads, up to
+10,000 ids per job, strictly read-only:
+  credda screen <ids...>         Submit ids (comma/space separated), or:
+  credda screen --file <path>    One id per line, or a CSV whose FIRST column
+                                 is the id (a leading "id"/"userId"/
+                                 "externalId" header row is skipped).
+         [--wait]                Poll until the job finishes, then print the
+                                 summary (exit 1 if the job FAILED).
+  credda screenings list [--cursor <c>] [--limit <n>]
+  credda screenings get <id>     Job status + summary
+  credda screenings results <id> [--csv <outfile>]
+                                 Per-user results (JSON; --csv writes the CSV
+                                 attachment to a file instead)
+
 Webhooks (needs CREDDA_API_KEY):
   credda webhooks list                     Your webhook subscriptions
   credda webhooks create <url> <event..>   Subscribe (secret shown ONCE)
   credda webhooks delete <id>              Remove a webhook
   credda webhooks test <id>                Send a synthetic signed delivery
   credda webhooks deliveries <id>          Recent delivery attempts (incl. retries)
+  credda webhooks recent [event..]         Recent events across ALL your endpoints
+                                           (sample data for automation platforms;
+                                           falls back to catalog examples, flagged
+                                           isExample, when nothing has fired yet)
 
 Local development:
   credda listen [port]           Local webhook receiver: verifies each delivery's
@@ -63,6 +174,134 @@ function requireArg(args, name) {
 function show(ctx, value) {
     ctx.out(JSON.stringify(value, null, 2));
 }
+/**
+ * Extra stderr lines for a failed command.
+ *
+ * The important one is the **request id**: it is the single fastest way for
+ * Credda to diagnose a failure, and a CLI user has nowhere else to find it.
+ * Also surfaces the machine code (so it can be looked up in
+ * `GET /api/v1/errors`) and any `Retry-After` the server asked for.
+ *
+ * Duck-typed rather than `instanceof CreddaError` on purpose — the router
+ * imports only TYPES from the SDK, so it stays pure and trivially mockable.
+ * Pure and exported for testing.
+ */
+export function errorHints(e) {
+    if (!e || typeof e !== 'object')
+        return [];
+    const err = e;
+    const lines = [];
+    if (typeof err.code === 'string' && err.code) {
+        lines.push(`  code:      ${err.code}  (see https://api.credda.io/api/v1/errors)`);
+    }
+    if (typeof err.requestId === 'string' && err.requestId) {
+        lines.push(`  requestId: ${err.requestId}  (quote this to support)`);
+    }
+    if (typeof err.retryAfterMs === 'number' && err.retryAfterMs > 0) {
+        lines.push(`  retry in:  ${Math.ceil(err.retryAfterMs / 1000)}s`);
+    }
+    return lines;
+}
+/**
+ * Tiny flag parser: `--name value` for valued flags, bare `--name` for
+ * booleans, everything else positional. Unknown `--flags` are an error rather
+ * than silently becoming positionals.
+ */
+export function parseFlags(args, spec = {}) {
+    const valued = new Set(spec.valued ?? []);
+    const bools = new Set(spec.boolean ?? []);
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith('--')) {
+            const name = a.slice(2);
+            if (bools.has(name)) {
+                flags[name] = true;
+            }
+            else if (valued.has(name)) {
+                const v = args[++i];
+                if (v === undefined)
+                    throw new Error(`--${name} needs a value — see "credda help"`);
+                flags[name] = v;
+            }
+            else {
+                throw new Error(`unknown flag --${name} — see "credda help"`);
+            }
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { positional, flags };
+}
+function numFlag(flags, name) {
+    const v = flags[name];
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (typeof v !== 'string' || v === '' || !Number.isFinite(n)) {
+        throw new Error(`--${name} must be a number`);
+    }
+    return n;
+}
+function intFlag(flags, name) {
+    const n = numFlag(flags, name);
+    if (n !== undefined && (!Number.isInteger(n) || n < 1)) {
+        throw new Error(`--${name} must be a positive integer`);
+    }
+    return n;
+}
+function strFlag(flags, name) {
+    const v = flags[name];
+    return typeof v === 'string' ? v : undefined;
+}
+/** `--cursor` / `--limit` shared by the paginated list commands. */
+function pageQuery(flags) {
+    return { limit: intFlag(flags, 'limit'), cursor: strFlag(flags, 'cursor') };
+}
+const ID_HEADER_NAMES = /^(id|userid|user_id|externalid|external_id)$/i;
+/**
+ * Parse the ids for `credda screen`. Inline args may be comma- and/or
+ * space-separated. A file is one id per line — or a CSV, in which case only
+ * the FIRST column is read (a leading header row named id/userId/externalId
+ * is skipped). Deduped, order-preserving. Deliberately simple: no quoted-CSV
+ * handling — an id containing a comma isn't a valid external id anyway.
+ */
+export function parseIdList(input) {
+    const raw = [];
+    if (input.inline) {
+        for (const chunk of input.inline)
+            raw.push(...chunk.split(/[\s,]+/));
+    }
+    if (input.fileText !== undefined) {
+        const lines = input.fileText.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const cell = lines[i].split(',')[0].trim();
+            if (!cell)
+                continue;
+            if (i === 0 && ID_HEADER_NAMES.test(cell))
+                continue; // CSV header row
+            raw.push(cell);
+        }
+    }
+    const seen = new Set();
+    const ids = [];
+    for (const id of raw) {
+        const trimmed = id.trim();
+        if (trimmed && !seen.has(trimmed)) {
+            seen.add(trimmed);
+            ids.push(trimmed);
+        }
+    }
+    return ids;
+}
+function requireCsvIo(ctx) {
+    if (!ctx.fetchCsv || !ctx.writeFile) {
+        throw new Error('CSV output is not available in this environment');
+    }
+    return { fetchCsv: ctx.fetchCsv, writeFile: ctx.writeFile };
+}
 /** Classify verify input: trust-export bundle JSON, VC-JWT, or compact credential. */
 export function classifyCredentialInput(raw) {
     const trimmed = raw.trim();
@@ -131,6 +370,32 @@ export async function runCli(argv, ctx) {
             case 'did':
                 show(ctx, await ctx.client.getDidDocument());
                 return 0;
+            case 'benchmarks':
+                // Public catalog: cohort dimensions + the k-anonymity floor. A benchmark
+                // is a distribution fact, never a verdict.
+                show(ctx, await ctx.client.getBenchmarks());
+                return 0;
+            case 'reason-codes':
+                // Public adverse-action reason-code catalog (ECOA / Reg B). Credda
+                // supplies the attribution only — it is not a creditor.
+                show(ctx, await ctx.client.getReasonCodes());
+                return 0;
+            case 'badges': {
+                // Public: the closed set of Open Badges 3.0 achievements this issuer
+                // will sign. A verifier reads the criteria from the ISSUER rather than
+                // trusting the narrative inside the document it is checking.
+                const [sub, ...rest] = args;
+                switch (sub) {
+                    case 'list':
+                        show(ctx, await ctx.client.getOpenBadgeAchievements());
+                        return 0;
+                    case 'get':
+                        show(ctx, await ctx.client.getOpenBadgeAchievement(requireArg(rest, 'badgeId')));
+                        return 0;
+                    default:
+                        throw new Error(`unknown badges subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
             case 'score':
                 show(ctx, await ctx.client.getScore(requireArg(args, 'userId'), requireKey(ctx)));
                 return 0;
@@ -143,14 +408,436 @@ export async function runCli(argv, ctx) {
             case 'risk':
                 show(ctx, await ctx.client.getRisk(requireArg(args, 'userId'), requireKey(ctx)));
                 return 0;
+            case 'trust-summary': {
+                const { positional, flags } = parseFlags(args, { boolean: ['narrative'] });
+                const userId = requireArg(positional, 'userId');
+                show(ctx, await ctx.client.getTrustSummary(userId, requireKey(ctx), {
+                    narrative: flags.narrative === true,
+                }));
+                return 0;
+            }
+            case 'benchmark': {
+                // Where one subject sits within a cohort — percentile + distribution.
+                const { positional, flags } = parseFlags(args, { valued: ['dimension'] });
+                const userId = requireArg(positional, 'userId');
+                show(ctx, await ctx.client.getUserBenchmark(userId, requireKey(ctx), {
+                    dimension: strFlag(flags, 'dimension'),
+                }));
+                return 0;
+            }
+            case 'distribution': {
+                // Aggregate, k-anonymised cohort distribution (or a whole dimension).
+                const { positional, flags } = parseFlags(args, { valued: ['dimension', 'cohort'] });
+                if (positional.length > 0) {
+                    throw new Error(`distribution takes no positional arguments (got "${positional[0]}") — see "credda help"`);
+                }
+                show(ctx, await ctx.client.getBenchmarkDistribution(requireKey(ctx), {
+                    dimension: strFlag(flags, 'dimension'),
+                    cohort: strFlag(flags, 'cohort'),
+                }));
+                return 0;
+            }
+            case 'users': {
+                // Query + export your book of subjects (closed filter set).
+                const { positional, flags } = parseFlags(args, {
+                    valued: [
+                        'score-min', 'score-max', 'band', 'subject-type', 'active-since',
+                        'min-verified', 'sort', 'order', 'cursor', 'limit',
+                    ],
+                    boolean: ['verified'],
+                });
+                if (positional.length > 0) {
+                    throw new Error(`users takes no positional arguments (got "${positional[0]}") — see "credda help"`);
+                }
+                const query = {
+                    scoreMin: numFlag(flags, 'score-min'),
+                    scoreMax: numFlag(flags, 'score-max'),
+                    band: strFlag(flags, 'band'),
+                    subjectType: strFlag(flags, 'subject-type'),
+                    activeSince: strFlag(flags, 'active-since'),
+                    minVerifiedEvents: intFlag(flags, 'min-verified'),
+                    sort: strFlag(flags, 'sort'),
+                    order: strFlag(flags, 'order'),
+                    ...pageQuery(flags),
+                };
+                if (flags.verified === true)
+                    query.hasVerifiedEvents = true;
+                show(ctx, await ctx.client.listUsers(requireKey(ctx), query));
+                return 0;
+            }
             case 'usage': {
-                const days = args[0] ? Number(args[0]) : undefined;
+                const { positional, flags } = parseFlags(args, { valued: ['from', 'to', 'csv'] });
+                const days = positional[0] ? Number(positional[0]) : undefined;
                 if (days !== undefined && (!Number.isInteger(days) || days < 1)) {
                     throw new Error('usage [days] — days must be a positive integer');
                 }
-                show(ctx, await ctx.client.getUsage(requireKey(ctx), days));
+                const from = strFlag(flags, 'from');
+                const to = strFlag(flags, 'to');
+                if (days !== undefined && (from || to)) {
+                    throw new Error('usage — use either a [days] window or --from/--to, not both');
+                }
+                const key = requireKey(ctx);
+                const outfile = strFlag(flags, 'csv');
+                if (outfile) {
+                    const { fetchCsv, writeFile } = requireCsvIo(ctx);
+                    const qs = new URLSearchParams({ format: 'csv' });
+                    if (days !== undefined)
+                        qs.set('days', String(days));
+                    if (from)
+                        qs.set('from', from);
+                    if (to)
+                        qs.set('to', to);
+                    await writeFile(outfile, await fetchCsv(`/usage?${qs.toString()}`, key));
+                    show(ctx, { written: outfile });
+                    return 0;
+                }
+                const window = from || to ? { from, to } : days;
+                show(ctx, await ctx.client.getUsage(key, window));
+                return 0;
+            }
+            case 'activity': {
+                const { positional, flags } = parseFlags(args, {
+                    valued: ['action', 'from', 'to', 'cursor', 'limit'],
+                });
+                if (positional.length > 0) {
+                    throw new Error(`activity takes no positional arguments (got "${positional[0]}") — see "credda help"`);
+                }
+                show(ctx, await ctx.client.getActivity(requireKey(ctx), {
+                    ...pageQuery(flags),
+                    action: strFlag(flags, 'action'),
+                    from: strFlag(flags, 'from'),
+                    to: strFlag(flags, 'to'),
+                }));
+                return 0;
+            }
+            case 'verified-profile':
+                // A SECOND measure over the same ledger — it can never move a score.
+                show(ctx, await ctx.client.getVerifiedProfile(requireArg(args, 'userId'), requireKey(ctx)));
+                return 0;
+            case 'qualify': {
+                // The claim is ALWAYS recorded; --verified-by decides whether it counts
+                // as verified. Never assert it yourself — name the witness.
+                const { positional, flags } = parseFlags(args, {
+                    valued: ['category', 'label', 'issuer', 'verified-by'],
+                });
+                const userId = requireArg(positional, 'userId');
+                const category = strFlag(flags, 'category');
+                if (!category) {
+                    throw new Error('qualify needs --category <education|skill|certification|employment>');
+                }
+                show(ctx, await ctx.client.recordQualification(userId, {
+                    category: category,
+                    label: strFlag(flags, 'label'),
+                    issuer: strFlag(flags, 'issuer'),
+                    verifiedBy: strFlag(flags, 'verified-by'),
+                }, requireKey(ctx)));
+                return 0;
+            }
+            case 'professional-record': {
+                const [sub, ...rest] = args;
+                switch (sub) {
+                    case 'get':
+                        show(ctx, await ctx.client.getProfessionalRecord(requireArg(rest, 'userId'), requireKey(ctx)));
+                        return 0;
+                    case 'credential': {
+                        const { positional, flags } = parseFlags(rest, { valued: ['ttl'] });
+                        const userId = requireArg(positional, 'userId');
+                        const ttlSeconds = intFlag(flags, 'ttl');
+                        const minted = await ctx.client.mintProfessionalRecordCredential(userId, requireKey(ctx), ttlSeconds !== undefined ? { ttlSeconds } : {});
+                        show(ctx, minted);
+                        return 0;
+                    }
+                    case 'public':
+                        // Public: the token IS the subject's consent to present the record.
+                        show(ctx, await ctx.client.getPublicProfessionalRecord(requireArg(rest, 'token')));
+                        return 0;
+                    default:
+                        throw new Error(`unknown professional-record subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
+            case 'confirmations': {
+                // ⚠️ Auth is ASYMMETRIC here: preview/respond are the COUNTERPARTY's
+                // calls and take no API key at all, so requireKey() is deliberately
+                // scoped per-subcommand rather than hoisted for the whole group.
+                const [sub, ...rest] = args;
+                switch (sub) {
+                    case 'create': {
+                        const { flags } = parseFlags(rest, {
+                            valued: [
+                                'user', 'type', 'counterparty', 'counterparty-name', 'description',
+                                'stake', 'value', 'due', 'completed', 'return-url', 'expires-in',
+                                'idempotency-key',
+                            ],
+                        });
+                        const userId = strFlag(flags, 'user');
+                        const eventType = strFlag(flags, 'type');
+                        const counterpartyRef = strFlag(flags, 'counterparty');
+                        if (!userId || !eventType || !counterpartyRef) {
+                            throw new Error('confirmations create needs --user <externalId> (the subject), --type <eventType> and --counterparty <ref> (your key for the party being asked to confirm)');
+                        }
+                        const stake = strFlag(flags, 'stake');
+                        const value = numFlag(flags, 'value');
+                        const expiresInDays = intFlag(flags, 'expires-in');
+                        const created = await ctx.client.createConfirmationRequest({
+                            userId,
+                            eventType: eventType,
+                            counterpartyRef,
+                            ...(strFlag(flags, 'counterparty-name') ? { counterpartyName: strFlag(flags, 'counterparty-name') } : {}),
+                            ...(strFlag(flags, 'description') ? { description: strFlag(flags, 'description') } : {}),
+                            ...(stake ? { stakeLevel: stake } : {}),
+                            ...(value !== undefined ? { transactionValue: value } : {}),
+                            ...(strFlag(flags, 'due') ? { dueDate: strFlag(flags, 'due') } : {}),
+                            ...(strFlag(flags, 'completed') ? { completedAt: strFlag(flags, 'completed') } : {}),
+                            ...(strFlag(flags, 'return-url') ? { returnUrl: strFlag(flags, 'return-url') } : {}),
+                            ...(expiresInDays !== undefined ? { expiresInDays } : {}),
+                        }, requireKey(ctx), { idempotencyKey: strFlag(flags, 'idempotency-key') });
+                        ctx.err('NOTE: the confirmationToken below is shown ONCE — deliver it to the counterparty over your own channel.');
+                        show(ctx, created);
+                        return 0;
+                    }
+                    case 'list': {
+                        const { flags } = parseFlags(rest, { valued: ['status', 'cursor', 'limit'] });
+                        const status = strFlag(flags, 'status');
+                        show(ctx, await ctx.client.listConfirmations(requireKey(ctx), {
+                            ...pageQuery(flags),
+                            ...(status ? { status: status.toUpperCase() } : {}),
+                        }));
+                        return 0;
+                    }
+                    case 'get':
+                        show(ctx, await ctx.client.getConfirmation(requireArg(rest, 'id'), requireKey(ctx)));
+                        return 0;
+                    case 'cancel':
+                        show(ctx, await ctx.client.cancelConfirmation(requireArg(rest, 'id'), requireKey(ctx)));
+                        return 0;
+                    case 'preview': {
+                        // KEYLESS on purpose — the counterparty holds a token, not a key.
+                        const { positional, flags } = parseFlags(rest, { valued: ['token'] });
+                        const id = requireArg(positional, 'id');
+                        const token = strFlag(flags, 'token');
+                        if (!token)
+                            throw new Error('confirmations preview needs --token <t> (the one-time token you were sent)');
+                        show(ctx, await ctx.client.previewConfirmation(id, token));
+                        return 0;
+                    }
+                    case 'respond': {
+                        // KEYLESS on purpose. The decision is explicit: there is no default,
+                        // because confirming an outcome you did not witness is the one thing
+                        // this primitive exists to prevent.
+                        const { positional, flags } = parseFlags(rest, {
+                            valued: ['token'],
+                            boolean: ['confirm', 'decline'],
+                        });
+                        const id = requireArg(positional, 'id');
+                        const token = strFlag(flags, 'token');
+                        if (!token)
+                            throw new Error('confirmations respond needs --token <t> (the one-time token you were sent)');
+                        const confirm = flags.confirm === true;
+                        const decline = flags.decline === true;
+                        if (confirm === decline) {
+                            throw new Error('confirmations respond needs exactly one of --confirm or --decline');
+                        }
+                        show(ctx, await ctx.client.respondToConfirmation(id, token, confirm ? 'confirm' : 'decline'));
+                        return 0;
+                    }
+                    default:
+                        throw new Error(`unknown confirmations subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
+            case 'policies': {
+                const [sub, ...rest] = args;
+                const key = requireKey(ctx);
+                switch (sub) {
+                    case 'list': {
+                        const { flags } = parseFlags(rest, { valued: ['cursor', 'limit'] });
+                        show(ctx, await ctx.client.listPolicies(key, pageQuery(flags)));
+                        return 0;
+                    }
+                    case 'get':
+                        show(ctx, await ctx.client.getPolicy(requireArg(rest, 'id'), key));
+                        return 0;
+                    case 'create': {
+                        const { flags } = parseFlags(rest, {
+                            valued: ['name', 'user', 'metric', 'direction', 'threshold', 'component', 'band'],
+                            boolean: ['all'],
+                        });
+                        const name = strFlag(flags, 'name');
+                        const metric = strFlag(flags, 'metric');
+                        if (!name || !metric) {
+                            throw new Error('policies create needs --name <n> and --metric <score|component|band|verified_events>');
+                        }
+                        const userId = strFlag(flags, 'user');
+                        const appliesToAll = flags.all === true;
+                        if (Boolean(userId) === appliesToAll) {
+                            throw new Error('policies create needs exactly one of --user <externalId> (watch one subject) or --all (watch all your subjects)');
+                        }
+                        const threshold = numFlag(flags, 'threshold');
+                        const input = {
+                            name,
+                            metric: metric,
+                            ...(userId ? { userId } : { appliesToAll: true }),
+                        };
+                        const direction = strFlag(flags, 'direction');
+                        if (direction)
+                            input.direction = direction;
+                        if (threshold !== undefined)
+                            input.threshold = threshold;
+                        const component = strFlag(flags, 'component');
+                        if (component)
+                            input.component = component;
+                        const band = strFlag(flags, 'band');
+                        if (band)
+                            input.band = band;
+                        show(ctx, await ctx.client.createPolicy(input, key));
+                        return 0;
+                    }
+                    case 'update': {
+                        const { positional, flags } = parseFlags(rest, {
+                            valued: ['name', 'direction', 'threshold', 'component', 'band'],
+                            boolean: ['activate', 'deactivate'],
+                        });
+                        const id = requireArg(positional, 'id');
+                        if (flags.activate === true && flags.deactivate === true) {
+                            throw new Error('policies update — pass at most one of --activate / --deactivate');
+                        }
+                        const patch = {};
+                        const name = strFlag(flags, 'name');
+                        if (name)
+                            patch.name = name;
+                        const direction = strFlag(flags, 'direction');
+                        if (direction)
+                            patch.direction = direction;
+                        const threshold = numFlag(flags, 'threshold');
+                        if (threshold !== undefined)
+                            patch.threshold = threshold;
+                        const component = strFlag(flags, 'component');
+                        if (component)
+                            patch.component = component;
+                        const band = strFlag(flags, 'band');
+                        if (band)
+                            patch.band = band;
+                        if (flags.activate === true)
+                            patch.isActive = true;
+                        if (flags.deactivate === true)
+                            patch.isActive = false;
+                        if (Object.keys(patch).length === 0) {
+                            throw new Error('policies update needs at least one field to change — see "credda help"');
+                        }
+                        show(ctx, await ctx.client.updatePolicy(id, patch, key));
+                        return 0;
+                    }
+                    case 'delete':
+                        await ctx.client.deletePolicy(requireArg(rest, 'id'), key);
+                        show(ctx, { deleted: true });
+                        return 0;
+                    default:
+                        throw new Error(`unknown policies subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
+            case 'monitors': {
+                const [sub, ...rest] = args;
+                const key = requireKey(ctx);
+                switch (sub) {
+                    case 'list': {
+                        const { flags } = parseFlags(rest, { valued: ['cursor', 'limit'] });
+                        show(ctx, await ctx.client.listMonitors(key, pageQuery(flags)));
+                        return 0;
+                    }
+                    case 'get':
+                        show(ctx, await ctx.client.getMonitor(requireArg(rest, 'id'), key));
+                        return 0;
+                    case 'create': {
+                        const { flags } = parseFlags(rest, {
+                            valued: ['user', 'below', 'above'],
+                            boolean: ['band-change'],
+                        });
+                        const userId = strFlag(flags, 'user');
+                        if (!userId) {
+                            throw new Error('monitors create needs --user <externalId> (the user to watch)');
+                        }
+                        const belowScore = numFlag(flags, 'below');
+                        const aboveScore = numFlag(flags, 'above');
+                        const onBandChange = flags['band-change'] === true;
+                        if (belowScore === undefined && aboveScore === undefined && !onBandChange) {
+                            throw new Error('monitors create needs at least one condition: --below <score> (fires when the score crosses DOWN through it), --above <score> (crosses UP), or --band-change (any band change)');
+                        }
+                        show(ctx, await ctx.client.createMonitor({
+                            userId,
+                            ...(belowScore !== undefined ? { belowScore } : {}),
+                            ...(aboveScore !== undefined ? { aboveScore } : {}),
+                            ...(onBandChange ? { onBandChange } : {}),
+                        }, key));
+                        return 0;
+                    }
+                    case 'delete':
+                        await ctx.client.deleteMonitor(requireArg(rest, 'id'), key);
+                        show(ctx, { deleted: true });
+                        return 0;
+                    default:
+                        throw new Error(`unknown monitors subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
+            case 'screen': {
+                const { positional, flags } = parseFlags(args, {
+                    valued: ['file'],
+                    boolean: ['wait'],
+                });
+                const file = strFlag(flags, 'file');
+                if (file && positional.length > 0) {
+                    throw new Error('screen — pass ids inline OR --file <path>, not both');
+                }
+                const ids = parseIdList(file ? { fileText: await ctx.readInput(file) } : { inline: positional });
+                if (ids.length === 0) {
+                    throw new Error('screen — no ids found. Pass ids (comma/space separated) or --file <path> (one id per line, or a CSV whose first column is the id)');
+                }
+                const key = requireKey(ctx);
+                let job = (await ctx.client.createScreening(ids, key)).screening;
+                if (flags.wait === true) {
+                    const sleep = ctx.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+                    const interval = ctx.pollIntervalMs ?? 2000;
+                    while (job.status === 'QUEUED' || job.status === 'RUNNING') {
+                        ctx.err(`screening ${job.id}: ${job.status} — waiting…`);
+                        await sleep(interval);
+                        job = (await ctx.client.getScreening(job.id, key)).screening;
+                    }
+                    show(ctx, { screening: job });
+                    return job.status === 'COMPLETED' ? 0 : 1;
+                }
+                show(ctx, { screening: job });
+                if (job.status === 'QUEUED' || job.status === 'RUNNING') {
+                    ctx.err(`still ${job.status} — poll with "credda screenings get ${job.id}" (or re-run with --wait)`);
+                }
                 return 0;
             }
+            case 'screenings': {
+                const [sub, ...rest] = args;
+                const key = requireKey(ctx);
+                switch (sub) {
+                    case 'list': {
+                        const { flags } = parseFlags(rest, { valued: ['cursor', 'limit'] });
+                        show(ctx, await ctx.client.listScreenings(key, pageQuery(flags)));
+                        return 0;
+                    }
+                    case 'get':
+                        show(ctx, await ctx.client.getScreening(requireArg(rest, 'id'), key));
+                        return 0;
+                    case 'results': {
+                        const { positional, flags } = parseFlags(rest, { valued: ['csv'] });
+                        const id = requireArg(positional, 'id');
+                        const outfile = strFlag(flags, 'csv');
+                        if (outfile) {
+                            const { fetchCsv, writeFile } = requireCsvIo(ctx);
+                            await writeFile(outfile, await fetchCsv(`/screenings/${encodeURIComponent(id)}/results?format=csv`, key));
+                            show(ctx, { written: outfile });
+                            return 0;
+                        }
+                        show(ctx, await ctx.client.getScreeningResults(id, key));
+                        return 0;
+                    }
+                    default:
+                        throw new Error(`unknown screenings subcommand "${sub ?? ''}" — see "credda help"`);
+                }
+            }
             case 'webhooks': {
                 const [sub, ...rest] = args;
                 const key = requireKey(ctx);
@@ -162,7 +849,7 @@ export async function runCli(argv, ctx) {
                         const url = requireArg(rest, 'url');
                         const events = rest.slice(1);
                         if (events.length === 0) {
-                            throw new Error('webhooks create <url> <event...> — provide at least one event (score.updated, score.band_changed, dispute.resolved)');
+                            throw new Error('webhooks create <url> <event...> — provide at least one event (score.updated, score.band_changed, dispute.resolved, monitor.triggered, usage.quota_warning)');
                         }
                         const created = await ctx.client.createWebhook({ url, events: events }, key);
                         ctx.err('NOTE: the signing secret below is shown ONCE — store it now.');
@@ -179,6 +866,13 @@ export async function runCli(argv, ctx) {
                     case 'deliveries':
                         show(ctx, await ctx.client.getWebhookDeliveries(requireArg(rest, 'id'), key, 25));
                         return 0;
+                    case 'recent': {
+                        // Sample data across ALL endpoints — falls back to the event
+                        // catalog's examples (isExample:true) when nothing has fired yet.
+                        const eventType = rest.length > 0 ? rest : undefined;
+                        show(ctx, await ctx.client.getRecentWebhookEvents(key, { limit: 25, eventType }));
+                        return 0;
+                    }
                     default:
                         throw new Error(`unknown webhooks subcommand "${sub ?? ''}" — see "credda help"`);
                 }
@@ -208,6 +902,8 @@ export async function runCli(argv, ctx) {
         const message = e instanceof Error ? e.message : String(e);
         // SDK errors already carry a "credda:" prefix — don't double it.
         ctx.err(message.startsWith('credda:') ? message : `credda: ${message}`);
+        for (const line of errorHints(e))
+            ctx.err(line);
         return 1;
     }
 }