@checkbox-site/mcp 0.1.0 → 0.2.0

package/dist/tools.js

@@ -1,9 +1,11 @@
 // The Checkbox MCP tools. Names are stable snake_case; descriptions are written for an LLM (when to use, what to pass,
 // what the output means, what to do next). Every tool is a thin call (or two) to the public /v1 API, so scopes,
 // test/live isolation and validation are exactly the API's.
+import { nestedUnknownMessage, unknownArgumentsMessage, unknownKeysParams } from "./unknown-args.js";
 import { z } from 'zod';
+import { planTodo, todoLine } from "./todo.js";
 import { CheckboxApiError } from "./api.js";
-import { nextActionOf, untrusted } from "./format.js";
+import { ciHint, nextActionOf, untrusted } from "./format.js";
 import { keyAllows } from "./permissions.js";
 /** A failure the tool explains itself (not an API error): rendered as an error result with a next step. */
 export class ToolError extends Error {
@@ -31,20 +33,47 @@ const jurisdictions = z
     .union([z.literal('all'), z.array(z.string().max(10)).max(60)])
     .describe('Where the business sells: "all" (default) or state codes like ["US-CA","US-NY"] ("CA" works too). Federal law is always included.');
 const asOf = z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe('Evaluate the law as of this date, YYYY-MM-DD (default today).');
-const intervalStr = z.string().max(20).describe('Billing interval: "day", "week", "month" or "year".');
+/**
+ * Audit P2: notice kinds have two names for the trial email (trial_reminder in checks / verify, trial_ending in Notices).
+ * Every MCP tool accepts both (and charge_notice where the API checks it) and sends the API the name it expects.
+ */
+const EMAIL_KINDS = ['acknowledgment', 'trial_reminder', 'trial_ending', 'renewal_reminder', 'price_change', 'annual_terms', 'charge_notice', 'cancellation_confirmation'];
+const emailKind = z.enum(EMAIL_KINDS);
+/** The checks / verify API name (trial_reminder). */
+export const checkKind = (k) => (k === 'trial_ending' ? 'trial_reminder' : k);
+/** The Notices API name (trial_ending). */
+export const noticeKind = (k) => (k === 'trial_reminder' ? 'trial_ending' : k);
+const intervalStr = z.string().max(20).describe('Billing interval: day, week, month or year.');
 const planTermsShape = {
     merchant_name: z.string().max(200).optional().describe('Brand shown to subscribers, e.g. "Acme".'),
+    brand_name: z.string().max(200).optional().describe('Alias of merchant_name.'),
     plan_name: z.string().max(200).optional().describe('Plan / product name, e.g. "Pro".'),
-    price: z.union([z.number().positive(), z.string().max(40)]).optional().describe('Recurring price in MAJOR units, e.g. 19.99. Or give amount.'),
-    amount: z.number().int().positive().optional().describe('Recurring price in MINOR units, Stripe style: 1999 = $19.99.'),
+    price: z.union([z.number().positive(), z.string().max(40)]).optional().describe('Recurring price, major units (19.99).'),
+    amount: z.number().int().positive().optional().describe('Or minor units (1999 = $19.99).'),
     currency: z.string().length(3).optional().describe('ISO currency, default "usd".'),
     interval: intervalStr.optional(),
-    interval_count: z.number().int().min(1).max(36).optional().describe('Intervals between charges (default 1; 3 + month = quarterly).'),
+    interval_count: z.number().int().min(1).max(36).optional().describe('Default 1; 3 + month = quarterly.'),
     trial_days: z.number().int().min(0).max(730).optional().describe('Free-trial days (0 or absent = no trial).'),
-    cancel_url: z.string().max(2048).optional().describe('https URL where subscribers cancel online. Strongly recommended: generated text uses it.'),
+    // Pilot round 12 (change-guard): no way to describe a promo, so "$5 first month (50% off)" passed against a 20% coupon.
+    // The API also takes intro_amount / intro_amount_off (minor units); kept out here for the tool list's size.
+    intro_price: z.number().positive().optional().describe('Promo first-period price, major units ($8 → 8).'),
+    intro_percent_off: z.number().gt(0).lt(100).optional().describe('Or the promo as % off (coupon percent_off).'),
+    intro_periods: z.number().int().min(1).max(36).optional().describe('Billing periods the promo lasts (default 1).'),
+    cancel_url: z.string().max(2048).optional().describe('https URL where subscribers cancel online (used in generated text).'),
     cancel_timing: z.enum(['period_end', 'immediately']).optional().describe('When a cancellation takes effect (default period_end).'),
 };
-const planTerms = z.object(planTermsShape);
+/**
+ * Pilot round 13 (sveltekit, change-guard, api-only): nested objects were not strict, so plans[].price_cents, a bogus
+ * key or merchant.name were dropped with no word. Nested objects now refuse unknown keys with the closest known one.
+ */
+export function strictObject(shape, where, hints = {}) {
+    const known = Object.keys(shape);
+    return z
+        .object(shape, unknownKeysParams((keys) => nestedUnknownMessage(where, keys, known, hints)))
+        .strict();
+}
+const planTerms = strictObject(planTermsShape, 'terms');
+const merchantTerms = strictObject(planTermsShape, 'merchant');
 // Values above 30 are clamped to 30 instead of rejected (pilot: wait=60 was a raw -32602 validation error).
 const wait = z
     .number()
@@ -55,32 +84,51 @@ const wait = z
     .describe('Seconds to wait for the result before answering (0-30; larger values wait 30; default 25). Use 0 to return at once and poll later.');
 const listLimit = z.number().int().min(1).max(100).optional().describe('How many to return (1-100, default 10).');
 const startingAfter = z.string().max(100).optional().describe('Pagination cursor: the last id of the previous page (when has_more was true).');
+/** Plan fields agents reach for, mapped to the setup field (plans[] amounts are minor units). */
+const PLAN_FIELD_HINTS = Object.freeze({
+    price: 'amount (minor units: 800 = $8.00)',
+    price_cents: 'amount (minor units: 800 = $8.00)',
+    amount_cents: 'amount',
+    unit_amount: 'amount',
+    trial_period_days: 'trial_days',
+    billing_interval: 'interval',
+    plan_name: 'name',
+    stripe_price: 'price_id',
+    intro_price: 'intro_amount (minor units)',
+    cancel_url: 'account_url (a site field, not a plan field)',
+});
 const setupFactsShape = {
     site_url: z.string().max(2048).optional().describe('Public URL of the site (production, or a preview deployment), e.g. "https://acme.example".'),
     checkout_url: z.string().max(2048).optional().describe('Page where customers subscribe (pricing or checkout page).'),
-    account_url: z.string().max(2048).optional().describe('Account page where subscribers manage / cancel.'),
-    terms_url: z.string().max(2048).optional().describe('Terms of service URL. Checkbox fetches and checks it.'),
-    privacy_url: z.string().max(2048).optional().describe('Privacy policy URL.'),
-    refund_url: z.string().max(2048).optional().describe('Refund policy URL.'),
-    cancellation_url: z.string().max(2048).optional().describe('Cancellation policy URL, if separate from the Terms.'),
+    account_url: z.string().max(2048).nullable().optional().describe('Account page where subscribers manage / cancel (null clears a URL).'),
+    terms_url: z.string().max(2048).nullable().optional().describe('Terms of service URL. Checkbox fetches and checks it.'),
+    privacy_url: z.string().max(2048).nullable().optional().describe('Privacy policy URL.'),
+    refund_url: z.string().max(2048).nullable().optional().describe('Refund policy URL.'),
+    cancellation_url: z.string().max(2048).nullable().optional().describe('Cancellation policy URL, if separate from the Terms.'),
     support_email: z.string().max(320).optional().describe('Support address subscribers can write to.'),
-    merchant_name: z.string().max(100).optional().describe('The brand subscribers know (names the seller in generated disclosures), e.g. from the <title> or package.json. Default: the host name, which the plan then asks you to replace.'),
+    merchant_name: z.string().max(100).optional().describe('The brand subscribers know (names the seller in generated disclosures), e.g. from the <title> or package.json (also accepted as "brand"). Default: the host name, which the plan then asks you to replace.'),
     billing_platform: z
         .enum(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'woocommerce', 'custom'])
         .optional()
         .describe('Billing platform the code uses.'),
     plans: z
-        .array(z.object({
+        .array(strictObject({
         name: z.string().max(200).optional(),
         amount: z.number().int().min(0).optional().describe('Minor units (1900 = $19).'),
         currency: z.string().length(3).optional(),
         interval: z.enum(['day', 'week', 'month', 'year']).optional(),
         interval_count: z.number().int().min(1).max(36).optional(),
         trial_days: z.number().int().min(0).max(730).optional(),
-    }))
+        // Pilot round 13 (change-guard): intro / promo terms had nowhere to live, so the generated copy dropped them.
+        intro_amount: z.number().int().min(0).optional().describe('Promo first-period price, minor units.'),
+        intro_percent_off: z.number().gt(0).lt(100).optional(),
+        intro_amount_off: z.number().int().positive().optional(),
+        intro_periods: z.number().int().min(1).max(36).optional(),
+        price_id: z.string().max(200).optional().describe('Stripe Price id.'),
+    }, 'plans[]', PLAN_FIELD_HINTS))
         .max(50)
         .optional()
-        .describe('Plans and prices found in the code, e.g. [{"name":"Pro","amount":1900,"currency":"usd","interval":"month","trial_days":14}]. They decide which laws apply (trials, annual terms).'),
+        .describe('Plans and prices found in the code, e.g. [{"name":"Pro","amount":1900,"currency":"usd","interval":"month","trial_days":14}]; a promo adds intro_percent_off and intro_periods. They decide which laws apply and what generated copy states.'),
     project: z
         .object({
         name: z.string().max(200).optional().describe('package.json name.'),
@@ -88,13 +136,15 @@ const setupFactsShape = {
         package_manager: z.string().max(20).optional(),
         layout_file: z.string().max(500).optional().describe('Root layout / template where the snippet belongs, e.g. "app/layout.tsx".'),
         public_dir: z.string().max(500).optional(),
+        // Round-3 pilot (nextjs): kind was optional here but required by the API (parameter_missing
+        // project.checkout_code.0.kind). The schema now matches the API.
         checkout_code: z
-            .array(z.object({ file: z.string().max(500), line: z.number().int().min(1).optional(), kind: z.string().max(60).optional() }))
+            .array(z.object({ file: z.string().max(500), line: z.number().int().min(1).optional(), kind: z.string().min(1).max(60).describe('Required: stripe_checkout_session, stripe_payment_link, stripe_pricing_table, stripe_elements, subscribe_button, shopify_checkout…') }))
             .max(100)
             .optional()
             .describe('Where Stripe Checkout Sessions / payment links are created, e.g. [{"file":"app/api/checkout/route.ts","line":12,"kind":"stripe_checkout_session"}].'),
         pay_buttons: z
-            .array(z.object({ file: z.string().max(500), line: z.number().int().min(1).optional(), kind: z.string().max(60).optional() }))
+            .array(z.object({ file: z.string().max(500), line: z.number().int().min(1).optional(), kind: z.string().min(1).max(60).describe('Required, e.g. subscribe_button.') }))
             .max(100)
             .optional()
             .describe('Where the subscribe / pay buttons are rendered.'),
@@ -130,9 +180,7 @@ async function resolveSite(api, site) {
             operation_id: 'createSetupSession',
         });
     }
-    throw new ToolError(`The account has ${list.data.length}${list.has_more ? '+' : ''} sites; pass "site". Sites: ${list.data.map((s) => `${s.id} (${s.url})`).join(', ')}.`, undefined, {
-        sites: list.data.map((s) => ({ id: s.id, url: s.url })),
-    });
+    throw new ToolError(`The account has ${list.data.length}${list.has_more ? '+' : ''} sites; pass "site". Sites: ${list.data.map((s) => `${s.id} (${s.name ? `${untrusted(s.name, 60)}, ` : ''}${untrusted(s.url, 100)})`).join(', ')}.`, { type: 'pass_site', message: `Call the same tool again with "site" set to one of the ids above${list.has_more ? ' (list_sites shows the rest)' : ''}.` }, { sites: list.data.map((s) => ({ id: s.id, name: s.name ?? null, url: s.url })) });
 }
 /** The setup session to act on: the given id or the newest. */
 async function resolveSetupSession(api, id) {
@@ -145,40 +193,158 @@ async function resolveSetupSession(api, id) {
     return list.data[0].id;
 }
 const statusLine = (v) => (typeof v === 'string' ? v.toUpperCase() : String(v));
-/** Bullets for the failing / unclear checks of a /v1/checks result (the model reads these before the JSON). */
-function checkNotes(r, max = 8) {
-    const bad = r.checks.filter((c) => c.status === 'fail' || c.status === 'needs_review');
-    const notes = bad.slice(0, max).map((c) => {
+/**
+ * One bullet per check that needs something from the human, in the user-facing labels (status.ts): FIX NEEDED with the
+ * one change, YOUR CALL with the question and the recommended answer, LIVE CHECK PENDING with how it completes. The
+ * texts are Checkbox's own wording (never quoted from the checked page / email).
+ *
+ * Pilot round 12 (change-guard): the bullet said "NEEDS A FIX" / "LOOKS COMPLIANT" while the JSON said needs_review.
+ * Each bullet now carries the JSON status in brackets and its label never says more than the status does: a fix
+ * Checkbox could not confirm (needs_review) is YOUR CALL, and a note is CHECKS PASS (on a pass) or NOTE (needs_review).
+ * Round 16 (item 21, change-guard: the headline said "1 fix needed" over a "YOUR CALL" bullet): the bullet uses the
+ * roll-up's own word. A check the roll-up counts as a fix is FIX NEEDED; the bracket still says when it is needs_review.
+ */
+export function complianceBullet(checkId, c, fallbackStatus, title) {
+    const st = ['pass', 'fail', 'needs_review', 'not_applicable'].includes(fallbackStatus) ? ` [${fallbackStatus}]` : '';
+    if (!c)
+        return fallbackStatus === 'fail' || fallbackStatus === 'needs_review' ? `${fallbackStatus === 'fail' ? 'FIX NEEDED' : 'YOUR CALL'} ${checkId}${st}: ${title}` : null;
+    switch (c.status) {
+        case 'needs_fix':
+            return fallbackStatus === 'needs_review' ? `FIX NEEDED ${checkId}${st}: Checkbox could not confirm this is met; the fix: ${c.fix ?? title}` : `FIX NEEDED ${checkId}${st}: ${c.fix ?? title}`;
+        case 'your_call':
+            return `YOUR CALL ${checkId}${st}: ${c.question?.text ?? title}${c.question?.recommended ? ` Recommended: ${c.question.recommended}` : ''}`;
+        case 'pending_live_check':
+            return `LIVE CHECK PENDING ${checkId}${st}: ${c.pending_live_check ? `${c.pending_live_check.what} — ${c.pending_live_check.completes}` : title} (counts as passing the checks)`;
+        case 'compliant':
+            return c.note ? `${fallbackStatus === 'needs_review' ? 'NOTE' : 'CHECKS PASS'} ${checkId}${st}: ${c.note}` : null;
+        default:
+            return null;
+    }
+}
+/** Bullets for the checks of a /v1/checks result that need something (the model reads these before the JSON). */
+function checkNotes(r, max = 8, covered) {
+    const rank = { needs_fix: 0, your_call: 1, pending_live_check: 2, compliant: 3 };
+    // Agent audit round 2: six "NEEDS A FIX" lines with generic "<interval> at <price>" wording competed with the one
+    // engine-verified replacement that fixes all of them; when a verified fix covers a check, the line says so instead.
+    const coveredBy = (c) => !!covered && c.compliance?.status === 'needs_fix' && !(covered.except ?? []).includes(c.check_id);
+    const lines = r.checks
+        .map((c) => {
+        const line = coveredBy(c) ? `FIX NEEDED ${c.check_id} [${c.status}]: fixed by ${covered.by}` : complianceBullet(c.check_id, c.compliance, c.status, c.title);
         const cite = c.requirements?.[0]?.citation;
-        // The catalog title, not the explanation: explanations quote the checked page / email (untrusted text).
-        return `${c.status === 'fail' ? 'FAIL' : 'REVIEW'} ${c.check_id}: ${c.title}${cite ? ` [${cite}]` : ''} (explanation and fix in the JSON)`;
-    });
-    if (bad.length > max)
-        notes.push(`…and ${bad.length - max} more (see checks in the JSON).`);
+        return { c, line: line && cite && c.compliance_status !== 'compliant' ? `${line} [${cite}]` : line, r: rank[c.compliance_status ?? (c.status === 'fail' ? 'needs_fix' : 'your_call')] ?? 9 };
+    })
+        .filter((x) => !!x.line)
+        .sort((a, b) => a.r - b.r);
+    const notes = lines.slice(0, max).map((x) => x.line);
+    if (lines.length > max)
+        notes.push(`…and ${lines.length - max} more (see checks in the JSON).`);
     for (const w of r.warnings ?? [])
         notes.push(`Warning ${w.code}: ${w.message}`);
+    // A pass, or a needs_review whose roll-up is compliant (e.g. Stripe's own styling of custom_text, shown as a note).
+    const ci = ciHint(r.verdict === 'pass' || ['compliant', 'pending_live_check', 'verified_live'].includes(r.compliance?.status ?? ''));
+    if (ci)
+        notes.push(ci);
     return notes;
 }
-const verdictHeadline = (what, r) => `${what}: ${statusLine(r.verdict)} (${r.summary.fail} failing, ${r.summary.needs_review} need review, ${r.summary.pass} passing).`;
+/**
+ * Audit P1: a headline never says "Compliant": it says "Checks pass" (or "Not required for this plan" when no check
+ * applies), then the counts.
+ */
+export function plainLabel(label) {
+    return label
+        .replace(/^Looks compliant(?: with a note)?(?: — live check pending)?/i, 'Checks pass')
+        .replace(/\bCompliant\b/g, 'Checks pass')
+        .replace(/ is compliant\b/g, ': checks pass');
+}
+/** Audit P3: a check's evidence.summary / item details that only repeat its explanation are dropped. */
+function withoutDuplicateEvidence(c) {
+    const explanation = typeof c.explanation === 'string' ? c.explanation : '';
+    const ev = c.evidence;
+    if (!ev || !explanation)
+        return c;
+    const { summary, items, ...rest } = ev;
+    const same = (t) => typeof t === 'string' && t.length > 0 && explanation.includes(t);
+    return {
+        ...c,
+        evidence: {
+            ...rest,
+            ...(summary && !same(summary) ? { summary } : {}),
+            ...(items ? { items: items.map(({ detail, ...i }) => (same(detail) ? i : { ...i, detail })) } : {}),
+        },
+    };
+}
+/** Audit P3: requirement ids as their citations (deduplicated), at most `max` plus "and N more". */
+export function citationList(ids, requirements, max = 8) {
+    const byId = new Map((requirements ?? []).map((q) => [q.id, q.citation]));
+    const cites = [...new Set(ids.map((id) => byId.get(id) ?? id))];
+    return `${cites.slice(0, max).join('; ')}${cites.length > max ? `; and ${cites.length - max} more` : ''}`;
+}
+/** Audit P3: shortens at a word boundary, never mid-word. */
+export function clipWords(v, n) {
+    if (typeof v !== 'string' || v.length <= n)
+        return v;
+    const cut = v.slice(0, n - 1);
+    const space = cut.lastIndexOf(' ');
+    return `${(space > n * 0.6 ? cut.slice(0, space) : cut).replace(/[\s,;:.(—-]+$/, '')}…`;
+}
+const verdictHeadline = (what, r) => {
+    if (r.verdict === 'not_applicable')
+        return `${what}: Not required for this plan.`;
+    const label = r.compliance ? plainLabel(r.compliance.label) : statusLine(r.verdict);
+    // One counting system per headline: the task-based status label only (the per-check counts stay in data.summary).
+    // Pilot round 12: "Checks pass" next to verdict needs_review read as a contradiction; the headline names the verdict
+    // and the checks that keep it open.
+    if (r.verdict !== 'pass' && /^Checks pass/.test(label)) {
+        const open = r.checks.filter((c) => c.status === r.verdict).map((c) => c.check_id);
+        return `${what}: ${label} (verdict ${r.verdict}${open.length ? `: ${open.slice(0, 4).join(', ')}` : ''}).`;
+    }
+    return `${what}: ${label}.`;
+};
 /**
  * Keeps what the model needs to act and drops the bulk (everything stays available through the API): failing / unclear
  * checks with their first citations, the ids of passing checks, and failing / unclear requirements only. A check run
  * over "all" jurisdictions otherwise lists every state's requirement on every check (> 60 KB).
  */
+const FAILING_REQUIREMENTS_SHOWN = 8;
+/** Agent audit round 2: a passing result no longer echoes the 2 KB replacement / corrected params it did not need. */
+function withoutUnneededFix(r) {
+    const counts = r.compliance?.counts;
+    if (!counts || (counts.needs_fix ?? 0) > 0 || r.verdict === 'fail')
+        return r;
+    const { replacement: _r, plan_replacements: _pr, ...rest } = r;
+    const correction = rest.correction;
+    if (correction && !correction.patch?.length) {
+        const { corrected_params: _c, ...c } = correction;
+        return { ...rest, correction: c };
+    }
+    return rest;
+}
 function slimCheckResult(r) {
     const { checks, requirements, ...rest } = r;
     const open = (s) => s === 'fail' || s === 'needs_review';
+    const needsSomething = (c) => open(c.status) || c.compliance_status === 'pending_live_check' || c.compliance?.note;
     return {
         ...rest,
         checks: (checks ?? [])
-            .filter((c) => open(c.status))
+            .filter((c) => needsSomething(c))
             .map(({ requirements: reqs, ...c }) => ({
-            ...c,
+            ...withoutDuplicateEvidence(c),
             citations: [...new Set((reqs ?? []).map((q) => q.citation))].slice(0, 6),
             jurisdictions: [...new Set((reqs ?? []).map((q) => q.jurisdiction))],
         })),
         passing_checks: (checks ?? []).filter((c) => c.status === 'pass').map((c) => c.check_id),
-        failing_requirements: (requirements ?? []).filter((q) => open(q.status)).map((q) => ({ id: q.id, citation: q.citation, status: q.status })),
+        // Audit P1: failing_requirements lists only failing requirements; the ones left to review are counted apart.
+        // Agent audit round 2: a failing disclosure listed ~58 failing requirements (most of the payload); every check
+        // already carries its citations. The first ones are kept, with the total.
+        ...(() => {
+            const failing = (requirements ?? []).filter((q) => q.status === 'fail').map((q) => ({ id: q.id, citation: q.citation, status: q.status }));
+            return { failing_requirements: failing.slice(0, FAILING_REQUIREMENTS_SHOWN), ...(failing.length > FAILING_REQUIREMENTS_SHOWN ? { failing_requirements_total: failing.length } : {}) };
+        })(),
+        review_requirements: (() => {
+            const review = (requirements ?? []).filter((q) => q.status === 'needs_review');
+            const citations = [...new Set(review.map((q) => q.citation))];
+            return { count: review.length, citations: citations.slice(0, 8), ...(citations.length > 8 ? { more: citations.length - 8 } : {}) };
+        })(),
     };
 }
 async function optional(p) {
@@ -213,12 +379,42 @@ async function pollDeviceToken(api, deviceCode, maxWaitMs, intervalMs) {
     }
 }
 /** What the first checks did: ran, or held because the site's domain is not verified yet (scan gate). */
-function firstCheckNote(next) {
+function firstCheckNote(next, verify) {
     if (next?.type === 'verify_domain') {
-        return 'Site registered, but Checkbox has not scanned or fetched anything from it: it only visits websites their owners have verified. Follow Next to verify the domain (ask the human to publish the DNS TXT record or file), then call get_setup_status with verify=true. Meanwhile check pages by sending their HTML (check_page_html / verify_task with html).';
+        const ro = verify?.unverified_scan?.queued
+            ? ' First read-only scan queued (unverified: no checkout is submitted until you verify the domain); its results are labeled "unverified scan" and are not evidence.'
+            : '';
+        return `Site registered, but Checkbox has not scanned it fully: it only submits checkouts on websites their owners have verified. Until then it reads the site's own public homepage and Terms / privacy pages as an unverified preview (nothing stored as evidence; see the policies step).${ro} Follow Next to verify the domain (ask the human to publish the DNS TXT record or file, or add the meta tag; or install the snippet: Checkbox verifies the domain when it sees it live), then call get_setup_status with verify=true. Meanwhile check pages by sending their HTML (check_page_html / verify_task with html).`;
     }
     return 'First checks ran (site, Terms and policies fetched, first evaluation); follow Next.';
 }
+/** One line for a read-only (unverified) scan: always labeled, never evidence. */
+export function unverifiedScanNote(u) {
+    if (!u || typeof u !== 'object')
+        return null;
+    const x = u;
+    const c = x.counts ?? {};
+    if (x.status === 'queued' || x.status === 'running')
+        return 'UNVERIFIED SCAN queued: a read-only look at the site\'s own public pages (no checkout is submitted until the domain is verified).';
+    if (x.status !== 'completed')
+        return `UNVERIFIED SCAN ${x.status ?? 'unknown'}${x.error ? `: ${untrusted(x.error, 160)}` : ''}.`;
+    const failing = (x.findings ?? []).filter((f) => f.status === 'fail').slice(0, 5).map((f) => f.check_id).filter(Boolean);
+    return `UNVERIFIED SCAN (read-only, not evidence, no checkout submitted): ${c.pages_captured ?? 0} page(s) read; ${c.failing ?? 0} failing, ${c.needs_review ?? 0} to review, ${c.passing ?? 0} passing${failing.length ? ` (failing: ${failing.join(', ')})` : ''}. Verify the domain for the full scan, which replaces it.`;
+}
+/** Round 20: one line with the plans Checkbox judges the site against (setup's site_plans), so no second call is needed. */
+export function sitePlansNote(plans) {
+    if (!Array.isArray(plans))
+        return null;
+    if (!plans.length)
+        return 'Plans: none known yet. Pass plans[] (name, price, interval, trial, Stripe price id) with update_setup, or ask the human to connect Stripe.';
+    const lines = plans.slice(0, 6).map((p) => {
+        const every = (p.interval_count ?? 1) > 1 ? `every ${p.interval_count} ${p.interval}s` : `/${p.interval ?? '?'}`;
+        const trial = p.trial_days ? `, ${p.trial_days}-day trial` : ', no trial';
+        const ids = p.stripe_price_ids?.length ? `, ${p.stripe_price_ids.slice(0, 3).join(' ')}` : '';
+        return `${untrusted(p.name ?? 'plan', 80)} ${p.price ?? ''}${every}${trial}${ids}`;
+    });
+    return `Plans Checkbox judges against (${plans.length}): ${lines.join('; ')}${plans.length > 6 ? '; …' : ''}.`;
+}
 /**
  * setup_checkbox on an OAuth connection (one-click connector): the human approved in the browser already and the
  * connection itself is the credential, so nothing is pasted or saved. The site is registered by the setup session
@@ -233,12 +429,22 @@ async function setupOverOAuth(api, session, ctx) {
         notes.push(`Human review page: ${session.review_url}`);
     let next;
     let firstCheck;
+    // Normal round 3 (nextjs): the response's steps said "checks: action_required, Not started" next to first_check's
+    // "checks: done". The session returned is the one after the first check, so both agree.
+    let fresh;
     if (session.business?.site_url) {
         try {
             const v = await api.request('POST', `/v1/setup_sessions/${enc(session.id)}/verify`, { body: {} });
+            if (v.setup_session && typeof v.setup_session === 'object')
+                fresh = v.setup_session;
             next = v.setup_session?.next_action;
-            firstCheck = { evaluated: v.evaluated ?? false, scan: v.scan ?? null, steps: v.setup_session?.steps?.map((st) => `${st.key}: ${st.status}`) ?? [] };
-            notes.push(firstCheckNote(next));
+            firstCheck = { evaluated: v.evaluated ?? false, scan: v.scan ?? null, unverified_scan: v.unverified_scan ?? null, steps: v.setup_session?.steps?.map((st) => `${st.key}: ${st.status}`) ?? [] };
+            if (v.domain_verified)
+                notes.push(`Domain verified: ${v.domain_verified.method === 'snippet' ? `the Checkbox snippet is live on ${v.domain_verified.domain}` : `${v.domain_verified.domain} (${v.domain_verified.method})`}.`);
+            notes.push(firstCheckNote(next, v));
+            const pl = sitePlansNote(v.setup_session?.site_plans);
+            if (pl)
+                notes.push(pl);
         }
         catch (err) {
             notes.push(`First checks did not run yet (${err instanceof Error ? err.message.slice(0, 160) : 'error'}); call get_setup_status with verify=true.`);
@@ -251,26 +457,67 @@ async function setupOverOAuth(api, session, ctx) {
         headline: `Setup session ${session.id} started${session.business?.site_url ? ` for ${untrusted(session.business.site_url, 100)}` : ''}${session.site ? ` (test-mode site ${session.site})` : ''}.`,
         notes,
         ...(next ? { next } : {}),
-        data: { ...session, ...(firstCheck ? { first_check: firstCheck } : {}) },
+        data: (() => {
+            const doc = { ...session, ...(fresh ?? {}) };
+            const keys = labelledPublicKeys(doc.install?.snippet_key, doc.publishable_key);
+            return withoutLegacyScore({ ...doc, ...(keys.length ? { public_keys: keys } : {}), ...(firstCheck ? { first_check: firstCheck } : {}) });
+        })(),
     };
 }
+/**
+ * Pilot round 9 (nextjs): setup_checkbox still showed `insurable: false` and `score: 26.8` next to the status label.
+ * The API keeps both (deprecated) for backward compatibility; agents see only the one status.
+ */
+export function withoutLegacyScore(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const d = data;
+    const strip = (c) => {
+        if (!c || typeof c !== 'object')
+            return c;
+        // Audit P2: the deprecated per-check counts (failing / needs_review) disagreed with the label; the label and todo stay.
+        const { score: _score, insurable: _insurable, failing: _failing, needs_review: _needsReview, ...rest } = c;
+        return rest;
+    };
+    const out = { ...d };
+    if (d.compliance)
+        out.compliance = strip(d.compliance);
+    // Audit P3: a step whose next_action is the session's own next_action does not repeat it.
+    if (Array.isArray(d.steps) && d.next_action && typeof d.next_action === 'object') {
+        const top = JSON.stringify(d.next_action);
+        out.steps = d.steps.map((st) => (st && typeof st === 'object' && JSON.stringify(st.next_action) === top ? { ...st, next_action: 'same as next_action' } : st));
+    }
+    if (d.session && typeof d.session === 'object')
+        out.session = withoutLegacyScore(d.session);
+    if (d.first_check && typeof d.first_check === 'object')
+        out.first_check = withoutLegacyScore(d.first_check);
+    return out;
+}
+/**
+ * Facts given with the first setup_checkbox call, kept (in this MCP process) until the device_code poll applies them, so
+ * an agent that polls with only the device_code does not lose them. Bounded; entries expire with the device code.
+ */
+const PENDING_SETUP_FACTS = new Map();
+function rememberSetupFacts(deviceCode, facts) {
+    if (!deviceCode || !Object.keys(facts).length)
+        return;
+    if (PENDING_SETUP_FACTS.size >= 50)
+        PENDING_SETUP_FACTS.delete(PENDING_SETUP_FACTS.keys().next().value);
+    PENDING_SETUP_FACTS.set(deviceCode, facts);
+}
 const setupCheckbox = {
     name: 'setup_checkbox',
     title: 'Set up Checkbox for this project',
     description: [
-        'Start here when the user says "add Checkbox", "make my subscriptions compliant", or no Checkbox key is configured.',
-        'Checkbox monitors a subscription business against automatic-renewal laws (FTC ROSCA, California ARL, New York and ~26 other states).',
+        'Start here when the user says "add Checkbox", "make my subscriptions compliant", or the project is not connected to Checkbox yet.',
+        'Checkbox monitors a subscription business against automatic-renewal laws (federal law, 27 states, DC and New York City: FTC ROSCA, California ARL, New York and the other state laws).',
         '',
-        'Without an API key (first run): returns a link for the HUMAN to open and click Approve (they sign up with an email link or GitHub/Google if new; free, no card).',
-        'Show them the link in one line, then call setup_checkbox again with the returned device_code — it waits up to ~50 s for the approval; call again while it says pending.',
-        'On approval it returns test-mode API keys (shown once) and a setup session. Save CHECKBOX_SECRET_KEY to .env.local (git-ignored) and never commit it.',
-        '',
-        'With an API key: starts a setup session for the project (no human step) and returns the setup checklist with next_action.',
-        'Connected through the Checkbox connector (OAuth: claude.ai, Claude Desktop, Claude Code /mcp, Cursor): the human already approved; there is NO key to paste or save. Call it with site_url (and what else you know): it registers the site and runs the first checks in the same call.',
+        'Connected through the Checkbox connector (OAuth: claude.ai, Claude Desktop, Claude Code /mcp, Cursor, VS Code): the human already approved in the browser; there is NO key to ask for, paste or save. Call it with site_url (and what else you know): it registers the site and runs the first checks in the same call.',
         'Pass everything you already know from the codebase: site_url, checkout_url, terms/privacy/refund/cancellation URLs, billing_platform, plans, project.layout_file. Checkbox fetches and checks the Terms itself.',
         '',
-        'After this: follow next_action (usually install the snippet, then update_setup / get_setup_status with verify=true), then get_compliance_plan.',
-        'The `checkbox init` CLI does the same and also patches the layout file (pre-release: not on npm yet; never install an npm package named "checkbox", it is not ours).',
+        'Only for clients without OAuth (no API key configured on this server): it returns a link for the HUMAN to open and click Approve (free, no card). Show them the link in one line, then call setup_checkbox again with the returned device_code — it waits up to ~50 s; call again while it says pending. On approval it returns test-mode API keys (shown once): save CHECKBOX_SECRET_KEY to .env.local (git-ignored), never commit it, and never ask the human to paste a key.',
+        '',
+        'After this: follow next_action (usually verify the domain and install the snippet, then get_setup_status with verify=true), then get_compliance_plan.',
     ].join('\n'),
     input: {
         ...setupFactsShape,
@@ -305,30 +552,62 @@ const setupCheckbox = {
                 notes.push(`claude mcp add --transport http checkbox ${ctx.mcpUrl} --header "Authorization: Bearer $CHECKBOX_SECRET_KEY" (Cursor / VS Code: add the same header to the server config). Until then, the plan below is all you need; the HTTP API works with the key right away.`);
             }
             notes.push('The secret key is shown only this once. Never commit it; the publishable key (pk_) is safe in browser code (e.g. NEXT_PUBLIC_CHECKBOX_PUBLISHABLE_KEY).');
+            // Round 16 (pilot 15, sveltekit / change-guard): two public keys in one response, unexplained.
+            notes.push("Two public keys: the snippet tag's data-key is the site's snippet key (install.snippet_key; use the script_tag exactly as given); publishable_key is the account key for Checkbox Elements and consent receipts only.");
             // In the same call, with the new key: apply the facts given (they are not lost between the two calls), run the
             // first checks, and return the setup checklist's next step — exactly what `checkbox init` does.
-            const keyed = ctx.adoptKeys ? ctx.api : ctx.apiForKey?.(res.secret_key);
+            // Normal-round pilot (sveltekit): the first checks failed with "No API key provided" and the facts given with the
+            // first call were dropped. Always call with the new key, and apply the facts of BOTH calls (this one wins).
+            const keyed = ctx.apiForKey?.(res.secret_key) ?? (ctx.adoptKeys ? ctx.api : undefined);
             let next;
             let firstCheck;
+            let site = res.site ?? null;
+            let inputWarnings = [];
+            let snippetKey;
             if (keyed && res.setup_session) {
                 try {
-                    const facts = pick(args, Object.keys(setupFactsShape));
-                    if (Object.keys(facts).length)
-                        await keyed.request('POST', `/v1/setup_sessions/${res.setup_session}`, { body: facts });
+                    const facts = { ...(PENDING_SETUP_FACTS.get(args.device_code) ?? {}), ...pick(args, Object.keys(setupFactsShape)) };
+                    PENDING_SETUP_FACTS.delete(args.device_code);
+                    // Pilot round 13 (change-guard): `agent` given with the device_code call (or known only now: a stateless
+                    // remote connection has no client name on the first call) was never stored, so the session said agent null.
+                    const agentName = args.agent ?? ctx.key.appName ?? ctx.clientName;
+                    if (agentName)
+                        facts.client = { name: 'checkbox-mcp', version: ctx.serverVersion, agent: String(agentName).slice(0, 100) };
+                    if (Object.keys(facts).length) {
+                        const upd = await keyed.request('POST', `/v1/setup_sessions/${res.setup_session}`, { body: facts });
+                        if (Array.isArray(upd?.warnings))
+                            inputWarnings = upd.warnings;
+                    }
                     const v = await keyed.request('POST', `/v1/setup_sessions/${res.setup_session}/verify`, { body: {} });
                     next = v.setup_session?.next_action;
-                    firstCheck = { evaluated: v.evaluated ?? false, scan: v.scan ?? null, steps: v.setup_session?.steps?.map((st) => `${st.key}: ${st.status}`) ?? [] };
+                    snippetKey = v.setup_session?.install?.snippet_key;
+                    // Pilot round 13 (change-guard): the site created by these facts was missing from the result (site: null next
+                    // to "site: done"), and the JSON next_action was the device token's, not the checklist's.
+                    if (typeof v.setup_session?.site === 'string')
+                        site = v.setup_session.site;
+                    firstCheck = { evaluated: v.evaluated ?? false, scan: v.scan ?? null, steps: v.setup_session?.steps?.map((st) => `${st.key}: ${st.status}`) ?? [], ...(Array.isArray(v.setup_session?.site_plans) ? { site_plans: v.setup_session.site_plans } : {}) };
                     notes.push(firstCheckNote(next));
+                    const pl = sitePlansNote(v.setup_session?.site_plans);
+                    if (pl)
+                        notes.push(pl);
                 }
                 catch (err) {
                     notes.push(`First checks did not run yet (${err instanceof Error ? err.message.slice(0, 160) : 'error'}); call get_setup_status with verify=true.`);
                 }
             }
             return {
-                headline: `Approved. Checkbox account ready${res.site ? ` with test-mode site ${res.site}` : ''}; setup session ${res.setup_session ?? '(none)'}.`,
+                headline: `Approved. Checkbox account ready${site ? ` with test-mode site ${site}` : ''}; setup session ${res.setup_session ?? '(none)'}.`,
                 notes,
                 ...(next ? { next } : {}),
-                data: { ...res, env: { CHECKBOX_SECRET_KEY: res.secret_key, ...(res.publishable_key ? { CHECKBOX_PUBLISHABLE_KEY: res.publishable_key } : {}) }, ...(firstCheck ? { first_check: firstCheck } : {}) },
+                data: {
+                    ...res,
+                    site,
+                    ...(next ? { next_action: next } : {}),
+                    env: { CHECKBOX_SECRET_KEY: res.secret_key, ...(res.publishable_key ? { CHECKBOX_PUBLISHABLE_KEY: res.publishable_key } : {}) },
+                    public_keys: labelledPublicKeys(snippetKey ?? res.install?.snippet_key, res.publishable_key),
+                    ...(firstCheck ? { first_check: firstCheck } : {}),
+                    ...(inputWarnings.length ? { warnings: inputWarnings } : {}),
+                },
             };
         }
         if (!api.hasKey) {
@@ -338,6 +617,8 @@ const setupCheckbox = {
             };
             if (typeof args.billing_platform === 'string')
                 body.billing_platform = args.billing_platform;
+            if (typeof args.merchant_name === 'string' && args.merchant_name.trim())
+                body.merchant_name = args.merchant_name.trim();
             const project = args.project;
             if (project?.name)
                 body.project_name = project.name;
@@ -346,6 +627,7 @@ const setupCheckbox = {
             if (project?.package_manager)
                 body.package_manager = project.package_manager;
             const auth = await api.request('POST', '/v1/device/authorize', { anonymous: true, body });
+            rememberSetupFacts(auth.device_code, pick(args, Object.keys(setupFactsShape)));
             return {
                 headline: `Ask the human to open ${auth.verification_uri_complete} and click Approve (code ${auth.user_code}). It expires in ${Math.round(auth.expires_in / 60)} minutes.`,
                 notes: [
@@ -364,13 +646,31 @@ const setupCheckbox = {
         const notes = session.review_url ? [`Human review page: ${session.review_url}`] : [];
         if (session.next_action?.type === 'verify_domain')
             notes.push(firstCheckNote(session.next_action));
+        const plansLine = sitePlansNote(session.site_plans);
+        if (plansLine)
+            notes.push(plansLine);
         return {
             headline: `Setup session ${session.id} started${session.business?.site_url ? ` for ${untrusted(session.business.site_url, 100)}` : ''}${session.site ? ` (test-mode site ${session.site})` : ''}.`,
             notes,
-            data: session,
+            data: (() => {
+                const keys = labelledPublicKeys(session.install?.snippet_key, session.publishable_key);
+                return keys.length ? { ...withoutLegacyScore(session), public_keys: keys } : withoutLegacyScore(session);
+            })(),
         };
     },
 };
+/**
+ * Round 20 (pilot 19 item 16, sveltekit / change-guard: a pk_ site key and a pk_test_ key side by side, unlabelled): each
+ * public key says what it is for.
+ */
+export function labelledPublicKeys(snippetKey, publishableKey) {
+    const out = [];
+    if (typeof snippetKey === 'string' && snippetKey)
+        out.push({ key: snippetKey, name: 'Site snippet key', use: 'The data-key of the Checkbox snippet <script> tag, for this site only (use install.script_tag exactly as given).' });
+    if (typeof publishableKey === 'string' && publishableKey)
+        out.push({ key: publishableKey, name: 'Account publishable key', use: 'For Checkbox Elements (<checkbox-disclosure>) and consent receipts (data-publishable-key) only; never the snippet data-key.' });
+    return out;
+}
 const getSetupStatus = {
     name: 'get_setup_status',
     title: 'Get the setup checklist (optionally re-check the site)',
@@ -391,14 +691,30 @@ const getSetupStatus = {
             if (!keyAllows(key, 'setup_sessions:write'))
                 throw new ToolError('verify=true needs a key with setup_sessions write access; call again without verify.');
             const res = await api.request('POST', `/v1/setup_sessions/${enc(id)}/verify`, { body: {} });
-            return { headline: `Re-checked setup session ${id}.`, data: res, next: nextActionOf(res) ?? nextActionOf(res.session) };
+            const notes = [];
+            if (res.domain_verified)
+                notes.push(`Domain verified: ${res.domain_verified.method === 'snippet' ? `the Checkbox snippet is live on ${res.domain_verified.domain}` : `${res.domain_verified.domain} (${res.domain_verified.method})`}.`);
+            if (res.unverified_scan?.queued)
+                notes.push('First read-only scan queued (unverified: no checkout is submitted until you verify the domain).');
+            else if (res.unverified_scan?.reason)
+                notes.push(`No new read-only scan: ${untrusted(res.unverified_scan.reason, 200)}.`);
+            const ro = unverifiedScanNote(res.setup_session?.unverified_scan);
+            if (ro && !res.unverified_scan?.queued)
+                notes.push(ro);
+            const pl = sitePlansNote(res.setup_session?.site_plans);
+            if (pl)
+                notes.push(pl);
+            return { headline: `Re-checked setup session ${id}.`, ...(notes.length ? { notes } : {}), data: withoutLegacyScore(res), next: nextActionOf(res) ?? nextActionOf(res.session) };
         }
         const session = await api.request('GET', `/v1/setup_sessions/${enc(id)}`);
         const open = (session.steps ?? []).filter((s) => s.status && !['done', 'skipped', 'not_applicable'].includes(s.status));
+        const ro = unverifiedScanNote(session.unverified_scan);
+        const plansLine = sitePlansNote(session.site_plans);
         return {
             headline: `Setup session ${session.id}: ${session.status}; ${open.length} checklist step(s) open.`,
-            notes: open.slice(0, 8).map((s) => `${s.status}: ${s.title ?? s.key}`),
-            data: session,
+            // The policies step says what an unverified preview read (or that the pages wait for domain verification).
+            notes: [...open.slice(0, 8).map((s) => `${s.status}: ${s.title ?? s.key}${s.key === 'policies' && s.summary ? ` (${s.summary.slice(0, 240)})` : ''}`), ...(ro ? [ro] : []), ...(plansLine ? [plansLine] : [])],
+            data: withoutLegacyScore(session),
         };
     },
 };
@@ -424,9 +740,24 @@ const updateSetup = {
         const id = await resolveSetupSession(api, args.setup_session);
         const body = pick(args, [...Object.keys(setupFactsShape), 'snippet_installed_in', 'env_written', 'live_site', 'refetch_policies']);
         const session = await api.request('POST', `/v1/setup_sessions/${enc(id)}`, { body });
-        return { headline: `Updated setup session ${session.id}.`, data: session };
+        // Round 20 (pilot 19 item 6): a plans change re-evaluates the site; say where the new plan's tasks show up.
+        const notes = Array.isArray(args.plans) && args.plans.length
+            ? ['Plans saved: Checkbox re-evaluates the site with them now, so get_compliance_plan lists each plan\'s tasks (e.g. the trial reminder of a plan with a trial). If one seems missing, call verify_site to re-check at once.']
+            : [];
+        return { headline: `Updated setup session ${session.id}.`, notes, data: withoutLegacyScore(session) };
     },
 };
+/** Round 13 (pilot 12, codex: "sent" while nothing new arrived): the summary email's real delivery status, with when. */
+export function summaryEmailLine(status, d) {
+    const when = d?.at ? ` at ${new Date(d.at * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC` : '';
+    if (status === 'sent')
+        return `sent${d?.to ? ` to ${d.to}` : ''} (the mail server accepted it${when}; it is sent once per setup)`;
+    if (status === 'failed')
+        return `failed${d?.error ? ` (${d.error})` : ''}; call complete_setup again to retry`;
+    if (status === 'not_configured')
+        return 'not sent: this deployment has no email delivery';
+    return 'not sent';
+}
 const completeSetup = {
     name: 'complete_setup',
     title: 'Finish setup and email the human a summary',
@@ -438,20 +769,77 @@ const completeSetup = {
         const id = await resolveSetupSession(api, args.setup_session);
         const session = await api.request('POST', `/v1/setup_sessions/${enc(id)}/complete`, { body: {} });
         return {
-            headline: `Setup ${session.id} completed; summary email: ${session.owner_email ?? 'not sent'}.`,
+            headline: `Setup ${session.id} completed; summary email: ${summaryEmailLine(session.owner_email, session.owner_email_detail)}.`,
             notes: session.review_url ? [`Human review page: ${session.review_url}`] : [],
-            data: session,
+            data: withoutLegacyScore(session),
         };
     },
 };
+// ---------------------------------------------------------------------------------------------------------------------
+// Compliance plan loop
+// ---------------------------------------------------------------------------------------------------------------------
+/**
+ * Round 21 (pilot 20 item 8, lawyer): the plan status in words ("Checks pass"), never the bare machine value `compliant`
+ * an agent would repeat to a merchant. Older APIs without status_label: the same mapping here.
+ */
+const PLAN_STATUS_WORDS = { action_required: 'Fixes needed', verifying: 'Checking your changes', compliant: 'Checks pass', blocked: 'Your call' };
+export function planStatusWords(status, label) {
+    return label || PLAN_STATUS_WORDS[status] || status;
+}
+/** "Old task (covered by: Open task)": the open task sharing a check with a superseded one. Pure, exported for tests. */
+export function coveredLine(t, open) {
+    const ids = t.check_ids ?? [];
+    const by = open.find((o) => o.key !== t.key && (o.check_ids ?? []).some((c) => ids.includes(c)));
+    return by ? `${t.title} (covered by: ${by.title})` : `${t.title} (covered by another open task)`;
+}
+/** The plan with each task reduced to what an agent needs to choose the next one (the full task: get_task). */
+export function slimPlan(plan) {
+    const clip = clipWords;
+    const tasks = (plan.tasks ?? []).map((t) => {
+        const full = t;
+        const change = (full.change ?? {});
+        return {
+            id: t.id,
+            key: full.key,
+            title: t.title,
+            status: t.status,
+            priority: t.priority,
+            order: t.order,
+            tier: t.tier,
+            compliance_status: full.compliance_status,
+            why: clip(full.why, 400),
+            where: t.where,
+            change: { type: change.type, operation_id: change.operation_id ?? null, endpoint: change.endpoint ?? null },
+            blocked_on: full.blocked_on ?? null,
+            blocked_by: full.blocked_by ?? [],
+            question: full.question ?? null,
+            next_action: full.next_action ?? null,
+        };
+    });
+    return { ...plan, tasks: tasks };
+}
+/**
+ * One-time review hint: when a site's plan is compliant, the API hands out the prompt once per site
+ * (claimReviewPrompt). Never fails the tool: older servers or a missing scope simply mean no hint.
+ */
+async function reviewHint(api, site, trigger) {
+    try {
+        const p = await api.request('POST', `/v1/sites/${enc(site)}/review_prompt`, { body: { trigger } });
+        return p.show && p.message ? [`One-time: ${p.message}`] : [];
+    }
+    catch {
+        return [];
+    }
+}
 const getCompliancePlan = {
     name: 'get_compliance_plan',
     title: 'Get the compliance plan (ordered tasks)',
     description: [
-        'The main tool after setup. Returns the ordered tasks that make the site compliant with automatic-renewal laws, recomputed from the latest observations.',
+        'The main tool after setup. Returns the ordered tasks that make the site pass the automatic-renewal checks, recomputed from the latest observations.',
         'Each task has: requirement + legal citation, why (what Checkbox observed), where (file / component / URL / CSS selector / Stripe object), change (exact unified-diff template, copy text or Stripe params), and verify (how to check).',
-        'Plan status: action_required (apply open tasks), verifying (waiting for confirming observations), compliant (done), blocked (only human questions left).',
-        'Loop: apply the first open task in the code → verify_task → get_compliance_plan → … until status is compliant. Tasks with status "manual" carry a question: ask the HUMAN, then answer_task. Never invent answers.',
+        'Plan status: action_required (apply open tasks), verifying (waiting for confirming observations), compliant (done: the checks pass — "pending_live_check" tasks count as passing: they complete on their own or with a proof run), blocked (only human questions — "Your call" — left).',
+        'Tasks are tagged tier required / recommended / extra. Only required tasks matter for compliance; recommended and extra tasks are optional suggestions (mention them once, do not push them).',
+        'Loop: apply the first open required task in the code → verify_task → get_compliance_plan → … until the checks pass (status compliant). Tasks with status "manual" carry a question with a recommended answer: ask the HUMAN, then answer_task. Never invent answers.',
     ].join('\n'),
     input: { site: siteId.optional() },
     scopes: ['compliance_plans:read'],
@@ -460,10 +848,41 @@ const getCompliancePlan = {
         const site = await resolveSite(api, args.site);
         const plan = await api.request('GET', `/v1/sites/${enc(site)}/plan`);
         const open = (plan.tasks ?? []).filter((t) => !['done', 'wont_fix'].includes(t.status));
+        const required = open.filter((t) => (t.tier ?? 'required') === 'required');
+        const optional = open.filter((t) => (t.tier ?? 'required') !== 'required');
+        // One to-do list: the same ordered open tasks (titles, order, counts) as the dashboard, report, emails and CLI.
+        const todo = planTodo((plan.tasks ?? []));
+        const rest = required.filter((t) => !todo.some((x) => x.id === t.id));
+        const { score: _score, insurable: _insurable, ...shown } = plan;
         return {
-            headline: `Plan for ${site}: ${statusLine(plan.status)}, score ${plan.score ?? 'n/a'}, insurable ${plan.insurable ?? 'n/a'}. ${plan.summary ?? ''}`,
-            notes: open.slice(0, 10).map((t) => `#${t.order ?? '?'} ${t.id} [${t.status}${t.priority ? `, ${t.priority}` : ''}${t.change?.type ? `, ${t.change.type}` : ''}] ${t.title}`),
-            data: plan,
+            // Audit P2: one Next line (the plan's next_action below); the summary's own "Next: …" is not repeated.
+            headline: `Plan for ${site}: ${plainLabel(plan.compliance?.label ?? 'Not checked yet')} (plan status: ${planStatusWords(plan.status, plan.status_label)}).`,
+            notes: [
+                ...(todo.length ? [`To do (${todo.length}, in order):`] : []),
+                ...todo.map((t, i) => `${i + 1}. ${t.id} ${todoLine(t)}`),
+                ...rest.map((t) => `${t.id} [${t.status}${t.priority ? `, ${t.priority}` : ''}${t.change?.type ? `, ${t.change.type}` : ''}] ${t.title}`),
+                // Round 14: a task closed because it no longer applies is "Not applicable", never "done". Round 16 (pilot 15,
+                // codex): a task closed by a passing verification is "Done (verified)", never "Not applicable".
+                ...(() => {
+                    const closed = (plan.tasks ?? []);
+                    const verified = closed.filter((t) => t.status === 'done' && t.closed_reason === 'verified' && t.compliance_status !== 'not_applicable');
+                    // Round 20 (pilot 19 item 9): a task merged into another open task is "covered by" it, never "not applicable".
+                    const covered = closed.filter((t) => t.closed_reason === 'superseded');
+                    const na = closed.filter((t) => t.compliance_status === 'not_applicable' && t.closed_reason !== 'verified' && t.closed_reason !== 'superseded');
+                    return [
+                        ...(verified.length ? [`Done (verified): ${verified.map((t) => t.title).join('; ')}`] : []),
+                        ...(covered.length ? [`Merged into another task: ${covered.map((t) => coveredLine(t, open)).join('; ')}`] : []),
+                        ...(na.length ? [`Not applicable (closed without a change, nothing observed passing): ${na.map((t) => t.title).join('; ')}`] : []),
+                    ];
+                })(),
+                ...(optional.length ? [`Optional suggestions (${plan.protection_level ?? 'balanced'} protection; never block the checks from passing): ${optional.map((t) => t.title).join('; ')}`] : []),
+                ...(plan.optional_improvements ? ['Optional (never blocking, not part of compliance): conversion suggestions for this site with `suggest_improvements`.'] : []),
+                'Each task below is a summary; call get_task with its id for the full change (diff, copy or params) before applying it.',
+                ...(plan.status === 'compliant' ? await reviewHint(api, site, 'plan_compliant') : []),
+            ],
+            // Normal-round pilot (sveltekit): the full plan (53K characters) was cut mid-JSON by the client. The plan here is a
+            // compact summary of every task; get_task returns one task in full.
+            data: slimPlan(shown),
         };
     },
 };
@@ -476,9 +895,23 @@ const getTask = {
     annotations: { ...ro, title: 'Task' },
     async run(args, { api }) {
         const task = await api.request('GET', `/v1/tasks/${enc(String(args.task))}`);
-        return { headline: `Task ${task.id} [${task.status}]: ${task.title}`, data: task };
+        // Audit P3: a task citing every state's law listed dozens of citations; the first 8 and a count are enough here.
+        const cites = task.requirement?.citations;
+        const shown = Array.isArray(cites) && cites.length > 8 ? { ...task, requirement: { ...task.requirement, citations: cites.slice(0, 8), citations_more: cites.length - 8 } } : task;
+        const word = task.compliance_status === 'not_applicable' ? 'not applicable' : task.status;
+        return { headline: `Task ${task.id} [${word}]: ${task.title}`, data: shown };
     },
 };
+/** Audit: the pre-check's per-check results, one compact line each (agents only saw the overall verdict). */
+export function precheckLines(pre, max = 12) {
+    const checks = pre?.checks ?? [];
+    if (!checks.length)
+        return [];
+    const order = { fail: 0, needs_review: 1, missing_data: 1, pass: 2, not_applicable: 3 };
+    const sorted = [...checks].sort((a, b) => (order[a.status] ?? 1) - (order[b.status] ?? 1));
+    const lines = sorted.slice(0, max).map((c) => `${c.check_id}: ${c.status}${c.reason ? ` — ${untrusted(c.reason, 180)}` : ''}${c.fix ? ` Fix: ${untrusted(c.fix, 200)}` : ''}`);
+    return [`Pre-check (${pre?.verdict ?? 'n/a'}), per check:`, ...lines, ...(checks.length > max ? [`and ${checks.length - max} more (data.precheck.checks)`] : [])];
+}
 const verifyTask = {
     name: 'verify_task',
     title: 'Verify a task after applying its change',
@@ -494,29 +927,56 @@ const verifyTask = {
         task: z.string().max(100).describe('Task id (task_…).'),
         html: z.string().max(950_000).optional().describe('Page tasks: the rendered page HTML.'),
         stripe_checkout_session: z.record(z.string(), z.unknown()).optional().describe('Stripe tasks: the params your code passes to stripe.checkout.sessions.create.'),
+        stripe_checkout_sessions: z.array(z.record(z.string(), z.unknown())).max(10).optional().describe('Stripe tasks, one params object per plan.'),
         email: z
             .object({
-            kind: z.enum(['acknowledgment', 'trial_reminder', 'renewal_reminder', 'price_change', 'annual_terms', 'cancellation_confirmation']).optional(),
+            kind: emailKind.optional(),
             subject: z.string().max(1000),
             text: z.string().max(100_000).optional(),
             html: z.string().max(100_000).optional(),
         })
             .optional()
-            .describe('Email tasks: the new template.'),
+            .describe('Email tasks: the new template (passes when it matches one plan fully).'),
+        plan: z.string().min(1).max(200).optional().describe('Email tasks: only this plan (name).'),
+        price_id: z.string().min(1).max(200).optional().describe('Email tasks: only this plan (Price id).'),
         recheck: z.boolean().optional().describe('true re-checks a task that is already done (evaluates again now and queues a scan) instead of returning its last result.'),
         wait,
     },
     scopes: ['compliance_plans:write'],
     annotations: { ...write(true, true), title: 'Verify task' },
     async run(args, { api }) {
-        const body = pick(args, ['html', 'stripe_checkout_session', 'email', 'recheck']);
+        const body = pick(args, ['html', 'stripe_checkout_session', 'stripe_checkout_sessions', 'email', 'plan', 'price_id', 'recheck']);
+        if (body.email && typeof body.email === 'object' && body.email.kind)
+            body.email = { ...body.email, kind: checkKind(body.email.kind) };
         const v = await api.request('POST', `/v1/tasks/${enc(String(args.task))}/verify`, {
             query: { wait: args.wait ?? 25 },
             body,
         });
+        const hint = v.plan_status === 'compliant' && v.site ? await reviewHint(api, v.site, 'last_task_verified') : [];
         return {
-            headline: `Verification ${v.id} of ${String(args.task)}: ${statusLine(v.status)}${v.plan_status ? `; plan is now ${v.plan_status}` : ''}.`,
-            notes: v.status === 'failed' ? ['The change did not satisfy the check: read diff (expected vs observed), fix the code, and call verify_task again.'] : v.status === 'pending' ? ['Waiting for a confirming observation; call get_verification later (or continue with other tasks).'] : [],
+            headline: `Verification ${v.id} of ${String(args.task)}: ${statusLine(v.status)}${v.plan_status ? `; plan is now ${planStatusWords(v.plan_status, v.plan_status_label)}` : ''}.${v.checked ? ` Checked: ${untrusted(v.checked, 300)}.` : ''}`,
+            notes: [
+                ...precheckLines(v.precheck),
+                ...((v.status === 'failed' || v.status === 'not_checked') && v.next_action?.type === 'verify_domain'
+                    ? ['The domain is not verified yet. Waiting for the human to publish the DNS record / file / meta tag or install the snippet; don\'t retry until they say it\'s done. Nothing to change in the code.']
+                    : v.next_action?.type === 'retry_later'
+                        ? ['Checkbox could not confirm it (a problem on Checkbox\'s side): nothing to change in the code. Continue with the next task; verify again later.']
+                        : v.next_action?.type === 'live_check_pending' && v.status === 'pending'
+                            ? // Round 14 (pilot 13): Checkbox Notices sends this email; never "add the BCC".
+                                [v.next_action.description ?? 'Checkbox Notices sends this email: nothing to add to your code. Continue with the next task.']
+                            : v.next_action?.type === 'bcc_then_continue'
+                                ? ['The copy is checked; the task closes when the first real email arrives with the BCC. Add the BCC to your sending code and continue with the next task (no need to poll).']
+                                : v.status === 'failed'
+                                    ? ['The change did not satisfy the check: read diff (expected vs observed), fix the code, and call verify_task again.']
+                                    : v.status === 'not_checked'
+                                        ? ['Not checked yet: Checkbox is missing evidence (see next_action), not a code problem. Do not change the code for this; provide what next_action asks for.']
+                                        : v.status === 'pending_live_check'
+                                            ? ['Live check pending: the email content passes; Checkbox has not seen it sent for a real event yet. Nothing to change in the code: it completes on the first real send (or a proof run).']
+                                            : v.status === 'pending'
+                                                ? ['Waiting for a confirming observation; call get_verification later (or continue with other tasks).']
+                                                : []),
+                ...hint,
+            ],
             data: v,
         };
     },
@@ -524,7 +984,7 @@ const verifyTask = {
 const answerTask = {
     name: 'answer_task',
     title: 'Record the human\'s answer to a manual task',
-    description: 'For tasks with status "manual": record the HUMAN\'s answer to task.question. Ask the human first and pass their words; never answer on their behalf (answers are legal attestations stored in the evidence vault). answer is one of task.question.options (yes / no, or confirmed / needs_change). "no" / "needs_change" turns the task into a change you can apply.',
+    description: 'For tasks with status "manual": record the HUMAN\'s answer to task.question. Ask the human first and pass their words; never answer on their behalf (answers are legal attestations stored in the evidence vault). answer is one of task.question.options; yes / no also work (= confirmed / needs_change). "no" turns the task into a change you can apply.',
     input: {
         task: z.string().max(100).describe('Task id (task_…) with status manual.'),
         answer: z.string().max(40).describe('One of the task.question.options, as the human chose.'),
@@ -534,25 +994,31 @@ const answerTask = {
     annotations: { ...write(false), title: 'Answer task' },
     async run(args, { api }) {
         const task = await api.request('POST', `/v1/tasks/${enc(String(args.task))}/answer`, { body: pick(args, ['answer', 'note']) });
+        // Round 21 (pilot 20 item 16): "done" on a task Checkbox already closed succeeds without recording anything.
+        if (task.status === 'done' && task.next_action?.type === 'retrieve_plan')
+            return { headline: `${task.id} was already done (Checkbox closed it itself): nothing to answer, nothing recorded.`, data: task };
         return { headline: `Recorded the answer on ${task.id}; task is now ${task.status}.`, data: task };
     },
 };
 const verifySite = {
     name: 'verify_site',
     title: 'Re-check the whole site now',
-    description: 'Re-fetches the registered policies, pre-checks the checkout, re-evaluates every law and queues a scan. Use it for the first check after setup, after deploying several changes, or when the plan looks stale. Waits up to `wait` seconds, then call get_compliance_plan.',
+    description: 'Re-reads the connected billing platform (Stripe portal, prices, Checkout Sessions; rate-limited), re-fetches the registered policies, pre-checks the checkout, re-evaluates every law and queues a scan. Use it for the first check after setup, after deploying several changes, after changing a Stripe setting, or when the plan looks stale. Waits up to `wait` seconds, then call get_compliance_plan.',
     input: { site: siteId.optional(), wait },
     scopes: ['compliance_plans:write'],
     annotations: { ...write(true, true), title: 'Verify site' },
     async run(args, { api }) {
         const site = await resolveSite(api, args.site);
         const v = await api.request('POST', `/v1/sites/${enc(site)}/verify`, { query: { wait: args.wait ?? 25 }, body: {} });
+        // Pilot 11: say what was re-read from the billing platform (the note's first sentence), so a stale answer is visible.
+        const reread = /^(?:Re-read |Could not re-read |[A-Z][\w ]{0,40} was read ).*?(?:before judging\.|seconds\)\.|ago\.|earlier\.)/.exec(v.precheck?.note ?? '')?.[0];
         // A whole-site check that finds open checks produced the to-do list; it is not a failed change.
-        const headline = v.next_action?.type === 'verify_domain'
+        const base = v.next_action?.type === 'verify_domain'
             ? `Site check ${v.id}: nothing was fetched or scanned because the site's domain is not verified yet (Checkbox only visits websites their owners have verified). Follow Next to verify it.`
             : v.status === 'failed'
-                ? `${v.next_action?.type === 'first_check_complete' ? 'First check complete' : 'Site check complete'} (${v.id}): ${v.diff?.length ?? 0} check(s) do not pass yet — this is the to-do list, not a failed change.${v.plan_status ? ` Plan: ${v.plan_status}.` : ''}`
+                ? `${v.next_action?.type === 'first_check_complete' ? 'First check complete' : 'Site check complete'} (${v.id}): the open tasks of get_compliance_plan are the to-do list, not a failed change.${v.plan_status ? ` Plan: ${v.plan_status}.` : ''}`
                 : `Site check ${v.id}: ${statusLine(v.status)}${v.plan_status ? `; plan is ${v.plan_status}` : ''}.`;
+        const headline = reread ? `${base} ${reread}` : base;
         return { headline, data: v };
     },
 };
@@ -560,27 +1026,41 @@ const getVerification = {
     name: 'get_verification',
     title: 'Get a verification result',
     description: 'Status of a verification from verify_task / verify_site: pending, passed or failed, expected vs observed per check, the diff and next_action. Pass wait (≤ 30 s) to wait for a pending one.',
-    input: { verification: z.string().max(100).describe('Verification id (ver_…).'), wait: wait },
+    input: { verification: z.string().max(100).describe('ver_…, or task_… (its newest)'), wait: wait },
     scopes: ['compliance_plans:read'],
     annotations: { ...ro, title: 'Verification' },
     async run(args, { api }) {
         const v = await api.request('GET', `/v1/verifications/${enc(String(args.verification))}`, { query: { wait: args.wait ?? 0 } });
-        return { headline: `Verification ${v.id}: ${statusLine(v.status)}.`, data: v };
+        const notes = precheckLines(v.precheck);
+        return { headline: `Verification ${v.id}: ${statusLine(v.status)}.`, ...(notes.length ? { notes } : {}), data: v };
     },
 };
 // ---------------------------------------------------------------------------------------------------------------------
 // Synthetic test subscription
 // ---------------------------------------------------------------------------------------------------------------------
+/** createTestRun body from the tool's arguments (top-level shortcuts merged into `stripe`). Exported for tests. */
+export function startTestRunBody(args) {
+    const body = pick(args, ['mode', 'type', 'advance_time', 'cancel', 'email_wait_seconds', 'region', 'stripe', 'generic']);
+    const shortcuts = pick(args, ['checkout_url', 'test_account', 'checkout_steps', 'cancel_url', 'cancel_steps']);
+    if (Object.keys(shortcuts).length && body.type !== 'generic') {
+        body.stripe = { ...shortcuts, ...(body.stripe ?? {}) };
+        if (!body.mode && shortcuts.checkout_url)
+            body.mode = 'real_checkout';
+    }
+    return body;
+}
 const startTestRun = {
     name: 'start_test_run',
     title: 'Run a synthetic test subscription (test mode)',
     description: [
         'Observes the WHOLE subscription lifecycle, not just the checkout: in the billing platform\'s TEST mode Checkbox subscribes a test customer (card 4242…) whose email is a Checkbox inbox, waits for your acknowledgment email, fast-forwards a Stripe test clock through every legal notice window before trial end and renewal (collecting reminder emails), then cancels online and waits for the cancellation confirmation. Nothing is charged.',
-        'Needs a Stripe TEST key stored for the site (setup asks the human) — if missing, the error\'s next_action says how (call_api POST /v1/sites/{site}/test_credentials). For non-Stripe sites use type "generic".',
-        'Takes ~5-20 minutes: poll get_test_run (its next_action says when). Each step reports observations, check results and agent-readable fixes; apply them and run again.',
+        'Needs a Stripe TEST key stored for the site — the human adds it in the Checkbox dashboard (the site\'s Proof page); never ask them to paste it into the chat. If missing, the error\'s next_action says so. For non-Stripe sites use type "generic".',
+        'Usually 2-4 minutes: poll get_test_run (its next_action says when). Each step reports observations, check results and agent-readable fixes; apply them and run again.',
+        'mode "real_checkout" is the PROOF run: the shopper buys through the merchant\'s own checkout on its test deployment (stripe.checkout_url or stripe.payment_link), so the merchant\'s webhook handlers and email code fire; give stripe.test_account + stripe.cancel_url when customers cancel in the app. A step is "passed" only with evidence; "warning" means needs review.',
     ].join('\n'),
     input: {
         site: siteId.optional(),
+        mode: z.enum(['mirror', 'real_checkout']).optional().describe('Stripe runs: mirror (default; test clock through every notice window) or real_checkout (the proof run through the merchant\'s own checkout, webhooks and emails).'),
         type: z.enum(['stripe', 'generic']).optional().describe('stripe (default when a Stripe test key is stored) or generic (test coupon / test account, no time travel).'),
         advance_time: z.boolean().optional().describe('Advance a Stripe test clock through trial end and first renewal (default true).'),
         cancel: z.boolean().optional().describe('Cancel online at the end (default true).'),
@@ -588,22 +1068,38 @@ const startTestRun = {
         region: z.string().max(10).optional().describe('State the synthetic shopper visits from, e.g. "US-CA".'),
         stripe: z
             .object({
-            checkout_config: z.string().max(100).optional().describe('Registered checkout config (scc_…) to mirror; default the newest, else the latest live Checkout Session.'),
+            checkout_config: z.string().max(100).optional().describe('Registered checkout config (scc_…) to mirror; default the newest, else the latest live Checkout Session; "none" skips registered configs.'),
             price: z.string().max(200).optional().describe('A TEST-mode price id (price_…) to subscribe to when nothing is registered.'),
             trial_period_days: z.number().int().min(0).max(730).optional(),
             price_map: z.record(z.string(), z.string()).optional().describe('Live price id → test-mode price id.'),
             cancel_url: z.string().max(2048).optional().describe('Cancel on your own page instead of the Stripe customer portal.'),
+            checkout_url: z.string().max(2000).optional().describe('real_checkout: your checkout page on your TEST deployment.'),
+            payment_link: z.string().max(300).optional().describe('A Payment Link (plink_… or buy.stripe.com URL) to mirror or buy through.'),
+            pre_checkout_steps: z.array(z.record(z.string(), z.unknown())).max(30).optional().describe('real_checkout: clicks to reach the payment page, e.g. [{"action":"click","text":"Subscribe"}].'),
+            checkout_steps: z.array(z.record(z.string(), z.unknown())).max(30).optional().describe('real_checkout with an EMBEDDED checkout (Stripe Elements / Payment Element on your page): the steps that pay, e.g. [{"action":"fill","selector":"#email","value":"{{email}}"},{"action":"fill","selector":"#card","value":"4242424242424242"},{"action":"click","text":"I agree"},{"action":"click","text":"Pay"}]. {{email}} is the shopper\'s address (the run inbox).'),
+            test_account: z.object({ login_url: z.string().max(2000), email: z.string().max(320), password: z.string().max(500).optional() }).optional().describe('Test account on your deployment (password stored encrypted). email "{{inbox}}" signs up with the run\'s own test inbox.'),
+            cleanup_url: z.string().max(2000).optional().describe('Page that ends the test account\'s subscription before the checkout, so every run starts without one.'),
+            cancel_steps: z.array(z.record(z.string(), z.unknown())).max(30).optional().describe('Clicks that cancel in your flow.'),
+            cancel_via: z.enum(['merchant_flow', 'stripe_portal']).optional().describe('How your customers cancel.'),
+            reset_url: z.string().max(2000).optional().describe('Page that resets the test account before the checkout.'),
         })
             .optional()
             .describe('Stripe options.'),
         generic: z.record(z.string(), z.unknown()).optional().describe('Generic (non-Stripe) options as in the API: checkout_url, checkout_steps, complete_purchase { steps, promo_code }, account { login_url, email, password }, cancel_steps.'),
+        // Round-4 pilot (sveltekit, Cursor): clients that do not show nested schemas could not start the proof run. The most
+        // used real_checkout fields are also accepted at the top level and merged into `stripe`.
+        checkout_url: z.string().max(2000).optional().describe('Shortcut for stripe.checkout_url (real_checkout: your checkout page on your TEST deployment).'),
+        test_account: z.object({ login_url: z.string().max(2000), email: z.string().max(320), password: z.string().max(500).optional() }).optional().describe('Shortcut for stripe.test_account. email "{{inbox}}" uses the run inbox.'),
+        checkout_steps: z.array(z.record(z.string(), z.unknown())).max(30).optional().describe('Shortcut for stripe.checkout_steps (embedded checkout: fill email/card, tick consent, click pay).'),
+        cancel_url: z.string().max(2048).optional().describe('Shortcut for stripe.cancel_url.'),
+        cancel_steps: z.array(z.record(z.string(), z.unknown())).max(30).optional().describe('Shortcut for stripe.cancel_steps.'),
     },
     scopes: ['test_runs:write'],
     annotations: { ...write(false, true), title: 'Start test run' },
     async run(args, { api }) {
         const site = await resolveSite(api, args.site);
         const run = await api.request('POST', `/v1/sites/${enc(site)}/test_runs`, {
-            body: pick(args, ['type', 'advance_time', 'cancel', 'email_wait_seconds', 'region', 'stripe', 'generic']),
+            body: startTestRunBody(args),
         });
         return {
             headline: `Test run ${run.id} (${run.type}) ${run.status} for ${site}.${run.inbox_address ? ` Test subscriber inbox: ${run.inbox_address}.` : ''}`,
@@ -614,8 +1110,12 @@ const startTestRun = {
 const getTestRun = {
     name: 'get_test_run',
     title: 'Get a test run (steps, observations, fixes)',
-    description: 'A synthetic test subscription with every step (checkout, acknowledgment email, reminders at each legal window, cancellation, confirmation): what was observed, check results, evidence ids and fixes. While running, next_action.type is "wait" (poll again in a minute or two). When finished, apply the fixes (usually via get_compliance_plan) and start another run to verify. Without test_run, returns the newest run of the site.',
-    input: { test_run: z.string().max(100).optional().describe('Test run id (run_…). Default: the newest run of the site.'), site: siteId.optional() },
+    description: 'A synthetic test subscription with every step (checkout, acknowledgment email, reminders at each legal window, cancellation, confirmation): what was observed, check results, evidence ids and fixes. While running, next_action.type is "wait" and waiting_for says what it waits for (pass wait: 30 to get the answer as soon as the run moves on). When finished, apply the fixes (usually via get_compliance_plan) and start another run to verify. Without test_run, returns the newest run of the site.',
+    input: {
+        test_run: z.string().max(100).optional().describe('Test run id (run_…). Default: the newest run of the site.'),
+        site: siteId.optional(),
+        wait: z.number().int().min(0).max(30).optional().describe('Long-poll: wait up to this many seconds for the run to move on before answering.'),
+    },
     scopes: ['test_runs:read'],
     annotations: { ...ro, title: 'Test run' },
     async run(args, { api }) {
@@ -627,10 +1127,14 @@ const getTestRun = {
                 throw new ToolError(`Site ${site} has no test run yet.`, { type: 'start_test_run', message: 'Call start_test_run.', operation_id: 'createTestRun' });
             id = list.data[0].id;
         }
-        const run = await api.request('GET', `/v1/test_runs/${enc(id)}`);
+        const wait = typeof args.wait === 'number' && args.wait > 0 ? Math.min(30, Math.floor(args.wait)) : undefined;
+        const run = await api.request('GET', `/v1/test_runs/${enc(id)}`, wait ? { query: { wait } } : undefined);
+        const w = run.waiting_for;
+        const progress = w ? [w.step && w.steps_total ? `step ${w.step} of ${w.steps_total}` : '', w.minutes_left ? `about ${w.minutes_left} min left` : ''].filter(Boolean).join(', ') : '';
+        const waiting = w ? `Waiting for: ${w.what}${w.until ? ` (until ${new Date(w.until * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC at the latest)` : ''}${progress ? ` [${progress}]` : ''}` : null;
         return {
-            headline: `Test run ${run.id}: ${statusLine(run.status)}${run.phase ? ` (phase ${run.phase})` : ''}.`,
-            notes: (run.steps ?? []).map((s) => `${s.status ?? '?'}: ${s.title ?? s.key}${s.code ? ` (${s.code})` : ''}`).slice(0, 12),
+            headline: `Test run ${run.id}: ${run.status_label ?? statusLine(run.status)}${run.phase && run.status !== 'succeeded' && run.status !== 'failed' ? ` (phase ${run.phase})` : ''}.`,
+            notes: [...(waiting ? [waiting] : []), ...(run.steps ?? []).map((s) => `${s.status ?? '?'}: ${s.title ?? s.key}${s.code ? ` (${s.code})` : ''}`)].slice(0, 13),
             data: run,
         };
     },
@@ -642,9 +1146,9 @@ const checkDisclosure = {
     name: 'check_disclosure',
     title: 'Check checkout disclosure text',
     description: [
-        'Before shipping a checkout: checks the automatic-renewal disclosure shown next to the purchase button against every applicable law (ROSCA, CA, NY, …) and returns per-check verdicts with citations plus a REPLACEMENT verified by the rules engine (disclosure_text, consent_label, button_text and drop-in html).',
+        'Before shipping a checkout: checks the automatic-renewal disclosure shown next to the purchase button against every applicable law (ROSCA, CA, NY, …) and returns per-check verdicts with citations plus a REPLACEMENT verified by the rules engine (disclosure_text, consent_label, button_text, drop-in html and jsx).',
         'Pass the text exactly as rendered plus the plan terms. Example: {"text":"Renews monthly at $19.99 until you cancel.","price":19.99,"interval":"month","trial_days":14,"cancel_url":"https://acme.example/account/cancel","merchant_name":"Acme","consent":{"checkbox":true,"prechecked":false}}.',
-        'If verdict is fail, use replacement.html (or its texts) in the code, then call again to confirm pass. needs_review on styling means a rendered scan must confirm.',
+        'If verdict is fail, put replacement.jsx (React) or .html above the button, then call again with the new text, consent and placement.bold: true (it is semibold). needs_review on styling means a rendered scan must confirm.',
     ].join('\n'),
     input: {
         text: z.string().min(1).max(5000).describe('The disclosure shown next to the purchase button, exactly as rendered.'),
@@ -652,8 +1156,7 @@ const checkDisclosure = {
         interval: intervalStr,
         button_text: z.string().max(200).optional().describe('Purchase button label, e.g. "Start free trial".'),
         order_summary: z.string().max(1000).optional().describe('Other text next to the button (order summary), if any.'),
-        placement: z
-            .object({
+        placement: strictObject({
             above_button: z.boolean().optional(),
             same_page_as_payment: z.boolean().optional(),
             font_size_px: z.number().min(4).max(96).optional(),
@@ -661,16 +1164,15 @@ const checkDisclosure = {
             bold: z.boolean().optional(),
             boxed: z.boolean().optional(),
             body_font_size_px: z.number().min(4).max(96).optional(),
-        })
+        }, 'placement')
             .optional()
             .describe('Where and how the disclosure is shown (defaults: above the button, same page, 14px, high contrast).'),
-        consent: z
-            .object({
+        consent: strictObject({
             checkbox: z.boolean(),
             prechecked: z.boolean().optional(),
             label: z.string().max(1000).optional(),
             required: z.boolean().optional(),
-        })
+        }, 'consent')
             .optional()
             .describe('The consent checkbox, if the page has one. Omit when there is none.'),
         jurisdictions: jurisdictions.optional(),
@@ -680,7 +1182,8 @@ const checkDisclosure = {
     annotations: { ...ro, title: 'Check disclosure' },
     async run(args, { api }) {
         const r = await api.request('POST', '/v1/checks/disclosure', { body: args });
-        return { headline: verdictHeadline('Disclosure', r), notes: checkNotes(r), data: slimCheckResult(r) };
+        const covered = r.replacement?.verified ? { by: 'replacement (disclosure_text above the button + consent_label, or paste replacement.jsx in React / replacement.html elsewhere)', except: r.replacement.remaining_checks ?? [] } : undefined;
+        return { headline: verdictHeadline('Disclosure', r), notes: checkNotes(r, 8, covered), data: withoutUnneededFix(slimCheckResult(r)) };
     },
 };
 const checkStripeCheckoutSession = {
@@ -688,12 +1191,14 @@ const checkStripeCheckoutSession = {
     title: 'Check Stripe Checkout Session params (returns corrected params)',
     description: [
         'Before shipping Stripe Checkout code: pass EXACTLY the object your code passes to stripe.checkout.sessions.create (mode "subscription"). Checkbox evaluates it against automatic-renewal laws and returns correction.corrected_params — the full params with the fix applied, ready to paste — plus an RFC 6902 JSON patch and before/after verification per check.',
-        'When line_items reference a Price id (price_…), also pass merchant { price or amount, interval, trial_days, merchant_name, cancel_url } because the params alone do not state them.',
-        'Note: on Stripe-hosted pages "clear and conspicuous" stays needs_review (Stripe styles custom_text itself); the response explains this.',
+        'With a Price id (price_…) in line_items, pass site (its plans are used) or merchant { price, interval, trial_days, merchant_name, cancel_url }.',
+        'Note: Stripe styles custom_text itself, so "clear and conspicuous" stays needs_review here; the plan shows it as a note, never a fix.',
     ].join('\n'),
     input: {
         params: z.record(z.string(), z.unknown()).describe('The Checkout Session params object, e.g. {"mode":"subscription","line_items":[{"price":"price_123","quantity":1}],"success_url":"https://acme.example/welcome"}.'),
-        merchant: planTerms.optional().describe('What the params do not say: merchant_name, cancel_url, and price/interval when line_items use a Price id.'),
+        merchant: merchantTerms.optional().describe('What the params do not say: merchant_name, cancel_url, and price/interval when line_items use a Price id.'),
+        site: z.string().max(100).optional().describe('site_… whose plans judge it (as verify_task)'),
+        plan: z.string().max(200).optional().describe('With site: plan name or price_…'),
         jurisdictions: jurisdictions.optional(),
         as_of: asOf.optional(),
     },
@@ -701,12 +1206,14 @@ const checkStripeCheckoutSession = {
     annotations: { ...ro, title: 'Check Stripe Checkout Session' },
     async run(args, { api }) {
         const r = await api.request('POST', '/v1/checks/stripe_checkout_session', { body: args });
-        const notes = checkNotes(r);
-        if (r.correction?.patch?.length)
+        const fixing = !!r.correction?.patch?.length;
+        const notes = checkNotes(r, 8, fixing && r.correction.verification?.passes ? { by: 'correction.corrected_params' } : undefined);
+        if (fixing)
             notes.unshift(`Replace the params in your code with correction.corrected_params (${r.correction.patch.length} change(s); verified passes: ${r.correction.verification?.passes ?? 'n/a'}).`);
-        if (r.correction?.verification?.note)
+        // Agent audit round 2: on a pass the same Stripe-styling note was printed four times; it is printed once.
+        if (fixing && r.correction?.verification?.note)
             notes.push(r.correction.verification.note);
-        const { correction, ...rest } = slimCheckResult(r);
+        const { correction, ...rest } = withoutUnneededFix(slimCheckResult(r));
         return { headline: verdictHeadline('Stripe Checkout Session', r), notes, data: { correction, ...rest } };
     },
 };
@@ -714,32 +1221,35 @@ const checkEmail = {
     name: 'check_email',
     title: 'Check a subscription lifecycle email',
     description: [
-        'Checks an acknowledgment, trial reminder, renewal reminder, price-change, annual-terms or cancellation-confirmation email against the laws that require it, and returns a compliant template (subject, text, html with merge tags) verified by the rules engine, plus required_by (which laws make this email mandatory for this plan).',
+        'Checks an acknowledgment, trial reminder, renewal reminder, price-change, annual-terms or cancellation-confirmation email against the laws that require it, and returns a template that passes the checks (subject, text, html with merge tags), verified by the rules engine, plus required_by (which laws make this email mandatory for this plan).',
         'Example: {"kind":"trial_reminder","subject":"Your trial ends soon","text":"…","terms":{"price":19.99,"interval":"month","trial_days":14,"cancel_url":"https://acme.example/account/cancel","merchant_name":"Acme"}}.',
         'For WHEN each email must be sent, use get_notice_schedule.',
     ].join('\n'),
     input: {
-        kind: z.enum(['acknowledgment', 'trial_reminder', 'renewal_reminder', 'price_change', 'annual_terms', 'cancellation_confirmation']).describe('Which lifecycle email this is.'),
+        kind: emailKind.describe('Which email (trial_reminder = trial_ending).'),
         subject: z.string().min(1).max(1000).describe('Subject line.'),
         text: z.string().max(100_000).optional().describe('Plain-text body (give text, html or both).'),
         html: z.string().max(100_000).optional().describe('HTML body.'),
-        terms: planTerms
-            .extend({
+        terms: strictObject({
+            ...planTermsShape,
             previous_price: z.union([z.number().positive(), z.string().max(40)]).optional().describe('price_change: price before the change, major units.'),
             previous_amount: z.number().int().positive().optional(),
             support_contact: z.string().max(200).optional().describe('Support email / URL for the template.'),
-        })
-            .describe('The plan the email is about: price (or amount), interval and cancel_url at least.'),
+        }, 'terms')
+            .optional()
+            .describe('price, interval, cancel_url (optional with site); price_change: NEW price'),
+        site: z.string().max(100).optional().describe('site_… whose Stripe prices judge it (default: your Stripe site).'),
+        plan: z.string().max(200).optional().describe('Plan name or price_… (default: the one named)'),
         jurisdictions: jurisdictions.optional(),
         as_of: asOf.optional(),
     },
     scopes: ['checks:read'],
     annotations: { ...ro, title: 'Check email' },
     async run(args, { api }) {
-        const r = await api.request('POST', '/v1/checks/email', { body: args });
-        const notes = checkNotes(r);
-        notes.unshift(r.required_by?.length ? `Legally required for this plan by: ${r.required_by.join(', ')}.` : 'Not legally required for this plan (still good practice).');
-        return { headline: verdictHeadline(`Email (${String(args.kind)})`, r), notes, data: slimCheckResult(r) };
+        const r = await api.request('POST', '/v1/checks/email', { body: { ...args, kind: checkKind(args.kind) } });
+        const notes = checkNotes(r, 8, r.template?.verified ? { by: 'template (subject + text or html; add your greeting and sign-off around it if you like)', except: r.template.remaining_checks ?? [] } : undefined);
+        notes.unshift(r.required_by?.length ? `Legally required for this plan by: ${citationList(r.required_by, r.requirements)}.` : 'Not legally required for this plan (still good practice).');
+        return { headline: verdictHeadline(`Email (${String(args.kind)}${r.plan ? `, plan ${untrusted(r.plan, 60)}` : ''})`, r), notes, data: slimCheckResult(r) };
     },
 };
 const checkPageHtml = {
@@ -754,7 +1264,10 @@ const checkPageHtml = {
         html: z.string().max(1_000_000).optional().describe('Rendered checkout page HTML. Give html or url.'),
         url: z.string().max(2048).optional().describe('Live public page URL to fetch instead (live, activated accounts).'),
         page_kind: z.enum(['checkout', 'pricing']).optional().describe('Default checkout.'),
-        terms: planTerms.optional().describe('The plan sold on the page (helps judge price / interval statements).'),
+        terms: planTerms.optional().describe('The plan sold on the page. merchant_name / cancel_url alone are fine (no price compared).'),
+        plans: z.array(strictObject(planTermsShape, 'plans[]')).max(20).optional().describe('Multi-plan pricing page: EVERY plan it sells (price, interval, trial_days each). Each plan card is judged against its own plan; plan_replacements gives each plan its own markup for its own button.'),
+        checkout_type: z.enum(['own_page', 'stripe_checkout', 'payment_link']).optional().describe('Where shoppers pay (default: inferred).'),
+        site: z.string().max(100).optional().describe("Your site_…: judge it as verify_task does (the site's Stripe-checked plans)."),
         jurisdictions: jurisdictions.optional(),
         as_of: asOf.optional(),
     },
@@ -765,25 +1278,74 @@ const checkPageHtml = {
             throw new ToolError('Pass html (the rendered page) or url.');
         const r = await api.request('POST', '/v1/checks/page', { body: args });
         const notes = checkNotes(r);
+        // Round 17 (python-flask): on a Payment Link / Stripe Checkout page, replacement.html is the terms only.
+        if (r.replacement?.consent_on && r.replacement.note && r.verdict !== 'pass')
+            notes.push(`Replacement: ${r.replacement.note}`);
         if (r.extraction?.purchase_buttons) {
             const b = r.extraction.purchase_buttons;
             notes.unshift(b.length ? `Purchase buttons found: ${b.length} (first: ${untrusted(b[0], 60)}; texts in extraction.purchase_buttons).` : 'Purchase buttons found: none (send the rendered HTML).');
         }
-        return { headline: verdictHeadline('Page', r), notes, data: slimCheckResult(r) };
+        return { headline: verdictHeadline('Page', r), notes, data: withoutUnneededFix(slimCheckResult(r)) };
     },
 };
+const DAY_S = 86_400;
+/**
+ * Agent audit round 2: "2026-11-14: trial_ending (5 days before; US-UT)" said neither before what nor the allowed window,
+ * which is what a cron job needs; the window was only in epoch seconds. The line now states both relative to the event.
+ */
+export function noticeScheduleLine(n) {
+    const anchor = n.anchor_date ? Date.parse(`${n.anchor_date}T00:00:00Z`) / 1000 : undefined;
+    const event = n.occasion ? n.occasion.replace(/\s*\(.*\)$/, '').toLowerCase() : 'the event';
+    if (n.days_before === 0 || anchor === undefined || n.window_opens_at === undefined || n.window_closes_at === undefined) {
+        return `${n.send_date}: ${n.kind} — ${n.days_before === 0 ? `at ${event} (same day)` : `${n.days_before} days before ${event}`} (${n.jurisdictions.join(', ')})`;
+    }
+    const most = Math.round((anchor - n.window_opens_at) / DAY_S);
+    const least = Math.round((anchor - n.window_closes_at) / DAY_S);
+    const window = least >= 0 && most >= least ? `; allowed ${least === most ? `exactly ${least}` : `${least}–${most}`} days before` : '';
+    return `${n.send_date}: ${n.kind} — ${n.days_before} days before ${event} (${n.anchor_date})${window} (${n.jurisdictions.join(', ')})`;
+}
+/** One line per notice; a kind sent every charge shows its first date and how many follow. */
+export function noticeScheduleLines(notices) {
+    const out = [];
+    const seen = new Map();
+    for (const n of notices)
+        seen.set(n.kind, (seen.get(n.kind) ?? 0) + 1);
+    const shown = new Set();
+    for (const n of notices) {
+        const count = seen.get(n.kind);
+        if (count > 2) {
+            if (shown.has(n.kind))
+                continue;
+            shown.add(n.kind);
+            out.push(`${noticeScheduleLine(n)} — then the same before each of the next ${count - 1} charges (all in notices[])`);
+        }
+        else
+            out.push(noticeScheduleLine(n));
+    }
+    return out.slice(0, 12);
+}
+/** Notice kinds of the schedule → the compliance plan's email task for it (same names as get_compliance_plan). */
+export const NOTICE_KIND_TASKS = {
+    acknowledgment: { name: 'acknowledgment email', task: 'acknowledgment_email' },
+    trial_ending: { name: 'trial-ending reminder', task: 'trial_reminder' },
+    renewal_reminder: { name: 'renewal reminder', task: 'renewal_reminder' },
+    annual_terms: { name: 'yearly terms reminder', task: 'annual_terms_notice' },
+    charge_notice: { name: 'charge notice', task: 'charge_notice' },
+    price_change: { name: 'price-change notice', task: 'price_change_notice' },
+};
 const getNoticeSchedule = {
     name: 'get_notice_schedule',
     title: 'Get the dates each required notice must be sent',
     description: [
-        'For a plan (price, interval, trial) and a sign-up date: every legally required notice (acknowledgment, trial-ending reminder, renewal reminder, annual terms, price-change notice) with the recommended send date, the compliant window (earliest/latest), the jurisdictions it satisfies and citations; plus notice kinds NOT required and why.',
+        'For a plan (price, interval, trial) and a sign-up date: every legally required notice (acknowledgment, trial-ending reminder, renewal reminder, yearly terms reminder, charge notice, price-change notice — the same emails as the compliance plan\'s email tasks) with the recommended send date, the allowed send window (earliest/latest), the jurisdictions it satisfies and citations; plus notice kinds NOT required and why.',
         'Use it to implement reminder emails / cron jobs correctly. Example: {"terms":{"price":99,"interval":"year","trial_days":30},"start_date":"2026-11-01"}.',
     ].join('\n'),
     input: {
-        terms: planTerms.describe('The plan: price (or amount), interval, interval_count, trial_days.'),
+        terms: planTerms.optional().describe('The plan: price (or amount), interval, interval_count, trial_days (or site + plan).'),
+        site: z.string().max(100).optional().describe('site_… (its plans, jurisdictions)'),
+        plan: z.string().max(200).optional().describe('With site: plan name or price_…'),
         start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Sign-up date, YYYY-MM-DD (default today).'),
-        price_change: z
-            .object({ effective_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), new_price: z.number().positive().optional() })
+        price_change: strictObject({ effective_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), new_price: z.number().positive().optional() }, 'price_change')
             .optional()
             .describe('A planned price change to schedule the notice for.'),
         cycles: z.number().int().min(1).max(24).optional().describe('How many renewals to plan (default one year).'),
@@ -795,23 +1357,151 @@ const getNoticeSchedule = {
     annotations: { ...ro, title: 'Notice schedule' },
     async run(args, { api }) {
         const r = await api.request('POST', '/v1/checks/notice_schedule', { body: args });
+        const singleDay = [...new Set(r.notices.flatMap((n) => (n.timing_note ? [`${n.kind}: ${n.timing_note}`] : [])))].slice(0, 3);
+        const kinds = [...new Set(r.notices.map((n) => n.kind))];
         return {
-            headline: `${r.notices.length} required notice(s) for this plan.`,
+            // Polish round: one email per kind, named like the compliance plan's email tasks (the per-send dates follow).
+            headline: kinds.length
+                ? `${kinds.length} required email${kinds.length === 1 ? '' : 's'} for ${r.plan ? `plan ${untrusted(r.plan, 60)}` : 'this plan'}: ${kinds.map((k) => NOTICE_KIND_TASKS[k] ? `${NOTICE_KIND_TASKS[k].name} (plan task ${NOTICE_KIND_TASKS[k].task})` : k).join(', ')}; ${r.notices.length} send${r.notices.length === 1 ? '' : 's'} in the period below.`
+                : 'No required notices for this plan under these jurisdictions.',
             notes: [
-                ...r.notices.slice(0, 12).map((n) => `${n.send_date}: ${n.kind} (${n.days_before} days before; ${n.jurisdictions.join(', ')})`),
+                ...noticeScheduleLines(r.notices),
+                ...singleDay,
+                ...(r.rounding_rule ? [`Timing rule: ${r.rounding_rule}`] : []),
                 ...(r.not_required ?? []).map((n) => `Not required: ${n.kind} — ${n.reason}`),
+                ...(r.warnings ?? []).filter((w) => typeof w?.message === 'string').slice(0, 3).map((w) => w.message),
             ],
             data: r,
         };
     },
 };
+const SUGGESTION_SURFACE_NAMES = [
+    'checkout_page',
+    'stripe_checkout',
+    'acknowledgment_email',
+    'trial_reminder_email',
+    'renewal_reminder_email',
+    'price_change_email',
+    'cancellation_flow',
+    'cancellation_confirmation_email',
+];
+const suggestImprovements = {
+    name: 'suggest_improvements',
+    title: 'Suggest conversion improvements that keep the checks passing',
+    description: [
+        'OPTIONAL, after compliance: concrete ways to make the checkout page, Stripe Checkout, lifecycle emails and the cancellation flow convert or retain better WITHOUT breaking automatic-renewal laws. Deterministic library; every after-example was run through Checkbox\'s own checks for the merchant\'s states before it is offered.',
+        'Each suggestion gives apply.where + apply.content (the exact copy, Stripe JSON patch or flow change to make), apply.instructions, preconditions that must be true (never apply one whose precondition is false), and guardrails with catalog requirement ids (e.g. California / Colorado click-to-cancel next to any save offer, Minnesota ask-first). Never invent figures or add urgency, pre-checked boxes or obstacles.',
+        'With a site id (or one site in this mode): suggestions from what Checkbox observed. Or send the copy you are writing: terms + any of disclosure, page_html, stripe_checkout_session_params, emails, cancellation_flow (as in the check_* tools).',
+        'Surfaces whose compliance checks fail are held: fix them first (get_compliance_plan). Suggestions never block and never count toward compliance. After applying one, re-run the check named in verification.operation_id on the real copy.',
+    ].join('\n'),
+    input: {
+        site: siteId.optional(),
+        terms: planTerms.optional().describe('The plan sold (price or amount, interval, trial_days, merchant_name, cancel_url). Required with disclosure or emails.'),
+        other_plans: z.array(strictObject({ ...planTermsShape, name: z.string().max(80).optional().describe('Plan name, e.g. "Lite" (or plan_name).') }, 'other_plans[]')).max(10).optional().describe('Other plans you sell (enables cheaper-plan / plan-choice suggestions).'),
+        disclosure: z
+            .object({
+            text: z.string().min(1).max(5000).describe('Disclosure next to the purchase button, as rendered.'),
+            button_text: z.string().max(200).optional(),
+            order_summary: z.string().max(1000).optional(),
+            placement: z.object({ above_button: z.boolean().optional(), bold: z.boolean().optional(), boxed: z.boolean().optional(), font_size_px: z.number().min(4).max(96).optional() }).optional(),
+            consent: z.object({ checkbox: z.boolean(), prechecked: z.boolean().optional(), label: z.string().max(1000).optional() }).optional(),
+        })
+            .optional()
+            .describe('Your own checkout (as in check_disclosure, plan terms in terms).'),
+        page_html: z.string().max(1_000_000).optional().describe('Rendered checkout page HTML (as in check_page_html).'),
+        stripe_checkout_session_params: z.record(z.string(), z.unknown()).optional().describe('Exactly what your code passes to stripe.checkout.sessions.create.'),
+        emails: z
+            .array(z.object({
+            kind: z.enum(['acknowledgment', 'trial_reminder', 'renewal_reminder', 'price_change', 'cancellation_confirmation']),
+            subject: z.string().min(1).max(1000),
+            text: z.string().max(100_000).optional(),
+            html: z.string().max(100_000).optional(),
+            previous_price: z.union([z.number().positive(), z.string().max(40)]).optional().describe('price_change: the old price.'),
+        }))
+            .max(8)
+            .optional()
+            .describe('Lifecycle emails (as in check_email).'),
+        cancellation_flow: z
+            .object({
+            steps: z.array(z.object({ text: z.string().max(5000), buttons: z.array(z.string().max(200)).max(10).optional(), offer: z.boolean().optional() })).min(1).max(10),
+            confirmation_shown: z.boolean().optional(),
+        })
+            .optional()
+            .describe('Your cancellation flow, one entry per screen from the account page to the confirmation.'),
+        surfaces: z.array(z.enum(SUGGESTION_SURFACE_NAMES)).max(8).optional().describe('Only these surfaces.'),
+        trial_reminders: z.boolean().optional().describe('You send a trial-ending reminder to every trial subscriber.'),
+        jurisdictions: jurisdictions.optional(),
+        as_of: asOf.optional(),
+    },
+    scopes: ['checks:read'],
+    annotations: { ...ro, title: 'Suggest improvements' },
+    async run(args, { api }) {
+        const stateless = ['terms', 'disclosure', 'page_html', 'stripe_checkout_session_params', 'emails', 'cancellation_flow'].some((k) => args[k] !== undefined);
+        let r;
+        let where;
+        if (stateless && args.site === undefined) {
+            const body = pick(args, ['terms', 'other_plans', 'disclosure', 'emails', 'cancellation_flow', 'surfaces', 'trial_reminders', 'jurisdictions', 'as_of']);
+            if (args.page_html !== undefined)
+                body.page = { html: args.page_html };
+            if (args.stripe_checkout_session_params !== undefined)
+                body.stripe_checkout_session = { params: args.stripe_checkout_session_params };
+            r = await api.request('POST', '/v1/suggestions', { body });
+            where = 'the copy you sent';
+        }
+        else {
+            const site = await resolveSite(api, args.site);
+            const surfaces = Array.isArray(args.surfaces) ? args.surfaces.join(',') : undefined;
+            r = await api.request('GET', `/v1/sites/${enc(site)}/suggestions`, { ...(surfaces ? { query: { surfaces } } : {}) });
+            where = site;
+        }
+        const notes = ['Optional: never blocking, never counted toward compliance. Check every precondition before applying.'];
+        r.suggestions.slice(0, 15).forEach((s, i) => {
+            notes.push([
+                `${i + 1}. [${s.surface} · ${s.match}] ${s.title} (${s.key})`,
+                // "From your copy" only for the merchant's own text; anything else is an example (never present it as theirs).
+                s.before.source === 'your_copy' || (!s.before.source && s.match === 'detected')
+                    ? `   before, from your copy (${s.before.label}): ${untrusted(s.before.text, 160)}`
+                    : `   before, example (${s.before.label}): ${JSON.stringify(s.before.text.slice(0, 160))}`,
+                `   apply (${s.apply.type}) at ${s.apply.where}: ${JSON.stringify(s.apply.content.length > 600 ? `${s.apply.content.slice(0, 600)}…` : s.apply.content)}`,
+                `   how: ${s.apply.instructions}`,
+                ...(s.preconditions.length ? [`   only if true: ${s.preconditions.join(' ')}`] : []),
+                `   guardrails: ${s.guardrails.map((g) => g.requirement_ids.join('/')).join('; ')}`,
+                ...(s.placeholders.length ? [`   fill: ${s.placeholders.join(', ')}`] : []),
+                `   verified by ${s.verification?.operation_id ?? 'n/a'} (${s.verification?.verified ? `passes${s.verification.compliance_label ? `: ${s.verification.compliance_label}` : ''}` : 'not verified'}); re-run it on your real copy after the change.`,
+            ].join('\n'));
+        });
+        if (r.suggestions.length > 15)
+            notes.push(`…and ${r.suggestions.length - 15} more in data.suggestions.`);
+        const held = r.surfaces.filter((s) => s.held_by.length);
+        if (held.length)
+            notes.push(`Held (fix first with get_compliance_plan): ${held.map((s) => `${s.surface} (${s.held_label ? `${s.held_label}: ` : ''}${s.held_by.join(', ')})`).join('; ')}.`);
+        if (r.withheld.length)
+            notes.push(`Withheld: ${r.withheld.slice(0, 8).map((w) => `${w.key}: ${w.reason}`).join(' | ')}`);
+        return { headline: `Suggestions for ${where}: ${r.summary}`, notes, data: r };
+    },
+};
 // ---------------------------------------------------------------------------------------------------------------------
 // Sites, findings, scans, law updates
 // ---------------------------------------------------------------------------------------------------------------------
+/** One site in list_sites: what an agent needs to pick it. */
+export function siteListItem(s) {
+    const x = s;
+    return {
+        id: s.id,
+        object: 'site',
+        name: s.name ?? null,
+        url: s.url,
+        ...(x.platform ? { platform: x.platform } : {}),
+        ...(x.checkout?.url ? { checkout_url: x.checkout.url } : {}),
+        status: plainLabel(s.compliance?.label ?? 'Not checked yet'),
+        domain_verified: x.monitoring?.held_for_domain_verification !== true,
+        ...(x.archived ? { archived: true } : {}),
+    };
+}
 const listSites = {
     name: 'list_sites',
     title: 'List sites',
-    description: 'The account\'s sites in the current mode (test keys see only test-mode sites), newest first, each with its compliance score, insurable flag and open findings. Use it to find a site id.',
+    description: 'The account\'s sites in the current mode (test keys see only test-mode sites), newest first, each with its compliance status label. Use it to find a site id.',
     input: { limit: listLimit, starting_after: startingAfter, archived: z.boolean().optional().describe('true lists only archived sites.') },
     scopes: ['sites:read'],
     annotations: { ...ro, title: 'List sites' },
@@ -821,9 +1511,14 @@ const listSites = {
         });
         return {
             headline: `${list.data.length}${list.has_more ? '+' : ''} site(s) in ${key.mode === 'unknown' ? 'this' : key.mode} mode.`,
-            notes: list.data.map((s) => `${s.id} ${untrusted(s.url, 100)} — score ${s.compliance?.score ?? 'n/a'}, insurable ${s.compliance?.insurable ?? 'n/a'}, open findings ${s.compliance?.open_findings ?? 0}`),
-            data: list,
-            next: list.data.length ? null : { type: 'setup', message: 'No sites yet: call setup_checkbox with the site URL.', operation_id: 'createSetupSession' },
+            // Audit P2: name + URL per site, and a Next line either way.
+            notes: list.data.map((s) => `${s.id} ${s.name ? `${untrusted(s.name, 60)} ` : ''}${untrusted(s.url, 100)} — ${plainLabel(s.compliance?.label ?? 'Not checked yet')}`),
+            // Agent audit round 2: each site carried install details, webhook URLs, retention and legal hold (~1.5 KB) when
+            // an agent needs the id, URL and status; get_site_status / the API have the rest.
+            data: { ...list, data: list.data.map(siteListItem) },
+            next: list.data.length
+                ? { type: 'review_plan', message: list.data.length === 1 ? `Call get_compliance_plan with site "${list.data[0].id}" for what to change next.` : 'Call get_compliance_plan with the id of the site whose URL matches this project (listed above) for what to change next.', operation_id: 'retrieveCompliancePlan' }
+                : { type: 'setup', message: 'No sites yet: call setup_checkbox with the site URL.', operation_id: 'createSetupSession' },
         };
     },
 };
@@ -867,7 +1562,7 @@ const updateSite = {
     name: 'update_site',
     title: 'Update a site\'s settings (write)',
     description: [
-        'WRITE: updates a site — the fields plan tasks of change.type "config" ask for (their change.content is this tool\'s input): checkout_url, checkout_steps, test_account { login_url, email, password } (stored encrypted; the response echoes it without the password), name (the merchant name in generated legal copy), platform, jurisdictions, monitoring_interval_minutes.',
+        'WRITE: updates a site — the fields plan tasks of change.type "config" ask for (their change.content is this tool\'s input): checkout_url, checkout_steps, test_account { login_url, email, password } (stored encrypted; the response echoes it without the password), name (the merchant name in generated legal copy), platform, jurisdictions, monitoring_interval_minutes, protection_level (minimum = legal floor only; balanced = + recommended suggestions, the default; maximum = + extras; only required items ever affect compliance).',
         'The response is the site; check checkout.url / checkout.test_account to confirm. Then verify_task the task that asked for it.',
     ].join('\n'),
     input: {
@@ -875,19 +1570,24 @@ const updateSite = {
         name: z.string().max(200).optional().describe('Merchant / brand name (used in generated disclosures).'),
         checkout_url: z.string().max(2048).optional().describe('Page with the Subscribe / Buy button.'),
         checkout_steps: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe('Steps to reach the purchase button (clicks / fills), as in the API.'),
-        test_account: z
-            .object({ login_url: z.string().max(2048), email: z.string().max(320), password: z.string().max(200) })
+        test_account: strictObject({
+            login_url: z.string().max(2048),
+            email: z.string().max(320),
+            password: z.string().max(200),
+            reactivate_url: z.string().max(2048).optional().describe('Test-only page that re-subscribes the test account.'),
+        }, 'test_account')
             .optional()
-            .describe('A TEST subscriber account the scanner logs in with to try cancelling online.'),
+            .describe('A TEST subscriber account the scanner logs in with to try cancelling online (echoed back without the password).'),
         platform: z.enum(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'woocommerce', 'custom']).optional(),
         jurisdictions: z.array(z.string().max(10)).max(60).optional(),
         monitoring_interval_minutes: z.number().int().min(0).optional(),
+        protection_level: z.enum(['minimum', 'balanced', 'maximum']).optional().describe('Which tiers the plan lists: minimum (required only), balanced (default: + recommended suggestions), maximum (+ extras). Ask the human before changing it.'),
     },
     scopes: ['sites:write'],
     annotations: { ...write(false, true), title: 'Update site' },
     async run(args, { api }) {
         const site = await resolveSite(api, args.site);
-        const body = pick(args, ['name', 'checkout_url', 'checkout_steps', 'test_account', 'platform', 'jurisdictions', 'monitoring_interval_minutes']);
+        const body = pick(args, ['name', 'checkout_url', 'checkout_steps', 'test_account', 'platform', 'jurisdictions', 'monitoring_interval_minutes', 'protection_level']);
         if (!Object.keys(body).length)
             throw new ToolError('Pass at least one field to change (e.g. checkout_url, test_account, name).');
         const updated = await api.request('POST', `/v1/sites/${enc(site)}`, { body });
@@ -898,37 +1598,94 @@ const updateSite = {
         };
     },
 };
+/** The site's Shopify connection in one line, naming the tool (or the human step) that comes next. */
+export function shopifyLines(sh, site) {
+    if (!sh)
+        return [];
+    if (sh.connection === 'app') {
+        return sh.terms_published
+            ? [`Shopify: ${sh.shop ?? 'The store'} is connected through the Checkbox app; renewal terms published to the app block on ${new Date(sh.terms_published.published * 1000).toISOString().slice(0, 10)}. If the storefront does not show them, the merchant still has to place the "Renewal terms + consent" block once: ${sh.theme_editor_url ?? 'theme editor'}. publish_shopify_terms republishes after plan changes.`]
+            : [`Shopify: ${sh.shop ?? 'The store'} is connected through the Checkbox app; the renewal terms are not published yet: call publish_shopify_terms with site "${site}", then the merchant places the block once (${sh.theme_editor_url ?? 'theme editor'}).`];
+    }
+    if (sh.connection === 'own_app')
+        return [`Shopify: ${sh.shop ?? 'The store'} is connected with its own custom-app token (read-only): use the standalone theme snippet from the plan's sign-up task, or have the merchant install the Checkbox Shopify app so publish_shopify_terms can update the block.`];
+    return ['Shopify: the store is not connected. Only the merchant can connect it: install the Checkbox app in the Shopify admin, open it and click "Connect to Checkbox" (then publish_shopify_terms works).'];
+}
 const getSiteStatus = {
     name: 'get_site_status',
     title: 'Get a site\'s compliance status',
-    description: 'Where a site stands: compliance score (0-100), insurable flag, what blocks it (critical/high checks failing or unverified), the top open failing findings, latest scan, and whether the snippet is installed. Use it for "am I compliant?". For what to change, use get_compliance_plan.',
+    description: 'Where a site stands: one status (Checks pass, N fixes needed, Not set up yet, Not checked yet, Your call) and the to-do list: the compliance plan\'s ordered open tasks, as on the dashboard. Use it for "am I compliant?"; get_task gives each change.',
     input: { site: siteId.optional() },
     scopes: ['sites:read'],
     annotations: { ...ro, title: 'Site status' },
     async run(args, { api }) {
         const id = await resolveSite(api, args.site);
-        const [site, evaluation, findings] = await Promise.all([
+        const [site, evaluation, plan] = await Promise.all([
             api.request('GET', `/v1/sites/${enc(id)}`),
             optional(api.request('GET', `/v1/sites/${enc(id)}/evaluation`)),
-            optional(api.request('GET', '/v1/findings', { query: { site: id, status: 'fail', state: 'open', limit: 5 } })),
+            optional(api.request('GET', `/v1/sites/${enc(id)}/plan`)),
         ]);
-        const evaluated = 'score' in evaluation;
-        const top = 'data' in findings ? findings.data : [];
+        // Round-4 pilot (nextjs): "nothing left to do" while 13 critical/high checks were needs_review. Count them too.
+        const review = await optional(api.request('GET', '/v1/findings', { query: { site: id, status: 'needs_review', state: 'open', limit: 100 } }));
+        const evaluated = 'id' in evaluation;
+        const toReview = 'data' in review ? review.data : [];
+        const seriousReview = toReview.filter((f) => f.severity === 'critical' || f.severity === 'high');
+        const blocking = evaluated ? (evaluation.blockers ?? []).map((b) => b.check_id) : [];
+        // One to-do list: the plan's ordered open tasks, never a list built from findings.
+        const todo = 'tasks' in plan && Array.isArray(plan.tasks) ? planTodo(plan.tasks) : [];
+        const { checks: _omit, score: _score, insurable: _insurable, ...evalLite } = (evaluated ? evaluation : {});
+        // Status labels: the roll-up decides the headline; pending live checks count as compliant and say how they complete.
+        const roll = site.compliance?.rollup;
+        const pendingLive = roll?.pending_live_checks ?? [];
+        const rollStatus = site.compliance?.status;
+        const label = site.compliance?.label;
+        const ro = unverifiedScanNote(site.unverified_scan);
         const notes = [
-            ...(evaluated && evaluation.blockers?.length ? [`Blocking insurability: ${evaluation.blockers.map((b) => b.check_id).join(', ')}`] : []),
-            ...top.map((f) => `${f.severity.toUpperCase()} ${f.id} ${f.check_id}: ${f.title}`),
+            ...(todo.length ? [`To do (${todo.length}, from the compliance plan, in order):`, ...todo.map((t, i) => `${i + 1}. ${t.id} ${todoLine(t)}`)] : []),
+            ...(evaluated && label ? pendingLive.slice(0, 6).map((p) => `LIVE CHECK PENDING ${p.check_id}: ${p.what} — ${p.completes}`) : []),
+            ...(ro ? [ro] : []),
+            ...shopifyLines(site.shopify, site.id),
         ];
-        const { checks: _omit, ...evalLite } = (evaluated ? evaluation : {});
+        const { open_findings: _open, needs_review: _nr, ...complianceLite } = (site.compliance ?? {});
         return {
-            headline: evaluated
-                ? `${site.url}: score ${evaluation.score}, ${evaluation.insurable ? 'insurable' : 'NOT insurable'}, ${site.compliance?.open_findings ?? top.length} open failing finding(s).`
-                : `${site.url}: not evaluated yet.`,
+            headline: evaluated ? `${site.url}: ${plainLabel(label ?? 'Not checked yet')}.` : `${site.url}: Not checked yet.`,
             notes,
-            data: { site, evaluation: evaluated ? evalLite : null, top_findings: top },
+            data: { site: site.compliance ? { ...site, compliance: complianceLite } : site, evaluation: evaluated ? evalLite : null, todo },
             next: evaluated
-                ? top.length
-                    ? { type: 'fix', message: 'Call get_compliance_plan for the ordered changes that fix these.', operation_id: 'retrieveCompliancePlan' }
-                    : { type: 'none', message: 'No open failing findings.' }
+                ? todo.length && (rollStatus === 'needs_fix' || todo.some((t) => t.status === 'needs_fix' || t.status === 'not_set_up'))
+                    ? { type: 'fix', message: `Start with the first task (${todo[0].id}: ${todo[0].title}); get_compliance_plan / get_task give the exact change.`, operation_id: 'retrieveCompliancePlan' }
+                    : rollStatus === 'needs_fix'
+                        ? { type: 'fix', message: 'Call get_compliance_plan for the ordered changes.', operation_id: 'retrieveCompliancePlan' }
+                        : rollStatus === 'your_call' || todo.some((t) => t.status === 'your_call')
+                            ? { type: 'review', message: 'Some items need a decision from the human: call get_compliance_plan for the questions (each has a recommended answer).', operation_id: 'retrieveCompliancePlan' }
+                            : rollStatus === 'compliant' && !todo.length
+                                ? // Round 15 (pilot 14, change-guard: "Checks pass · 3 live checks pending" next to "the site is not shown
+                                    // as passing yet"): one status, one sentence. When the roll-up says Checks pass, next_action says the
+                                    // same; the live checks are named as what completes it, never as a reason it does not pass.
+                                    pendingLive.length
+                                        ? {
+                                            type: 'complete_live_checks',
+                                            message: `${plainLabel(label ?? 'Checks pass')}: nothing needs a code change. ${pendingLive.length} live check(s) complete on their own (${pendingLive
+                                                .slice(0, 3)
+                                                .map((p) => p.what)
+                                                .join('; ')}); get_compliance_plan says how each one completes (a proof run, BCC real sends, a test account).`,
+                                            operation_id: 'retrieveCompliancePlan',
+                                        }
+                                        : { type: 'none', message: `${plainLabel(label ?? 'Checks pass')}: every check that applies passes; nothing left to do. Keep monitoring on.` }
+                                : blocking.length || pendingLive.length || seriousReview.length || todo.length
+                                    ? // Normal round 4 (nextjs): "nothing left to do — Compliant" next to 2 blocking checks. Never call a site
+                                        // compliant while a blocking check, a pending live check or an open plan task remains.
+                                        {
+                                            type: 'complete_live_checks',
+                                            message: `Nothing needs a code change now, but the site is not shown as passing yet (${plainLabel(label ?? 'Not checked yet')}): ${[
+                                                todo.length ? `${todo.length} task(s) on the plan (${todo.slice(0, 3).map((t) => t.title).join('; ')})` : '',
+                                                blocking.length ? `blocking check(s) ${blocking.slice(0, 4).join(', ')}` : '',
+                                                pendingLive.length ? `${pendingLive.length} live check(s) pending` : '',
+                                                seriousReview.length && !todo.length ? `${seriousReview.length} check(s) to review` : '',
+                                            ].filter(Boolean).join(', ')}. Call get_compliance_plan for how each one completes (a proof run, BCC real sends, a test account).`,
+                                            operation_id: 'retrieveCompliancePlan',
+                                        }
+                                    : { type: 'none', message: 'Every check that applies has passed; nothing left to do. Keep monitoring on.' }
                 : { type: 'run_first_check', message: 'Call verify_site (or run_scan) for the first verdict.', operation_id: 'verifySite' },
         };
     },
@@ -936,10 +1693,10 @@ const getSiteStatus = {
 const listFindings = {
     name: 'list_findings',
     title: 'List compliance findings',
-    description: 'Findings (one per legal check per site) ordered by urgency: failing first, then by severity, each with citations. Filter by site, status (fail, needs_review, pass, not_applicable) and state (open, acknowledged, resolved, accepted_risk). Default: open failing findings. Use get_finding for the fix of one.',
+    description: 'Findings (one per legal check per site) ordered by urgency: failing first, then by severity, each with citations. Filter by site, status (fail, needs_review, pass, not_applicable) and state (open, acknowledged, resolved, accepted_risk). Default: every open finding of every status. Use get_finding for the fix of one.',
     input: {
         site: z.string().max(100).optional().describe('Only this site (site_…).'),
-        status: z.enum(['pass', 'fail', 'needs_review', 'not_applicable']).optional().describe('Default fail.'),
+        status: z.enum(['pass', 'fail', 'needs_review', 'not_applicable']).optional().describe('Default: all statuses.'),
         state: z.enum(['open', 'acknowledged', 'resolved', 'accepted_risk']).optional().describe('Default open.'),
         limit: listLimit,
         starting_after: startingAfter,
@@ -950,7 +1707,8 @@ const listFindings = {
         const list = await api.request('GET', '/v1/findings', {
             query: {
                 site: args.site,
-                status: args.status ?? 'fail',
+                // Normal round 3: with no filter, every open finding (it returned "0 finding(s)" while 13 were active).
+                status: args.status,
                 state: args.state ?? 'open',
                 limit: args.limit,
                 starting_after: args.starting_after,
@@ -958,7 +1716,7 @@ const listFindings = {
         });
         return {
             headline: `${list.data.length}${list.has_more ? '+' : ''} finding(s).`,
-            notes: list.data.map((f) => `${f.severity.toUpperCase()} ${f.id} [${f.status}] ${f.check_id}: ${f.title}${f.requirements?.[0] ? ` [${f.requirements[0].citation}]` : ''}`),
+            notes: list.data.map((f) => `${f.severity.toUpperCase()} ${f.id} [${f.compliance?.label ?? f.status}] ${f.check_id}: ${f.title}${f.requirements?.[0] ? ` [${f.requirements[0].citation}]` : ''}`),
             data: list,
         };
     },
@@ -982,12 +1740,43 @@ const getFinding = {
             ? await optional(api.request('GET', `/v1/findings/${enc(id)}/fix`, { query: pick(args, ['target', 'cancel_url', 'plan']) }))
             : { unavailable: 'This key has no fixes:read permission.' };
         return {
-            headline: `${finding.severity.toUpperCase()} ${finding.id} [${finding.status}] ${finding.check_id}: ${finding.title}`,
+            headline: `${finding.severity.toUpperCase()} ${finding.id} [${finding.compliance?.label ?? finding.status}] ${finding.check_id}: ${finding.title}`,
+            notes: [complianceBullet(finding.check_id, finding.compliance, finding.status, finding.title)].filter((x) => !!x),
             data: { finding, fix },
             next: nextActionOf(fix) ?? { type: 'apply_fix', message: 'Apply fix (or the matching task from get_compliance_plan), then call verify_site.', operation_id: 'verifySite' },
         };
     },
 };
+const publishShopifyTerms = {
+    name: 'publish_shopify_terms',
+    title: 'Publish renewal terms to the Shopify app block (write)',
+    description: [
+        'WRITE (admin key). Shopify store linked through the Checkbox Shopify app (get_site_status: shopify.connection "app"): publishes the engine-verified renewal terms + consent label for the site\'s real plan to the Checkbox app block. Read-only on the store except that app-owned metafield (no theme/product/checkout edits); safe to repeat.',
+        'The merchant still places the "Renewal terms + consent" block once: give them theme_editor_url from the result. Then verify_site.',
+        'shopify_not_connected: only the merchant can install the app in Shopify and click "Connect to Checkbox". terms_incomplete: follow next_action.',
+    ].join('\n'),
+    input: {
+        site: requiredSite,
+        cancel_url: z.string().max(2048).optional().describe('Cancellation URL to state (default: detected).'),
+        plan: z.string().max(200).optional().describe('Plan / price id (default: detected).'),
+    },
+    scopes: ['fixes:write'],
+    annotations: { ...write(true, true), title: 'Publish Shopify terms' },
+    async run(args, { api }) {
+        const site = String(args.site);
+        const r = await api.request('POST', `/v1/sites/${enc(site)}/fixes/shopify/publish`, { body: pick(args, ['cancel_url', 'plan']) });
+        return {
+            headline: `Published the verified renewal terms to the Checkbox app block on ${r.shop} (${r.id}).`,
+            notes: [
+                `Disclosure: ${untrusted(r.disclosure, 600)}`,
+                `Consent checkbox: ${untrusted(r.consent_label, 200)}`,
+                `Only the merchant can place the block (once): ask them to open ${r.theme_editor_url} , check the "Renewal terms + consent" block sits directly above the add-to-cart button, and click Save. Later publishes update it in place.`,
+            ],
+            data: r,
+            next: r.next_action ?? { type: 'place_theme_block', message: `After the merchant saved the block in the theme editor, call verify_site for ${r.site}.`, operation_id: 'verifySite' },
+        };
+    },
+};
 const runScan = {
     name: 'run_scan',
     title: 'Run a synthetic-shopper scan (write)',
@@ -1008,15 +1797,26 @@ const runScan = {
 const getScan = {
     name: 'get_scan',
     title: 'Get a scan',
-    description: 'A scan\'s status (queued → running → completed | failed), warnings, and once completed the evaluation it produced with score and insurable flag.',
+    description: 'A scan\'s status (queued → running → completed | failed), warnings, and once completed the evaluation it produced (the site status and to-do list update from it).',
     input: { scan: z.string().max(100).describe('Scan id (scan_…).') },
     scopes: ['scans:read'],
     annotations: { ...ro, title: 'Scan' },
     async run(args, { api }) {
         const scan = await api.request('GET', `/v1/scans/${enc(String(args.scan))}`);
         const done = scan.status === 'completed';
+        // Audit P1: a queued scan of a site held for domain verification does not run until the domain is verified.
+        if (scan.status === 'queued' && scan.site) {
+            const site = await optional(api.request('GET', `/v1/sites/${enc(scan.site)}`));
+            if ('monitoring' in site && site.monitoring?.held_for_domain_verification) {
+                return {
+                    headline: `Scan ${scan.id}: queued (waiting for domain verification). It does not run until the site's domain is verified.`,
+                    data: scan,
+                    next: { type: 'verify_domain', message: `Do the plan's verify_domain task first (get_compliance_plan for site ${scan.site}); polling this scan changes nothing until then.`, operation_id: 'retrieveCompliancePlan' },
+                };
+            }
+        }
         return {
-            headline: `Scan ${scan.id}: ${statusLine(scan.status)}${done ? `, score ${scan.score ?? 'n/a'}, insurable ${scan.insurable ?? 'n/a'}` : ''}${scan.error ? ` — error: ${untrusted(scan.error, 160)}` : ''}.`,
+            headline: `Scan ${scan.id}: ${statusLine(scan.status)}${done && scan.compliance?.label ? ` — ${plainLabel(scan.compliance.label)}` : ''}${done ? '; the site status and to-do list are updated (get_site_status)' : ''}${scan.error ? ` — error: ${untrusted(scan.error, 160)}` : ''}.`,
             data: scan,
             next: done
                 ? { type: 'review', message: 'Call get_compliance_plan for what to change.', operation_id: 'retrieveCompliancePlan' }
@@ -1029,32 +1829,58 @@ const getScan = {
 const sendFeedback = {
     name: 'send_feedback',
     title: 'Send feedback to the Checkbox team',
-    description: 'Report a problem or a missing feature in Checkbox. Include what you tried and what you expected (and the site / request id or tool name when there is one). Use type "bug" for something broken, "idea" for a missing feature, "question" for something unclear. The Checkbox team reads every message.',
+    description: 'Bug, idea or question: what you tried, happened, expected. type review: only after the human said yes and saw the text; about Checkbox, not the site: no site names, URLs, quotes, secrets, customer data or claims the site broke a law. score 0-10 (would recommend); ≤5 phrases in liked, disliked, wrong_verdicts ("check.id: why wrong"); stack e.g. "Next.js + Stripe".',
     input: {
-        type: z.enum(['bug', 'idea', 'question']).optional().describe('bug, idea or question (default idea).'),
-        message: z.string().min(1).max(5000).describe('What you tried, what happened, what you expected.'),
-        site: z.string().max(200).optional().describe('Site id it is about (optional).'),
-        request_id: z.string().max(200).optional().describe('Request-Id of the API call it is about (optional).'),
-        tool: z.string().max(200).optional().describe('The tool or command involved (optional).'),
+        type: z.enum(['bug', 'idea', 'question', 'review']).optional(),
+        message: z.string().optional(),
+        score: z.number().int().min(0).max(10).optional(),
+        liked: z.array(z.string()).optional(),
+        disliked: z.array(z.string()).optional(),
+        wrong_verdicts: z.array(z.string()).optional(),
+        would_keep_using: z.boolean().optional(),
+        stack: z.string().optional(),
+        site: z.string().optional(),
+        request_id: z.string().optional(),
+        tool: z.string().optional(),
     },
     scopes: ['account:read'],
     annotations: { ...write(false, false), title: 'Send feedback' },
     async run(args, ctx) {
         const context = {};
-        for (const k of ['site', 'request_id', 'tool'])
+        // Reviews are about Checkbox, not the merchant's site: no site or request id is attached to them.
+        for (const k of args.type === 'review' ? ['tool'] : ['site', 'request_id', 'tool'])
             if (typeof args[k] === 'string' && args[k])
                 context[k] = String(args[k]);
         const agent = ctx.key.appName ?? ctx.clientName;
         if (agent)
             context.agent = String(agent).slice(0, 100);
-        const fb = await ctx.api.request('POST', '/v1/feedback', { body: { ...(args.type ? { type: args.type } : {}), message: args.message, ...(Object.keys(context).length ? { context } : {}) } });
+        if (args.type !== 'review' && !(typeof args.message === 'string' && args.message.trim()))
+            throw new ToolError('Write a message (what you tried, what happened, what you expected).');
+        if (args.type === 'review' && typeof args.score !== 'number')
+            throw new ToolError('A review needs score (0-10). Ask the human; never guess it.');
+        const body = { ...pick(args, ['type', 'message', 'score', 'liked', 'disliked', 'wrong_verdicts', 'would_keep_using', 'stack']), ...(Object.keys(context).length ? { context } : {}) };
+        const fb = await ctx.api.request('POST', '/v1/feedback', { body });
         return {
-            headline: `Feedback ${fb.id} sent to the Checkbox team (${fb.status}).`,
+            headline: `${args.type === 'review' ? 'Review' : 'Feedback'} ${fb.id} sent to the Checkbox team (${fb.status}).${fb.redacted ? ' Some text looked like a secret, card number or email address and was replaced with [redacted].' : ''}`,
             data: fb,
             next: { type: 'none', message: 'Nothing else to do; the team replies by email to the account owner when needed.' },
         };
     },
 };
+const LAW_CHANGES_SHOWN = 10;
+/**
+ * Agent audit round 2: list_law_updates with limit 3 printed 62 KB (one catalog update carried 195 requirement changes,
+ * each with its full summary). Each update keeps its first changes in short form, with the total.
+ */
+export function lawUpdateItem(u) {
+    const changes = Array.isArray(u.changes) ? u.changes : [];
+    const { changes: _c, ...rest } = u;
+    return {
+        ...rest,
+        changes: changes.slice(0, LAW_CHANGES_SHOWN).map((c) => pick(c, ['requirement_id', 'change', 'citation', 'title', 'effective_date'])),
+        ...(changes.length > LAW_CHANGES_SHOWN ? { changes_total: changes.length } : {}),
+    };
+}
 const listLawUpdates = {
     name: 'list_law_updates',
     title: 'List law updates and their impact',
@@ -1069,17 +1895,21 @@ const listLawUpdates = {
         return {
             headline: `${list.data.length}${list.has_more ? '+' : ''} law update(s).`,
             notes: list.data.map((u) => `${u.date} ${u.id} (${(u.jurisdictions ?? []).join(', ')}): ${u.summary}${u.impacts?.length ? ` — affects ${u.impacts.length} site(s)` : ''}`),
-            data: list,
+            data: { ...list, data: list.data.map(lawUpdateItem) },
         };
     },
 };
 function toDisclosureTerms(t) {
-    const out = pick(t, ['merchant_name', 'amount', 'currency', 'interval', 'interval_count', 'trial_days', 'cancel_url', 'cancel_timing']);
+    const out = pick(t, ['merchant_name', 'amount', 'currency', 'interval', 'interval_count', 'trial_days', 'intro_percent_off', 'intro_periods', 'cancel_url', 'cancel_timing']);
+    if (out.merchant_name === undefined && typeof t.brand_name === 'string')
+        out.merchant_name = t.brand_name;
     if (out.amount === undefined && t.price !== undefined) {
         const n = typeof t.price === 'number' ? t.price : Number(String(t.price).replace(/[^0-9.]/g, ''));
         if (Number.isFinite(n) && n > 0)
             out.amount = Math.round(n * 100);
     }
+    if (typeof t.intro_price === 'number' && t.intro_price >= 0)
+        out.intro_amount = Math.round(t.intro_price * 100);
     return out;
 }
 function reactSnippet(d) {
@@ -1100,7 +1930,7 @@ function reactSnippet(d) {
 const elementsInstallNotes = [
     'Put script_tag in <head>; put element_html inside the sign-up form directly ABOVE the pay button. It keeps the button disabled until the shopper ticks the (unchecked, required) box.',
     'Your server receives checkbox_consent_id (cons_…) with the form: store it with the subscription (e.g. Stripe metadata.checkbox_consent).',
-    'Do not restyle it below body size or hide it; guard rails restore compliant styles and report violations.',
+    'Do not restyle it below body size or hide it; guard rails restore the required styles and report what they found.',
 ];
 const elementsTermsShape = {
     merchant_name: planTermsShape.merchant_name,
@@ -1115,29 +1945,30 @@ const elementsTermsShape = {
 };
 const getCompliantDisclosure = {
     name: 'get_compliant_disclosure',
-    title: 'Generate a compliant disclosure for given terms',
+    title: 'Generate a disclosure that passes the checks for given terms',
     description: [
         'Generates the locked, engine-verified automatic-renewal disclosure for a plan: disclosure_text, consent_label (for an unchecked, required checkbox), button_text and drop-in html. The same wording Checkbox Elements and Fixes use.',
-        'Give the terms: price (major units) or amount (minor), interval, trial_days, cancel_url, merchant_name. Example: {"merchant_name":"Acme","price":19.99,"interval":"month","trial_days":14,"cancel_url":"https://acme.example/account/cancel"}.',
+        'Give the terms: price (major units) or amount (minor), interval, trial_days, cancel_url, merchant_name, promo (intro_price or intro_percent_off, intro_periods). Example: {"merchant_name":"Acme","price":19.99,"interval":"month","trial_days":14,"cancel_url":"https://acme.example/account/cancel"}.',
         'With site (and a key allowed to create disclosures), it also returns the Checkbox Elements snippet (script tag + <checkbox-disclosure> element + React usage) that records each consent as evidence.',
     ].join('\n'),
-    input: { ...elementsTermsShape, interval: z.enum(['day', 'week', 'month', 'year']).describe('Billing interval.'), site: z.string().max(100).optional().describe('Site id (site_…) to also get the Elements snippet for.'), jurisdictions: jurisdictions.optional() },
+    // Round 15 (P4): a promo (intro price) is stated with how long it lasts.
+    input: { ...elementsTermsShape, brand_name: planTermsShape.brand_name, intro_price: planTermsShape.intro_price, intro_percent_off: planTermsShape.intro_percent_off, intro_periods: planTermsShape.intro_periods, interval: z.enum(['day', 'week', 'month', 'year']).describe('Billing interval.'), site: z.string().max(100).optional().describe('Site id (site_…) to also get the Elements snippet for.'), jurisdictions: jurisdictions.optional() },
     scopes: ['checks:read'],
-    annotations: { ...ro, readOnlyHint: false, title: 'Compliant disclosure' },
+    annotations: { ...ro, readOnlyHint: false, title: 'Disclosure that passes the checks' },
     async run(args, { api, key }) {
         if (typeof args.site === 'string' && args.site && keyAllows(key, 'consents:write')) {
             const d = await api.request('POST', '/v1/disclosures', { body: { site: args.site, terms: toDisclosureTerms(args) } });
             return {
-                headline: `Compliant disclosure ${d.id}${d.verification?.passes === undefined ? '' : d.verification.passes ? ' (passes the sign-up checks on your checkout)' : ' (see verification: not every check passes yet)'}.`,
+                headline: `Disclosure ${d.id}${d.verification?.passes === undefined ? '' : d.verification.passes ? ' (passes the sign-up checks on your checkout)' : ' (see verification: not every check passes yet)'}.`,
                 notes: [`Disclosure: ${d.text}`, `Consent label: ${d.consent_label}`, ...elementsInstallNotes],
                 data: { ...d, react: reactSnippet(d) },
             };
         }
         // No site: generate from the terms with the stateless check (the replacement does not depend on the text checked).
-        const body = { text: '(no disclosure yet)', ...pick(args, ['merchant_name', 'plan_name', 'price', 'amount', 'currency', 'interval', 'interval_count', 'trial_days', 'cancel_url', 'cancel_timing', 'jurisdictions']) };
+        const body = { text: '(no disclosure yet)', ...pick(args, ['merchant_name', 'brand_name', 'plan_name', 'price', 'amount', 'currency', 'interval', 'interval_count', 'trial_days', 'intro_price', 'intro_percent_off', 'intro_periods', 'cancel_url', 'cancel_timing', 'jurisdictions']) };
         const r = await api.request('POST', '/v1/checks/disclosure', { body });
         return {
-            headline: `Compliant disclosure generated (engine-verified: ${r.replacement.verified}).`,
+            headline: `Suggested disclosure generated (${r.replacement.verified ? 'passes the checks, verified by the rules engine' : 'not fully verified by the rules engine'}).`,
             notes: [
                 `Disclosure: ${r.replacement.disclosure_text}`,
                 `Consent label: ${r.replacement.consent_label}`,
@@ -1154,7 +1985,7 @@ const getElementsSnippet = {
     title: 'Get the Checkbox Elements snippet for a site',
     description: [
         'Returns paste-ready Checkbox Elements markup for a site: the pinned <script> tag (with SRI) for <head>, the <checkbox-disclosure> element for directly above the pay button, the publishable key, and a React usage example.',
-        'The element renders the locked compliant disclosure with an unchecked, required consent checkbox, gates the pay button, and records each consent (cons_…) in the evidence vault. Terms come from the site\'s billing connection unless you pass them.',
+        'The element renders the locked disclosure (it passes the checks) with an unchecked, required consent checkbox, gates the pay button, and records each consent (cons_…) in the evidence vault. Terms come from the site\'s billing connection unless you pass them.',
         'This creates a disclosure record (write, safe to repeat). Consents themselves are recorded by the browser, never by agents.',
     ].join('\n'),
     input: { site: requiredSite, plan: z.string().max(200).optional().describe('Billing price / plan id (price_…) when the site has several.'), ...elementsTermsShape },
@@ -1259,7 +2090,7 @@ const listDueNotices = {
     annotations: { ...ro, title: 'Due notices' },
     async run(args, { api }) {
         const list = await api.request('GET', '/v1/notices/due', {
-            query: pick(args, ['site', 'status', 'kind', 'subscription', 'limit', 'starting_after']),
+            query: { ...pick(args, ['site', 'status', 'kind', 'subscription', 'limit', 'starting_after']), ...(typeof args.kind === 'string' ? { kind: args.kind.split(',').map((k) => noticeKind(k.trim())).join(',') } : {}) },
         });
         const overdue = list.data.filter((d) => d.status === 'overdue').length;
         return {
@@ -1304,7 +2135,7 @@ const getNoticeTemplates = {
         site: z.string().max(100).optional().describe('Site (site_…): adds BCC addresses; required with check.'),
         check: z
             .object({
-            kind: z.enum(['acknowledgment', 'trial_ending', 'renewal_reminder', 'annual_terms', 'price_change', 'cancellation_confirmation']).describe('Notice kind.'),
+            kind: emailKind.describe('Notice kind.'),
             subject: z.string().max(1000).describe('Subject (merge fields allowed).'),
             text: z.string().max(100_000).optional().describe('Plain-text body.'),
             html: z.string().max(100_000).optional().describe('HTML body.'),
@@ -1320,7 +2151,7 @@ const getNoticeTemplates = {
             if (!args.site)
                 throw new Error('site is required to check a template (its plan and jurisdictions scope the check).');
             const r = await api.request('POST', '/v1/notices/templates/check', {
-                body: { site: args.site, ...check },
+                body: { site: args.site, ...check, kind: noticeKind(check.kind) },
             });
             return {
                 headline: `Template check: ${r.verdict.toUpperCase()}.`,
@@ -1343,8 +2174,9 @@ const callApi = {
     name: 'call_api',
     title: 'Call any Checkbox API endpoint',
     description: [
-        'For a next_action whose operation has no dedicated tool (e.g. createTestCredential, createStripeCheckoutConfig, checkDomainVerification, updateTask, updateSite, listConsents). Calls the Checkbox /v1 API with this server\'s key; paths and bodies are in https://app.checkbox.site/v1/openapi.json.',
-        'Examples: {"method":"POST","path":"/v1/sites/site_123/test_credentials","body":{"type":"stripe_test","secret_key":"rk_test_…"}} ; {"method":"GET","path":"/v1/account"}.',
+        'For a next_action whose operation has no dedicated tool (e.g. createStripeCheckoutConfig, updateTask, updateNoticeSettings, listConsents). Calls the Checkbox /v1 API with this server\'s connection; paths and bodies are in https://app.checkbox.site/v1/openapi.json.',
+        'Examples: {"method":"GET","path":"/v1/account"} ; {"method":"POST","path":"/v1/sites/site_123/domain_verification/check"}.',
+        'Never send API keys or Stripe keys through it: keys are added by the human in the Checkbox dashboard, never pasted into the chat.',
         'GET is read-only. POST/DELETE change data: only do what the user or a next_action asked for. DELETE archives or removes objects — confirm with the user first.',
     ].join('\n'),
     input: {
@@ -1369,10 +2201,74 @@ const callApi = {
     },
 };
 /** Every tool, in the order clients list them. */
+/**
+ * Round 12 (pilot 11, nextjs + agent users): setup_checkbox dropped unknown fields silently; the homepage prompt says
+ * "brand", the schema says merchant_name, so the site was named "localhost" with no warning. Common spellings of the
+ * brand are read as merchant_name; any other unknown field is listed back as ignored.
+ */
+export const SETUP_FIELD_ALIASES = Object.freeze({ brand: 'merchant_name', brand_name: 'merchant_name', business_name: 'merchant_name', company_name: 'merchant_name', platform: 'billing_platform' });
+const BILLING_PLATFORMS = new Set(['stripe', 'shopify', 'recharge', 'chargebee', 'recurly', 'paddle', 'woocommerce', 'custom']);
+export function normalizeSetupArgs(raw, known) {
+    const args = {};
+    const aliased = [];
+    const ignored = [];
+    for (const [k, v] of Object.entries(raw))
+        if (known.has(k))
+            args[k] = v;
+    for (const [k, v] of Object.entries(raw)) {
+        if (known.has(k))
+            continue;
+        const to = SETUP_FIELD_ALIASES[k];
+        const ok = typeof v === 'string' && !!v.trim() && (to !== 'billing_platform' || BILLING_PLATFORMS.has(v.trim().toLowerCase()));
+        if (to && known.has(to) && ok && args[to] === undefined) {
+            args[to] = to === 'billing_platform' ? v.trim().toLowerCase() : v.trim().slice(0, 100);
+            aliased.push(`${k} (read as ${to})`);
+        }
+        else
+            ignored.push(k);
+    }
+    return { args, aliased, ignored };
+}
+/** Messages of the API's `warnings` ({ code, message }) on a setup result (or its session). */
+export function apiWarningMessages(data) {
+    if (!data || typeof data !== 'object')
+        return [];
+    const d = data;
+    const list = Array.isArray(d.warnings) ? d.warnings : Array.isArray(d.session?.warnings) ? d.session.warnings : [];
+    return list.flatMap((w) => (w && typeof w === 'object' && typeof w.message === 'string' ? [`Warning: ${w.message}`] : []));
+}
+function acceptingSetupAliases(def) {
+    const known = new Set(Object.keys(def.input));
+    return {
+        ...def,
+        passthrough: true,
+        async run(raw, ctx) {
+            const { args, aliased, ignored } = normalizeSetupArgs(raw, known);
+            // Round 18 (item 19, pilot 17): update_setup refuses unknown top-level fields, as it refuses unknown nested ones
+            // (an ignored field read as "saved" to the agent).
+            if (ignored.length && def.name === 'update_setup') {
+                throw new ToolError(unknownArgumentsMessage(def.name, ignored, [...known]), { type: 'fix_request', message: 'Rename or remove those fields and call update_setup again.' });
+            }
+            const out = await def.run(args, ctx);
+            // Pilot round 13: the API's input warnings (plan amounts that look like dollars, or differ from the Stripe Price)
+            // are shown, and kept next to the field warnings below.
+            const apiWarnings = apiWarningMessages(out.data);
+            if (!aliased.length && !ignored.length && !apiWarnings.length)
+                return out;
+            const warnings = [
+                ...apiWarnings,
+                ...(aliased.length ? [`Read ${aliased.join(', ')}.`] : []),
+                ...(ignored.length ? [`Ignored unknown field${ignored.length === 1 ? '' : 's'}: ${ignored.join(', ')}. ${def.name} accepts: ${[...known].filter((k) => k !== 'device_code').join(', ')}.`] : []),
+            ];
+            const data = out.data && typeof out.data === 'object' && !Array.isArray(out.data) ? { ...out.data, warnings } : out.data;
+            return { ...out, notes: [...warnings, ...(out.notes ?? [])], data };
+        },
+    };
+}
 export const TOOLS = [
-    setupCheckbox,
+    acceptingSetupAliases(setupCheckbox),
     getSetupStatus,
-    updateSetup,
+    acceptingSetupAliases(updateSetup),
     completeSetup,
     getCompliancePlan,
     getTask,
@@ -1387,12 +2283,14 @@ export const TOOLS = [
     checkEmail,
     checkPageHtml,
     getNoticeSchedule,
+    suggestImprovements,
     listSites,
     createSite,
     updateSite,
     getSiteStatus,
     listFindings,
     getFinding,
+    publishShopifyTerms,
     runScan,
     getScan,
     listLawUpdates,
@@ -1413,9 +2311,9 @@ export const TOOL_OPERATIONS = {
     update_setup: ['updateSetupSession'],
     update_site: ['updateSite'],
     complete_setup: ['completeSetupSession'],
-    get_compliance_plan: ['retrieveCompliancePlan'],
+    get_compliance_plan: ['retrieveCompliancePlan', 'claimReviewPrompt'],
     get_task: ['retrieveTask'],
-    verify_task: ['verifyTask'],
+    verify_task: ['verifyTask', 'claimReviewPrompt'],
     answer_task: ['answerTask'],
     verify_site: ['verifySite'],
     get_verification: ['retrieveVerification'],
@@ -1426,11 +2324,13 @@ export const TOOL_OPERATIONS = {
     check_email: ['checkEmail'],
     check_page_html: ['checkPage'],
     get_notice_schedule: ['checkNoticeSchedule'],
+    suggest_improvements: ['listSiteSuggestions', 'suggestImprovements'],
     list_sites: ['listSites'],
     create_site: ['createSite'],
     get_site_status: ['retrieveSite', 'retrieveLatestEvaluation', 'listFindings'],
     list_findings: ['listFindings'],
     get_finding: ['retrieveFinding', 'retrieveFindingFix'],
+    publish_shopify_terms: ['publishShopifyTerms'],
     run_scan: ['createScan'],
     get_scan: ['retrieveScan'],
     list_law_updates: ['listLawUpdates'],