@cookiecrumbs-eu/mcp 0.7.0

package/dist/mcp/src/tools-config.js

@@ -0,0 +1,943 @@
+/**
+ * Everything a site's configuration consists of beyond the banner draft, as MCP tools: the site
+ * itself (name, retention, settings), the scan schedule, services, issue suppression, install
+ * checks, domain verification, alerts and alert channels, webhooks, templates, version promotion
+ * and scheduled exports. Together with tools.ts this is the whole dashboard, reachable from an
+ * agent — the point of the product.
+ *
+ * The same two rules as tools.ts: a tool is advertised only when the token carries one of its
+ * scopes, and every write is two-step (`confirm:false` shows what would change and changes
+ * nothing; `confirm:true` does it). Destructive tools carry `destructiveHint`.
+ */
+import { z } from 'zod';
+import { CliError } from "../../cli/src/errors.js";
+import { jsonDiff } from "./diff.js";
+import { meta } from "./matrix.js";
+import { ENV, allSites, jsonBlock, resolveSite } from "./shared.js";
+// --- small helpers ---------------------------------------------------------
+const CONFIRM = z.boolean().optional().describe('false (default) = dry run: show what would change and change nothing; true = do it');
+const SITE = z.string().optional().describe('site id, primary domain or name (optional when the token is bound to one site or the workspace has only one)');
+/** The dry-run block for writes that carry no banner lint. */
+function plan(what, diff, extra = []) {
+    return [
+        `DRY RUN — nothing was changed. ${what}`,
+        '',
+        diff ? '```diff\n' + diff + '\n```' : 'Nothing would change — the target already has this content.',
+        ...extra,
+        '',
+        'Call the same tool again with `confirm: true` to apply it.',
+    ].join('\n');
+}
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+const bool = (v) => (typeof v === 'boolean' ? v : undefined);
+const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string').map((s) => s.trim()).filter(Boolean) : undefined);
+/** Keep only the keys that were actually given — a patch never carries `undefined`. */
+function compact(o) {
+    const out = {};
+    for (const [k, v] of Object.entries(o))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Everything the site row says apart from timestamps and keys — what an agent compares. */
+const siteView = (s) => ({ id: s.id, name: s.name, primary_domain: s.primary_domain, status: s.status, retention_months: s.retention_months, settings: s.settings ?? {} });
+async function serviceByRef(ctx, site, ref) {
+    const services = await ctx.api.services(site);
+    return (services.find((s) => s.id === ref) ??
+        services.find((s) => String(s.name).toLowerCase() === ref.toLowerCase()) ??
+        services.find((s) => String(s.provider_name ?? '').toLowerCase() === ref.toLowerCase()) ??
+        services.find((s) => String(s.provider_domain ?? '').toLowerCase() === ref.toLowerCase()) ??
+        null);
+}
+async function templateByRef(ctx, ref) {
+    const templates = await ctx.api.templates();
+    return templates.find((t) => t.id === ref) ?? templates.find((t) => t.name.toLowerCase() === ref.toLowerCase()) ?? null;
+}
+async function webhookByRef(ctx, ref) {
+    const hooks = await ctx.api.webhooks();
+    return hooks.find((h) => h.id === ref) ?? hooks.find((h) => h.url === ref) ?? null;
+}
+async function channels(ctx) {
+    const r = await ctx.api.request('GET', '/alert-channels');
+    return r.items ?? [];
+}
+async function channelByRef(ctx, ref) {
+    const all = await channels(ctx);
+    return all.find((c) => c.id === ref) ?? all.find((c) => c.name.toLowerCase() === ref.toLowerCase()) ?? null;
+}
+async function exportSchedules(ctx, siteId) {
+    const r = await ctx.api.request('GET', '/export-schedules', { query: { site_id: siteId } });
+    return r.items ?? [];
+}
+const SERVICE_FIELDS = {
+    category_key: z.string().optional().describe("one of the site's category keys, e.g. analytics"),
+    provider_name: z.string().optional(),
+    provider_domain: z.string().optional(),
+    privacy_url: z.string().nullable().optional(),
+    host_patterns: z.array(z.string()).optional().describe('hosts the service loads from; drives blocking'),
+    script_patterns: z.array(z.string()).optional(),
+    iframe_patterns: z.array(z.string()).optional(),
+    cookie_patterns: z.array(z.string()).optional(),
+    storage_keys: z.array(z.string()).optional(),
+    legal_basis: z.enum(['consent', 'legitimate_interest', 'contract', 'legal_obligation']).optional(),
+    justification: z.string().nullable().optional(),
+    first_party: z.boolean().optional(),
+    status: z.enum(['discovered', 'managed', 'ignored']).optional(),
+    ignore_reason: z.string().nullable().optional(),
+    description: z.string().optional().describe('what the visitor is told (English)'),
+};
+function servicePatch(args) {
+    const p = compact({
+        category_key: str(args.category_key),
+        provider_name: str(args.provider_name),
+        provider_domain: str(args.provider_domain)?.toLowerCase(),
+        host_patterns: list(args.host_patterns),
+        script_patterns: list(args.script_patterns),
+        iframe_patterns: list(args.iframe_patterns),
+        cookie_patterns: list(args.cookie_patterns),
+        storage_keys: list(args.storage_keys),
+        legal_basis: str(args.legal_basis),
+        first_party: bool(args.first_party),
+        status: str(args.status),
+    });
+    if ('privacy_url' in args)
+        p.privacy_url = args.privacy_url === null ? null : str(args.privacy_url) ?? null;
+    if ('justification' in args)
+        p.justification = args.justification === null ? null : str(args.justification) ?? null;
+    if ('ignore_reason' in args)
+        p.ignore_reason = args.ignore_reason === null ? null : str(args.ignore_reason) ?? null;
+    if (str(args.description))
+        p.descriptions = { en: str(args.description) };
+    return p;
+}
+const SCHEDULE_FIELDS = {
+    cadence: z.enum(['monthly', 'weekly', 'daily']).optional().describe('the plan may cap it; the answer shows the cadence in force'),
+    page_cap: z.number().int().min(1).max(20000).optional(),
+    states: z.array(z.enum(['no_interaction', 'reject_all', 'accept_all'])).optional(),
+    start_urls: z.array(z.string()).optional().describe('[] = the home page'),
+    include_patterns: z.array(z.string()).optional().describe('path patterns to crawl, e.g. /blog/**; [] = everything'),
+    exclude_patterns: z.array(z.string()).optional(),
+    respect_robots: z.boolean().optional().describe('false only on a verified domain'),
+    paused: z.boolean().optional(),
+};
+// --- the tools -------------------------------------------------------------
+export const CONFIG_TOOLS = [
+    // ---- sites ----------------------------------------------------------------------------------
+    {
+        name: 'create_site',
+        ...meta('create_site'),
+        description: 'Create a site in the workspace: it gets production and preview environments, default categories and a first banner draft. `confirm:false` (default) shows what would be created.',
+        inputSchema: {
+            name: z.string().min(1).max(120),
+            primary_domain: z.string().describe('a hostname like www.example.com'),
+            languages: z.array(z.string()).optional().describe('BCP-47 tags, default ["en"]'),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const name = str(args.name);
+            const domain = str(args.primary_domain)?.toLowerCase();
+            if (!name || !domain)
+                throw new CliError('usage', 'Pass `name` and `primary_domain`.', 2);
+            const languages = list(args.languages);
+            const proposed = { name, primary_domain: domain, languages: languages?.length ? languages : ['en'] };
+            const existing = (await allSites(ctx)).find((s) => s.primary_domain?.toLowerCase() === domain);
+            if (args.confirm !== true) {
+                return plan(`Would create site “${name}” for ${domain}.`, jsonDiff({}, proposed, 'no site', 'new site'), [
+                    '',
+                    existing ? `Note: ${existing.primary_domain} already exists as site ${existing.id} (“${existing.name}”); the server will refuse a duplicate domain.` : 'The domain is not used by another site in this workspace.',
+                    'The plan’s site limit applies (402 when reached).',
+                ]);
+            }
+            const site = await ctx.api.createSite(proposed);
+            ctx.sites = null;
+            return [`Created site ${site.id} (“${site.name}”, ${site.primary_domain}).`, jsonBlock(siteView(site)), '', 'Next: get_banner to see its draft, scan_site to see what loads, check_install once cc.js is on the page.'].join('\n');
+        },
+    },
+    {
+        name: 'update_site',
+        ...meta('update_site'),
+        description: 'Rename a site, set how long consent records are kept (retention_months) or change a site setting. The primary domain cannot change; languages are part of the banner config (update_banner). Two-step: `confirm:false` shows the diff.',
+        inputSchema: {
+            site: SITE,
+            name: z.string().min(1).max(120).optional(),
+            retention_months: z.number().int().optional().describe('12, 24, 36 … 120; the plan may cap it'),
+            settings: z
+                .object({
+                public_versions_feed: z.boolean().optional(),
+                consent_cookie_name: z.string().nullable().optional().describe('null resets to the default'),
+                reask_months: z.number().int().min(1).max(13).nullable().optional(),
+            })
+                .optional(),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const current = await ctx.api.site(id);
+            const patch = compact({ name: str(args.name), retention_months: num(args.retention_months), settings: args.settings && typeof args.settings === 'object' ? args.settings : undefined });
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', 'Nothing to change: pass name, retention_months or settings.', 2);
+            const after = { ...siteView(current), ...compact({ name: patch.name, retention_months: patch.retention_months }) };
+            if (patch.settings) {
+                const s = { ...current.settings, ...patch.settings };
+                for (const [k, v] of Object.entries(s))
+                    if (v === null)
+                        delete s[k];
+                after.settings = s;
+            }
+            const diff = jsonDiff(siteView(current), after, `site ${id} (current)`, `site ${id} (proposed)`);
+            if (args.confirm !== true)
+                return plan(`Would update site ${id} (“${current.name}”).`, diff, patch.retention_months ? ['', 'Shortening retention deletes older consent records at the next retention run; the RPC refuses a value the plan does not allow (402).'] : []);
+            const site = await ctx.api.updateSite(id, patch);
+            ctx.sites = null;
+            return [`Site ${id} updated.`, jsonBlock(siteView(site))].join('\n');
+        },
+    },
+    {
+        name: 'list_domains',
+        ...meta('list_domains'),
+        description: 'The domains of a site with their verification state and the token to publish (DNS TXT or meta tag).',
+        inputSchema: { site: SITE },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const items = await ctx.api.domains(id);
+            if (!items.length)
+                return `Site ${id} has no domains.`;
+            return items
+                .map((d) => `- ${d.hostname}  id ${d.id}\n  ${d.verified_at ? `verified ${d.verified_at}` : `NOT verified · method ${d.verification_method} · publish: ${instructions(d)}`}`)
+                .join('\n');
+        },
+    },
+    {
+        name: 'verify_domain',
+        ...meta('verify_domain'),
+        description: '(Re)issue the ownership-verification token for a domain and say exactly what to publish. The worker performs the check; a passed install check verifies the domain too. Two-step.',
+        inputSchema: { site: SITE, domain: z.string().describe('domain id or hostname'), method: z.enum(['dns_txt', 'meta']).optional().describe('default dns_txt'), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const ref = String(args.domain ?? '').trim().toLowerCase();
+            const d = (await ctx.api.domains(id)).find((x) => x.id === ref || x.hostname.toLowerCase() === ref);
+            if (!d)
+                return `No domain “${ref}” on site ${id}. Use list_domains.`;
+            if (d.verified_at)
+                return `${d.hostname} is already verified (${d.verified_at}). Nothing to do.`;
+            const method = (str(args.method) ?? 'dns_txt');
+            if (args.confirm !== true)
+                return plan(`Would set ${d.hostname} to ${method} verification and keep its token.`, jsonDiff({ verification_method: d.verification_method }, { verification_method: method }, 'current', 'proposed'), ['', `You would then publish: ${instructions({ ...d, verification_method: method })}`]);
+            const out = await ctx.api.verifyDomain(d.id, method);
+            return [`${out.hostname}: ${out.verification_method} verification requested.`, `Publish this, then wait for the next check:`, `  ${instructions(out)}`].join('\n');
+        },
+    },
+    // ---- scanning: schedule, install, alerts ------------------------------------------------------
+    {
+        name: 'list_scans',
+        ...meta('list_scans'),
+        description: 'Recent scans of a site (newest first): status, trigger, pages, summary.',
+        inputSchema: { site: SITE, limit: z.number().int().min(1).max(100).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const r = await ctx.api.request('GET', `/sites/${id}/scans`, { query: { limit: num(args.limit) ?? 10 } });
+            const items = r.items ?? [];
+            if (!items.length)
+                return `Site ${id} has no scans yet — scan_site queues one.`;
+            return items.map((s) => `- ${s.id}  ${s.status} · ${s.environment} · via ${s.trigger} · ${s.pages_crawled ?? 0} pages · queued ${s.queued_at}${s.finished_at ? ` · finished ${s.finished_at}` : ''}${s.summary ? `\n  summary ${JSON.stringify(s.summary)}` : ''}`).join('\n');
+        },
+    },
+    {
+        name: 'get_scan_diff',
+        ...meta('get_scan_diff'),
+        description: 'What changed between a scan and the one before it: findings added, removed or re-classified.',
+        inputSchema: { scan_id: z.string() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const out = await ctx.api.scanDiff(String(args.scan_id));
+            return jsonBlock(out);
+        },
+    },
+    {
+        name: 'get_scan_schedule',
+        ...meta('get_scan_schedule'),
+        description: 'The scheduled-scan settings of a site: cadence, next run, page cap, consent states, start URLs, path patterns, robots, paused.',
+        inputSchema: { site: SITE },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            return jsonBlock(await ctx.api.scanSchedule(id));
+        },
+    },
+    {
+        name: 'set_scan_schedule',
+        ...meta('set_scan_schedule'),
+        description: 'Change the scan schedule. Only the fields you pass change; cadence and page_cap are clamped to the plan and the answer shows the values in force. Two-step.',
+        inputSchema: { site: SITE, ...SCHEDULE_FIELDS, confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const current = await ctx.api.scanSchedule(id);
+            const patch = compact({
+                cadence: str(args.cadence),
+                page_cap: num(args.page_cap),
+                states: list(args.states),
+                start_urls: list(args.start_urls),
+                include_patterns: list(args.include_patterns),
+                exclude_patterns: list(args.exclude_patterns),
+                respect_robots: bool(args.respect_robots),
+                paused: bool(args.paused),
+            });
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', `Nothing to change: pass one of ${Object.keys(SCHEDULE_FIELDS).join(', ')}.`, 2);
+            const view = (s) => ({ cadence: s.cadence, page_cap: s.page_cap, states: s.states, start_urls: s.start_urls, include_patterns: s.include_patterns, exclude_patterns: s.exclude_patterns, respect_robots: s.respect_robots, paused: s.paused });
+            const diff = jsonDiff(view(current), { ...view(current), ...patch }, `schedule ${id} (current)`, `schedule ${id} (proposed)`);
+            if (args.confirm !== true)
+                return plan(`Would change the scan schedule of site ${id}.`, diff, ['', `Next scheduled run today: ${current.paused ? 'none (paused)' : current.next_run_at ?? 'not scheduled yet'}. Changing the cadence re-plans it.`]);
+            const saved = await ctx.api.updateScanSchedule(id, patch);
+            const clamped = [];
+            if (patch.cadence && saved.cadence !== patch.cadence)
+                clamped.push(`cadence ${patch.cadence} was clamped to ${saved.cadence} by the plan`);
+            if (patch.page_cap && saved.page_cap !== patch.page_cap)
+                clamped.push(`page_cap ${patch.page_cap} was clamped to ${saved.page_cap} by the plan`);
+            return [`Schedule of site ${id} saved.`, ...clamped.map((c) => `Note: ${c}.`), jsonBlock(view(saved)), `Next run: ${saved.paused ? 'none while paused' : saved.next_run_at ?? '—'}`].join('\n');
+        },
+    },
+    {
+        name: 'get_install_status',
+        ...meta('get_install_status'),
+        description: 'Is cc.js installed and working on the site? The most recent install checks, newest first.',
+        inputSchema: { site: SITE, limit: z.number().int().min(1).max(100).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const items = await ctx.api.installChecks(id, num(args.limit) ?? 5);
+            if (!items.length)
+                return `No install check has run for site ${id} yet. check_install queues one.`;
+            return [`Latest: ${items[0].ok ? 'OK' : 'NOT OK'} at ${items[0].checked_at} on ${items[0].url}`, ...items.map((c) => `- ${c.checked_at}  ${c.ok ? 'ok ' : 'FAIL'}  ${c.kind}  ${c.url}  ${JSON.stringify(c.result)}`)].join('\n');
+        },
+    },
+    {
+        name: 'check_install',
+        ...meta('check_install'),
+        description: 'Queue an install check: the worker fetches the page and looks for cc.js with this site’s public key. Optionally wait (`wait` seconds) for the result. A passed check also verifies the domain.',
+        inputSchema: { site: SITE, url: z.string().optional().describe('page to check; default the home page'), wait: z.number().int().min(0).max(300).optional().describe('seconds to wait for the result; 0 = return at once') },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const queued = await ctx.api.requestInstallCheck(id, str(args.url));
+            const wait = num(args.wait) ?? 0;
+            if (!wait)
+                return `Install check queued for ${queued.url} (job ${queued.job_id}). Read the result with get_install_status in a moment.`;
+            const since = Date.parse(queued.requested_at) || Date.now();
+            const deadline = Date.now() + wait * 1000;
+            let found = null;
+            while (Date.now() < deadline && !found) {
+                await new Promise((r) => setTimeout(r, 3000));
+                found = (await ctx.api.installChecks(id, 5)).find((c) => c.kind === 'install' && Date.parse(c.checked_at) >= since) ?? null;
+            }
+            if (!found)
+                return `Install check queued (job ${queued.job_id}) but no result within ${wait}s — is a worker running? Read it later with get_install_status.`;
+            return [`Install ${found.ok ? 'OK' : 'BROKEN'} on ${found.url} (checked ${found.checked_at}).`, jsonBlock(found.result)].join('\n');
+        },
+    },
+    {
+        name: 'list_alerts',
+        ...meta('list_alerts'),
+        description: 'The alert inbox: new trackers, pre-consent loads, unclassified trackers, removals, broken installs. Open by default.',
+        inputSchema: {
+            site: SITE,
+            status: z.enum(['open', 'acknowledged', 'resolved', 'all']).optional(),
+            kind: z.enum(['new_tracker', 'preconsent', 'unclassified', 'removed', 'install_broken']).optional(),
+            min_severity: z.enum(['info', 'low', 'medium', 'high', 'critical']).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const siteId = args.site ? await resolveSite(ctx, args.site) : ctx.siteId ?? undefined;
+            const page = await ctx.api.alerts({ site_id: siteId, status: str(args.status) ?? 'open', kind: str(args.kind), min_severity: str(args.min_severity), limit: num(args.limit) ?? 50 });
+            if (!page.items.length)
+                return `No ${str(args.status) ?? 'open'} alerts.${page.counts ? ` Counts: ${JSON.stringify(page.counts)}` : ''}`;
+            return [...page.items.map((a) => `- ${a.id}  [${a.severity}] ${a.kind} · ${a.status} · site ${a.site_id ?? 'workspace'} · ${a.created_at ?? ''}\n  ${a.title ?? ''}`), page.counts ? `Counts: ${JSON.stringify(page.counts)}` : ''].filter(Boolean).join('\n');
+        },
+    },
+    {
+        name: 'acknowledge_alert',
+        ...meta('acknowledge_alert'),
+        description: 'Mark an alert as seen (it stays in the inbox as acknowledged). Two-step.',
+        inputSchema: { alert_id: z.string(), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = String(args.alert_id);
+            if (args.confirm !== true)
+                return plan(`Would acknowledge alert ${id}.`, jsonDiff({ status: 'open' }, { status: 'acknowledged' }, 'current', 'proposed'));
+            const a = await ctx.api.acknowledgeAlert(id);
+            return `Alert ${a.id} is now ${a.status}.`;
+        },
+    },
+    {
+        name: 'resolve_alert',
+        ...meta('resolve_alert'),
+        description: 'Resolve an alert. Two-step.',
+        inputSchema: { alert_id: z.string(), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = String(args.alert_id);
+            if (args.confirm !== true)
+                return plan(`Would resolve alert ${id}.`, jsonDiff({ status: 'open' }, { status: 'resolved' }, 'current', 'proposed'));
+            const a = await ctx.api.resolveAlert(id);
+            return `Alert ${a.id} is now ${a.status}.`;
+        },
+    },
+    // ---- services and issues --------------------------------------------------------------------
+    {
+        name: 'list_services',
+        ...meta('list_services'),
+        description: 'The services (trackers) a site declares: category, provider, legal basis, matching patterns, status.',
+        inputSchema: { site: SITE, status: z.enum(['discovered', 'managed', 'ignored']).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const items = await ctx.api.services(id, str(args.status));
+            if (!items.length)
+                return `Site ${id} has no services${args.status ? ` with status ${args.status}` : ''}.`;
+            return items.map((s) => `- ${s.name}  id ${s.id}\n  category ${s.category_key} · ${s.status} · basis ${s.legal_basis ?? '—'} · provider ${s.provider_name ?? '—'} (${s.provider_domain ?? '—'})\n  hosts ${(s.host_patterns ?? []).join(', ') || '—'} · cookies ${(s.cookie_patterns ?? []).join(', ') || '—'}`).join('\n');
+        },
+    },
+    {
+        name: 'add_service',
+        ...meta('add_service'),
+        description: 'Declare a service the site uses (a tracker the scanner did not find, or one to record by hand). It joins the declaration and the block list at the next publish. Two-step.',
+        inputSchema: { site: SITE, name: z.string().min(1), ...SERVICE_FIELDS, category_key: z.string().describe("one of the site's category keys, e.g. analytics"), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const name = str(args.name);
+            const category = str(args.category_key);
+            if (!name || !category)
+                throw new CliError('usage', 'Pass `name` and `category_key`.', 2);
+            const body = { ...servicePatch(args), name, category_key: category, status: str(args.status) ?? 'managed' };
+            const dup = await serviceByRef(ctx, id, name);
+            if (args.confirm !== true)
+                return plan(`Would add service “${name}” (${category}) to site ${id}.`, jsonDiff({}, body, 'no service', 'new service'), dup ? ['', `Note: a service named “${dup.name}” already exists (${dup.id}); use update_service to change it.`] : []);
+            const created = await ctx.api.createService(id, body);
+            return [`Service ${created.id} added to site ${id}.`, jsonBlock(created), '', 'Publish (push_config) so the declaration and the block list follow.'].join('\n');
+        },
+    },
+    {
+        name: 'update_service',
+        ...meta('update_service'),
+        description: 'Change a service: category, provider, matching patterns, legal basis, status. Only the fields you pass change. Two-step.',
+        inputSchema: { site: SITE, service: z.string().describe('service id, name, provider name or provider domain'), name: z.string().optional(), ...SERVICE_FIELDS, confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const svc = await serviceByRef(ctx, id, String(args.service));
+            if (!svc)
+                return `No service matches “${args.service}” on site ${id}. Use list_services.`;
+            const patch = { ...servicePatch(args), ...compact({ name: str(args.name) }) };
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', 'Nothing to change: pass at least one field.', 2);
+            const diff = jsonDiff(svc, { ...svc, ...patch }, `service ${svc.id} (current)`, `service ${svc.id} (proposed)`);
+            if (args.confirm !== true)
+                return plan(`Would update service “${svc.name}” on site ${id}.`, diff);
+            const updated = await ctx.api.updateService(svc.id, patch);
+            return [`Service ${updated.id} updated.`, jsonBlock(updated)].join('\n');
+        },
+    },
+    {
+        name: 'delete_service',
+        ...meta('delete_service'),
+        description: 'Delete a service. Its cookies leave the declaration and its findings return to unclassified on the next scan. Two-step; destructive.',
+        inputSchema: { site: SITE, service: z.string().describe('service id or name'), confirm: CONFIRM },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const svc = await serviceByRef(ctx, id, String(args.service));
+            if (!svc)
+                return `No service matches “${args.service}” on site ${id}. Use list_services.`;
+            if (args.confirm !== true)
+                return plan(`Would DELETE service “${svc.name}” (${svc.id}) from site ${id}.`, jsonDiff(svc, {}, `service ${svc.id}`, 'deleted'), ['', 'This cannot be undone; the service can be declared again with add_service.']);
+            await ctx.api.deleteService(svc.id);
+            return `Service ${svc.id} (“${svc.name}”) deleted. Publish so the declaration and the block list follow.`;
+        },
+    },
+    {
+        name: 'suppress_issue',
+        ...meta('suppress_issue'),
+        description: 'Suppress a compliance issue with a reason (the reason is the record and appears in the audit trail). Two-step.',
+        inputSchema: { site: SITE, issue: z.string().describe('issue id, or an issue code such as unclassified_tracker when the site has exactly one open issue with it'), reason: z.string().min(1).max(500), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const ref = String(args.issue ?? '').trim();
+            const issues = await ctx.api.issuesOf(id, 'all');
+            const byId = issues.find((i) => i.id === ref);
+            const byCode = issues.filter((i) => i.code === ref && i.status === 'open');
+            const issue = byId ?? (byCode.length === 1 ? byCode[0] : null);
+            if (!issue)
+                return byCode.length > 1 ? `${byCode.length} open issues carry code ${ref}; pass the id of the one you mean: ${byCode.map((i) => i.id).join(', ')}.` : `No issue “${ref}” on site ${id}. Use get_compliance_status.`;
+            const reason = str(args.reason);
+            if (!reason)
+                throw new CliError('usage', 'A `reason` is required — it is kept with the issue.', 2);
+            if (args.confirm !== true)
+                return plan(`Would suppress issue ${issue.id} (${issue.code}, ${issue.severity}) on site ${id}.`, jsonDiff({ status: issue.status, suppress_reason: issue.suppress_reason ?? null }, { status: 'suppressed', suppress_reason: reason }, 'current', 'proposed'), ['', 'Suppressing does not make the finding lawful; it records that a person decided the rule does not apply here, and why.']);
+            const out = await ctx.api.suppressIssue(issue.id, reason);
+            return `Issue ${out.id} (${out.code}) is now ${out.status}: “${out.suppress_reason}”.`;
+        },
+    },
+    {
+        name: 'unsuppress_issue',
+        ...meta('unsuppress_issue'),
+        description: 'Reopen a suppressed compliance issue. Two-step.',
+        inputSchema: { site: SITE, issue: z.string().describe('issue id'), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const issue = (await ctx.api.issuesOf(id, 'suppressed')).find((i) => i.id === String(args.issue));
+            if (!issue)
+                return `No suppressed issue “${args.issue}” on site ${id}.`;
+            if (args.confirm !== true)
+                return plan(`Would reopen issue ${issue.id} (${issue.code}).`, jsonDiff({ status: 'suppressed', suppress_reason: issue.suppress_reason ?? null }, { status: 'open', suppress_reason: null }, 'current', 'proposed'));
+            const out = await ctx.api.unsuppressIssue(issue.id);
+            return `Issue ${out.id} (${out.code}) is now ${out.status}.`;
+        },
+    },
+    // ---- versions -------------------------------------------------------------------------------
+    {
+        name: 'promote_version',
+        ...meta('promote_version'),
+        description: 'Publish a preview version to production, as it is. `confirm:false` shows the diff between the current production version and the preview version.',
+        inputSchema: { site: SITE, number: z.number().int().min(1).describe('the preview version number'), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const versions = await ctx.api.versions(id);
+            const target = versions.find((v) => v.number === Number(args.number));
+            if (!target)
+                return `Site ${id} has no v${args.number}. Versions: ${versions.map((v) => `v${v.number} (${v.environment ?? 'production'})`).join(', ') || 'none'}.`;
+            if ((target.environment ?? 'production') !== 'preview')
+                return `v${target.number} is already a ${target.environment ?? 'production'} version; promote takes a preview version.`;
+            const live = versions.filter((v) => (v.environment ?? 'production') === 'production').sort((a, b) => b.number - a.number)[0] ?? null;
+            const targetFull = await ctx.api.version(target.id);
+            const liveFull = live ? await ctx.api.version(live.id) : null;
+            const diff = jsonDiff(liveFull?.config ?? {}, targetFull.config ?? {}, `production v${live?.number ?? '—'}`, `preview v${target.number}`);
+            if (args.confirm !== true)
+                return plan(`Would promote preview v${target.number} of site ${id} to production${live ? `, replacing v${live.number}` : ''}.`, diff, ['', 'The publish gates (plan features, lint) run again on promotion.']);
+            const out = await ctx.api.promote(target.id);
+            return [`Promoted v${target.number} of site ${id} to production.`, jsonBlock(out)].join('\n');
+        },
+    },
+    // ---- templates ------------------------------------------------------------------------------
+    {
+        name: 'list_templates',
+        ...meta('list_templates'),
+        description: 'Banner templates: the built-in ones and the workspace’s own.',
+        inputSchema: {},
+        readOnlyHint: true,
+        async run(ctx) {
+            const items = await ctx.api.templates();
+            if (!items.length)
+                return 'No templates.';
+            return items.map((t) => `- ${t.name}  id ${t.id}  (${t.org_id ? 'workspace' : 'built-in'})${t.description ? `\n  ${t.description}` : ''}`).join('\n');
+        },
+    },
+    {
+        name: 'get_template',
+        ...meta('get_template'),
+        description: 'One template with its full BannerConfig.',
+        inputSchema: { template: z.string().describe('template id or name') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const t = await templateByRef(ctx, String(args.template));
+            if (!t)
+                return `No template “${args.template}”. Use list_templates.`;
+            const full = await ctx.api.template(t.id);
+            return [`${full.name} (${full.org_id ? 'workspace' : 'built-in'}) · id ${full.id}`, jsonBlock(full.config ?? null)].join('\n');
+        },
+    },
+    {
+        name: 'apply_template',
+        ...meta('apply_template'),
+        description: 'Apply a template to one or more site drafts (never publishes). `groups` limits what is copied: layout, theme, texts, regions, consent_mode, behaviour. Two-step.',
+        inputSchema: {
+            template: z.string().describe('template id or name'),
+            sites: z.array(z.string()).optional().describe('site ids/domains/names; default: the resolved site'),
+            site: SITE,
+            groups: z.array(z.enum(['layout', 'theme', 'texts', 'regions', 'consent_mode', 'behaviour'])).optional(),
+            env: ENV.optional().describe('which draft to write, default preview'),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const t = await templateByRef(ctx, String(args.template));
+            if (!t)
+                return `No template “${args.template}”. Use list_templates.`;
+            const refs = list(args.sites);
+            const siteIds = refs?.length ? await Promise.all(refs.map((r) => resolveSite(ctx, r))) : [await resolveSite(ctx, args.site)];
+            const env = str(args.env) ?? 'preview';
+            const groups = list(args.groups);
+            if (args.confirm !== true) {
+                const full = await ctx.api.template(t.id);
+                const cfg = (full.config ?? {});
+                const picked = groups?.length ? Object.fromEntries(groups.map((g) => [g, cfg[g]])) : cfg;
+                return plan(`Would apply template “${t.name}” (${groups?.length ? groups.join(', ') : 'all groups'}) to the ${env} draft of ${siteIds.length} site(s): ${siteIds.join(', ')}.`, jsonDiff({}, picked, 'nothing', `template ${t.name}`), ['', 'Texts are merged per language and category the site already has; nothing is published.']);
+            }
+            const results = await ctx.api.applyTemplate(t.id, { site_ids: siteIds, groups: groups?.length ? groups : undefined, env });
+            return results.map((r) => `- ${r.site_id}: ${r.ok ? 'draft updated' : `FAILED — ${r.error ?? 'unknown error'}`}${r.ok && r.lint?.issues?.length ? ` (lint: ${r.lint.issues.map((i) => i.code).join(', ')})` : ''}`).join('\n') + '\n\nNothing is published; use push_config or the dashboard to publish.';
+        },
+    },
+    {
+        name: 'save_template',
+        ...meta('save_template'),
+        description: 'Save a workspace template from a site’s draft (or from a full BannerConfig), or update an existing workspace template. Needs the shared_templates feature. Two-step.',
+        inputSchema: {
+            name: z.string().min(1).max(80),
+            site: SITE.describe('site whose draft becomes the template (when no config is given)'),
+            env: ENV.optional().describe('which draft, default production'),
+            config: z.record(z.unknown()).optional().describe('a full BannerConfig instead of a site draft'),
+            template: z.string().optional().describe('id or name of an existing workspace template to update'),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const name = str(args.name);
+            if (!name)
+                throw new CliError('usage', 'Pass `name`.', 2);
+            const existing = args.template ? await templateByRef(ctx, String(args.template)) : null;
+            if (args.template && !existing)
+                return `No template “${args.template}”. Use list_templates.`;
+            if (existing && !existing.org_id)
+                return `“${existing.name}” is built-in and cannot be changed; save a copy under a new name instead.`;
+            let config;
+            let source;
+            if (args.config && typeof args.config === 'object') {
+                config = args.config;
+                source = 'the given config';
+            }
+            else {
+                const id = await resolveSite(ctx, args.site);
+                const env = str(args.env) ?? 'production';
+                config = (await ctx.api.getDraft(id, env)).config;
+                source = `the ${env} draft of site ${id}`;
+            }
+            if (args.confirm !== true) {
+                const before = existing ? ((await ctx.api.template(existing.id)).config ?? {}) : {};
+                return plan(`Would ${existing ? `update template “${existing.name}”` : `create template “${name}”`} from ${source}.`, jsonDiff(before, config, existing ? `template ${existing.name}` : 'no template', name), ['', 'Requires the shared_templates plan feature (402 otherwise).']);
+            }
+            const saved = existing
+                ? await ctx.api.updateTemplate(existing.id, { name, config: config })
+                : await ctx.api.createTemplate({ name, config: config });
+            return `${existing ? 'Updated' : 'Saved'} template “${saved.name}” (${saved.id}). Apply it with apply_template.`;
+        },
+    },
+    {
+        name: 'delete_template',
+        ...meta('delete_template'),
+        description: 'Delete a workspace template (built-ins cannot be deleted). Two-step; destructive.',
+        inputSchema: { template: z.string().describe('template id or name'), confirm: CONFIRM },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const t = await templateByRef(ctx, String(args.template));
+            if (!t)
+                return `No template “${args.template}”.`;
+            if (!t.org_id)
+                return `“${t.name}” is built-in and cannot be deleted.`;
+            if (args.confirm !== true)
+                return plan(`Would DELETE workspace template “${t.name}” (${t.id}).`, jsonDiff({ id: t.id, name: t.name }, {}, 'template', 'deleted'), ['', 'Sites it was applied to keep their drafts; only the template goes.']);
+            await ctx.api.deleteTemplate(t.id);
+            return `Template “${t.name}” deleted.`;
+        },
+    },
+    // ---- webhooks -------------------------------------------------------------------------------
+    {
+        name: 'list_webhooks',
+        ...meta('list_webhooks'),
+        description: 'Outbound webhook endpoints of the workspace (never their secrets), with last delivery status.',
+        inputSchema: { site: SITE.describe('only endpoints of this site') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const items = await ctx.api.webhooks(args.site ? await resolveSite(ctx, args.site) : undefined);
+            if (!items.length)
+                return 'No webhook endpoints.';
+            return items.map((e) => `- ${e.url}  id ${e.id}\n  events ${(e.events ?? []).join(', ')} · ${e.enabled === false ? 'disabled' : 'enabled'} · scope ${e.site_id ? `site ${e.site_id}` : 'workspace'} · last delivery ${e.last_delivery_at ?? '—'} ${e.last_status ?? ''}`).join('\n');
+        },
+    },
+    {
+        name: 'create_webhook',
+        ...meta('create_webhook'),
+        description: 'Create a webhook endpoint (https only). The signing secret is returned once, in the confirmed answer, and can only be rotated afterwards. Two-step.',
+        inputSchema: {
+            url: z.string().url(),
+            events: z.array(z.string()).optional().describe('event types, default ["*"]'),
+            site: SITE.describe('restrict to one site; default the whole workspace'),
+            description: z.string().max(500).optional(),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const url = str(args.url);
+            if (!url || !/^https:\/\//i.test(url))
+                throw new CliError('usage', 'Pass an https `url`.', 2);
+            const events = list(args.events)?.length ? list(args.events) : ['*'];
+            const siteId = args.site ? await resolveSite(ctx, args.site) : null;
+            const body = { url, events, site_id: siteId, description: str(args.description) ?? null };
+            if (args.confirm !== true)
+                return plan(`Would create a webhook endpoint for ${url}.`, jsonDiff({}, body, 'no endpoint', 'new endpoint'), ['', 'Requires the webhooks plan feature. The secret is shown once, in the confirmed answer — store it in the receiver at once.']);
+            const created = await ctx.api.createWebhook(body);
+            const endpoint = created.endpoint ?? created;
+            return [`Endpoint ${endpoint.id} created for ${url}.`, created.secret ? `Signing secret (shown once): ${created.secret}` : 'The gateway returned no secret.', 'Verify deliveries with the Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature).'].join('\n');
+        },
+    },
+    {
+        name: 'update_webhook',
+        ...meta('update_webhook'),
+        description: 'Change a webhook endpoint: url, events, description, enabled. Two-step.',
+        inputSchema: { webhook: z.string().describe('endpoint id or url'), url: z.string().url().optional(), events: z.array(z.string()).optional(), description: z.string().nullable().optional(), enabled: z.boolean().optional(), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const hook = await webhookByRef(ctx, String(args.webhook));
+            if (!hook)
+                return `No webhook endpoint “${args.webhook}”. Use list_webhooks.`;
+            const patch = compact({ url: str(args.url), events: list(args.events), enabled: bool(args.enabled), description: 'description' in args ? (args.description === null ? null : str(args.description) ?? null) : undefined });
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', 'Nothing to change: pass url, events, description or enabled.', 2);
+            const view = (h) => ({ url: h.url, events: h.events, description: h.description, enabled: h.enabled });
+            if (args.confirm !== true)
+                return plan(`Would update endpoint ${hook.id}.`, jsonDiff(view(hook), { ...view(hook), ...patch }, 'current', 'proposed'));
+            const updated = await ctx.api.request('PATCH', `/webhooks/${hook.id}`, { body: patch });
+            return [`Endpoint ${hook.id} updated.`, jsonBlock(updated)].join('\n');
+        },
+    },
+    {
+        name: 'delete_webhook',
+        ...meta('delete_webhook'),
+        description: 'Delete a webhook endpoint and its delivery history. Two-step; destructive.',
+        inputSchema: { webhook: z.string().describe('endpoint id or url'), confirm: CONFIRM },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const hook = await webhookByRef(ctx, String(args.webhook));
+            if (!hook)
+                return `No webhook endpoint “${args.webhook}”.`;
+            if (args.confirm !== true)
+                return plan(`Would DELETE endpoint ${hook.id} (${hook.url}) and its deliveries.`, jsonDiff({ id: hook.id, url: hook.url, events: hook.events }, {}, 'endpoint', 'deleted'));
+            await ctx.api.deleteWebhook(hook.id);
+            return `Endpoint ${hook.id} (${hook.url}) deleted.`;
+        },
+    },
+    // ---- alert channels -------------------------------------------------------------------------
+    {
+        name: 'list_alert_channels',
+        ...meta('list_alert_channels'),
+        description: 'Where alerts are delivered (e-mail, Slack, webhook) and the rules on each channel. Secrets are never returned.',
+        inputSchema: {},
+        readOnlyHint: true,
+        async run(ctx) {
+            const items = await channels(ctx);
+            if (!items.length)
+                return 'No alert channels. Alerts still appear in the inbox (list_alerts).';
+            return items.map((c) => `- ${c.name}  id ${c.id}  ${c.kind} · ${c.enabled ? 'enabled' : 'disabled'} · ${c.verified_at ? 'verified' : 'unverified'} · scope ${c.site_id ? `site ${c.site_id}` : 'workspace'}\n  config ${JSON.stringify(c.config)} · ${(c.rules ?? []).length} rule(s)`).join('\n');
+        },
+    },
+    {
+        name: 'create_alert_channel',
+        ...meta('create_alert_channel'),
+        description: 'Create an alert channel: email ({config:{to:[…]}}), slack_webhook or webhook (the URL goes in `secret`, write-only). Two-step.',
+        inputSchema: {
+            kind: z.enum(['email', 'slack_webhook', 'webhook']),
+            name: z.string().min(1).max(80),
+            config: z.record(z.unknown()).optional().describe('email: {to:["a@b.eu"]}; slack/webhook: optional {channel}'),
+            secret: z.string().optional().describe('the Slack incoming-webhook URL or the webhook URL; stored write-only'),
+            site: SITE.describe('scope the channel to one site; default the workspace'),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const kind = str(args.kind);
+            const name = str(args.name);
+            if (!kind || !name)
+                throw new CliError('usage', 'Pass `kind` and `name`.', 2);
+            const config = (args.config && typeof args.config === 'object' ? args.config : {});
+            const siteId = args.site ? await resolveSite(ctx, args.site) : null;
+            const shown = { kind, name, config, site_id: siteId, secret: args.secret ? '(set, not shown)' : '(none)' };
+            if (args.confirm !== true)
+                return plan(`Would create ${kind} alert channel “${name}”.`, jsonDiff({}, shown, 'no channel', 'new channel'), ['', 'Slack and webhook channels need the matching plan feature; e-mail is available everywhere.']);
+            const created = await ctx.api.request('POST', '/alert-channels', { body: { kind, name, config, secret: str(args.secret) ?? null, site_id: siteId } });
+            return [`Alert channel ${created.id} (“${created.name}”, ${created.kind}) created.`, 'Rules decide which alerts go there; the dashboard’s Alerts page sets them.'].join('\n');
+        },
+    },
+    {
+        name: 'update_alert_channel',
+        ...meta('update_alert_channel'),
+        description: 'Rename, enable/disable, or change the config or secret of an alert channel. Two-step.',
+        inputSchema: { channel: z.string().describe('channel id or name'), name: z.string().optional(), enabled: z.boolean().optional(), config: z.record(z.unknown()).optional(), secret: z.string().optional().describe('rotating it clears verified_at'), confirm: CONFIRM },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const ch = await channelByRef(ctx, String(args.channel));
+            if (!ch)
+                return `No alert channel “${args.channel}”. Use list_alert_channels.`;
+            const patch = compact({ name: str(args.name), enabled: bool(args.enabled), config: args.config && typeof args.config === 'object' ? args.config : undefined, secret: str(args.secret) });
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', 'Nothing to change: pass name, enabled, config or secret.', 2);
+            const view = (c) => ({ name: c.name, enabled: c.enabled, config: c.config });
+            const after = { ...view(ch), ...compact({ name: patch.name, enabled: patch.enabled, config: patch.config }) };
+            if (args.confirm !== true)
+                return plan(`Would update alert channel “${ch.name}”.`, jsonDiff(view(ch), after, 'current', 'proposed'), patch.secret ? ['', 'The secret would be replaced (it is never shown) and the channel becomes unverified until the next delivery succeeds.'] : []);
+            const updated = await ctx.api.request('PATCH', `/alert-channels/${ch.id}`, { body: patch });
+            return [`Alert channel ${updated.id} updated.`, jsonBlock(view(updated))].join('\n');
+        },
+    },
+    {
+        name: 'delete_alert_channel',
+        ...meta('delete_alert_channel'),
+        description: 'Delete an alert channel and its rules. Two-step; destructive.',
+        inputSchema: { channel: z.string().describe('channel id or name'), confirm: CONFIRM },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const ch = await channelByRef(ctx, String(args.channel));
+            if (!ch)
+                return `No alert channel “${args.channel}”.`;
+            if (args.confirm !== true)
+                return plan(`Would DELETE alert channel “${ch.name}” (${ch.kind}) and its ${(ch.rules ?? []).length} rule(s).`, jsonDiff({ id: ch.id, name: ch.name, kind: ch.kind }, {}, 'channel', 'deleted'));
+            await ctx.api.request('DELETE', `/alert-channels/${ch.id}`);
+            return `Alert channel “${ch.name}” deleted.`;
+        },
+    },
+    // ---- usage and scheduled exports -----------------------------------------------------------
+    {
+        name: 'get_usage',
+        ...meta('get_usage'),
+        description: 'Usage meters of the workspace for a month: pageviews, sites, seats, consents, scan pages, exports — used, limit and percentage.',
+        inputSchema: { period: z.string().optional().describe('YYYY-MM, default this month') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const u = await ctx.api.usage(str(args.period));
+            const meters = u.meters ?? [];
+            return [`Usage for ${u.period ?? 'this month'} (plan ${u.plan ?? ctx.me?.org?.plan ?? '—'})`, ...meters.map((m) => `- ${m.metric}: ${m.used}${m.limit == null || m.limit < 0 ? ' (unlimited)' : ` / ${m.limit}${m.pct != null ? ` (${m.pct}%)` : ''}`}`)].join('\n');
+        },
+    },
+    {
+        name: 'list_export_destinations',
+        ...meta('list_export_destinations'),
+        description: 'Customer-owned S3 buckets scheduled exports are delivered to (never the secret key).',
+        inputSchema: {},
+        readOnlyHint: true,
+        async run(ctx) {
+            const r = await ctx.api.request('GET', '/export-destinations');
+            const items = r.items ?? [];
+            if (!items.length)
+                return 'No export destinations. Register a bucket in the dashboard under Consent log → Exports.';
+            return items.map((d) => `- ${d.name}  id ${d.id}  ${d.endpoint}/${d.bucket}${d.prefix ? `/${d.prefix}` : ''} · ${d.verified_at ? 'verified' : 'unverified'}${d.last_error ? ` · last error: ${d.last_error}` : ''}`).join('\n');
+        },
+    },
+    {
+        name: 'list_export_schedules',
+        ...meta('list_export_schedules'),
+        description: 'Recurring proof exports: kind, cadence, destination, next and last run.',
+        inputSchema: { site: SITE.describe('only schedules of this site') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const items = await exportSchedules(ctx, args.site ? await resolveSite(ctx, args.site) : undefined);
+            if (!items.length)
+                return 'No scheduled exports.';
+            return items.map((s) => `- ${s.name ?? s.kind}  id ${s.id}  ${s.kind} ${s.cadence} → destination ${s.destination_name ?? s.destination_id} · ${s.enabled ? 'enabled' : 'disabled'} · next ${s.next_run_at ?? '—'} · last ${s.last_run_at ?? '—'} ${s.last_status ?? ''}`).join('\n');
+        },
+    },
+    {
+        name: 'create_export_schedule',
+        ...meta('create_export_schedule'),
+        description: 'Schedule a recurring proof export of a site to a registered destination. Needs the scheduled_exports feature. Two-step.',
+        inputSchema: {
+            site: SITE,
+            destination: z.string().describe('destination id or name'),
+            kind: z.enum(['consent_jsonl', 'consent_csv', 'audit_bundle']),
+            cadence: z.enum(['daily', 'weekly', 'monthly']),
+            env: ENV.optional(),
+            hour_utc: z.number().int().min(0).max(23).optional(),
+            day_of_week: z.number().int().min(0).max(6).optional().describe('weekly: 0 = Sunday'),
+            day_of_month: z.number().int().min(1).max(28).optional(),
+            lookback_days: z.number().int().min(1).max(395).optional(),
+            name: z.string().max(80).optional(),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const siteId = await resolveSite(ctx, args.site);
+            const dests = (await ctx.api.request('GET', '/export-destinations')).items ?? [];
+            const ref = String(args.destination ?? '').trim();
+            const dest = dests.find((d) => d.id === ref) ?? dests.find((d) => String(d.name).toLowerCase() === ref.toLowerCase());
+            if (!dest)
+                return `No export destination “${ref}”. Known: ${dests.map((d) => `${d.name} (${d.id})`).join(', ') || 'none'}.`;
+            const body = compact({ site_id: siteId, destination_id: String(dest.id), kind: str(args.kind), cadence: str(args.cadence), environment: str(args.env), hour_utc: num(args.hour_utc), day_of_week: num(args.day_of_week), day_of_month: num(args.day_of_month), lookback_days: num(args.lookback_days), name: str(args.name) });
+            if (args.confirm !== true)
+                return plan(`Would schedule a ${body.cadence} ${body.kind} export of site ${siteId} to “${dest.name}”.`, jsonDiff({}, body, 'no schedule', 'new schedule'), ['', dest.verified_at ? 'The destination is verified.' : 'Note: the destination is not verified yet; runs will fail until a probe succeeds.']);
+            const created = await ctx.api.request('POST', '/export-schedules', { body });
+            return [`Export schedule ${created.id} created.`, jsonBlock(created)].join('\n');
+        },
+    },
+    {
+        name: 'update_export_schedule',
+        ...meta('update_export_schedule'),
+        description: 'Change a scheduled export: kind, cadence, timing, window, destination, enabled. Two-step.',
+        inputSchema: {
+            schedule: z.string().describe('schedule id or name'),
+            destination: z.string().optional(),
+            kind: z.enum(['consent_jsonl', 'consent_csv', 'audit_bundle']).optional(),
+            cadence: z.enum(['daily', 'weekly', 'monthly']).optional(),
+            env: ENV.optional(),
+            hour_utc: z.number().int().min(0).max(23).optional(),
+            day_of_week: z.number().int().min(0).max(6).optional(),
+            day_of_month: z.number().int().min(1).max(28).optional(),
+            lookback_days: z.number().int().min(1).max(395).optional(),
+            enabled: z.boolean().optional(),
+            name: z.string().max(80).nullable().optional(),
+            confirm: CONFIRM,
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const all = await exportSchedules(ctx);
+            const ref = String(args.schedule ?? '').trim();
+            const s = all.find((x) => x.id === ref) ?? all.find((x) => String(x.name ?? '').toLowerCase() === ref.toLowerCase());
+            if (!s)
+                return `No export schedule “${ref}”. Use list_export_schedules.`;
+            const patch = compact({ destination_id: str(args.destination), kind: str(args.kind), cadence: str(args.cadence), environment: str(args.env), hour_utc: num(args.hour_utc), day_of_week: num(args.day_of_week), day_of_month: num(args.day_of_month), lookback_days: num(args.lookback_days), enabled: bool(args.enabled), name: 'name' in args ? (args.name === null ? null : str(args.name)) : undefined });
+            if (!Object.keys(patch).length)
+                throw new CliError('usage', 'Nothing to change.', 2);
+            const view = (x) => ({ kind: x.kind, cadence: x.cadence, environment: x.environment, hour_utc: x.hour_utc, day_of_week: x.day_of_week, day_of_month: x.day_of_month, lookback_days: x.lookback_days, enabled: x.enabled, name: x.name ?? null, destination_id: x.destination_id });
+            if (args.confirm !== true)
+                return plan(`Would update export schedule ${s.id}.`, jsonDiff(view(s), { ...view(s), ...patch }, 'current', 'proposed'));
+            const updated = await ctx.api.request('PATCH', `/export-schedules/${s.id}`, { body: patch });
+            return [`Export schedule ${updated.id} updated.`, jsonBlock(view(updated))].join('\n');
+        },
+    },
+    {
+        name: 'delete_export_schedule',
+        ...meta('delete_export_schedule'),
+        description: 'Delete a scheduled export (already delivered files stay in the bucket). Two-step; destructive.',
+        inputSchema: { schedule: z.string().describe('schedule id or name'), confirm: CONFIRM },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const all = await exportSchedules(ctx);
+            const ref = String(args.schedule ?? '').trim();
+            const s = all.find((x) => x.id === ref) ?? all.find((x) => String(x.name ?? '').toLowerCase() === ref.toLowerCase());
+            if (!s)
+                return `No export schedule “${ref}”.`;
+            if (args.confirm !== true)
+                return plan(`Would DELETE export schedule ${s.id} (${s.kind} ${s.cadence}).`, jsonDiff({ id: s.id, kind: s.kind, cadence: s.cadence }, {}, 'schedule', 'deleted'));
+            await ctx.api.request('DELETE', `/export-schedules/${s.id}`);
+            return `Export schedule ${s.id} deleted.`;
+        },
+    },
+];
+/** What to publish for a domain to verify, in one line. */
+function instructions(d) {
+    return d.verification_method === 'meta'
+        ? `<meta name="cookiecrumbs-verification" content="${d.verification_token}"> in the <head> of https://${d.hostname}/`
+        : `DNS TXT record _cookiecrumbs.${d.hostname} = "cookiecrumbs-verification=${d.verification_token}"`;
+}