@reddoorla/maintenance 0.85.2 → 0.87.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { a as AuditResult, S as Site, A as AuditName, b as RecipeResult, R as RecipeName, I as InventoryProvider } from './types-OIQZ5hWN.js';
 export { C as ConfigName } from './types-OIQZ5hWN.js';
-import * as airtable_lib_airtable_base_js from 'airtable/lib/airtable_base.js';
+import { A as AirtableBase, a as FleetEventType } from './fleet-events-cF2Om88w.js';
 import { F as FormType } from './types-RXY-vY-5.js';
 export { SyncConfigsOptions, syncConfigs } from './recipes/sync-configs.js';
+import 'airtable/lib/airtable_base.js';
 
 type SpawnResult = {
     code: number;
@@ -119,7 +120,15 @@ type FormSubmitOutcome = {
     formPresent: true;
     success: boolean;
     detail?: string;
+    /** Click → success banner VISIBLE. A user-experience number: it includes the
+     *  browser's own render of the banner, which no server budget governs. */
     elapsedMs?: number;
+    /** Click → the action's POST response arrives. This is the span the site's
+     *  `INGEST_TIMEOUT_MS` abort budget actually governs (it wraps the
+     *  site→central fetch, which is nested inside this POST), so it — not
+     *  `elapsedMs` — is what the budget check must compare against. Undefined
+     *  when no POST was observed. */
+    postElapsedMs?: number;
 } | {
     testModeUndeclared: true;
 };
@@ -388,13 +397,6 @@ declare function localPath(path: string, opts?: LocalPathOptions): InventoryProv
 
 declare function fromJsonFile(path: string): InventoryProvider;
 
-type AirtableConfig = {
-    apiKey: string;
-    baseId: string;
-};
-type AirtableBase = ReturnType<typeof openBase>;
-declare function openBase(cfg: AirtableConfig): airtable_lib_airtable_base_js.AirtableBase;
-
 type AirtableInventoryOptions = {
     /**
      * Local workdir to compute each site's path as `{workdir}/{slug}`.
@@ -407,21 +409,105 @@ type AirtableInventoryOptions = {
  * Read sites from the Airtable Websites table as an InventoryProvider.
  * Each row becomes one Site; `path` is computed as `{workdir}/{slug}`.
  * Only LIVE `maintenance` sites that have a `url` are included — pre-launch
- * stages ("launch period" / "in development", via isPreLaunch) are excluded so a
+ * stages ("launching" / "building", via isPreLaunch) are excluded so a
  * not-yet-live site is never audited as production (its deploy/domain/uptime/CMS
  * audits would fail against nothing and red its Airtable row) nor swept by other
  * `--fleet airtable` ops; it re-enters the fleet when a Launch report flips its
- * Status to "maintenance". The production URL is exposed as `Site.deployedUrl` so
+ * Status to "maintained". The production URL is exposed as `Site.deployedUrl` so
  * the lighthouse audit can run against it with no checkout. `repoUrl` is
  * intentionally NOT set from `url` — a clone source must come from `gitRepo`
  * (`owner/repo`), never the production URL.
  */
 declare function fromAirtableBase(base: AirtableBase, opts?: AirtableInventoryOptions): InventoryProvider;
 
+/**
+ * The site-status vocabulary — ONE module owns it (#539 Phase 4).
+ *
+ * The fleet's lifecycle names were inherited from an Airtable single-select
+ * written by hand years ago ("probably not our problem"). The operator approved
+ * a canonical vocabulary, and the migration is now COMPLETE in both stores:
+ * Airtable's "Status" single-select carries exactly the six canonical options
+ * and nothing else. This module no longer knows the old names at all.
+ *
+ * The retired mapping, kept as the record of what was merged into what:
+ *
+ *   old (retired 2026-08-25)    new (canonical)
+ *   ─────────────────────────   ───────────────
+ *   in development              building
+ *   launch period               launching
+ *   maintenance                 maintained
+ *   hosting                     hosted-only
+ *   probably not our problem    external
+ *   legacy                    ┐
+ *   deprecated                ┴ archived        ← approved MERGE, many-to-one
+ *
+ * `legacy` and `deprecated` were already treated identically by every PREDICATE
+ * (ARCHIVED_STATUSES held both), so collapsing them changes no *selection* — no
+ * fleet op gains or loses a site. It is NOT true that collapsing them changes
+ * nothing at all, and one surface proved it: the cockpit's Archived lane LABELS
+ * each row with its Status cell, and canonicalizing there rendered all 12 live
+ * archived rows as "archived". That lane now labels from `statusRaw`, which is
+ * exactly why `WebsiteRow.statusRaw` exists. The rule this leaves behind:
+ * canonical values decide BEHAVIOUR; anything DISPLAYING a Status cell, or
+ * writing one back, uses the raw cell.
+ *
+ * The merge had NO clean reverse map while both vocabularies coexisted, which
+ * is why `toAirtableStatus` had to pick one archived name deliberately. With the
+ * old names retired there is nothing left to pick between, and no code path
+ * feeds operator-supplied text through it anyway (see
+ * `src/recipes/forms-notify-target.ts`, which writes `--restore` verbatim).
+ *
+ * THE SHAPE OF THE TRANSITION (three stages):
+ *
+ *   stage 1 (DONE)  code speaks the NEW vocabulary internally; reads canonicalize
+ *                   at the two Airtable/Turso seams; writes still emit the OLD
+ *                   Airtable option names. Airtable untouched. No SELECTION
+ *                   change — every predicate picks exactly the sites it picked
+ *                   before (pinned row-by-row in tests/reports/airtable/
+ *                   site-status.test.ts). Displayed labels come from `statusRaw`.
+ *   stage 2 (DONE)  the Airtable "Status" single-select gained the 6 new options
+ *                   and all 44 cells were migrated (verified live: maintained=13,
+ *                   archived=12, external=9, building=6, hosted-only=2,
+ *                   launching=2 — zero old values, zero unrecognized), `db sync`
+ *                   ran clean (mismatches=0), and AIRTABLE_USES_NEW_VOCABULARY
+ *                   flipped to true. Writers now emit canonical names verbatim.
+ *                   The alias map STAYS: the 7 old options still exist in the
+ *                   field, so a human can still pick one in the Airtable UI.
+ *   stage 3 (DONE)  the operator deleted the 7 old options from the Airtable
+ *                   "Status" field on 2026-08-25, which is what made this safe:
+ *                   the gate was always "no old value CAN BE ENTERED", not
+ *                   merely "none is stored". Verified against the live base
+ *                   before any code changed — the field carries exactly the six
+ *                   canonical choices, byte-exact, and all 44 cells still hold a
+ *                   canonical value with ZERO blanks (deleting a single-select
+ *                   option CLEARS the cells using it, so "no cell was blanked"
+ *                   was checked, not assumed). AIRTABLE_STATUS_ALIASES,
+ *                   AIRTABLE_OLD_NAMES and AIRTABLE_USES_NEW_VOCABULARY are
+ *                   gone; both functions reduce to the identity.
+ *
+ * WHAT CHANGED IN BEHAVIOUR AT STAGE 3, and it is the only thing that did: an
+ * old name is no longer translated. `canonicalizeStatus("maintenance")` used to
+ * yield `maintained`; it now yields `"maintenance"` verbatim, which
+ * `isUnrecognizedStatus` flags and the cockpit surfaces as a watch row. That is
+ * intended. The option cannot be selected any more, so a stored old value would
+ * mean something went wrong — a restored backup, a scripted write, an API
+ * caller with a stale constant — and the fleet should say so rather than absorb
+ * it into a status nobody chose.
+ *
+ * Canonicalization happens on READ, never at rest: `src/db/import-airtable.ts`
+ * still stores the raw Airtable cell verbatim in `sites.status`, so the hourly
+ * parity check keeps comparing raw-to-raw and the importer stays honest to its
+ * source. Both readers — `mapRow` (Airtable) and `rowFromJoined` (Turso) — run
+ * the raw value through `canonicalizeStatus`, which is what keeps the #558
+ * reader-equivalence instrument green.
+ */
+/** The canonical site lifecycle vocabulary. */
+type Status = "building" | "launching" | "maintained" | "hosted-only" | "external" | "archived";
+
 type Frequency = "None" | "Monthly" | "Quarterly" | "Yearly";
-type Status = "in development" | "launch period" | "maintenance" | "hosting" | "probably not our problem" | "deprecated" | "legacy";
+
 /**
- * Per-site notification routing. When present on a `maintenance` site, the form
+ * Per-site notification routing. When present on a `maintained` site, the form
  * notification is addressed by the value of a submission field (`field`, read from
  * `extraFields`) — e.g. route a contact form's `interest` to a different recipient
  * per option, always CC-ing a shared address. Absent (`null`) → the site keeps the
@@ -443,7 +529,17 @@ type WebsiteRow = {
     id: string;
     name: string;
     url: string;
+    /** Canonical lifecycle status (see ./site-status.ts). Canonicalized at the read
+     *  boundary, so an old-vocabulary Airtable cell and a new one read identically.
+     *  A present-but-unrecognized cell survives VERBATIM (blind-cast) rather than
+     *  becoming null — `isUnrecognizedStatus` flags it, and null would make
+     *  due.ts/preflight.ts treat the row as eligible-by-default. */
     status: Status | null;
+    /** The literal Airtable Status cell behind `status` — same pattern as
+     *  `maintenanceFreqRaw`. The dashboard status editor round-trips THIS, so its
+     *  dropdown offers and preselects the values Airtable actually holds while the
+     *  two vocabularies coexist. Null = blank cell. */
+    statusRaw: string | null;
     pointOfContact: string | null;
     maintenanceFreq: Frequency;
     testingFreq: Frequency;
@@ -670,6 +766,18 @@ type WebsiteRow = {
      */
     prismicAckUntil: string | null;
     notifyRouting: NotifyRouting | null;
+    /** The RAW `Notify Routing` cell, verbatim. Same reason `statusRaw` exists: the
+     *  dashboard editor round-trips this JSON, and re-serializing the PARSED object
+     *  would drop any key the parser ignores and reformat what the operator typed —
+     *  a silent rewrite of a cell they only opened to look at. */
+    notifyRoutingRaw: string | null;
+    /** Read-back of the code-owned next-due dates (date-only, written by the
+     *  nightly `writeNextDueDates`). These exist so the writer can DIFF the
+     *  freshly-computed dates against what the row already holds and skip the
+     *  ~31 no-op writes a night the fleet was paying for (#539 Phase 3). Null =
+     *  cell blank or the operator-added `Next … at` column absent. */
+    nextMaintenanceAt: string | null;
+    nextTestingAt: string | null;
 };
 /** The `Prismic Models` cell — see {@link WebsiteRow.prismicModels} for why it
  *  carries a third state that no other verdict column in this table has. */
@@ -844,6 +952,135 @@ type ReportRow = {
     overrideBy: string | null;
     overrideAt: string | null;
 };
+/** Called with the record Airtable echoed back from the create, before it is
+ *  mapped (#539 Phase 5). Structurally typed rather than importing the db
+ *  layer's `RawRecord`, so this module stays the leaf it has always been. */
+type CreatedDraftMirror = (rec: {
+    id: string;
+    fields: Record<string, unknown>;
+}) => Promise<void>;
+
+/** Report rows (migration 0007). PK = Airtable rec id. `checklist` is JSON
+ *  keyed by the STABLE checklist key (src/reports/checklist.ts), not the
+ *  Airtable column name; `rendered_html` is the downloaded attachment body. */
+interface ReportsTable {
+    id: string;
+    site_id: string | null;
+    report_id: string | null;
+    report_type: string | null;
+    period: string | null;
+    period_start: string | null;
+    period_end: string | null;
+    completed_on: string | null;
+    lighthouse_performance: number | null;
+    lighthouse_accessibility: number | null;
+    lighthouse_best_practices: number | null;
+    lighthouse_seo: number | null;
+    ga_users_current: number | null;
+    ga_users_previous: number | null;
+    search_found_page1: number | null;
+    search_position: number | null;
+    last_tested_date: string | null;
+    commentary: string | null;
+    subject_override: string | null;
+    draft_ready: number;
+    approved_to_send: number;
+    approved_at: string | null;
+    approved_by: string | null;
+    send_override: number;
+    override_reason: string | null;
+    override_by: string | null;
+    override_at: string | null;
+    sent_at: string | null;
+    delivery_status: string | null;
+    resend_message_id: string | null;
+    checklist: string | null;
+    checklist_auto_evidence: string | null;
+    rendered_html: string | null;
+}
+
+/** Columns a report writer mirrors after its Airtable write (same pattern as
+ *  mirrorSiteField): the approve/override flow, the resend-webhook's delivery
+ *  status, and — since #539 Phase 5 — the drafting path's queue flag and a
+ *  re-run's refreshed scores.
+ *
+ *  `rendered_html` stays deliberately OUT even though the drafting path now
+ *  writes it: bodies go through `storeRenderedHtml`, so a request handler
+ *  holding a patch cannot accidentally write megabytes of HTML. `sent_at` and
+ *  `resend_message_id` stay out because nothing but the send batch writes them
+ *  and the hourly sync converges those. */
+type ReportMirrorPatch = Partial<Pick<ReportsTable, "approved_to_send" | "approved_at" | "approved_by" | "send_override" | "override_reason" | "override_by" | "override_at" | "delivery_status" | "commentary" | "draft_ready" | "lighthouse_performance" | "lighthouse_accessibility" | "lighthouse_best_practices" | "lighthouse_seo" | "ga_users_current" | "ga_users_previous" | "search_found_page1" | "search_position" | "completed_on">>;
+
+/** #539 Phase 5: the Turso write-through for the Reports write surface.
+ *
+ *  Before this, the only report mirrors were UPDATEs on the request path
+ *  (approve, override, delivery status, commentary). Everything the DRAFTING
+ *  path writes — the row itself, the rendered body, the queue flag, a re-run's
+ *  refreshed scores — reached Turso only via the hourly sync. Two of those are
+ *  visible to the operator today: a fresh draft's row does not exist, and its
+ *  preview route answers "No rendered body stored" for up to an hour. At the
+ *  freeze they stop being windows.
+ *
+ *  Deliberately UNLIKE `makeHealthMirrorBestEffort`, this never returns null.
+ *  #585 is the reason: Phase 3's next-due mirror silently no-opped in production
+ *  for weeks because the factory returned null without creds, and a dead
+ *  dual-write then looked exactly like a healthy one — the only tell was an
+ *  ABSENT log suffix nobody was watching for. Here creds-absent is a state the
+ *  mirror REPORTS, so every write emits one REPORT_MIRROR line and an absent
+ *  line means the wiring is gone, not that conditions were quiet.
+ */
+
+/** The three shapes a report write takes. Injected as ONE object rather than
+ *  three parameters because they share a db handle and always travel together:
+ *  a caller holding `created` but not `body` produces exactly the half-mirrored
+ *  state (row present, preview 404) this module exists to prevent. */
+type ReportMirror = {
+    /** A row Airtable just CREATED, as Airtable echoed it back. */
+    created: CreatedDraftMirror;
+    /** A freshly rendered body for an existing row. */
+    body: (reportId: string, html: string) => Promise<void>;
+    /** Columns just written to an existing row. */
+    patch: (reportId: string, patch: ReportMirrorPatch) => Promise<void>;
+};
+
+/** #539 Phase 5: the Turso write-through for the ONE-OFF Websites writers.
+ *
+ *  Phase 3 mirrored the nightly sweep — the audit write-back, github-signals and
+ *  the next-due dates. It did not touch the writers that run on their own
+ *  schedule or on demand: the analytics soft-fail stamp, the Renovate
+ *  auto-fix counter, the prismic-models verdict, `updateLaunched`, the
+ *  forms notify target, and the SINGLE-SITE audit write-back (only the fleet
+ *  path ever passed a mirror). Each of those reached Turso solely via the hourly
+ *  sync, which stops existing at the freeze.
+ *
+ *  It lives in `src/db` rather than a feature folder because its callers span
+ *  audits, recipes, CLI commands and the send path — no one feature owns it.
+ *
+ *  Deliberately UNLIKE `makeHealthMirrorBestEffort`, this never returns null.
+ *  #585 is the reason: that factory returned null without creds and the
+ *  dual-write silently no-opped in production for weeks, because a dead mirror
+ *  and a healthy one produced identical output — the only tell was an ABSENT log
+ *  suffix nobody was watching for. Here creds-absent is a state the mirror
+ *  REPORTS, so a missing SITE_MIRROR line means the wiring is gone.
+ */
+
+/** Two ops because the Websites row is split across two Turso tables. Callers
+ *  pass the EXACT FieldSet the Airtable writer returned, so the mirror can never
+ *  carry a different payload than the write it shadows. */
+type SiteMirror = {
+    /** A row Airtable just CREATED, as Airtable echoed it back (`ensure-site`).
+     *  Every other op is an UPDATE, which does nothing for a row that does not
+     *  exist yet — so without this a bootstrapped site is invisible to Turso and
+     *  every mirror the rest of the bootstrap fires reports `mirrored=missed`. */
+    created: (rec: {
+        id: string;
+        fields: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Columns that live in `site_health`. */
+    health: (siteId: string, fields: Record<string, unknown>) => Promise<void>;
+    /** Columns that live in `sites`. */
+    site: (siteId: string, fields: Record<string, unknown>) => Promise<void>;
+};
 
 type ShootOptions = {
     url: string;
@@ -884,7 +1121,9 @@ type RefreshHeaderDeps = {
         url: string;
         slug?: string;
     }) => Promise<GeneratedHeaderImage>;
-    upload?: (recordId: string, field: string, bytes: Uint8Array, filename: string, contentType: string) => Promise<void>;
+    upload?: (recordId: string, field: string, bytes: Uint8Array, filename: string, contentType: string, opts?: {
+        replaceIn?: string;
+    }) => Promise<void>;
 };
 type DraftOptions = {
     /** Where to write the local preview HTML when `previewOnly`. Defaults to `reports/<slug>/draft.html`. */
@@ -918,6 +1157,22 @@ type DraftOptions = {
      *  entirely. Tests set `false` (or a stub) so a unit suite never launches a
      *  browser or resolves DNS. Production leaves it unset and gets the real thing. */
     refreshHeader?: RefreshHeaderDeps | false;
+    /** #539 Phase 5: Turso write-through for everything this function writes to
+     *  Airtable — the created row, the rendered body, and the queue flag — so a
+     *  fresh draft is fully readable in the Turso-backed console immediately
+     *  instead of after the next hourly sync.
+     *
+     *  Deliberately NOT defaulted here. Defaulting would open a real libSQL handle
+     *  from inside `draftReportForSite`, which every unit test calls — and on a
+     *  machine with TURSO_* exported that means a test suite writing rows into
+     *  production. The wiring lives at the composition roots (cli/commands/report.ts,
+     *  recipes) where it is pinned by test, the same division `runFleetWriteBack`
+     *  uses for the health mirror. */
+    reportMirror?: ReportMirror;
+    /** #539 Phase 5: the Websites-row twin of `reportMirror`. Drafting stamps
+     *  `Analytics soft-fail at` on the SITE row, which is a different Turso table
+     *  and a different mirror. Injected for the same reason — see reportMirror. */
+    siteMirror?: SiteMirror;
 };
 /** An enrichment fetch that *errored* (not one that was legitimately skipped
  *  because it isn't configured / the site lacks the inputs). Surfaced so a
@@ -996,6 +1251,10 @@ type ResendClient = {
 
 type OrchestrateOptions = {
     resend?: ResendClient;
+    /** #539 Phase 5: Turso write-through for the Websites row a Launch send
+     *  updates. Injected rather than defaulted — this function is called directly
+     *  by tests, and a default would open a real libSQL handle inside the suite. */
+    siteMirror?: SiteMirror;
 };
 declare function sendApprovedReports(options?: OrchestrateOptions): Promise<{
     output: string;
@@ -1145,8 +1404,6 @@ type AttentionItem = {
     autoFixExhausted?: boolean;
 };
 
-type FleetEventType = "pr_automerged" | "vuln_cleared" | "ci_recovered" | "site_launched" | "fleet_swept" | "cert_renewed" | "report_sent_with_override";
-
 type Tier = "attention" | "watch" | "healthy" | "pre-launch";
 type SiteCard = {
     site: WebsiteRow;
@@ -1191,7 +1448,7 @@ type CockpitSummary = {
     attention: number;
     watch: number;
     healthy: number;
-    /** Count of pre-live "launch period" sites still muted as expected pre-launch
+    /** Count of pre-live "launching" sites still muted as expected pre-launch
      *  conditions. A piercing alarm (piercesPreLaunchMute) re-tiers such a site to
      *  attention, so it counts there instead — muted never means "hidden if broken". */
     preLaunch: number;
@@ -1221,7 +1478,15 @@ type RecentEntry = {
     ts: string;
 };
 /** A Websites row surfaced OUTSIDE the fleet cards: archived (legacy/deprecated)
- *  or holding an unrecognized Status cell. `status` is the raw cell value. */
+ *  or holding an unrecognized Status cell.
+ *
+ *  `status` is the RAW Airtable cell, not the canonical status (#539 Phase 4).
+ *  These two lanes exist to mirror what Airtable holds so a row can never
+ *  silently vanish, and both of them survive on the distinction the canonical
+ *  vocabulary erases: `legacy` and `deprecated` both canonicalize to `archived`,
+ *  so labelling the lane canonically would render 12 live rows identically and
+ *  disagree with the cell the operator is looking at. Everything else about
+ *  these rows — which lane they land in — is decided canonically. */
 type OffFleetSiteEntry = {
     name: string;
     slug: string;
@@ -1268,7 +1533,7 @@ type SiteAlarmContext = {
  * fetches data, then hands it here. Easier to unit-test, easier to render
  * a static preview from CLI later.
  */
-declare function renderSiteDashboardHtml(site: WebsiteRow, reports: ReportRow[], submissions?: SubmissionRow[], spamTotals?: ScreenOutTotals | null, now?: Date, alarm?: SiteAlarmContext | null): string;
+declare function renderSiteDashboardHtml(site: WebsiteRow, reports: ReportRow[], submissions?: SubmissionRow[], spamTotals?: ScreenOutTotals | null, now?: Date, alarm?: SiteAlarmContext | null, operatorEmail?: string | null): string;
 
 /**
  * Render the fleet cockpit as a single HTML document. Pure function: no Airtable
@@ -1277,7 +1542,7 @@ declare function renderSiteDashboardHtml(site: WebsiteRow, reports: ReportRow[],
  * and hands it here. Renders the doc shell + verdict bar + the per-site Needs-you
  * feed + the collapsed Fleet browse panel (one flat, filterable card grid).
  */
-declare function renderCockpitHtml(model: CockpitModel): string;
+declare function renderCockpitHtml(model: CockpitModel, operatorEmail?: string | null): string;
 
 /**
  * Verify an `Authorization: Basic <base64>` header against the configured
@@ -1300,7 +1565,45 @@ declare function renderCockpitHtml(model: CockpitModel): string;
  */
 declare function verifyBasicAuth(authHeader: string | null | undefined, expectedPassword: string | null): boolean;
 
-/** Read the bundled 2400x3200 plate. */
+/** Per-report-type headline overlays, stamped over the CLEAN plate at send time
+ *  (see orchestrate.ts). Types with no entry go out on the clean plate.
+ *
+ *  Source: Figma "Web-Maintenance-Email" (mQ3hy2d9JnOG9ljCzbZS8j) —
+ *  Maintenance is node 158:15, Testing is 153:721 ("maintenance & testing",
+ *  which is what a Testing report actually covers). Export each at 4x; Figma
+ *  crops a text export to its ink box, which is why these are 1328x660 /
+ *  1715x664 rather than the 1840x720 text box.
+ *
+ *  ⚠️ A Figma MCP `download_assets` export arrives FLATTENED — never
+ *  transparent — and it flattens onto WHATEVER SITS BEHIND THE NODE, which is
+ *  not one fixed colour: Maintenance/Testing live inside a white Header frame
+ *  and come back on white, while Announcement/Launch sit on the bare canvas and
+ *  come back on Figma's canvas grey (30,30,30). Stamping either unprocessed
+ *  paints a solid slab over the paper texture — that, not a bad design file, is
+ *  what made the 2026-08-20 Testing asset unusable.
+ *
+ *  Recover the alpha instead of re-exporting by hand: for ink C over backdrop B,
+ *  a = (px - B) / (C - B). DETECT B (the export's most common colour) rather
+ *  than assuming white, and pick the channel with the largest |C - B| — green
+ *  separates the brand red from white by 221 levels but from canvas grey by only
+ *  4, which would quantise the alpha to noise. Verified against the known-good
+ *  Maintenance asset at mean abs alpha diff 0.022, 0.0037% of pixels off by
+ *  more than 8.
+ *
+ *  Editing this copy needs Figma desktop, not the Plugin API: `characters`
+ *  requires loadFontAsync and the MCP font environment carries no Helvetica at
+ *  all, so the licensed Helvetica Neue LT Std can never load there. */
+declare const HEADLINE_FILES: {
+    readonly Maintenance: "headline-maintenance.png";
+    readonly Testing: "headline-testing.png";
+    readonly Announcement: "headline-announcement.png";
+    readonly Launch: "headline-launch.png";
+};
+type HeadlineKind = keyof typeof HEADLINE_FILES;
+/** Read the bundled 2400x3200 CLEAN plate (no headline — the report type's
+ *  headline is stamped at send time, so one stored image serves every type). */
 declare function loadPlate(): Promise<Uint8Array>;
+/** Read a headline overlay (transparent PNG, ink-box cropped). */
+declare function loadHeadline(kind: HeadlineKind): Promise<Uint8Array>;
 
-export { ALL_AUDIT_NAMES, ALL_RECIPE_NAMES, type AirtableInventoryOptions, AuditName, AuditResult, BLURRED_CID, type BumpDepsOptions, type BundledImage, CHECK_CID, type ConvertToPnpmOptions, DEFAULT_INIT_STEPS, type DraftOptions, type DraftResult, type DueItem, type GenerateInput, type GeneratedHeaderImage, type HeaderImage, type InitOptions, type InitResult, type InitStep, type InitStepResult, InventoryProvider, type LighthouseScores, type LocalPathOptions, type OnboardAudit, type OnboardOptions, type OrchestrateOptions, RecipeName, RecipeResult, type RefreshHeaderDeps, type RenderResult, type ReportData, type ReportType, Site, type UpgradeSvelte4to5Options, a11yAudit, a11yFixturesPage, bumpDeps, convertToPnpm, depsAudit, domainFromUrl, draftReportForSite, findDueReports, fromAirtableBase, fromJsonFile, generateHeaderImage, init, isRecipeName, lighthouseAudit, lintAudit, loadBundledImages, loadPlate, localPath, onboard, renderCockpitHtml, renderReportHtml, renderSiteDashboardHtml, runAudits, runAuditsAcross, securityAudit, selfCaretRange, selfPackageVersion, sendApprovedReports, svelteCodemods, upgradeSvelte4to5, verifyBasicAuth };
+export { ALL_AUDIT_NAMES, ALL_RECIPE_NAMES, type AirtableInventoryOptions, AuditName, AuditResult, BLURRED_CID, type BumpDepsOptions, type BundledImage, CHECK_CID, type ConvertToPnpmOptions, DEFAULT_INIT_STEPS, type DraftOptions, type DraftResult, type DueItem, type GenerateInput, type GeneratedHeaderImage, type HeaderImage, type InitOptions, type InitResult, type InitStep, type InitStepResult, InventoryProvider, type LighthouseScores, type LocalPathOptions, type OnboardAudit, type OnboardOptions, type OrchestrateOptions, RecipeName, RecipeResult, type RefreshHeaderDeps, type RenderResult, type ReportData, type ReportType, Site, type UpgradeSvelte4to5Options, a11yAudit, a11yFixturesPage, bumpDeps, convertToPnpm, depsAudit, domainFromUrl, draftReportForSite, findDueReports, fromAirtableBase, fromJsonFile, generateHeaderImage, init, isRecipeName, lighthouseAudit, lintAudit, loadBundledImages, loadHeadline, loadPlate, localPath, onboard, renderCockpitHtml, renderReportHtml, renderSiteDashboardHtml, runAudits, runAuditsAcross, securityAudit, selfCaretRange, selfPackageVersion, sendApprovedReports, svelteCodemods, upgradeSvelte4to5, verifyBasicAuth };