Every release, every change

noteReverted

• •packages/db tenant-scope + apps/worker job-context return to fail-open default with HELPMESH_TENANT_STRICT=1 as the opt-in strict mode (pre-alpha.113 behavior).

noteRetained (all genuine hardening from alpha.108–112 stays)

• •Context wrapping at the boundaries that DO hold context: apiHandler request wrapping, worker dispatch, widget, inbound webhooks. Tenant-resolution + ingest + SSR + bypass-route wraps. Audit mode (HELPMESH_TENANT_AUDIT=1). All manual tenantId filters and app-layer guards.

noteFollow-up (true fail-closed, done right)

Convert every single-promise runWithX(() => prisma.op()) wrap to async () => prisma.op() codebase-wide (mechanical), add a route-level strict test harness / staging DB to exercise every tenant-scoped path under strict *before* prod, then re-flip. Not a passive soak.

noteSecurity — changed

• •`packages/db` tenant-scope extension: a missing AsyncLocalStorage store on a tenant-scoped model throws by default. A forgotten runWithTenant()/runWithSuperAdmin() is now a loud 500, not a silent cross-tenant read. HELPMESH_TENANT_STRICT=0 is an emergency break-glass that restores the old fail-open pass-through without a code deploy; explicit-null tenantId always throws.
• •`apps/worker` dispatch: an unclassified job with no tenantId (and not in the cross-tenant allowlist) throws by default; same HELPMESH_TENANT_STRICT=0 break-glass.

noteValidation

• •Reached only after wrapping HTTP resolution, worker dispatch, widget, inbound webhooks, MFA pre-check, SSR pages, legal directories, and ~11 apiHandler-bypass routes — discovered via production audit mode + a static sweep.
• •Strict was run on live production for 30 minutes with 0 throws before flipping the default. Tests pin the new default + break-glass; db 229 / worker 224 / web 1682 green.

fixFixed

• •Public legal pages /legal/dpo and /legal/ropa-summary: cross-tenant public directories (DpoContact / RopaActivity where isPublic) now read under runWithSuperAdmin.
• •API routes that bypass `apiHandler` and query tenant-scoped models pre-context, now wrapped:

- ai/sentiment, ai/search-articles, system/activity, privacy/consent|export|delete, invoices/[id]/pdf|resend-email → runWithTenant (session/invoice tenant). - system/health (global counts), public/reports/[shareToken] (share-token lookup), and billing/webhook's tenant-resolution helpers + cross-tenant referral grant → runWithSuperAdmin; each Stripe event handler's writes → runWithTenant(tenant.id).

noteNotes

• •Full web suite green under HELPMESH_TENANT_STRICT=1 (1682 tests); billing/webhook diff reviewed line-by-line. With this, all statically- and runtime-discovered pre-context paths are wrapped — clearing the way for env-flip re-validation and the production fail-closed flip.

fixFixed

• •Public KB pages ((kb)/[tenantSlug] layout, home, [collectionSlug], articles/[articleSlug]): tenant is now resolved by public slug under runWithSuperAdmin (cross-tenant), then its collections/articles and the powered-by-badge check load under runWithTenant(tenant.id). Previously these server components queried Tenant/Collection/Article with no context.
• •Branding preview (/preview/branding): the session-tenant lookup now runs under runWithTenant(activeTenantId).

noteNotes

• •Source-contract guard tests added; web suite green under HELPMESH_TENANT_STRICT=1.
• •Found via HELPMESH_TENANT_AUDIT=1 (alpha.110) on live traffic. Audit mode remains enabled in prod to enumerate any remaining unwrapped paths before the fail-closed flip.

featureAdded

• •Audit mode (HELPMESH_TENANT_AUDIT=1): logs one structured line per distinct (model.operation @ call-site) for every tenant-scoped Prisma query that runs without tenant context, then passes through unchanged (never throws). Lets the full set of unwrapped pre-context call sites be enumerated from real production traffic before flipping fail-closed — instead of discovering them by 500-ing paths one at a time. Logs code locations only (no query args or row data); deduped per process.

fixFixed

• •MFA enforcement pre-check (checkMfaRequired) issued tenant.findUnique before the handler's runWithTenant, so it fired context-less on every authenticated mutation — a confirmed source of strict-mode throws. Now wrapped in runWithTenant(tenantId).

noteNotes

• •Audit-mode unit tests added; db + web suites green.

noteChanged — ingest routes

• •Twilio (SMS + voice): inbox resolution now runs under runWithSuperAdmin; all customer/thread/message writes run under runWithTenant(inbox.tenantId) (previously executed with no tenant context).
• •WhatsApp: inbox resolution wrapped in runWithSuperAdmin; each message persisted under runWithTenant(inbox.tenantId).
• •Slack, Postmark, widget sessions: the cross-tenant resolution lookup now runs under runWithSuperAdmin (their per-tenant processing was already scoped).
• •Widget KB: popular-articles query wrapped in runWithTenant; the full-text search path is raw SQL with an explicit tenantId filter (unaffected by the scope extension).

noteNotes

• •Adds a source-contract guard test for the ingest wrappers. Web suite green under HELPMESH_TENANT_STRICT=1.
• •With this, the known pre-context surfaces (worker dispatch, HTTP tenant resolution, widget + inbound webhooks) all declare intent explicitly — clearing the way for an env-flip validation ahead of the production fail-closed switch.

noteChanged — data layer / workers

• •Worker jobs establish tenant context at the dispatch boundary (HELP-11): a new runJobWithContext wraps every job once — jobs carrying tenantId run under runWithTenant, the cross-tenant maintenance/fan-out crons run under runWithSuperAdmin, and an unclassified context-less job warns (or fails under strict). Covers all 37 processors centrally instead of per-processor wrapping; fixes the sla-check sweep that threw under a strict-mode trial.
• •Tenant resolution runs under explicit super-admin context (HELP-11): resolveTenant (API handler) and the public-KB hostname resolver now run under runWithSuperAdmin, since resolution is inherently cross-tenant and precedes per-tenant context. The real per-tenant context is still established by the handler afterward.

noteNotes

• •Verified green under HELPMESH_TENANT_STRICT=1: web 1669 · worker 224 · db 222 · core 591.
• •The production fail-closed flip itself remains gated on wrapping the remaining widget / inbound-webhook pre-context paths and a clean full validation run.

noteSecurity — fixed

• •Cross-tenant access via `X-Tenant-Id` / `x-user-id` headers removed (HELP-10, HELP-17): tenant and acting-user identity now derive only from authenticated sources (API key / session / hostname). Header dropped from CORS.
• •Pusher channel authorization (HELP-13): /api/pusher/auth verifies every channel against the caller's active tenant before authorizing (tenant channels by equality; thread/presence by a tenant-scoped lookup). Parity with the customer-side widget authorizer.
• •Webhook SSRF blocked (HELP-15): new @helpmesh/core SSRF classifiers (ipaddr.js) reject targets resolving to private/loopback/link-local/metadata IPs — at registration and, authoritatively, at delivery. Stored response bodies capped at 2KB.
• •HTML sanitizer replaced with DOMPurify (HELP-14): isomorphic-dompurify (real DOM allow-list) supersedes the bypassable regex, making the long-standing "sanitised with DOMPurify" claim true. Regression tests cover the nested-script and entity-encoded javascript: bypasses.

noteChanged — data layer

• •Tenant scoping is schema-derived (HELP-12): the scoped-model set comes from Prisma.dmmf (every model with a tenantId column — 54) instead of a hand-maintained 20-model list; a new tenant-owned model can no longer be forgotten and leak.
• •Admin routes carry explicit super-admin context (HELP-94): getSuperAdmin() establishes it once, covering all 25 /api/admin routes.
• •CI runs the unit suite fail-closed (HELPMESH_TENANT_STRICT=1, HELP-11 partial): a forgotten runWithTenant() now fails the build. Production default flip deferred.
• •next.config: merged the duplicate experimental block that had been dropping serverComponentsExternalPackages (HELP-101); externalized isomorphic-dompurify.

noteTests

• •core 591 · db 222 · web 1683 · worker 217 — all green, including under fail-closed strict mode. next build clean.

noteAdded — web (inbox-v2)

• •`GET /api/v1/threads/counts`: one aggregate endpoint returning real per-view / channel / label thread counts. Tenant-scoped on every query (label counts scope through the thread relation since ThreadLabel has no tenantId); channels/labels via groupBy (no N+1). Pure, unit-tested mappers in apps/web/src/lib/thread-counts.ts.
• •Count badges on the Inbox Views column, refreshed whenever the list refreshes. A badge renders only for a positive count — an absent badge means genuinely zero, never a fabricated number.
• •Inbox list filter: a "Filter conversations…" field over the loaded list (subject / customer name / email), with a "no matches" state. ⌘K remains the global search.

noteChanged — web (shell)

• •The global top bar is hidden on `/inbox` at `xl`+ (the width where the Views column appears), reclaiming vertical space to match the inbox-v2 design. Below xl it stays.
• •New · Notifications · Account moved from the top bar into the global sidebar rail (bottom cluster), so they stay reachable app-wide — including on the inbox and in the mobile slide-in nav. Affects every agent page's chrome; the top bar is now search + mobile-nav only.

noteTests

• •+4 web (count mappers). Build · typecheck · lint clean; threads suite green.

noteAdded — web (inbox-v2, surgical/additive)

• •Inbox Views column (InboxViews): net-new left navigator with Views (All open · Urgent · Pending · Assigned to me · Unassigned · Snoozed), Channels (Email · Live chat · API), and Labels (live from /api/v1/labels). Wired to the inbox's existing filter state — no data-layer rewrite. Persistent at xl (≥1280px); supersedes the TabBar at that width, which still drives tabs below it.
• •`GET /api/v1/threads`: new channel and label (labelId) filters, built through a pure, unit-tested apps/web/src/lib/thread-filters.ts (buildThreadFilterWhere).
• •View counts are intentionally not rendered yet — avoids invented data; a real aggregate endpoint is the next phase.

noteFixed — web (white-label)

• •The "Powered by HelpMesh" badge now respects showPoweredBy. It was gated on *enable* (alpha.103) but ignored at *render*, so paying white-label tenants still saw it on KB, customer portal, and widget-session surfaces. Hidden only when the tenant both opted out and currently holds the whitelabel entitlement (re-checked at render, so a downgrade restores the badge). New shouldShowPoweredByBadge() + pure poweredByBadgeVisible().

noteTests

• •+8 web (3 entitlements render-gate, 5 thread-filters). Build · typecheck · lint clean.

noteAdded — web (super-admin)

• •Performance (/admin/performance + GET /api/admin/performance): platform performance from rows the system already records —

- Webhook delivery (7d): volume, success rate, average latency (WebhookDelivery.duration), plus a 7-day daily-volume trend. - Event processing: outbox backlog (pending), events processed in the last hour, and average processing lag (processedAt − createdAt) over recent events. - Throughput: messages + threads created in the last 24h / 7d. - DB ping latency. New Operations → Performance sidebar entry. Dark-themed. Aggregation math in a pure, unit-tested apps/web/src/lib/admin-performance.ts.

noteNote

• •This completes Phase 4 across the four surfaces with a real data source (billing, alerts, incidents, performance). Per-service infra metrics (CloudWatch/AWS) remain out of scope — they have no in-app data source and are not stubbed. This page is explicitly labeled "application-level metrics (not infra/CloudWatch)".

noteTests

• •Web suite 1657 passing (+7: 5 helper + 2 route).

noteChanged — web (authorization)

• •New tenantHasCapability(tenantId, key) + pure capabilitiesRequiredForSettingsPatch(body) helpers (apps/web/src/lib/entitlements.ts), both resolving plan default ⊕ super-admin override.
• •customDomain — POST /api/v1/tenant/email-domain now returns 403 HM-PLAN-INSUFFICIENT unless the tenant holds the customDomain capability.
• •sso — PATCH /api/v1/tenant returns 403 HM-PLAN-INSUFFICIENT when setting a non-null samlConfig without the sso capability.
• •whitelabel — PATCH /api/v1/tenant returns 403 when hiding the "Powered by" badge (showPoweredBy=false) without the whitelabel capability.
• •Non-breaking by design: only *enabling* a paid feature is gated. Clearing/disabling (samlConfig=null, showPoweredBy=true, BYOD DELETE/GET) is always allowed, so tenants already using a feature are never cut off mid-stream.

noteNote

• •Honoring showPoweredBy at *render* time (KB/portal layouts + the embeddable widget currently always show the badge) is a separate, pre-existing wiring gap — not addressed here. This ship governs the *setting*, not the badge render.

noteTests

• •Web suite 1650 passing (+6 entitlement helper/decision).

noteAdded — platform / web (super-admin)

• •`Incident` + `IncidentUpdate` models (migration 20260608000000_platform_incidents). Platform-level — no `tenantId`, deliberately omitted from TENANT_SCOPED_MODELS so the tenant middleware never scopes them. Purely additive (two new tables + two enums).
• •API: GET/POST /api/admin/incidents, GET/PATCH /api/admin/incidents/[id], POST /api/admin/incidents/[id]/updates (appends a timeline entry and advances incident status in one transaction; RESOLVED stamps resolvedAt). Super-admin only; Zod-validated via new @helpmesh/core incident schemas.
• •UI: /admin/incidents (list + inline open-incident form, open-count) and /admin/incidents/[id] (severity/status, impact, affected tenants, post-update form, reverse-chronological timeline). New Operations → Incidents sidebar entry. Dark-themed.
• •All data is admin-entered — nothing synthetic. (No AuditLog entry: that model requires a tenantId; incidents are platform-level and carry their own timeline + createdByUserId trail.)

noteTests

• •Core suite 582 passing (+6 incident schema/helper), web suite 1644 passing (+4 incident route).

noteAdded — web (super-admin)

• •Alerts (/admin/alerts + GET /api/admin/alerts): a cross-tenant attention feed that aggregates real platform conditions — overdue/failed GDPR deletions (72h SLA breach → critical), auto-disabled webhooks (→ warning), and billing states (unpaid → critical, past-due → warning, trial expiring ≤3d → info). Severity-summarized tiles + a deep-linked alert list with an "All clear" empty state. New Operations → Alerts sidebar entry. Dark-themed.
• •Aggregation logic lives in a pure, React/DB-free buildAlerts/summarizeAlerts (apps/web/src/lib/admin-alerts.ts) so it is fully unit-tested. Categories with no backing data simply yield no alerts — nothing synthetic.

noteNote

• •Remaining Phase 4 surfaces incidents and performance are still not built — no real data source (no incident model; perf would need a CloudWatch/health time-series). They will not be stubbed with fabricated numbers.

noteTests

• •Web suite 1640 passing (+9: 7 aggregation + 2 route).

noteAdded — web (super-admin)

• •Billing (/admin/billing + GET /api/admin/billing): cross-tenant revenue overview — estimated MRR/ARR, active-subscription / past-due / cancelling counts, MRR-by-plan bars, a per-tenant subscription table, and the 10 most recent invoices (from the local Invoice mirror, with Stripe PDF links). New Revenue → Billing sidebar entry. Dark-themed.
• •Honest MRR basis: a new shared estimateTenantMrrCents (packages/core/src/billing/mrr.ts) computes MRR from plan list-price × paid seats, normalizing annual to monthly. It is not Stripe-invoiced revenue — coupons/credits/proration/tax are ignored and ENTERPRISE (contact-sales, list price $0) counts as $0. The UI labels this clearly. Only ACTIVE subscriptions count toward MRR.

noteNote

• •The remaining Phase 4 surfaces (incidents, performance, alerts) are still not built — they have no backend data source and will not be stubbed with fabricated numbers.

noteTests

• •Core suite 576 passing (+4 MRR), web suite 1631 passing (+2 billing route).

noteChanged — web (super-admin)

• •Compliance index (/admin/compliance) re-skinned dark: dark stat tiles + per-tenant SLA table; added a DPO registry quick-link alongside ROPA register.
• •ROPA index + detail re-skinned dark (filters, summary tiles, stale-review flags, lawful-basis sections, toggles).
• •DPO registry index + detail re-skinned dark (scope filters, jurisdiction chips, certifications, retire action).
• •Create forms (ROPA "New activity" + "New DPO", added in alpha.97) restyled dark via a dark rebuild of the shared form kit (_form/fields.tsx) plus dark page chrome.

noteNote

• •The admin console is now fully dark across every shipped page. Remaining work is Phase 4 net-new surfaces (cross-tenant billing, incidents, performance, alerts) — these need real backends before they can be built honestly and are not stubbed.

noteTests

• •Web suite 1629 passing.

noteChanged — web (super-admin)

• •AI costs (/admin/ai-costs) re-skinned dark: dark stat tiles, trend bars, and usage table (keeps the shared estimateAiCostUsd basis from alpha.97).
• •Promo codes (/admin/promo-codes) re-skinned dark: create form (dark inputs/radios), table, status pills, archive/restore actions — all intact, dropped the light @helpmesh/ui primitives for card-d/input-d/btn-*/pill.
• •Pages directory (/admin/pages) re-skinned dark: dark section cards, route rows, role pills, and notes banner.
• •Webhooks (/admin/webhooks) re-skinned dark: filter chips, health stat tiles, top-failing list, and the delivery-health table.

noteNote

• •Remaining light pages: the compliance cluster (/admin/compliance + ropa/dpo + the two alpha.97 create forms) re-skins next (Phase 3b, to match docs/ui-previews/compliance-center.html). Phase 4 net-new surfaces (billing, incidents, performance, alerts) still need real backends before they can be built honestly.

noteTests

• •Web suite 1629 passing.

noteFixed — web (super-admin)

• •ROPA "New activity" was a dead link. The ROPA index linked to /admin/compliance/ropa/new, which never existed (404). Built the full GDPR Art. 30 create form (number, role, purpose, Art. 6 + Art. 9 lawful basis, data-subject / personal-data / recipient categories, retention, conditional cross-border transfer block, safeguards, DPIA + public flags) → POST /api/admin/compliance/ropa.
• •AI costs used a divergent pricing formula. The page hard-coded a straight $3/$15 per-MTok rate; every other surface uses the shared blended estimateAiCostUsd (Sonnet+Haiku). Switched the admin page to the shared estimator so the dollar figures match billing, and made the copy honest ("indicative, not authoritative invoicing").

noteAdded — web (super-admin)

• •DPO registry create. POST /api/admin/compliance/dpo had no UI; added a New DPO button on the registry and a full create form (scope, conditional tenant binding, contact details, jurisdictions, certifications editor, mandatory/public flags, appointment date).
• •Shared compliance form primitives (_form/fields.tsx) and React-free payload builders (_form/payloads.ts) covered by 11 new unit tests.

noteTests

• •Web suite 1629 passing.

noteChanged — web (super-admin)

• •Add-tenant wizard (/admin/tenants/new) rebuilt as the approved dark 4-step wizard (Workspace → Owner → Plan & trial → Review) with a stepper, dark inputs, live subdomain availability check, per-step gating, and a dark review + success screen. Same POST /api/admin/tenants contract — no functional change, just the wizard UX.
• •System health (/admin/system-health) re-skinned dark (status banner, database + memory/runtime cards); dropped its redundant inner page-width wrapper so it sits correctly in the console shell.

noteNote

• •Still light (next): /admin/{webhooks,ai-costs,compliance,pages,promo-codes}; net-new surfaces (billing, incidents, performance, alerts) follow in Phase 4.

noteTests

• •Web suite 1618 passing.

noteChanged — web (super-admin)

• •Tenant detail (/admin/tenants/:id) re-skinned dark: stat tiles, compliance + threads/billing cards, webhook health rows, recent-activity rows, the Manage SideSheet (now a dark sheet via scoped .sa-root so inputs/buttons style correctly inside the portal), inline Suspend/Reactivate, the Entitlements card, and the Danger zone delete — every control and handler unchanged.
• •Tenants list (/admin/tenants) re-skinned dark: dark grid table, status pills, region pills, search, impersonate + resend-invite actions intact.
• •Global audit log (/admin/activity) re-skinned dark: dark filter bar + rows, sensitive badge, tenant links, load-more.

noteNote

• •Remaining admin pages (webhooks, AI costs, compliance, system-health, Pages CMS, promo-codes) + the add-tenant wizard and net-new surfaces (billing, incidents, performance, alerts) re-skin in Phases 2b–4.

noteTests

• •Web suite 1618 passing.

noteChanged — web (super-admin)

• •Dark-navy console chrome: /admin layout is now the approved left-sidebar shell (.sa-root/.sa-shell) — grouped nav (Overview / Customers / Operations / Compliance / Platform) carrying every existing admin route, dark topbar, super-admin identity card. New sa Tailwind palette + scoped .sa-* component classes in globals.css (no leakage to tenant/marketing surfaces).
• •Home ecosystem dashboard: /admin rebuilt to the dark dashboard — stat cards (active tenants, open threads, users, needs-attention), tenants-by-status + by-plan distribution panels, a recent-tenants table, and a platform-health panel. Uses real /api/admin/metrics data only (no fabricated numbers); period toggle drives the real 7d/30d signup delta.
• •GET /api/admin/metrics now also returns recentTenants (latest 6 active, with plan/status/region + member/thread counts).

noteFixed — web

• •Jira reverse-sync webhook URL now surfaced in the integration card: GET /api/v1/integrations/jira returns the full webhookUrl (secret embedded, OWNER-scoped); the card shows it with reveal + copy + setup steps. Previously the secret was generated + verified but never shown, so the webhook couldn't be wired without a DB query.

noteNote — phased rebuild in progress

• •Inner admin pages (tenant detail, audit log, tenants list, promo/AI-costs/compliance/system-health/pages) still render their prior light style inside the dark shell until their phases land. Designed-but-unbuilt surfaces (cross-tenant billing, incidents, performance, alerts, add-tenant wizard) come in later phases.

noteTests

• •Web suite 1618 passing.

noteAdded — core (`@helpmesh/core`)

• •packages/core/src/billing/entitlements.ts — the capability registry (CAPABILITY_KEYS, CAPABILITY_LABELS), planCapabilities() (TRIAL→STARTER), and the resolver resolveEntitlement(s) (effective = override ?? planDefault). 9 tests.

noteAdded — db (migration)

• •New TenantEntitlementOverride model (@@unique([tenantId, key])) + Tenant.entitlementOverrides back-relation; added to the tenant-scope middleware set. Migration 20260607000000_tenant_entitlement_overrides (additive — new table only).

noteAdded — web

• •getTenantEntitlements(tenantId) server helper (plan + overrides → resolved map) — the single call future feature gates should use.
• •`GET /api/admin/tenants/:id/entitlements` (resolved list) · `PUT /:key` ({enabled,note?} upsert) · `DELETE /:key` (revert to plan default) — super-admin only, key validated against the registry, audit-logged (tenant.entitlement_set / _cleared). 12 tests.
• •Entitlements card on the tenant detail page: per-capability toggle, plan-default indicator, "overridden" badge, and reset-to-default. Preview: apps/web/scratch/ui-previews/admin-tenant-entitlements.html.

noteNot enforced yet (honest scope)

• •This ships the override plane + resolver. Capabilities without a runtime gate today (customDomain, sso, etc.) stay metadata until a feature adopts getTenantEntitlements — no retroactive enforcement.

noteTests

• •Core 572, web 1617 passing.

noteAdded — web (`/api/admin/activity`)

• •`GET` — super-admin-only cross-tenant audit log. Cursor-paginated; filters by tenantId, actorId, entity, action substring, sensitive (allow-list), and from/to date range. Each row includes its tenant + actor and an isSensitive flag. Unscoped via the same admin pass-through the sibling routes use.

noteAdded — web (`/admin/activity`)

• •New audit-activity page: filterable, paginated table (time · tenant · actor · action · entity) with a sensitive-action badge, an action search box, a "sensitive only" toggle, load-more pagination, and tenant cells linking to the tenant drilldown. Added an Activity entry to the super-admin nav.

noteTests

• •7 new tests for the endpoint (403 + enrichment + cross-tenant default + action/sensitive/tenant filters + pagination). Web suite: 1605 passing.

noteAdded — web (`/api/admin/metrics`)

• •`GET` — super-admin-only cross-tenant KPIs in one round trip: tenant totals + status/plan distribution (groupBy), new-signup counts (7d/30d), active + soon-expiring trials, soft-deleted count, platform totals (users, open threads, customers), and a health rollup (disabled webhooks, pending data-deletions). Cheap counts/groupBys; unscoped via the same admin pass-through the sibling routes use.

noteAdded — web (`/admin`)

• •New Overview landing page: stat cards (tinted icon + delta chip + caps label + big number), tenants-by-status and tenants-by-plan distribution bars, a platform-health card linking to Webhooks/Compliance, and quick links. Added an Overview entry to the super-admin nav.

noteTests

• •3 new tests for the metrics endpoint (403 + shaped-output + total-excludes-deleted). Web suite: 1598 passing.

noteAdded — web (`/api/admin/tenants/:id`)

• •`PATCH` — super-admin-only partial update of status, plan, paidSeats, trialEndsAt, auditRetentionDays, requireMfa, requireTwoAdminDelete. Zod-.strict() (unknown keys rejected), computes a changed-only before/after diff, writes an AuditLog (action: 'tenant.updated', context.actorType: 'super_admin'). No-ops when nothing changed. Region and billing identity are deliberately not editable here.
• •`DELETE` — super-admin-only soft-delete (sets status=DELETED + deletedAt; no customer data purged). Requires a type-the-slug confirmSlug and refuses with 409 HM-TENANT-ACTIVE-SUBSCRIPTION while a Stripe subscription is still ACTIVE (cancel billing first). Audit-logged as tenant.soft_deleted.

noteAdded — web (`/admin/tenants/:id`)

• •Manage button → SideSheet editor for the full field set (status, plan, seats, trial-end, audit retention, MFA + two-admin-delete toggles). Notes that plan/seat changes update HelpMesh only, not Stripe.
• •Inline Suspend / Reactivate on the Status row (one-click abuse/billing response).
• •Danger zone card with slug-confirmation delete; disabled with an explanatory note while billing is active.

noteTests

• •16 new runtime tests for PATCH/DELETE (403/400/404/409/no-op/happy-path + audit-log + diff assertions). Web suite: 1595 passing.

noteChanged — web

• •Settings → Channels: replaced the manual "Bot User OAuth Token / Channel ID / Save Manual Config" form with a single one-click Install HelpMesh into Slack OAuth button. The connected indicator now derives from an active SLACK inbox, not the legacy (dead) Tenant.settings.channelConfig.
• •Settings → Integrations: the Slack card button now launches OAuth directly; removed the dead manual-token panel, corrected the description (notifications → inbound tickets), and dropped the hardcoded "connected" badge.
• •Removed the orphaned channelConfig / slackBotToken / slackChannelId state + save/disconnect handlers that wrote to a store nothing read at runtime (same pattern as the alpha.80 Jira cleanup).

noteAdded — worker (`channel-outbound`)

• •When an agent reply can't be delivered because a channel's credentials are missing (channel never connected / disconnected), the worker posts an agent-only SYSTEM message into the thread: "⚠️ This reply couldn't be delivered to {Slack/WhatsApp/SMS} — reconnect in Settings → Channels." systemEvent null = customer never sees it; SYSTEM authorType means the outbox fanout won't re-enqueue (no loop); tenant-scoped via runWithTenant. Renders via the existing system-message UI. 4 new tests.

noteInfra — Slack now functional in prod

• •Created helpmesh-prod/slack-client-id / -client-secret / -signing-secret in Secrets Manager and wired SLACK_CLIENT_ID / SLACK_CLIENT_SECRET / SLACK_SIGNING_SECRET into the web task def (rev 33). Slack OAuth install/callback + inbound webhook signature verification are now live. Tenants connect at Settings → Integrations → Slack.

noteSecurity — encrypt channel secrets at rest

• •New apps/web/src/server/channels/token-store.ts (encrypt/decrypt) + apps/worker/src/lib/channel-secrets.ts (decrypt) — AES-256-GCM via the shared GOOGLE_TOKEN_ENCRYPTION_KEY, mirroring the CRM token-stores. Backward-compatible: legacy plaintext secrets (no v1: prefix) pass through and re-encrypt on next reconnect. No migration.
• •Slack OAuth callback now encrypts slackBotToken + slackIncomingWebhookUrl before persisting to Inbox.config; worker channel-outbound decrypts on read.

noteWhatsApp — real wiring (was non-functional)

• •New POST/GET/DELETE /api/v1/integrations/whatsapp (ADMIN-gated): persists phoneNumberId + encrypted accessToken to a WHATSAPP Inbox.config — the store the inbound webhook (findWhatsAppInbox) and outbound worker actually read. Replaces the legacy Tenant.settings.channelConfig path, which nothing at runtime consumed.
• •Settings → Inboxes WhatsApp card repointed at the new endpoint (connect/status/disconnect); removed the fake hardcoded phone number; access token no longer retained in the form after save.
• •Worker decrypts the WhatsApp access token before sending.

noteCorrectness — Slack webhook

• •Verify the request signature before echoing the url_verification challenge (was probe-able unauthenticated).
• •Ignore any message carrying a subtype (edits/deletes/joins/file shares) + empty/user-less messages, so they no longer spawn spurious threads.

noteAdded — tests (~22 new)

• •web: channel token-store round-trip + legacy passthrough; WhatsApp route isolation (ADMIN gate, Zod-before-write, token encryption, tenant scoping, GET never returns the token); Slack callback encryption contract; Slack webhook correctness contract.
• •worker: channel-secrets cross-surface decrypt round-trip + legacy passthrough.

noteDeferred

• •Agent-facing "channel disconnected" delivery surfacing (needs a thread system-message + UI — feature work, tracked in docs/specs/tier-3c-channel-hardening.md).

noteAdded — channels (`packages/channels/src/salesforce/contact-client.ts`)

• •listCaseStatusesByIds(accessToken, instanceUrl, caseIds, sinceIso) — SOQL SELECT Id, Status FROM Case WHERE Id IN (…) AND LastModifiedDate > <since>. Bounded by the tenant's own linked-Case ids; no query for an empty list. 401 → INVALID_SESSION.

noteAdded — worker

• •salesforce-case-poll-fanout (salesforce-case-poll-fanout.ts): every 15 min, enqueues one salesforce-case-poll per active integration (de-duped by tenant-scoped jobId), mirroring the HubSpot sync fanout. Cross-tenant scan under runWithSuperAdmin.
• •salesforce-case-poll (salesforce-case-poll.ts): per tenant, pulls the current Status of linked Cases changed since lastPolledAt (bounded at 200) and reconciles each onto its thread — only when the mapped status differs. Emits a normal thread.status_changed event in the same transaction (realtime + the other integrations propagate; the echo back to Salesforce is idempotent). Advances lastPolledAt. Deletion cleanup is left to the push path's existing 404 handling.
• •Reverse mapping mapCaseStatusToThreadStatus (salesforce-case-mapping.ts): New→OPEN, Working/Escalated→PENDING, Closed→RESOLVED; unrecognised/custom statuses → null (thread left untouched).

featureChanged

• •Registered both processors in the worker PROCESSOR_MAP + processors barrel, and added the salesforce-case-poll-fanout-cron (15-min) scheduler.

noteAdded — tests (19 new)

• •3 channels (listCaseStatusesByIds: empty-list short-circuit, SOQL shape, 401) + 2 reverse-mapping + 9 poll isolation + 5 fanout isolation.

noteAdded — channels (`packages/channels/src/salesforce/contact-client.ts`)

• •findContactByEmail, findLeadByEmail (unconverted only), listAccountOpportunities (open, ≤10, soonest close first) via the SOQL query endpoint. escapeSoql guards every interpolated value against injection. 401 → INVALID_SESSION (token store refresh + retry); other failures → SOQL_QUERY_FAILED.

noteAdded — API route (`GET /api/v1/customers/:id/salesforce`, AGENT-gated)

• •Tenant-scoped customer lookup, then a live match (Contact → Lead) + Opportunity fetch through the token wrapper. Soft-degrading discriminated response ({ enabled, linked, recordType, recordId, salesforceUrl, …record fields, opportunities, opportunitiesError }) — never 5xx's the panel just because Salesforce is misconfigured; never returns token material or another tenant's customer.

noteAdded — UI (`apps/web/src/components/agent/SalesforceContextCard.tsx`)

• •Three states matching the approved preview (docs/ui-previews/salesforce-customer-context.html): not linked / linked as Lead (status + rating) / linked as Contact (account + owner + open Opportunities with Lightning deep-links). Self-hides when Salesforce is disabled or the tenant never connected. Slotted into customer-detail below the HubSpot context card.

noteAdded — tests (18 new)

• •10 channels (find Contact/Lead/Opportunities: mapping, null, SOQL shape, escaping, 401→INVALID_SESSION, 500→SOQL_QUERY_FAILED) + 8 route-isolation (AGENT gate, tenant scoping, soft-degrade, no token leakage).

noteAdded — channels (`packages/channels/src/salesforce/case-client.ts`)

• •createCase (POST the Case sObject → returns the new id) and updateCase (PATCH; returns false on 404 so the caller drops a stale link). Both throw INVALID_SESSION on 401 so the worker token store refreshes + retries; config rejections surface as CASE_CREATE_FAILED / CASE_UPDATE_FAILED with the HTTP status.

noteAdded — worker

• •salesforce-case-sync processor (apps/worker/src/processors/salesforce-case-sync.ts): fires on thread.created + thread.status_changed. Creates a Case on first sight, PATCHes Status/Subject on later changes. Skip-and-log on: disconnected/revoked, record type not picked (skipped-no-config), Case deleted upstream (drops the link), 400 picklist/record-type rejection (skipped-invalid-field, with auto-clear of a deleted record type). BullMQ retry reserved for 5xx/429/network.
• •Pure mapping helpers (salesforce-case-mapping.ts): mapThreadStatusToCaseStatus (OPEN→New, PENDING→Working, RESOLVED/CLOSED/SPAM→Closed), composeCaseSubject (255-char cap), composeCaseDescription (500-char preview + deep-link), buildCaseUrl (Lightning record URL).
• •Worker token store (apps/worker/src/lib/salesforce-credentials.ts): withSalesforceAccessToken — cached token first, refresh-once-and-retry on 401 (Salesforce omits expires_in); invalid_grant marks the row revoked. No circuit breaker (BullMQ handles backoff), matching the HubSpot/Jira worker token stores.

featureChanged

• •apps/worker/src/processors/outbox.ts step 6f dispatches salesforce-case-sync alongside the HubSpot ticket + Jira issue syncs; registered in the worker PROCESSOR_MAP.

noteAdded — tests (26 new)

• •7 channels (createCase/updateCase: success, 401→INVALID_SESSION, 404→false, 400→failure) + 7 mapping + 12 worker isolation (tenant scoping, provider-scoped LinkedIssue mutations, skip-and-log paths).

noteAdded — schema (`migration 20260605120000_tier3b3_salesforce_integration`, additive)

• •New SalesforceIntegration model (one row per tenant, tenantId @unique) + SalesforceEnvironment enum (PRODUCTION/SANDBOX). Encrypted refresh + access tokens (AES-256-GCM via the shared GOOGLE_TOKEN_ENCRYPTION_KEY), per-org instanceUrl, org/user identity, granted scopes, Case sync config (caseRecordTypeId / caseRecordTypeName / defaultCaseOrigin), and telemetry watermarks.

noteAdded — channels client (`packages/channels/src/salesforce/`)

• •OAuth client: authorize-URL builder, code exchange, refresh (no token rotation), revoke, and identity fetch, all environment-aware (login vs test.salesforce.com). Single SalesforceApiError discriminated union.
• •Case describe client: one describe call returns the org's Case record types + Origin picklist values. Throws INVALID_SESSION on 401 so the token store can refresh + retry.

noteAdded — token store (`apps/web/src/server/salesforce/token-store.ts`)

• •withSalesforceAccessToken wrapper: tries the cached access token, and on a 401 INVALID_SESSION refreshes once and retries (Salesforce omits expires_in, so there's no pre-emptive expiry). Refresh gated by the shared circuit breaker, namespaced :salesforce; invalid_grant marks the row revoked.

noteAdded — API routes (all OWNER-gated except the public callback)

• •GET/PUT/DELETE /api/v1/integrations/salesforce (state / save Case config / disconnect), GET /connect (environment toggle → signed-state redirect), GET /callback (public — verifies signed state before trusting the tenant), GET /case-record-types (picker data).

noteAdded — UI

• •SalesforceIntegrationCard + SalesforceCaseSyncSection wired into Settings → Integrations (replacing the old "coming soon" tile): Production/Sandbox toggle, OAuth popup, record-type + Origin pickers. Matches the approved preview at docs/ui-previews/salesforce-integration.html.

noteAdded — tests (43 new)

• •20 channels (OAuth client + Case describe) + 23 route-isolation (tenant scoping, OWNER gating, no token leakage in responses, verify-state-before-trust on the callback).

featureChanged

• •OAuthStatePayload gains an optional environment field so the sandbox/production choice survives the OAuth round-trip (additive; HubSpot + Jira unaffected — re-verified against the state-signer suite).

noteAdded — webhook route (`apps/web/src/app/api/v1/integrations/jira/webhook/route.ts`)

• •Public POST endpoint (no apiHandler wrapper — Jira doesn't send a session cookie).
• •Secret lives in the query string: POST /api/v1/integrations/jira/webhook?secret=<per-integration-secret>. Per-tenant 32-byte secret generated on connect (Phase 1).
• •Tenant resolution via runWithSuperAdmin scan of JiraIntegration rows with revokedAt: null and webhookSecret IS NOT NULL. Constant-time secret comparison via jira.verifyJiraWebhookSecret (from Phase 1).
• •Generic 401 on missing or mismatched secret (anti-probe — never leaks the failure mode).
• •Only acts on jira:issue_updated + jira:issue_deleted. Other events return 200 with ignored-event (no retry loop from Jira's side).
• •Malformed JSON → 400, not 500.
• •Job dispatch keyed on jira-issue-webhook:${tenantId}:${issueKey}:${eventType} for safe dedup of duplicate webhook fires.

noteAdded — worker processor (`apps/worker/src/processors/jira-issue-webhook.ts`)

• •Reconciles a single Jira webhook event with HelpMesh's LinkedIssue row.
• •Outcomes: updated (refreshed title + status), deleted (Jira said deleted OR our getIssue returned null), skipped-no-link (no LinkedIssue row — not our issue), skipped-not-connected (Atlassian 401 → mark revoked).
• •Tenant-scoped via runWithTenant; linkedIssue.deleteMany always scoped by (provider: 'jira', externalId) so we never accidentally drop another provider's links.
• •Idempotent: re-running for the same event re-pulls + re-writes the same fields.

noteAdded — tests (19 new)

• •route.isolation.test.ts — 10 contract tests for the inbound endpoint: public POST (no apiHandler), runWithSuperAdmin lookup, constant-time verify, generic 401, allowed-event filter, ignored-event 200, malformed-JSON 400, stable jobId for dedup, BullMQ retry semantics.
• •jira-issue-webhook.isolation.test.ts — 9 contract tests for the worker: tenant isolation, no-link skip, direct deletion shortcut, 404-race deletion, 401 → revoke, title+status refresh, scoped deletes (never cross-provider).

noteTenant action (one-time, to enable real-time updates)

After deploy, tenants who want real-time Issue → Thread reconciliation must: 1. Go to Jira → Settings → System → WebHooks → Create webhook. 2. URL: copy from the Integrations card — https://helpmesh.io/api/v1/integrations/jira/webhook?secret=<your-secret>. The secret was generated in Phase 1 and is unique per tenant. 3. Subscribe to: Issue updated + Issue deleted. 4. Set the JQL filter to your sync project (e.g. project = SUP) so HelpMesh only receives events for issues we mirror. 5. Save + enable. Tenants who skip this step still get one-way Thread → Issue sync from Phase 2 — Jira-side changes just don't reflect back into HelpMesh until they wire up the webhook.

noteOut of scope (deferred indefinitely)

• •Comment sync (HelpMesh messages ↔ Jira comments). Bigger semantics question — who owns the comment, do agents get pinged when Jira commenters reply, etc. Revisit if customers ask.
• •Custom field sync (HelpMesh custom fields → Jira custom fields). Per-tenant configuration spaghetti.
• •Assignee mapping (HelpMesh user → Atlassian account). Same per-user link table problem HubSpot Phase 2.4 deferred.

noteAdded — pure mapping helpers (`apps/worker/src/processors/jira-issue-mapping.ts`)

• •pickTransitionId(status, transitions) — case-insensitive name match against the available Jira workflow transitions. Falls back to Jira's standard 3-bucket statusCategory taxonomy (new / indeterminate / done) when name doesn't match, so tenant-renamed workflows still work. Returns null when nothing matches.
• •composeIssueSummary({publicNumber, subject}) — [#1234] subject, capped at 254 chars per Jira's documented summary limit.
• •composeIssueDescription({...}) — capped at 500 chars of body preview; full thread lives back in HelpMesh via deep-link.
• •buildIssueUrl(baseUrl, issueKey) — ${baseUrl}/browse/${issueKey} for LinkedIssue.externalUrl.

noteAdded — worker processor (`apps/worker/src/processors/jira-issue-sync.ts`)

• •Triggered by outbox dispatch on thread.created + thread.status_changed — same shape as HubSpot Phase 2.4.
• •Uses the existing LinkedIssue model (provider-agnostic) as the Thread → Jira bridge; no new schema column.
• •Skip-and-log (NOT retry) on: integration missing/revoked, project + issue-type pickers not completed, thread status maps to no available transition, issue deleted upstream.
• •Auto-recovery: 401 on any Atlassian call → mark integration revoked. 404 on transition / list-transitions → drop the LinkedIssue row so the next event re-creates.
• •Idempotent: re-running for the same thread no-ops (no status change) or PATCHes the same transition (Jira treats that as a no-op).
• •Wired into the worker dispatcher as 'jira-issue-sync'.

noteAdded — worker credential helper (`apps/worker/src/lib/jira-credentials.ts`)

• •Mirror of apps/web/src/server/jira/token-store.ts. Decrypts the API token via GOOGLE_TOKEN_ENCRYPTION_KEY, returns full JiraCredentials for outbound API calls. markJiraRevoked(tenantId) for the 401 path.

noteAdded — outbox dispatch step 6e

• •New dispatch in apps/worker/src/processors/outbox.ts — keyed on jira-issue-sync:${event.id}, 3 attempts + exp backoff. Fired alongside the HubSpot ticket-sync dispatch when an outbox event with thread.created / thread.status_changed lands.

noteAdded — tests (26 new)

• •jira-issue-mapping.test.ts — 19 tests covering name match, status-category fallback (renamed workflows), edge cases (empty transitions, mismatch), summary cap, description truncation, baseUrl normalization.
• •jira-issue-sync.isolation.test.ts — 7 contract tests: tenant isolation, every skip guard, auto-recovery on 401 / 404, LinkedIssue create/delete shape.

noteTenant action (none)

Phase 2 is automatic — tenants who picked a project + issue type in Phase 1 now see automatic Thread → Issue mirroring without any further action. Tenants who haven't picked yet see no sync (worker no-ops with skipped-no-pickers).

noteAdded — schema

• •New JiraIntegration model: id, createdAt, updatedAt, tenantId (unique), connectedByUserId, baseUrl, atlassianEmail, encryptedApiToken, projectKey, defaultIssueType, atlassianAccountId, atlassianDisplayName, webhookSecret (Phase 3 ready), lastSyncedAt, lastValidatedAt, lastUsedAt, revokedAt.
• •Migration 20260604190000_tier3b3_jira_integration — additive only. Existing tenants with the plaintext scaffold are unaffected until they reconnect.

noteAdded — Jira REST client (`packages/channels/src/jira/`)

• •validateCredentials(creds) — GET /rest/api/3/myself, throws INVALID_CREDENTIALS on 401/403 so the PUT route can return a typed 422 to the UI.
• •listProjects(creds) — GET /rest/api/3/project/search. Caps at 50.
• •listIssueTypes(creds, projectKey) — GET /rest/api/3/issue/createmeta/{key}/issuetypes. Filters out sub-task types. Returns null on 404 (project deleted upstream).
• •createIssue(creds, input) — POST with ADF-wrapped plaintext description. Wires for Phase 2.
• •getIssue(creds, issueKey) — single-issue fetch, null on 404.
• •listTransitions(creds, issueKey) — workflow transitions for Phase 2 status mapping.
• •transitionIssue(creds, issueKey, transitionId) — POST transition, returns true/false/throws.
• •verifyJiraWebhookSecret(...) — constant-time secret comparison for Phase 3.
• •All errors funnel through JiraApiError with a discriminated code union.

noteAdded — token-store (`apps/web/src/server/jira/token-store.ts`)

• •AES-256-GCM encryption via the shared GOOGLE_TOKEN_ENCRYPTION_KEY (same trust boundary as Google/Zoom/HubSpot — no operational benefit to splitting).
• •getJiraCredentials(tenantId) — tenant-scoped read, decrypt, return JiraCredentials. Throws JiraNotConnectedError on missing/revoked.
• •markJiraRevoked(tenantId) — flips revokedAt. Routes call this on Atlassian 401 to defuse repeated failed calls.

noteAdded — API endpoints (5)

• •GET /api/v1/integrations/jira — return connection state + project/issue-type picks. Surfaces legacyPlaintextConfig: true when the old scaffold is detected so the UI renders a "Reconnect to secure your token" banner.
• •PUT /api/v1/integrations/jira — OWNER-only, Zod-validated. On credential save: validates against Atlassian FIRST (no encrypting typos), then encrypts + upserts. On picker save: just persists. Generates a fresh webhookSecret on first save (Phase 3 ready). Auto-clears legacy plaintext config after a successful new save.
• •DELETE /api/v1/integrations/jira — OWNER-only disconnect. Marks revokedAt; no upstream revoke call (Atlassian has no equivalent).
• •GET /api/v1/integrations/jira/projects — OWNER-only. 401 from Atlassian → mark revoked + return 409.
• •GET /api/v1/integrations/jira/issue-types?projectKey=X — OWNER-only. Returns 404 when project was deleted upstream.

noteAdded — UI (`apps/web/src/components/settings/JiraIntegrationCard.tsx`)

• •Matches the approved preview at docs/ui-previews/jira-integration.html. Three states: Available / Credentials form / Connected + picker.
• •Legacy-config tenants see a "Reconnect to secure your token" amber banner instead of generic "Connect".
• •Credential form: Base URL + Atlassian email + API token (with show/hide). Help text links to Atlassian's token page. "Test & save" hits the live /myself endpoint via PUT before persisting.
• •Picker section: lazy project dropdown (GET /projects), cascading issue-type dropdown (GET /issue-types?projectKey=X on change), "Sync inactive" pill until both are picked.
• •Slotted into Settings → Integrations alongside HubSpot / Google Meet / Zoom (4-card grid).
• •Removed the in-page plaintext form from apps/web/src/app/(agent)/settings/integrations/page.tsx — the new card owns the entire Jira UX.

noteAdded — tests (52 new)

• •client.test.ts — 23 HTTP-shape tests covering all 7 client functions + auth header construction + trailing-slash stripping.
• •webhook.test.ts — 5 constant-time secret-comparison tests (Phase 3 verifier ready).
• •route.isolation.test.ts (root) — 11 contract tests: OWNER gate, Zod validation, validate-before-encrypt, 422 on bad creds, webhook secret generation, legacy-plaintext signal, tenant isolation, never-echo-token.
• •route.isolation.test.ts (projects) — 7 contract tests covering OWNER gate, 401 → revoke, typed errors.
• •route.isolation.test.ts (issue-types) — 6 contract tests covering query validation, 404 → upstream-deleted signal.

noteTenant action (one-time, after Phase 1 deploy)

Existing tenants who pre-configured Jira via the scaffold will see a "Reconnect to secure your token" banner in Settings → Integrations. The plaintext token in Tenant.settings.integrations.jira keeps working for nothing (no API endpoints actually read from it anymore) but the new flow encrypts it properly. New tenants connect via the standard form.

noteAdded — OAuth scope expansion

• •New scope bundle HUBSPOT_OAUTH_SCOPES_PHASE_2_5: Phase 2.4 bundle plus crm.objects.deals.read. UI canary HUBSPOT_DEAL_READ_SCOPE (single source of truth — UI checks scopes.includes(HUBSPOT_DEAL_READ_SCOPE)).
• •Connect route now requests the expanded bundle on every new flow. Existing tenants reconnect once; Phase 1+2.4 functionality keeps working until they do.
• •"Last touch" intentionally comes via the existing contacts.read scope (new contact property notes_last_contacted) instead of expanding into engagement scopes. One new scope total.

noteAdded — HubSpot deal client (`packages/channels/src/hubspot/deal-client.ts`)

• •listContactDeals(accessToken, contactId) — POST to /crm/v3/objects/deals/search with an associated-contact filter, sorts by hs_lastmodifieddate DESC, caps at 10 results.
• •Pinned property whitelist (HUBSPOT_DEAL_PROPERTIES) — never all-properties, never spread upstream deal.properties into responses. PII guardrail.
• •Two new HubspotOAuthError codes: CONTACT_DEALS_FETCH_FAILED, DEAL_FETCH_FAILED.

noteAdded — contact-sync property extensions (Phase 1 worker, transparent upgrade)

• •Sweep + webhook contact pull now includes notes_last_contacted + num_associated_deals. Surfaced in Customer.metadata.hubspot.lastContactedAt + .associatedDealCount. No schema change; the metadata blob is the same column.

noteAdded — API endpoints

• •GET /api/v1/customers/:id/hubspot — AGENT-gated, soft-degrading. Returns synced metadata (cheap) + live deal fetch (when scope granted). Discriminated response shape: enabled/linked/dealScopeGranted/dealsError ∈ {scope-missing, fetch-failed, null}. Live fetch never 5xx's — failure surfaces as dealsError: 'fetch-failed' so the UI degrades gracefully.
• •GET /api/v1/customers/:id extended to include hubspotContactId in the response shape.

noteAdded — UI card (`apps/web/src/components/agent/HubspotContextCard.tsx`)

• •Matches the approved preview at docs/ui-previews/hubspot-customer-context.html. Three states: (A) not linked → "Sync now" CTA, (B) linked + deal scope missing → reconnect banner + synced metadata, (C) full context → synced metadata + open deals + deep-link.
• •Self-hides when HubSpot isn't enabled on the deployment or the tenant has never connected. No empty placeholder.
• •Slots into the customer-detail left column between Custom fields and Activity.

noteAdded — tests (25 new)

• •deal-client.test.ts — 8 HTTP-shape tests covering search request body, contact filter, error codes, empty results, PII pinned-list guardrail.
• •oauth-client.test.ts — +4 scope bundle + deal-read canary + contact-property additions tests.
• •hubspot-contact-sync.test.ts — +2 mapping tests for lastContactedAt + associatedDealCount surfacing.
• •hubspot/route.isolation.test.ts — 11 contract tests for the new context route (AGENT gate, tenant isolation, soft-degrade discriminators, deep-link URL pattern, PII pinned-list).

noteOut of scope (deferred)

• •Owner email resolution (would need crm.objects.owners.read). UI shows the numeric ownerId. Revisit in 2.6 if agents complain.
• •Engagement timeline beyond notes_last_contacted. Would need a new scope per engagement type (calls/emails/meetings/notes). Defer until customers ask.
• •Recent closed-won deals. Currently only "open deals" are pulled. Easy add when needed.

noteTenant action required (one-time per workspace)

After deploy, tenants reconnect HubSpot (second reconnect in two ships) to grant the crm.objects.deals.read scope. Phase 1 + 2.4 surfaces keep working through the transition; the customer-detail card shows an inline "Reconnect to grant deals scope" banner until they do.

noteFixed — lint

• •Added eslint-config-next@14.2.21 + matching peer eslint@^8.57.0 to apps/web/package.json devDeps. Without this, next lint ran against the root .eslintrc.cjs only, which couldn't resolve react-hooks/exhaustive-deps / @next/next/no-img-element rules referenced via inline disable comments — exit 1 on every CI run.
• •New apps/web/.eslintrc.json extends next/core-web-vitals + disables the noisy react/no-unescaped-entities rule (apostrophes/quotes in JSX text — handled correctly by HTML parsers; rule is widely considered too noisy).
• •Removed 3 unused imports surfaced by the new linter:
• •Refactored a 4-case redirect switch into a map lookup in apps/web/src/app/(agent)/settings/developer/page.tsx/settings/developer/page.tsx) to clear no-fallthrough (the cases worked because redirect() throws, but the linter can't see that).

- Button from [apps/web/src/app/(agent)/customers/[id]/tickets/page.tsx](apps/web/src/app/(agent)/customers/[id]/tickets/page.tsx) - AlertTriangle from apps/web/src/app/(agent)/settings/deletion-approvals/page.tsx/settings/deletion-approvals/page.tsx) - EmptyState from apps/web/src/app/(agent)/settings/widget/page.tsx/settings/widget/page.tsx)

noteFixed — test

• •4 packages were missing per-package vitest.config.ts and inheriting the root config's include glob (packages/**/*.test.ts), which resolved relative to the package cwd and matched nothing. Result: pnpm test exited 1 on those packages with "No test files found."
• •Added per-package configs to packages/channels (170 tests now run), packages/config (13 tests), packages/events (0 tests, passWithNoTests: true), packages/integrations (0 tests, passWithNoTests).

noteVerified

• •pnpm lint — 14/14 tasks successful, 0 errors, 25 warnings (all pre-existing react-hooks/exhaustive-deps + no-img-element in unrelated UI code).
• •pnpm test — 12/12 tasks successful, 1,196 tests green across @helpmesh-io/sdk, config, db, core, auth, ai, reporting, channels, billing, worker.
• •pnpm --filter @helpmesh/web test:unit — 161 files, 1,483 tests green.
• •Combined: 2,679 unit tests green repo-wide.

noteAdded — schema

• •Thread.hubspotTicketId (nullable, unique-per-tenant) — stable link between a HelpMesh thread and its HubSpot ticket. Per-provider column (not reusing externalRef) so future Salesforce/Zendesk mirrors get their own slot.
• •HubspotIntegration.ticketPipelineId (nullable) — admin's pipeline pick. Null means ticket sync is disabled even if the OAuth scope was granted; cleared if the picked pipeline is deleted upstream.
• •HubspotIntegration.lastTicketSyncedAt (nullable) — telemetry watermark surfaced in the Integrations card.
• •Migration 20260516193000_tier3b2_hubspot_ticket_sync — additive only.

noteAdded — OAuth scope expansion

• •New scope bundle HUBSPOT_OAUTH_SCOPES_PHASE_2_4: Phase 1 scopes plus crm.objects.tickets.read, crm.objects.tickets.write, crm.schemas.tickets.read. Existing connections detect "ticket sync available" via the crm.objects.tickets.write canary; the Integrations card shows a "Reconnect to enable" banner until the tenant re-authorizes.
• •Connect route now requests the expanded bundle on every new flow.

noteAdded — HubSpot ticket client (`packages/channels/src/hubspot/ticket-client.ts`)

• •listTicketPipelines(accessToken) — enumerate the tenant's ticket pipelines.
• •getTicketPipelineById(accessToken, pipelineId) — returns null on 404 so the worker can auto-clear deleted-upstream picks.
• •createTicket(accessToken, input) — POST with optional contact association (typeId 16 = ticket→contact).
• •updateTicket(accessToken, ticketId, patch) — idempotent stage moves; returns null on 404 so the worker can drop the link.
• •Four new error codes on HubspotOAuthError: TICKET_PIPELINES_FETCH_FAILED, TICKET_PIPELINE_NOT_FOUND, TICKET_CREATE_FAILED, TICKET_UPDATE_FAILED.

noteAdded — pure mapping helpers (`apps/worker/src/processors/hubspot-ticket-mapping.ts`)

• •mapThreadStatusToStageId(status, stages) — partitions stages by metadata.isClosed === 'true' and maps OPEN→first open, PENDING→middle open, RESOLVED→first closed, CLOSED/SPAM→last closed. Returns null when the pipeline can't represent the status.
• •previewStageMapping(stages) — drives the picker UI's "stages will be mapped like this" caption.
• •mapThreadPriorityToHubspot(priority) — URGENT/HIGH → HIGH, NORMAL → MEDIUM, LOW → LOW (HubSpot has no URGENT).
• •composeTicketSubject({publicNumber, subject}) — prefixes [#1234] so agents bouncing between HelpMesh + HubSpot correlate at a glance.
• •composeTicketContent({customerLabel, channel, helpmeshUrl, firstMessageBody}) — capped at 500 chars of preview; full thread lives back in HelpMesh via deep-link.

noteAdded — worker processor (`apps/worker/src/processors/hubspot-ticket-sync.ts`)

• •Triggered by the outbox on thread.created and thread.status_changed. Loads thread + customer + integration under runWithTenant, applies guards, and either creates or updates the ticket.
• •Skip-and-log (NOT retry) on: integration missing/revoked, ticket scope missing, no pipeline picked, customer not yet linked to HubSpot, status doesn't map to any stage, pipeline deleted upstream.
• •BullMQ retry (3 attempts, exp backoff) on transient HubSpot errors.
• •Auto-recovery: 404 on getTicketPipelineById clears ticketPipelineId (reverts UI to "pick a pipeline"); 404 on updateTicket drops Thread.hubspotTicketId so the next event re-creates.
• •Job name hubspot-ticket-sync registered in the standard-queue dispatcher; deduplicated by outbox event id.

noteAdded — API endpoints

• •GET /api/v1/integrations/hubspot/ticket-pipelines — OWNER-only. Returns [{id, label, stages: [{id, label, displayOrder, metadata.isClosed}]}]. 409 if disconnected or scope missing.
• •PUT /api/v1/integrations/hubspot/ticket-pipeline — OWNER-only. Body {pipelineId}. Zod-validated. Verifies the pipeline still exists upstream before persisting (no stale picks); empty string clears the pick without disconnecting OAuth.
• •GET /api/v1/integrations/hubspot extended with ticketScopeGranted, ticketPipelineId, lastTicketSyncedAt, syncedTicketCount.

noteAdded — Integrations card UI (`apps/web/src/components/settings/HubspotTicketSyncSection.tsx`)

• •Matches the approved preview at docs/ui-previews/hubspot-ticket-sync.html. Three states: (A) scope missing → blue "Reconnect to enable" banner; (B) pipeline not picked → dropdown picker + "Enable ticket sync" CTA; (C) configured → status line + "Change pipeline" link.
• •"Reconnect" reuses the existing popup OAuth handler — Cancel-bug safe.
• •Stacks below the FREE-tier warning if both apply.

noteAdded — tests (89 new across 6 files)

• •hubspot-ticket-mapping.test.ts — 18 mapping tests covering all status/priority/stage edge cases.
• •ticket-client.test.ts — 13 HTTP-shape tests for the four ticket helpers (associations, 404 handling, error codes).
• •hubspot-ticket-sync.isolation.test.ts — 14 contract tests for the worker processor + outbox dispatch (tenant isolation, every guard, idempotency, auto-recovery, 3-attempt retry).
• •ticket-pipelines/route.isolation.test.ts + ticket-pipeline/route.isolation.test.ts — 16 route-level isolation tests (OWNER gate, tenant scope, 409 paths, Zod validation, scope gate, never-expose-tokens).
• •oauth-client.test.ts — +2 scope-bundle assertions.

noteOut of scope (deferred to alpha.78+)

• •Reverse direction (HubSpot Ticket → HelpMesh Thread).
• •HelpMesh agent → HubSpot owner mapping (tickets sync unassigned in 2.4).
• •Reply threading (HelpMesh messages → HubSpot ticket conversation timeline).
• •Phase 2.5 customer-detail panel (HubSpot card on the customer page).

noteTenant action required (one-time)

After deploy, every tenant on the Free/Starter/Pro tier needs to: Settings → Integrations → HubSpot → Disconnect → Reconnect (grant new ticket scopes at HubSpot's consent screen) → pick a pipeline. Contact sync continues working through the entire transition; ticket sync activates the moment the pipeline is picked.

noteAdded — schema

• •HubspotIntegration.hubspotPortalId is now indexed. The webhook endpoint identifies the source integration by HubSpot's portalId (NOT our internal tenantId — HubSpot has no concept of HelpMesh tenants). Without this index every webhook fire would be a table scan.
• •Migration 20260516020824_tier3b2_hubspot_portal_index — additive only (new index, no data migration).

noteAdded — HubSpot REST client

• •`getContactById(accessToken, contactId)` — targeted single-contact fetch with the locked property list. Returns null on 404 (HubSpot deleted the record between event emission and our fetch — treat as deletion).
• •`verifyWebhookSignature(input)` — HubSpot's v3 HMAC algorithm: HMAC-SHA256(secret, method+fullUrl+rawBody+timestamp), 5-min replay window, constant-time comparison. Uses Web Crypto so it works in both Node and Edge runtimes. Typed result discriminates MISSING_HEADERS / STALE_TIMESTAMP / BAD_SIGNATURE so callers can log the precise reason internally without leaking it back to HubSpot.
• •New CONTACT_FETCH_FAILED error code in the HubspotOAuthError discriminator.
• •9 new unit tests: getContactById (fetch shape, 404→null, other-failure error), verifyWebhookSignature (happy path + 5 rejection paths including proxy-rewrite defense).

noteAdded — webhook endpoint

• •`apps/web/src/app/api/v1/integrations/hubspot/webhook/route.ts` — POST, public (no apiHandler), reads raw body before parsing (HMAC covers exact bytes), verifies signature against appUrl() (NOT req.url, defends against ALB rewrites), looks up integration by portalId via runWithSuperAdmin (cross-tenant query, no tenant context on inbound webhooks), enqueues one hubspot-contact-webhook job per event. De-dup keyed on (portalId, objectId, subscriptionType, occurredAt) so HubSpot's retry storms collapse safely.
• •Responds 401 on signature failure WITHOUT echoing the verify reason (anti-probe).
• •Responds 200 with { accepted: true, queued: N } on success. ACKs fast — slow work happens in the worker.
• •9 isolation-contract tests covering the public-route shape, raw-body-before-parse ordering, HMAC verification call site, 401-on-failure shape, cross-tenant lookup via superAdmin, de-dup jobId, response payload doesn't leak tenantId / refresh tokens.

noteAdded — worker

• •`apps/worker/src/processors/hubspot-contact-webhook.ts` — handles a single event:
• •Tenant isolation: payload carries tenantId (resolved by the webhook route from the source portalId); every prisma call runs inside runWithTenant.
• •Wired into worker's PROCESSOR_MAP as hubspot-contact-webhook.

- contact.creation + contact.propertyChange → re-fetch via getContactById + upsert through the shared upsertContact helper (same path the sweep worker uses). - contact.deletion → soft-delete the linked Customer (set deletedAt, clear hubspotContactId). - 404 from HubSpot during fetch → treat as deletion (idempotent soft-delete).

noteOperational notes

• •Migration runs via deploy.sh prod --migrate.
• •No env-var or task-def change — HUBSPOT_CLIENT_SECRET (already wired on web + worker since alpha.72+.74) is the HMAC key.
• •User must complete the HubSpot dev portal webhook subscription: in the Legacy Apps → HelpMesh app → "Webhooks" tab, set the target URL to https://helpmesh.io/api/v1/integrations/hubspot/webhook and subscribe to contact.creation, contact.propertyChange (on properties email/firstname/lastname/phone/company/lifecyclestage/hubspot_owner_id), and contact.deletion. Until that step is done, the endpoint exists but never fires — the 15-min cron from alpha.75 continues to handle sync.
• •Defers to alpha.77+: crm.objects.tickets.write scope expansion + Thread → Ticket sync (biggest remaining piece).

noteAdded — manual sync

• •`apps/web/src/app/api/v1/integrations/hubspot/sync/route.ts` — POST (OWNER-only) endpoint. Calls enqueueHubspotContactSync({ tenantId }), returns 202 Accepted with the BullMQ job id. Idempotent (queue de-duplicates by jobId = hubspot-contact-sync:<tenantId>).
• •8 isolation-contract tests covering OWNER gate, tenant scope, disabled short-circuit, revoked-row 409, 202 shape, queue-failure 503 path, no token leakage.

noteAdded — cron fanout

• •`apps/worker/src/processors/hubspot-sync-fanout.ts` — cross-tenant fanout. Single findMany (runWithSuperAdmin-wrapped because there's no tenant context for a cron), one queue add per active integration. Per-tenant failures don't abort the loop.
• •Registered on the low queue with a 15-minute scheduler (hubspot-sync-fanout-cron).

noteAdded — UI feedback on the integration card

• •`apps/web/src/app/api/v1/integrations/hubspot/route.ts` — GET response now includes syncedContactCount (cheap count of Customer WHERE tenantId = ? AND hubspotContactId IS NOT NULL, indexed).
• •`apps/web/src/components/settings/HubspotIntegrationCard.tsx` — new "Sync now" button (RefreshCw icon, spins while queueing). Last-synced line displays "Last synced 5m ago · 142 contacts" using a relative-time formatter. Polls the status endpoint 8 s after a manual trigger so the contact count visibly updates without a page reload.

noteNote

• •No schema change. No migration.
• •Worker task-def :4 (set in alpha.74) already had the env wiring; nothing to update.
• •Defers to alpha.76: webhook handler for upstream live updates. Defers to alpha.77+: crm.objects.tickets.write scope expansion + Thread → Ticket sync.

noteAdded — schema

• •`Customer.hubspotContactId String?` + @@unique([tenantId, hubspotContactId]) + @@index([hubspotContactId]). Per-provider column rather than reusing externalId so future Salesforce/Zendesk sync workers can layer in without collision.
• •Migration 20260516012526_tier3b2_hubspot_contact_link — additive only: new nullable column + new unique constraint + new index. Existing customers unaffected until a worker run links them.

noteAdded — HubSpot REST client

• •`packages/channels/src/hubspot/oauth-client.ts` — listContactsModifiedSince(accessToken, sinceMs, after?) wraps POST /crm/v3/objects/contacts/search with the hs_lastmodifieddate >= since filter, ASC sort (deterministic high-water-mark advancement), and the locked property list (email, firstname, lastname, phone, company, lifecyclestage, hubspot_owner_id, hs_lastmodifieddate).
• •Added CONTACT_SEARCH_FAILED to HubspotOAuthError.code discriminator.
• •5 new unit tests covering request shape, no-filter-on-first-sync, cursor pagination, response passthrough, and the new error code.

noteAdded — worker

• •`apps/worker/src/lib/hubspot-token.ts` — worker-side mirror of the web token store. AES-256-GCM via shared GOOGLE_TOKEN_ENCRYPTION_KEY, refreshes on demand, auto-marks revokedAt on invalid_grant. No circuit-breaker (BullMQ's retry+backoff already handles the upstream-flaky case).
• •`apps/worker/src/processors/hubspot-contact-sync.ts` — processes the hubspot-contact-sync job: pages through modified contacts (capped at 5 pages = ~500 contacts per job), upserts each as a Customer, advances lastSyncedAt. Idempotent (re-running same window is a no-op), tenant-scoped on every prisma call.
• •`apps/worker/src/processors/hubspot-contact-mapping.ts` — pure helpers (composeName, mergeHubspotMetadata) extracted so unit tests don't drag in the token-store/prisma dependency chain.
• •9 new unit tests covering name composition (whitespace, missing sides), metadata merging (namespace preservation, defensive non-object handling, re-sync overwrite, null fallbacks).
• •Match strategy: existing-by-hubspotContactId → update in place; existing-by-email with no link → adopt; otherwise create fresh row. Never steals a customer already linked to a different HubSpot id.

noteAdded — web app

• •`apps/web/src/lib/hubspot/sync-queue.ts` — enqueueHubspotContactSync({ tenantId }) adds a job to the standard queue, de-duped by jobId = hubspot-contact-sync:<tenantId> so back-to-back enqueues collapse.
• •`apps/web/src/app/api/v1/integrations/hubspot/callback/route.ts` — after the upsert, fires enqueueHubspotContactSync({ tenantId }). Failure is logged + swallowed so an enqueue glitch doesn't break the connect flow.

noteOperational notes

• •Worker task-def `helpmesh-prod-worker:4` registered with the four HubSpot env entries (HUBSPOT_ENABLED + HUBSPOT_CLIENT_ID + HUBSPOT_CLIENT_SECRET + GOOGLE_TOKEN_ENCRYPTION_KEY) — the web task-def was wired in alpha.72 already.
• •Migration applies via --migrate. Additive only.
• •Phase 2.2 (alpha.75): manual sync button + cron poll every 15 min. Phase 2.3 (alpha.76): webhook handler with HMAC verification. Phase 2.4 (alpha.77+): ticket-write scope expansion + Thread → Ticket sync.

noteFixed — Branding live preview was blank

• •`apps/web/next.config.mjs` — the global security headers were setting X-Frame-Options: DENY + CSP frame-ancestors 'none' for every path, including /preview/branding. The branding settings page tries to embed /preview/branding?surface=help as a same-origin iframe and was blocked.
• •Scoped a more permissive override at /preview/:path*: X-Frame-Options: SAMEORIGIN + CSP frame-ancestors 'self'. Other routes keep the strict global headers.
• •Refactored the CSP construction to share directives between the strict (global) and same-origin (preview) variants — only frame-ancestors differs.

noteFixed — HubSpot "Cancel" navigated away from HelpMesh

• •`apps/web/src/components/settings/HubspotIntegrationCard.tsx` — the Connect button now opens the OAuth flow in a centered popup window (600×760). HubSpot's Cancel button on the consent screen navigates the popup to www.hubspot.com and the main HelpMesh tab is preserved. If the popup is blocked, falls back to a same-tab navigation so the existing ?hubspot=<status> callback handling still works.
• •`apps/web/src/app/api/v1/integrations/hubspot/callback/route.ts` — the callback HTML now branches at runtime: if window.opener is present, post a hubspot-oauth-result message to the opener (with the status string) and window.close(). Otherwise fall back to the original meta-refresh redirect to /settings/integrations?hubspot=<status>.
• •The integration card now listens for the postMessage and reloads its connection state in-place — no full-page reload, no flicker.

noteNote

• •Pure UI / config / client-side wiring. No schema, no migration, no API contract change.
• •HubSpot's Cancel behavior is non-spec-compliant (real OAuth servers should redirect_uri with error=access_denied). The popup is a defensive wrapper around HubSpot's UX choice; if HubSpot ever fixes this, the popup pattern still works.

noteAdded — OAuth flow

• •`packages/channels/src/hubspot/oauth-client.ts` — REST client with buildAuthorizationUrl, exchangeCodeForTokens, refreshAccessToken, revokeToken, fetchAccountInfo. Maps HubSpot's invalid_grant response onto a typed HubspotOAuthError so callers can mark the integration revoked. Phase 1 scopes locked at oauth + crm.objects.contacts.read + crm.objects.companies.read.
• •`packages/channels/src/hubspot/oauth-client.test.ts` — 11 unit tests covering authorize-URL shape, token-exchange body format (form-encoded with client creds in body, NOT HTTP Basic — different from Zoom), refresh-token rotation, revoke 200/204/404 handling, access-token introspection with tier fallback.

noteAdded — token store + refresh circuit

• •`apps/web/src/server/hubspot/token-store.ts` — mirrors server/zoom/token-store.ts. getValidHubspotAccessToken(tenantId) decrypts the cached access token, refreshes when within 60 s of expiry, persists the rotated refresh token (HubSpot rotates on every refresh — same as Zoom), and auto-marks revokedAt on invalid_grant. Shares the refresh circuit-breaker with Google + Zoom, namespaced as ${tenantId}:hubspot so a HubSpot outage doesn't open the circuit for the other providers.

noteAdded — API routes

• •`apps/web/src/app/api/v1/integrations/hubspot/connect/route.ts` — GET (OWNER-only) signs a 10-minute state token and 302s to HubSpot's /oauth/authorize.
• •`apps/web/src/app/api/v1/integrations/hubspot/callback/route.ts` — public, verifies the signed state, exchanges code for tokens, calls fetchAccountInfo (token introspection + tier endpoint), upserts the HubspotIntegration row with encrypted refresh + access tokens.
• •`apps/web/src/app/api/v1/integrations/hubspot/route.ts` — GET returns connection state (portal id, account email, tier, scopes, last-used) for the integration card. DELETE (OWNER-only) best-effort revokes upstream then marks revokedAt locally.
• •`apps/web/src/app/api/v1/integrations/hubspot/route.isolation.test.ts` — 7 contract tests asserting apiHandler + tenant-scoping on every prisma.hubspotIntegration call, OWNER guard on DELETE, no encrypted-token leakage in the response shape, revoked rows treated as not-connected.

noteAdded — Settings UI

• •`apps/web/src/components/settings/HubspotIntegrationCard.tsx` — Connect / Disconnect card with HubSpot orange (#FF7A59), Connected as ... display from hubspotAccountEmail, FREE-tier warning chip, callback-status messages mapped from the ?hubspot=... query param.
• •`apps/web/src/app/(agent)/settings/integrations/page.tsx` — mounted the new card alongside Google Meet + Zoom; removed the dead coming-soon HubSpot tile from the providers grid.
• •`apps/web/src/app/(agent)/settings/layout.tsx` — added Integrations entry to the settings sub-nav under the Developer section (Plug icon, above API keys). Every integration card the page hosts — Slack, Zapier, Jira, Webhooks, Google Meet, Zoom, HubSpot — was previously only reachable by typing /settings/integrations directly.

noteOperational notes

• •Requires HUBSPOT_ENABLED=true + HUBSPOT_CLIENT_ID + HUBSPOT_CLIENT_SECRET + GOOGLE_TOKEN_ENCRYPTION_KEY injected via ECS task-def. Web task-def helpmesh-prod-web:30 registered with these entries; secrets stored at helpmesh-prod/hubspot-client-id + helpmesh-prod/hubspot-client-secret. IAM execution role (helpmesh-prod-ecs-execution) already covers the path.
• •Migration 20260515073000_tier3b2_hubspot_integration (groundwork commit 6e1c9d7) applies on this deploy via --migrate. Adds the HubspotIntegration table + HubspotAccountTier enum, fully additive.
• •Phase 2 (alpha.73+): bidirectional sync workers (Contact → Customer, Thread → Ticket), webhook handler for upstream changes, ticket-write scopes added to OAuth consent.

noteFixed — FIX-4: customer portal `/portal/new`

• •`apps/web/src/app/(customer)/portal/new/page.tsx` — made the Subject field required (min 3 chars, both client validation + submit-button guard) so agents stop receiving titleless body-walls.
• •Replaced the hardcoded "Our team typically responds within 2 hours" footer with generic "We'll reply by email and you'll see updates here in the portal." The 2-hour promise was untrue for any tenant whose SLA differs from the default. Per-tenant response-time copy will surface once /api/widget/v1/sessions exposes the inbox SLA target (separate follow-up).

noteFixed — FIX-5: agent profile page stale stubs

• •`apps/web/src/app/(agent)/settings/profile/page.tsx` — the Security section had three "Read only" / "Coming soon" badges (Password / MFA / Active sessions) that all shipped real on /settings/security back in FIX-1 (alpha.62). Replaced the dead badges with Change password → / Manage MFA → / View devices → Link buttons that route to the actual surfaces.
• •Replaced the dead Generate personal token (coming soon) disabled button with a new "API access" section that links to /settings/developer (where tenant API keys already work). Description acknowledges that per-user tokens are still on the roadmap rather than pretending they're days away.

noteNote

• •Pure UI / copy / routing changes. No schema, no migration, no API contract change.
• •Removes three stale TODO(PR-E) / TODO(PR-F) comments from the profile page.

fixFixed

• •`apps/web/src/app/(agent)/onboarding/page.tsx` — replaced the fake handleConnect() toggle (and connectedChannels local state) with three <Link> cards that route to the real setup surfaces:
• •Removed the dead Support Email input field. Real email setup lives on the dedicated settings page where Postmark verification, domain check, and forwarding-address generation actually happen.

- Email → /settings/channels/email (Postmark inbound forwarding) - Live Chat Widget → /settings/widget (embed script + branding) - Slack → /settings/integrations/slack (OAuth) Each card shows a "Set up →" affordance with an external-arrow icon. Subcopy clarifies "You can come back here anytime."

noteNote

• •Honest UX. No more green "Connected" badges for things that aren't connected.
• •Tier-3 onboarding restyle preserves the wizard shell, progress stepper, and Branding / Team / Ready steps unchanged.

fixFixed

• •`apps/web/src/middleware.ts` — removed /knowledge from PROTECTED_PREFIXES. The marketing page at apps/web/src/app/(marketing)/knowledge/page.tsx (Open Graph + JSON-LD enabled, listed in the AI-crawler carve-out per anti-scraping.md) now serves 200 to anonymous visitors. Tenant-facing public articles live under /[tenantSlug]/articles/[slug] and were never affected by this prefix.
• •`apps/web/src/__tests__/middleware-auth-gate.test.ts` — updated assertions: /knowledge and /knowledge/anything now expected false in the public-surface group, dropped from the protected-surface group. Test count unchanged at 9.

noteNote

• •Pure middleware fix. No schema, no migration, no API change.
• •Surfaces this affected: every link to /knowledge, the public-features OG image / share link, indexed search engine results pointing at the page.

fixFixed

• •`apps/web/src/app/(agent)/home/page.tsx` — gated COUNT-style KPIs through a single isEmptyWorkspace = totalThreadCount === 0 signal, reusing the same value that already drives the onboarding checklist (no new fetch). Applied across all four KPI surfaces:
• •Once the first thread arrives, totalThreadCount flips positive and every card reverts to live numbers. Derived metrics (avg response, CSAT, SLA) keep their existing inline != null em-dash paths unchanged.

- TeamKpis: Open tickets value + subtitle + sparkline em-dash when empty - AgentKpis: My open tickets + Awaiting first reply em-dash + subtitle swap - Admin "Your queue" (inline, uses analyticsMine): My open tickets + My new today + My pending replies em-dash + subtitle swap - ViewerKpis (historical view): all four count cards (Total tickets, This month, Resolved, Resolution rate) em-dash when historical.totalAllTime === 0

noteNote

• •Pure presentation change. No new endpoint, no schema change, no extra fetch.
• •Sparkline is hidden in the empty state (not a flat baseline) — a sparkline of zeros reads as misleading.

fixFixed

• •`packages/auth/src/config.ts` — added pages.error: '/login' so NextAuth routes every auth error back to the login page with ?error=<code> instead of its stock "Server error" card.
• •`apps/web/src/app/(auth)/login/page.tsx` — read ?error=<code> via useSearchParams and feed it into the existing error state. New describeAuthError() helper maps NextAuth codes (AccessDenied, OAuthAccountNotLinked, CredentialsSignin, SessionRequired, default) to user-readable messages. Raw codes are never echoed — they leak implementation details.

noteNote

• •Pure UI/config polish. No schema, no migration, no API change.

fixFixed

• •`packages/auth/src/config.ts` — added a helpmeshUserAdapter() wrapper around PrismaAdapter(prismaUnscoped). Overrides createUser and updateUser to translate emailVerified → emailVerifiedAt and image → avatarUrl on the way in, and back on the way out. Reads (getUser*, linkAccount) flow through untouched — NextAuth treats the row's extra fields as opaque user data.

noteNote

• •Cheaper than renaming columns: a global rename would force a migration + every call-site rewrite across the repo. Adapter-boundary translation keeps the schema stable.
• •No new tests added — existing 21 auth tests still pass. Adapter behaviour to be verified by user dogfooding Google sign-in with a brand-new account post-deploy.

fixFixed

• •`packages/auth/src/config.ts` — moved the HASH_SECRET resolution + production-only throw out of module scope into a lazy getHashSecret() called by deviceFingerprint and ipHash. Next.js' next build "Collect page data" step imports every route module to read its runtime config; a module-level throw killed the entire build even though no request was being served. Every staging + production CI run has been failing since alpha.62 because of this — local deploys via scripts/deploy.sh were unaffected (Docker BuildKit cache reused a layer that pre-dated the throw). The throw still fires at request time when the env var is genuinely missing.
• •`apps/web/src/app/(agent)/layout.tsx` — when useSession().status === 'unauthenticated', the alpha.64 redirect called router.replace('/login') but left the stale session cookie in place. Edge middleware on /login saw hasSessionToken() === true and bounced the user back to /inbox, so client-side navigation appeared to "do nothing." Switched to signOut({ callbackUrl }) so the cookie is cleared before the redirect; added a useRef guard to keep React's effect re-runs from queueing parallel signOut calls.
• •`apps/web/src/app/(auth)/login/page.tsx` — "Start a free trial" was <a href="mailto:hello@helpmesh.io"> (legacy stub from before signup was built). Pointed at /signup like every marketing CTA. next/link was already imported.

noteNote

• •No schema changes, no migration. Pure code-only redeploy.
• •Outstanding: Google OAuth prisma.user.create() fails for brand-new users (existing Google accounts work because PrismaAdapter findUniques them). Separate User-schema issue, will ship as its own alpha.

fixFixed

• •`apps/web/src/app/(agent)/layout.tsx` — added a useEffect that calls router.replace('/login?callbackUrl=...') when useSession().status flips to 'unauthenticated'. Self-corrects on the next NextAuth session-poll cycle (~30s) or immediately on hard refresh. Closes the loop on FIX-1's sign-out-everywhere UX.

noteNote

• •Pure UI change. No schema, no migration, no API surface changes.

fixFixed

• •`packages/auth/src/config.ts` — widened the HASH_SECRET cascade to IP_HASH_SECRET ?? IP_HASH_SALT ?? NEXTAUTH_SECRET ?? AUTH_SECRET. Matches what every other module in the repo already accepts (apps/web/src/lib/impersonation.ts, apps/web/src/app/api/v1/integrations/*/route.ts, apps/web/src/lib/env-secrets.ts). Throw message updated accordingly.

noteNote

• •No schema changes, no migration. Code-only redeploy.
• •Pre-landing review miss: auth-package tests don't run under NODE_ENV=production, so the module-import throw was invisible until prod boot. Follow-up to add a NODE_ENV=production smoke test for the auth package import.

featureAdded

• •`UserDevice` model + `User.tokenVersion` + `User.passwordLastChangedAt` (additive migration 20260514183304_fix1_user_device_tracking). One row per (userId, fingerprint). User-scoped (a User can belong to multiple tenants), not tenant-scoped.
• •`events.signIn` callback in @helpmesh/auth: upserts one UserDevice per sign-in (Credentials + OAuth) using a stable SHA-256 fingerprint over UA + Accept-Language + per-user salt. IPs are hashed with SHA-256 + per-user salt per data-handling.md — raw IPs are never stored. UA truncated to 256 chars for forensics. Sign-in always succeeds even if device tracking errors.
• •`GET /api/v1/users/me/sessions` — returns the current user's active devices ordered by lastSeenAt, with the row matching the current request's fingerprint marked isCurrent: true.
• •`DELETE /api/v1/users/me/sessions` — "Sign out everywhere." In one transaction: increments User.tokenVersion (the session() guard rejects every JWT carrying the old version) and marks every non-current UserDevice row revoked. The caller is also logged out and bounces to /login.
• •`tokenVersion` guard in the NextAuth session() callback: invalidates any JWT whose embedded tokenVersion is older than the current User.tokenVersion. Backward-compatible — tokens issued before this version have no embedded version and are auto-bumped on next sign-in.
• •Exposed helpers from @helpmesh/auth: deviceFingerprint, deviceLabel, ipHash (all SHA-256, all per-user-salted, all truncated for storage).

featureChanged

• •`POST /api/v1/auth/change-password` — replaced the no-op Session.deleteMany() (the Session table is empty under JWT strategy) with real session invalidation: tokenVersion++, passwordLastChangedAt = now, mark every UserDevice revoked, all in a single transaction. UI now redirects to /login after the response. Argon2 imports swapped to the existing @helpmesh/auth hashPassword / verifyPassword wrappers — removes the dev-only Function('return import("argon2")') indirection that broke under Next 14 dev mode ESM resolution.
• •Security page UI — removed the Potemkin "Chrome on macOS, Dubai" fallback. Empty state now renders "No active sessions." instead of fake demo rows. Added formatLastActive() relative-time helper. "Sign out all other sessions" redirects to /login because the tokenVersion bump kills the current device's JWT too.
• •`@helpmesh/auth` — added next as a peerDependency so import { headers } from 'next/headers' resolves cleanly. The package only uses next/headers inside the events.signIn request-context block.

securitySecurity

• •Sign out everywhere is now real. Bumping User.tokenVersion invalidates every active JWT for that user at the session() guard, not just one cookie.
• •Forced rotation on password change. Changing your password now invalidates every device in one transaction (forensic-grade audit trail via revokedAt timestamps).
• •No raw IPs stored. Per data-handling.md, IPs are PII under GDPR — UserDevice.ipHash is a 24-char SHA-256 prefix with a per-user salt.

noteTest coverage

• •End-to-end verified on the dev stack (5/5 pass): credentials sign-in resolves session; GET sessions returns the real device row marked isCurrent; second sign-in collapses to the same row id (upsert correctness); DELETE sessions bumps tokenVersion and the next /api/auth/session returns null; POST change-password returns 200, bumps tokenVersion, sets passwordLastChangedAt, revokes devices, and invalidates the current JWT.

noteSchema (additive migration)

• •New Tag model: tenant-scoped, soft-delete tombstone, locked palette color, free-form group for UI clustering. Unique (tenantId, key). key is immutable after creation.
• •New CustomerTag join: tenant-scoped, (customerId, tagId) unique. appliedByRuleId attribution distinguishes manual edits from rule firings.
• •New TagRule model: tenant-scoped, JSONB condition validated by Zod, trigger enum (PERIODIC ships now; EVENT lands in tier-3b/3). matchedCount + lastEvaluatedAt backfilled by the evaluator.
• •TagKind enum (PLAN / AUTO / MANUAL) + TagRuleTrigger enum.

noteZod (@helpmesh/core)

• •TagKeySchema enforces lowercase kebab-case, max 60 chars, starts with letter. Stable identifier referenced by automation rules + (future) CRM sync.
• •TagRuleConditionSchema is a discriminated union over op (count_gt/_gte/_lt, avg_lt/_gt, no_activity_days_gt, plan_tier_in). Closed source enum (thread/csat/customer/plan). Hard caps: numeric value 0..100_000, windowDays 1..365, windowCount 1..50, plan_tier_in.value ≤ 20.
• •UpdateTagSchema omits key and kind — Zod silently strips client attempts; immutability is the security model.
• •TAG_LIMITS constants: 200 tags + 50 active rules per tenant + 4-hour evaluator cadence + reserved PLAN keys (vip/enterprise/growth/standard).

noteAPI (10 new routes)

• •GET /api/v1/tags — list with customerCount inline (groupBy)
• •POST /api/v1/tags — ADMIN — create MANUAL tag; rejects reserved keys with 422
• •PATCH /api/v1/tags/:id — ADMIN — update (label/color/description/group); rejects PLAN with 422
• •DELETE /api/v1/tags/:id — ADMIN — soft-delete tombstone; rejects PLAN with 422
• •POST /api/v1/tags/:id/apply/:customerId — AGENT+ — manually tag a customer; rejects PLAN+AUTO with 422
• •DELETE /api/v1/tags/:id/apply/:customerId — AGENT+ — untag; same PLAN+AUTO rejection
• •GET /api/v1/tag-rules — list rules
• •POST /api/v1/tag-rules — ADMIN — create rule; promotes MANUAL → AUTO on first rule attachment; rejects PLAN target with 422
• •PATCH /api/v1/tag-rules/:id — ADMIN — update; honors the active-rule cap on flipping isActive
• •DELETE /api/v1/tag-rules/:id — ADMIN — hard delete (rules aren't customer data)

noteWorker

• •New tag-rule-evaluator processor sweeps every 4 hours (TAG_LIMITS.evaluatorIntervalMinutes). For each active PERIODIC TagRule:
• •Skips rules whose target tag is tombstoned. Closed-shape Prisma queries — no $queryRaw / $executeRaw.

1. Defensive TagRuleConditionSchema.safeParse(rule.condition) (drift guard — drift-detected rules log + continue rather than auto-disable). 2. Resolve into a closed-shape Prisma query (no raw SQL paths) for each source × op combination. 3. Diff matched customers vs currently-applied appliedByRuleId = rule.id rows. 4. Add missing / remove orphaned in a single per-rule prisma.$transaction; emit one customer.tag_applied / customer.tag_unapplied OutboxEvent per change. 5. Bump rule.matchedCount + rule.lastEvaluatedAt.

noteUI

• •/settings/tags (NEW) — three stat tiles, tag groups (PLAN rendered read-only), and the auto-rules card. Closed-set condition builder modal with 4 concrete shapes (thread volume / CSAT avg / no-activity days / plan-tier in) mapped to the closed-enum server schema via serializeCondition.
• •/settings/security (modified) — adds two nav cards at the top (IP allowlist + SSO) with anchor IDs so cross-page deep links resolve here. Full visual consolidation deferred to a tier-3b/1b polish PR; this delivers the user-visible "one place to go for security" outcome without rewriting the existing 575-line page.
• •Settings sidebar gets a "Tags" entry under "Content & Tagging" between Labels and Knowledge base.

noteOpenAPI

• •2 new response schemas (Tag, TagRule) + 10 new route registrations.

noteTests (+97 net)

• •Core: +34 schema tests (regex, hard caps, discriminated-union narrowing, immutable-key + immutable-tagId guards)
• •Web: +46 isolation tests across 5 route files (~9 source-introspection assertions each)
• •Worker: +17 tests (matchesNumeric pure-function + 11 source-introspection on the evaluator transaction shape)
• •Net totals: core 563 + web 1443 + worker 97 = 2103 passing

noteLocked decisions (from scope §4 + §6)

• •PLAN tags are auto-derived from billing. Reserved keys reject user creation with 422.
• •`Tag.key` is immutable after creation. UpdateTagSchema omits key; client attempts are silently stripped at the Zod boundary.
• •PLAN + AUTO tags reject manual apply/unapply with 422. The evaluator owns AUTO rows, billing sync owns PLAN.
• •MANUAL → AUTO auto-promotion when first rule attaches. Evaluator becomes source of truth.
• •Cross-tenant lookups return 404, not 403. No information disclosure.
• •Caps: 200 tags + 50 active rules per tenant. Evaluator at 4-hour cadence.

noteDeferred to tier-3b/2 + tier-3b/3

• •HubSpot (tier-3b/2): OAuth + webhook receiver + sync queue + Tag ↔ HubSpot property mirror.
• •Salesforce + Jira (tier-3b/3): reuses HubSpot scaffolding; wires Automation.conditions to read customer.hasTag(); activates EVENT-trigger TagRule sweeps.
• •Variant 4 full visual consolidation: nav cards + anchors ship now; the stacked single-page section layout from the preview is a polish PR.

noteRefs

• •Scope doc: docs/plans/pr-tier-3b-1-scope.md
• •Preview anchors: docs/ui-previews/integrations-and-extras.html Variant 4 (lines 629–764) + Variant 14 (lines 1703–1824)
• •PR: #120

noteSchema (additive migration)

• •New SavedReport model: tenantId, name, definition (JSONB validated by Zod), schedule (enum-mapped preset), scheduleRecipients, shareToken + shareTokenIssuedAt + shareTokenExpiresAt, pinned, createdById, deletedAt + deletedById (tombstone soft-delete). Unique on (tenantId, name). Indexes on (tenantId, deletedAt), (tenantId, pinned), (tenantId, schedule). No backfill.

noteZod (@helpmesh/core)

• •ReportDefinitionSchema with closed enums for source (threads/agents/csat), chart (bars/line/area/donut/table/big-number), dimension field, measure aggregator, filter op. Hard caps: dimensions ≤ 3, measures 1..5, filters ≤ 10. Custom date-range validates the 90-day span at the union level.
• •CreateSavedReportSchema, UpdateSavedReportSchema, SetScheduleSchema, ShareTokenIssueSchema.
• •SAVED_REPORT_LIMITS constants pin the 30-day share lifetime, dual rate-limit (10/min/token + 30/min/IP), and 3-failure auto-disable threshold.
• •SCHEDULE_PRESET_TO_CRON maps the 4 fixed presets to cron expressions server-side — no raw cron from input.

noteAPI (12 new routes)

• •GET /api/v1/reports/saved — pinned-first list, cursor pagination
• •POST /api/v1/reports/saved — create (AGENT+)
• •GET /api/v1/reports/saved/:id — read one (404 for cross-tenant)
• •PATCH /api/v1/reports/saved/:id — update (creator OR ADMIN)
• •DELETE /api/v1/reports/saved/:id — soft-delete tombstone
• •POST /api/v1/reports/saved/:id/preview — read-only live composition
• •POST /api/v1/reports/saved/:id/share — ADMIN — issue/rotate share token (returns token ONCE)
• •DELETE /api/v1/reports/saved/:id/share — ADMIN — revoke
• •POST /api/v1/reports/saved/:id/schedule — ADMIN — set schedule + recipients (validated against tenant membership)
• •DELETE /api/v1/reports/saved/:id/schedule — ADMIN — clear schedule
• •POST /api/v1/reports/saved/:id/pdf — enqueue one-off PDF render
• •GET /api/v1/public/reports/:shareToken — no auth, token-only; crypto.timingSafeEqual compare; dual rate-limit; 410 on expiry, 404 on revoked/unknown; renders tenant branding (logoUrl + brandingTokens.primaryColor)

noteWorker

• •New scheduled-report processor on a 5-minute sweep. Reads SavedReport rows with non-null schedule whose preset's mapped cron lands in the current sweep window, emits report.pdf_requested OutboxEvent into the existing report-pdf-generate processor for fanout. Auto-disables a schedule after 3 consecutive failures in a 24h window (matches Phase W webhook auto-disable pattern, scaled down because cron firings are rarer).

noteUI

• •/reports/builder — three-pane builder (field library left, canvas center, live preview right). Click-to-add field pills (keyboard-first; no drag-drop needed for a11y or completeness). Chart-type segmented control (bars/line/area/donut/table/big-number). Below 1024px shows "Open on desktop to edit" empty state.
• •/reports/builder/:id — edit existing saved report. Server-side resolves the row via runWithTenant before hydrating the client.
• •/reports/saved — pinned-first index with inline pin/unpin/delete. EmptyState CTA links straight to /reports/builder.
• •/r/:token — public read-only viewer. Tenant branding ON (Q3 locked decision): renders tenant logo in header, primary color as header border-bottom, HelpMesh footer attribution non-removable.
• •/reports — header gets "+ New report" + "My reports" CTAs (single-import touch).

noteOpenAPI

• •12 new route registrations + 2 new response schemas (SavedReport, SavedReportShareToken) in packages/core/src/openapi/registrations.ts. /api/v1/openapi will surface the real shapes post-deploy.

noteTests (+112 net)

• •Core: 42 schema tests covering enum boundaries, hard-cap rejections, date-range 90-day span, filter injection-guard regex.
• •Web: 56 isolation tests across 7 route files (source-introspection regex over each handler — fast, no DB, catches contract regressions).
• •Worker: 14 tests against shouldFireNow cron matching + source-introspection on the failure-counting + auto-disable transaction shape.
• •Net totals: core 529 + web 1397 + worker 80 = 2006 passing.

noteLocked decisions (from scope §14)

• •Share-token lifetime 30 days (Q1 lock).
• •Schedule presets 4 fixed — Mon 9am, Fri 5pm, monthly 1st 9am, daily 8am — no raw cron from input (Q2 lock).
• •Public share renders tenant branding ON (Q3 lock).
• •Public route rate-limit 10/min/token AND 30/min/IP combined (lower bucket wins; Q4 lock). IP hashed with per-tenant salt before storage per data-handling.md.

noteRefs

• •Scope doc: docs/plans/pr-tier-3-reports-4c-scope.md
• •Preview anchor: docs/ui-previews/reports.html Variant 6 (lines 1331–1545)
• •PR: #118

noteSchema (additive migration)

• •Tenant.videoDefaults Json @default('{}'). Single typed column shared by both new pages — each form surfaces the subset of fields relevant to its provider, missing keys fall through to schema defaults so it's safe for either page to write only its provider's settings. No backfill.

noteZod (@helpmesh/core)

• •New VideoDefaultsSchema with .strict(). Fields: defaultProvider (google-meet/zoom/last-used), defaultDurationMinutes (15/30/45/60), meetUseAgentCalendarBusy, meetSendReminderEmail, meetAutoShareRecording, zoomWaitingRoom, zoomRequirePasscode, zoomAutoRecord (off/cloud/local).
• •Default provider locked to google-meet per feedback_video_provider_default.

noteAPI

• •New GET /api/v1/integrations/google-meet/agents — one row per active membership tagged with Google connection state. Today only the OAuth initiator is connected (per-tenant schema); the endpoint is shaped for the eventual per-agent flow so the UI doesn't need to change when that lands.
• •New GET /api/v1/integrations/zoom/scopes — Zoom granted-scopes list. Per feedback_zoom_granular_scopes — Zoom split create/update/delete into separate scopes; UI disables matching actions for missing scopes. Returns needsReconnect: true when granted scopes exist but a required one is missing.
• •Extended PATCH /api/v1/tenant with a videoDefaults branch (mirrors BrandingTokens + WidgetConfig pattern: validate, replace-not-merge into JSON column).
• •Extended GET /api/v1/tenant to select videoDefaults.

noteUI

• •/settings/integrations/google-meet — header with gradient 'M' logo + 'Default video provider' chip when enabled · 3 stat tiles (placeholders pending events pipeline) · connected agents list (X-of-Y counter, per-row Connected/Pending pill) · default behavior form (provider default + duration + 3 Meet toggles).
• •/settings/integrations/zoom — granular-scopes warning banner · 'Reconnect required' banner (only when needsReconnect) · Marketplace app card · granted scopes list with Granted/Missing-required/Optional pills · default behavior form (waiting room, passcode, auto-record).
• •Both pages keep their form-row + toggle patterns inline rather than extracting shared components prematurely. Each page < 250 LoC.

noteWidget carry-over from alpha.58 (now finally rolling)

• •/settings/widget rewrite (3-tile stat strip + dark embed-code panel + configuration card + per-locale welcome editor + live preview iframe).
• •apps/web/public/widget.js rebuilt to 15.38 KB (5.40 KB gzip) with previewMode + 'remount' command additions.
• •apps/web/public/widget-preview.html static page mounting the production widget bundle in preview mode.

noteTests

• •11 new VideoDefaultsSchema input contract assertions.
• •4 new source-string tests pinning the route wiring.
• •6 new isolation contract assertions on /google-meet/agents.
• •7 new isolation contract assertions on /zoom/scopes.
• •1341/1341 passing across the full apps/web suite (24 net new from this PR; widget tests already counted in alpha.58).

noteProduction incident (alpha.58 deploy, 2026-05-13 ~19:30 UTC)

• •The alpha.58 deploy of PR #116 (widget) ran with --migrate and partially succeeded: the intended widget_config migration applied to prod RDS, but a second migration (20260513232628_video_defaults) was inadvertently included in the docker image because Dockerfile COPY . picked up an in-flight migration directory from the next branch's working tree.
• •The unintended migration's hand-trim was missed; it tried to re-create an index that already exists in prod and failed with relation "ApiKey_deprecatedAt_idx" already exists.
• •Migration task exited 1 → deploy.sh aborted before rolling the new image. Prod app continued serving alpha.57 (no user-visible impact).
• •Recovery: cleared the failed _prisma_migrations row via a one-off ECS task running prisma migrate resolve --rolled-back 20260513232628_* (exit code 0 confirmed in CloudWatch).
• •This release's migration is 20260513232743_video_defaults (different timestamp, clean SQL — drift hand-trimmed); the widget_config migration is already applied so prisma migrate deploy skipped it.
• •Gotcha captured in memory: feedback_dockerfile_copy_in_flight_branch.md. Future-fix candidates: git stash in deploy.sh before docker build, or use git archive HEAD | docker build - so the docker context is the committed tree.

noteGates

• •Web typecheck: clean
• •Full repo typecheck: 15/15 packages clean
• •Web tests: 1341/1341
• •Web lint: 7 pre-existing errors / 0 new
• •CI (PR #117): 8m54s green

noteSchema (additive migration)

• •Tenant.widgetConfig Json @default('{}') — replaces the legacy settings.widgetXxx catch-all keys (widgetPosition, widgetPrimaryColor, widgetWelcomeMessage), which keep working until tenants resave through the new typed shape. No backfill.

noteZod (@helpmesh/core)

• •WidgetConfigSchema with .strict() — unknown keys rejected, not silently stripped. Defaults pre-fill so the widget bootstrap is robust to tenants who have never saved through the new shape.
• •Fields: position (bottom-right / bottom-left / custom-anchor), launcherColor (#hex, optional, falls through to brandingTokens), launcherIcon (chat / help / headset / mail), showOnMobile, preChatFields (max 4), hiddenOnPaths (max 50), welcomeMessages (per-locale dict).

noteAPI

• •Extended PATCH /api/v1/tenant — new widgetConfig branch mirrors the BrandingTokens pattern: Zod-validate, replace-not-merge into the JSON column.
• •Extended GET /api/v1/tenant — selects widgetConfig so the page hydrates without a second round-trip.
• •ADMIN-gated (no privilege regression).

noteWidget bundle (apps/widget → apps/web/public/widget.js, 15.38 KB / 5.40 KB gzip)

• •New previewMode config flag — when true, skips api.configure(), analytics.track(), and api.createSession() so admins can preview without polluting their inbox or counting against analytics.
• •New 'remount' command — tears down the prior host element and re-inits cleanly. Used by the preview iframe so config edits propagate live.
• •Bundle grew 322 bytes (5.06 → 5.40 KB gzipped). New branches are guarded behind if (config.previewMode) so production callers pay no extra runtime cost.

noteUI

• •/settings/widget rewrite: 3-tile stat strip (placeholders pending events pipeline) + dark embed-code panel with copy button + configuration card (position seg-tabs + launcher color picker with 'Reset to brand' + 4 built-in icons + show-on-mobile toggle + pre-chat field chips + hide-on-paths textarea) + per-locale welcome message editor + live preview iframe.
• •apps/web/public/widget-preview.html — tiny static page that loads /widget.js, decodes ?config= for first paint, then listens for postMessage({ type: 'helpmesh-preview-config', config }) from the parent. Uses 'remount' to apply each update cleanly. iframe sandbox='allow-scripts allow-same-origin'.

noteVerified end-to-end locally (browse-driven)

• •Initial render with ?config= query: widget mounts in bottom-right with the supplied color and greeting.
• •postMessage({ position: 'bottom-left', launcherColor: '#16a34a', greeting: '…' }): launcher hops to bottom-left, header + CTA + close button + link color all switch to green, greeting re-renders. No console errors.

noteTests

• •11 new Zod input contract assertions covering all enums, hex shorthand, array caps, .strict() rejection of unknown keys, and welcomeMessages shape.
• •4 new source-string tests pinning the route wiring (import, safeParse call, directFields.widgetConfig write, GET+PATCH select).
• •1317/1317 passing across the full apps/web suite (15 net new).

noteDecision log

• •Per the locked memory cap on Shadow-DOM preview (§6.3 of the kickoff plan), the fallback was supposed to be the existing fake-mock WidgetSurface. Spiked the real iframe with no time cap (per user direction) and it worked first try — keeping it. The previewMode + remount widget changes are the foundation for a future per-tenant live-preview embeddable.

noteGates

• •Web typecheck: clean
• •Widget typecheck: clean
• •Web tests: 1317/1317 passing
• •Widget bundle: 15.38 KB (5.40 KB gzip), under the 16 KB ceiling
• •Web lint: 7 pre-existing errors / 0 new

noteSchema (additive migration)

• •CustomFieldEntity enum (THREAD / CUSTOMER / COMPANY). THREAD is the default — every existing row stays a ticket field; no backfill needed.
• •CustomField.entity (default THREAD).
• •CustomField.isCustomerVisible (default false) — controls whether the field renders in the customer-facing portal.
• •CustomField.defaultValue (nullable text).
• •CustomField.validation (Json {} default) — separate from the existing options json so per-type validation (regex, min/max length, numeric bounds) stays cleanly separated from SELECT enum options.
• •@@index([tenantId, entity]) — powers the ?entity= filter and the EntityTabs query path.

noteAPI

• •Extended GET /api/v1/custom-fields — optional ?entity=THREAD|CUSTOMER|COMPANY filter validated against the enum allow-list before reaching Prisma. orderBy is now [{ entity }, { position }] so each EntityTab sorts independently.
• •Extended POST /api/v1/custom-fields — accepts entity, isCustomerVisible, defaultValue (nullable), validation. Position is computed per-entity (not global) so adding a CUSTOMER field doesn't shift THREAD positions.
• •Extended PATCH /api/v1/custom-fields/:id — accepts the same four fields. defaultValue uses the destructure + if (defaultValue !== undefined) pattern so a client can clear the field via PATCH { defaultValue: null }.
• •No new endpoints — the four existing routes (GET, POST, PATCH, DELETE) cover the full surface.

noteUI

• •/settings/custom-fields redesign: EntityTabs above the list (Tickets / Customers / Companies, with per-entity counts). Switching tabs filters client-side and seeds the entity field on new-field creation.
• •Table layout: FIELD (name + monospace key) / TYPE (color badge) / REQUIRED / VISIBLE TO (Agent only vs Agent + Customer) / actions.
• •Field editor pane: grid-2 layout with Name / Type chips / Required toggle / Visible-to-customer toggle / Default value on the left, Options builder on the right (only when type=SELECT).
• •Honest encryption banner: "AES-256-GCM via AWS KMS" — never "your encryption key" (per locked memory). Notes that values are redacted in audit logs by default.

noteTests

• •7 isolation contract assertions on list/create.
• •6 isolation contract assertions on detail/update/delete.
• •First isolation tests this surface has ever had. Custom-fields routes had zero coverage before this PR — gap closes here.

noteDeferred to follow-up PRs

• •FILLED % column (preview shows it). Thread-level field values live on Thread.customFieldValues JSON, so computing fill rate requires scanning every Thread's JSON for the key — not cheap at scale. Lands once we decide whether to materialize a counter.
• •Drag-to-reorder mutation. Grip handles render but the position-swap endpoint isn't wired (existing per-entity position integer is honored on read).

noteGates

• •Web typecheck: clean
• •Web tests: 1302/1302 passing (13 new)
• •Web lint: 7 pre-existing errors / 0 new

noteSchema (additive migration)

• •Label.description (TEXT, optional) — surfaced in the labels picker tooltip and on the labels admin row.
• •Label.mergedIntoId (self-FK, ON DELETE SET NULL) + Label.mergedAt — soft tombstone left by the merge endpoint. Kept ~90d so audit logs + compiled automation references stay readable; future cleanup job hard-deletes them.
• •@@index([tenantId, mergedIntoId]) for the default 'hide tombstones' query path.

noteAPI

• •Extended GET /api/v1/labels — ?includeMerged=true to see tombstones (default off). Returns per-row usage30d computed via a single prisma.threadLabel.groupBy keyed by labelId — cheap, revisit at thousands-of-labels scale.
• •Extended POST /api/v1/labels — accepts description.
• •Extended PATCH /api/v1/labels/:id — accepts description (nullable so the client can clear).
• •New POST /api/v1/labels/:id/merge-into/:targetId — single transaction:

1. Drop ThreadLabel duplicates (threads that already have both labels) 2. Re-point remaining ThreadLabel rows to the target 3. Tombstone the source (mergedIntoId + mergedAt) 4. Emit OutboxEvent label.merged 5. Write AuditLog row with source/target pairing Cross-tenant defense via two tenant-scoped findFirst lookups (404 if either is missing). Self-merge → 400. Already-merged → 409 HM-CONFLICT-ALREADY-MERGED.

noteUI

• •/settings/labels redesign: description editor inline on each row, usage30d badge, "Show merged" toggle.
• •New LabelMergeModal — pick target label, confirm impact (count of threads being re-pointed), single-click merge with optimistic feedback.

noteTests

• •7 isolation contract assertions on list/create.
• •8 isolation contract assertions on the merge endpoint (tenant pinning, 404-not-403, self-merge 400, already-merged 409, atomic single-tx with all 3 prisma writes + outbox + audit, threadLabel duplicate handling).

noteGates

• •Web typecheck: clean
• •Web tests: 1268/1268 passing (15 new)
• •Web lint: 7 pre-existing errors / 0 new

noteSchema (additive migration)

• •New CannedScope enum (TEAM | PERSONAL).
• •Five additive columns on CannedResponse: scope (default TEAM keeps existing rows visible to the whole tenant), userId (nullable FK to User, ON DELETE SET NULL), locale (free-form), usageCount, lastUsedAt.
• •Two new composite indexes for picker queries.
• •User.personalCannedResponses back-relation.

noteAPI

• •Extended GET /api/v1/canned-responses — ?scope=TEAM|PERSONAL|ALL + ?locale=. PERSONAL rows are only visible to the calling user (never bleed across agents). Search composes via AND so the visibility OR never widens scope. Orders by (lastUsedAt desc, name asc) for recency-first picking.
• •Extended POST /api/v1/canned-responses — accepts scope/locale; PERSONAL requires a signed-in caller; duplicate shortcut still returns 409.
• •Extended PATCH /api/v1/canned-responses/:id — accepts scope/locale (locale nullable so the client can clear it).
• •New POST /api/v1/canned-responses/:id/record-use?count=N — atomic increment + lastUsedAt update. WHERE pins both tenantId + id (no cross-tenant bump). 404-not-403 cross-tenant shape. count bounded to [1, 20]. Designed for composer batching (5s debounce per scope §4.3 Q14).

noteUI (`/settings/canned-responses`)

• •Scope filter tabs at the top: All / Team / Personal.
• •Optional locale dropdown (auto-populated from distinct locales in result set).
• •Per-row badges: ScopePill (blue Team / violet Personal), LocaleChip for non-null locales, usage line ("Used 42 times · 2h ago") when usageCount > 0.
• •Create/edit form: Visibility seg-toggle + optional Locale text input.

noteTests

• •21 new isolation contract assertions across 3 test files (list/create, [id] PATCH/DELETE, record-use). Web suite 1253 → 1274 passing.

noteGates

• •Web typecheck: clean
• •Web tests: 1274/1274 passing
• •Web lint: 7 pre-existing errors / 0 new

noteUI

• •4-tile rolled-up stat strip above the webhook list using the locked dashboard stat-card style (tinted icon + caps label + big number).
• •Tiles: Active endpoints / Deliveries (7d) / Success rate (7d, tone-coded emerald ≥ 95% / amber 80–95% / red < 80%) / Auto-disabled (red when > 0).
• •Data computed client-side from the existing GET /api/v1/webhooks response — no extra fetch.
• •Strip is hidden when the tenant has zero webhooks (preserves the existing empty-state UX).
• •WebhookCard, RevealedSecretBanner, CreateWebhookModal, SigningDocs — untouched.

noteGates

• •Web typecheck: clean
• •Web tests: 1253/1253 still passing (no new tests — pure presentation; existing route tests cover the data shape)
• •Web lint: 7 pre-existing errors / 0 new

noteUI

• •NEW page at /settings/integrations/zapier.
• •Header card with Zapier branding + "Open in Zapier" CTA.
• •3 stat tiles: Active Zaps (inferred), Live API keys, Total webhooks.
• •Webhook URL panel for Zapier triggers with copy-to-clipboard.
• •API keys panel (read-only mask via GET /api/v1/api-keys), links to /settings/api-keys for management.
• •Active Zaps list — filtered from GET /api/v1/webhooks where url matches the hooks.zapier.com host. Per scope §4.3 Q8, we do NOT enumerate Zaps via the Zapier API (fragile, requires a separate Zapier app integration); the link-out to the user's Zapier dashboard covers anything not visible from our webhook subscriptions.
• •Templates grid — 3 link-out cards to Zapier-hosted templates.

noteGates

• •Web typecheck: clean
• •Web tests: 1253/1253 still passing (no new tests — pure presentation over endpoints already covered by their own isolation tests)
• •Web lint: 7 pre-existing errors / 0 new

noteSchema (additive migration)

• •Thread.@@index([tenantId, firstResponseAt]) — powers the median FRT measure.
• •Thread.@@index([tenantId, assigneeId, createdAt]) — powers the per-agent workload chart + activity heatmap aggregations.
• •SLAPolicy.atRiskPercent Int @default(25) — per-policy override threshold. UI editor at /settings/sla-policies is deferred; the field ships harmless until consumed by a future variant 5 PR.

noteAPI

• •New GET /api/v1/reports/agents/[id] (N2) — per-agent: stats, 30-day workload, CSAT distribution, resolution histogram (6 buckets), low-CSAT feed, working-hours pass-through, hour-of-week activity heatmap (Redis 1h cache). All thread reads pin tenantId; CSAT joins via thread.assigneeId. Returns 404 (not 403) for cross-tenant access. ?days bounded 7..180.
• •Extended GET /api/v1/system/activity — ?sensitive=true narrows the result to actions on the new SENSITIVE_AUDIT_ACTIONS allow-list. Every row now carries a server-side isSensitive: boolean flag driving the SensitiveBadge.

noteCore

• •packages/core/src/data/sensitiveAuditActions.ts — 13-action allow-list (PII deletion, impersonation, AI-safety overrides, content rollback, real-PII test sends) drawn from real codebase action names. isSensitiveAuditAction() O(1) check.

noteUI

• •/reports/agents/[id] — new page with 6 new components in apps/web/src/components/reports/agent-detail/: WorkloadChart (recharts BarChart), CsatDistributionList, ResolutionHistogram (recharts BarChart), ActivityHeatmap (plain SVG, UTC-bucketed), WeeklySchedule (read-only render of User.workingHours), OOOEmptyState (current-OOO stopgap + "history coming soon" empty state).
• •/settings/audit-log — adds 4 compliance summary tiles (on-screen / sensitive / distinct actors / last 7d), "Sensitive only" toggle, SensitiveBadge on rows, and replaces the inline expand-JSON with a AuditDetailDrawer (SideSheet) that renders BEFORE/AFTER key-by-key. Existing row layout preserved.

noteTests

• •packages/core: 5 new unit tests on the sensitive-action allow-list (487/487 passing).
• •apps/web: 10 new isolation contract assertions on N2 + 3 new on /system/activity (1253/1253 passing).

noteDeferred to follow-up PRs

• •Variant 2 list redesign at /reports/agents (currently a tab inside /reports).
• •Variants 4/5 standalone routes (CSAT trends + SLA compliance pages).
• •Variant 6 custom report builder (tier-3c, has SavedReport schema).
• •OutOfOfficeWindow schema + per-window OOO history.
• •/settings/sla-policies editor for the new atRiskPercent field.

noteAPI

• •Extended GET /api/v1/reports/overview — now accepts ?days=N alongside ?from=&to=, adds ?compareWith=prior_period (per-KPI percent deltas against the immediately preceding window), adds sparklines.* (5 evenly-spaced buckets per KPI), and computes a real csatAverage (was hard-coded null).
• •New GET /api/v1/reports/anomalies — z-score on weekly thread volume per channel + per label, ≥2σ threshold + MIN_CURRENT_COUNT=5 to suppress trivial spikes. Returns top 3 outliers ranked by absolute z-score. Powers the Smart Suggestions tile.
• •New GET /api/v1/reports/csat/distribution — rating histogram (1–5) with ?groupBy=overall|channel|agent.
• •New GET /api/v1/reports/csat/comments — cursor-paginated feed of CSATResponse rows with non-null comment, filterable by minRating/maxRating/free-text search. Minimal join surface (id + name on customer + assignee, no body leak).

noteUI — Overview tab redesign in place

• •4 KPI tiles via new KpiSparkTile component (tinted icon top-left + delta chip top-right + caps label + huge number with unit + 5-bar SVG sparkline bottom-right). Avg-response-time tile uses invertDelta so "down" reads as good.
• •Volume area chart + Channel donut row.
• •3-col bottom row: Top labels bar + LatestCsatList 4-row preview + SmartSuggestionsTile (gradient hero card reading from /anomalies, loading / empty / populated states).
• •"Investigate & draft KB article" CTA stubs to /inbox?search=<label> — the KB-draft AI flow is deferred per scope §6.8.

noteTests

• •5 new isolation test files (35 contract assertions) for the 4 routes — tenant scoping, Zod validation, no-leak select patterns, threshold constants, default-deny enum handling.
• •Web suite 1217 → 1252 passing.

noteDeferred to follow-up PRs

• •Route split (/reports/agents, /reports/csat, /reports/sla, /reports/meetings).
• •Variants 2/4/5 deep redesigns + variant 3 (/reports/agents/[id]) + variant 7 (audit log redesign).
• •N6–N10 endpoints (saved reports CRUD + aggregator + share token — tier-3c).
• •2 new CSV exports (CSAT + audit log with streaming + 100k cap).

note`/settings/kb` — list redesign (variant 1)

• •AI Suggestions panel polls GET /api/v1/kb/ai-jobs?status=succeeded&limit=10 every 30s; per-row Accept → POST /ai-jobs/:id/accept; Dismiss → POST /ai-jobs/:id/dismiss.
• •Bulk-action bar (publish / unpublish / archive / translate) reveals on multi-select; calls POST /api/v1/kb/articles/bulk directly.
• •Translate opens a locale-picker popover then dispatches action: 'translate' with targetLocales[].
• •New collection filter alongside status + locale.
• •Honours feedback_no_shortcuts.md: no visible kbd chips.

note`/settings/kb/structure` — NEW route (variant 2)

• •Collection-level drag-reorder via @dnd-kit/sortable. No cross-collection drag in v1 (scope §7).
• •Reads alpha.49 GET /collections enriched shape (articleCount, healthScore, lastUpdatedAt, iconKey, visibility).
• •Optimistic local reorder PATCHes /collections/reorder and reverts on 409.
• •Per-collection more_vert menu surfaces "Suggest a split" → POST /collections/:id/split-suggestion (gated to ≥15 articles).
• •Three stat tiles (collections / total articles / avg health) at the top, health colour-coded green/amber/red against 85/60 thresholds.

note`/settings/kb/[articleId]` — editor redesign (variant 3)

• •Full-bleed editor layout with top bar (status pill + autosave indicator + Preview / Revisions / AI assist / Publish) and a right rail (Publishing + SEO + Versions sections).
• •Autosave (2s debounce) via PATCH /articles/:slug?asDraft=true — only title + body + autosavedAt mutate per the alpha.49 route comments.
• •Cheap client-side conflict guard: before every save (autosave or explicit) GET the article and compare updatedAt against the cached value; on mismatch surface "edited elsewhere — reload" toast and abort.
• •Revisions side-sheet lists revisions from GET /revisions; "Save current as version" calls POST /revisions for an explicit snapshot.
• •AI right-rail dispatches the 4 scope §4.3 actions (rewrite-title, summarize, translate, tone-check) against the new POST /api/v1/kb/ai-jobs route.
• •New Tiptap extensions: Underline (already present), Strike, Image (https-only prompt), Table (3x3 default, header row, no resize). Editor init dynamically imports all extensions in parallel — no SSR cost.

noteSchema preflight

• •Article.@@unique([tenantId, slug, locale]) — replaces the old (tenantId, slug) constraint so the same slug can ship across en + ar + fr. Migration 20260513040000_article_slug_locale_unique (additive: drops old constraint, adds new). Safe on live data because no existing tenant has same-slug-different-locale rows yet.

noteNew API route

• •POST /api/v1/kb/ai-jobs (NEW, ADMIN-gated) — single-article enqueue used by the editor right-rail. Mirrors the bulk-translate + split-suggestion pattern: ArticleAiJobCreateSchema validation, route-level superRefine that translate requires targetLocale, ownership check on articleId via tenantId, single row in queued status, BullMQ fan-out via enqueueArticleAiJob.

noteTests

• •packages/core/__tests__/kb-bulk-action.test.ts (8 cases) — locks KbBulkActionSchema against the bar's payload shapes.
• •packages/core/__tests__/kb-collection-reorder.test.ts (5 cases) — locks KbCollectionReorderSchema against the canvas's payload shapes.
• •packages/core/__tests__/kb-ai-job-create.test.ts (8 cases) — locks ArticleAiJobCreateSchema against the 4 right-rail kinds + edges.
• •apps/web/.../kb/ai-jobs/route.isolation.test.ts (+6 cases) — locks the new POST route's ADMIN gate, Zod validation, translate-locale enforcement, tenant-scoped ownership, queued status, BullMQ enqueue.
• •apps/web/src/lib/kb/__tests__/editor-schema-compat.test.ts (17 cases) — pre-flight ProseMirror schema compatibility for the new Image + Table extensions.

Repo typecheck clean (15/15). Core tests 490/490. Web tests 1217/1217. PR #108.

noteSchema (1 additive migration)

• •Collection.iconKey String? — material-symbol name for the structure-canvas tile rendering. NULL renders a fallback folder icon.
• •Collection.visibility String @default('public') — 'public' | 'restricted' | 'internal'. Indexed on (tenantId, visibility) for the public /knowledge filter.
• •Article.autosavedAt DateTime? — editor draft-autosave signal. Distinct from updatedAt (which Prisma auto-stamps on viewCount increments).
• •ArticleAiJob model — one row per AI job. Status transitions queued → running → succeeded | failed are written by the BullMQ worker; admins move succeeded rows to accepted or dismissed from the suggestions panel. 60-day retention; per-tenant + per-article indexes.
• •Migration: 20260513020000_knowledge_base_tier3.

note`@helpmesh/core` validators (5 new schemas)

• •ArticleAiJobKindSchema (6 kinds), ArticleAiJobStatusSchema (6 states), ArticleAiJobCreateSchema, ArticleAiJobListQuerySchema
• •KbBulkActionSchema with superRefine enforcing targetCollectionId for move and targetLocales for translate
• •KbCollectionReorderSchema

noteAPI routes (11 new + extended)

| Path | Method | Auth | Status | |---|---|---|---| | /api/v1/kb/articles | GET | session | extended (?segment, ?author, ?counts) | | /api/v1/kb/articles/bulk | POST | ADMIN | NEW (publish / unpublish / archive / move / translate; ownership-verified; translate fans out per-locale ArticleAiJob) | | /api/v1/kb/articles/:slug | PATCH | ADMIN | extended (?asDraft=true autosave path; sets autosavedAt; skips status flips + revision write) | | /api/v1/kb/articles/:slug/revisions | GET/POST | session/ADMIN | NEW (explicit "Save version" + revisions drawer) | | /api/v1/kb/articles/:slug/revisions/:version/restore | POST | ADMIN | NEW (writes a NEW revision, never rolls version back; audited) | | /api/v1/kb/collections | GET | session | extended (healthScore + articleCount + lastUpdatedAt + iconKey + visibility) | | /api/v1/kb/collections/reorder | PATCH | ADMIN | NEW (atomic $transaction; rejects stale id sets with HM-REORDER-STALE 409) | | /api/v1/kb/collections/:id/split-suggestion | POST | ADMIN | NEW (queues ArticleAiJob) | | /api/v1/kb/ai-jobs | GET | session | NEW (suggestions panel; cursor pagination) | | /api/v1/kb/ai-jobs/:id/accept | POST | ADMIN | NEW (per-kind apply: translate → new locale Article; summarize → seoMeta merge; rewrite-title → title update; auto-generate → body replace; sanitized HTML on every body write) | | /api/v1/kb/ai-jobs/:id/dismiss | POST | ADMIN | NEW (idempotent; terminal-state 409) | | /api/v1/kb/public/articles/:slug | GET | hostname-resolved tenant | NEW (publicHandler via withTenant; PUBLISHED + public-collection only; sanitized body; best-effort viewCount increment; top-3 related) | | /api/v1/kb/public/articles | GET | hostname-resolved tenant | NEW (?sort=trending\|recent&limit=6; limit hard-capped at 24; no body in projection) | | /api/v1/kb/public/collections | GET | hostname-resolved tenant | NEW (visibility=public + per-collection articleCount) |

noteWorker (`apps/worker`)

• •processArticleAiJob processor + article-ai-job queue registration. Status-machine + tenant-scoped run + CAS claim via updateMany. Per-kind LLM calls are scaffolded with pending: true placeholders so the suggestions panel can render a "model not yet configured" hint until the orchestrator wires land in a follow-up. The status-machine + audit + sanitization boilerplate is the production-critical part shipping today.

noteWeb helpers

• •apps/web/src/lib/kb/ai-job-queue.ts — enqueueArticleAiJob(jobId, tenantId) helper. Used by /articles/bulk (translate fanout) and /collections/:id/split-suggestion. BullMQ jobId is derived from the row id so duplicate API calls don't create duplicate queue entries.

noteExplicitly deferred to PR-3b (alpha.50)

• •/settings/kb redesign — article list with filter pills + AI suggestions panel + bulk-action bar (variant 1)
• •/settings/kb/structure NEW — collection-hierarchy canvas with drag-to-reorder + health dots + "split this collection" CTA (variant 2)
• •/settings/kb/[articleId] redesign — Tiptap editor with autosave + revisions drawer + AI right-rail (variant 3, the largest piece — ~2-3 dev-days alone)
• •/knowledge/[slug] NEW — public article page with JSON-LD + related strip (variant 4)
• •/knowledge redesign — help-center home with semantic search + popular/recent strips (variant 5)
• •Real LLM orchestrator wiring for each ArticleAiJob kind — all 6 branches currently return { pending: true, reason } placeholders

noteQuality

• •pnpm typecheck — clean across all 16 packages
• •@helpmesh/web — 1188/1188 tests pass (was 1113 on alpha.48; +75 new across 11 KB isolation files)
• •11 new isolation tests cover every route's tenant-scope predicate, role-gate, ownership-verification, and (for AI accept) HTML sanitization
• •Zero new any, function size ≤30 lines, structured error codes throughout

noteSchema (1 additive migration)

• •DataDeletionRequest.customerIds: String[] — bulk-delete target array. Singular customerId stays populated with the first id for back-compat with the alpha.43 deletion-approvals UI and audit queries. Legacy rows are backfilled with a single-item array via UPDATE … SET customerIds = ARRAY[customerId].
• •Migration: 20260513010000_customers_tier3.

noteAPI extensions

• •GET /api/v1/customers — new ?include=deleted,inactive, ?counts=true, server-side ?tier= filter. Returns an aggregate: { active, inactive, deleted, byTier } block when counts=true so the filter pills can render counts without a second round-trip. Default predicate unchanged (still hides soft-deleted).
• •GET /api/v1/customers/:id — now projects pendingDeletion: { requestId, requestedBy, requestedAt, expiresAt } | null. Matches either the singular customerId column OR any bulk customerIds array that includes this id.
• •GET /api/v1/customers/:id/threads — accepts ?status=&priority=&channel=&from=&to= (multi-value via URLSearchParams.getAll). Every value is allowlist-validated against the Prisma enum before reaching the predicate.

noteREST API (new)

• •GET /api/v1/privacy/single-admin-check — session-min auth. Returns { adminCount, requireTwoAdminDelete, canDelete }. Drives the V8 single-admin block in /settings/data-privacy + the disabled state on the GDPR delete modal.

noteHelpers

• •paginated(data, nextCursor, hasMore, extras?) — optional extras block merged at the top level of the response envelope. Lets aggregate counts ride alongside paginated results without breaking the existing envelope.

noteUI

• •/customers — filter pills with live counts (?counts=true), Show inactive / Show deleted toggles, bulk-action bar (Export + Request GDPR delete; "Apply tag" intentionally disabled, scope §2.2), per-row pending-deletion + soft-deleted state with yellow / gray tinting, row-level Select checkboxes (disabled on pending or deleted rows).
• •/customers/:id — pending-deletion banner (V6) above the header with a Cancel-request button for the requester, "Request delete" action in the header (hidden when one is already pending).
• •/customers/:id/tickets — NEW sub-page. Full ticket history with multi-select status / priority / channel filter pills, server-side filtered via the alpha.48 /customers/:id/threads query params.
• •/settings/data-privacy — V8 single-admin block. Renders only when requireTwoAdminDelete=true AND adminCount < 2. Healthy workspaces don't see the warning.
• •GDPRDeleteRequestModal — shared component. Single or bulk target, confirmation phrase typing guardrail (DELETE CUSTOMER / DELETE N CUSTOMERS), single-admin warning, ≥10-char reason field, fans out to the existing POST /api/v1/privacy/delete per id.

noteAlready shipped pre-alpha.48 (scope §3 routes 4-8 + 9-extra)

• •POST /api/v1/privacy/delete (queue-not-execute under requireTwoAdminDelete) — alpha.43
• •GET/DELETE/POST /api/v1/privacy/deletion-requests (list, cancel, approve, reject) — alpha.43
• •canApproveDeletion helper (blocks self-approval + single-admin + expired + non-pending) — alpha.43, tested
• •GET /api/v1/privacy/deletion-requests/pending-count — alpha.46

noteExplicitly deferred

• •CustomerTag model + tag groups — own scope, not built (scope §2.2). "Apply tag" UI is disabled with tooltip.
• •CustomerNote model — own scope (scope §2.2). Detail-page notes preview already renders an empty state.
• •Company model + Customer.companyId FK + MRR/ARR — own scope doc later (scope §2.4).
• •Bulk-delete server endpoint — current flow fans out client-side; a one-shot bulk POST is a follow-up.
• •/api/v1/customers/export CSV — Export-selected button hooks to this URL with the selected ids, endpoint to follow.

noteQuality

• •pnpm typecheck — all packages clean
• •4 new isolation tests (customers list, customers/:id, customers/:id/threads, privacy/single-admin-check)
• •Zero new any, function size ≤30 lines, RTL via logical properties preserved
• •Generic error responses with structured code fields

noteAPI extensions (4 routes, no new endpoints)

• •GET /api/v1/analytics — new fields: slaCompliancePercent, slaCompliancePrevPercent, slaComplianceWindowDays, csatAverage, csatPrevAverage, csatResponseCount, avgFirstResponseMinutesPrev. All scoped through the existing baseWhere predicate; prev-period delta source uses a paired 7-day window (7–14 days ago). Returns null (not 100%) when the window is empty so brand-new tenants don't paint fake compliance numbers.
• •GET /api/v1/reports/volume — accepts ?bucket=hour|day (default day). Hourly mode runs DATE_TRUNC('hour', "createdAt") over the last 24h, hard-capped at 24 buckets. Day mode is unchanged; the hourly query is skipped via Promise.resolve([]) when bucket=day so there's no wasted DB round-trip.
• •GET /api/v1/system/activity — rows whose entity === 'Thread' now carry a thread: { id, publicNumber, subject, status } projection so the dashboard table can render PRO-6-000131 instead of the bare cuid. Single tenant-scoped IN-list query post-aggregation; non-Thread rows get thread: null.
• •GET /api/v1/analytics/attention — every list row now carries slaCountdownMs (ms until soonest open SLA deadline, negative when breached, null when no deadline applies). Server-computed so the UI can render "expires in 12m" without reformatting client-side.

noteHelpers (`apps/web/src/lib/home-helpers.ts`)

• •slaSparkline(series) — 100% on zero-volume days (no false dip)
• •responseTimeSparkline(series) — null minutes → 0 (no-data gap)
• •deltaForMetric(current, previous, { lowerIsBetter? }) — unified delta tone resolver; returns null when previous is zero/null (no fake "100% increase" noise)

noteUI (`/home`)

• •KPI strip refresh — Team + Agent modes now render Open / Avg response / CSAT / SLA compliance tiles with prev-period deltas + iconTone mapped to scope §4.2. Viewer mode unchanged.
• •Volume card — 24h/7d/30d segmented toggle. 24h renders a bar chart of hourly buckets via bucket=hour; 7d/30d uses the existing area chart with fillVolumeGaps. Single state, fetched lazily on window change.
• •Recent activity — list-with-avatars → 5-column table (Action / Ticket / Agent / Time / Status). Ticket cells render #publicNumber as a link to /inbox/<id>; non-thread rows fall back to a font-mono Entity#hash label. Reuses the same export name and import path so the page consumer doesn't change.
• •Header — action button pair now reads Export report + New ticket (primary). Matches the preview's tenant-dashboard.html L154-173.

notePreview banned-pattern check

• •No ⌘K chip or <CommandShortcut> rendered. The existing chrome search button already opens the palette via onClick; placeholder text is plain ("Search tickets, customers, articles, settings…"). Per feedback_no_shortcuts.md.

noteOut of scope (deferred to follow-ups)

• •AIHandoffPanel / TodaysMeetingsPanel / OnboardingChecklist — explicitly NOT touched (scope §1 non-goal).
• •/api/v1/dashboard/overview aggregator — considered + rejected in scope §2.1 (per-endpoint cache-control + single-slow-query risk).

noteQuality

• •4 new isolation tests for the API extensions (analytics, attention, volume, system/activity)
• •12 new unit tests on the three new helpers
• •Zero schema migration, zero new any, function size ≤30 lines, RTL via logical properties

noteSchema (1 additive migration)

• •MessageSystemEvent enum + nullable Message.systemEvent column. Drives the new customer-safe SYSTEM-event projection on the widget. Existing rows untouched (NULL = "agent-only"), so this is safe on a live Message table without backfill.
• •Migration: 20260512230000_tier_2_closeout.

note`@helpmesh/core`

• •message/systemEvent — PORTAL_VISIBLE_SYSTEM_EVENTS (4-entry allowlist) + isPortalVisibleSystemEvent() helper. Unit-tested.

noteWorker

• •deletion-request-expiry processor + hourly cron (deletion-request-expiry-cron). Flips stale AWAITING_APPROVAL DataDeletionRequest rows to EXPIRED once expiresAt has passed, plus an AuditLog row in the same transaction. Closes the compliance hygiene gap noted in alpha.43's requireTwoAdminDelete work (#1).

noteWidget API

• •GET /api/widget/v1/articles/:slug/print — print-friendly HTML page (browser "Save as PDF" path). Session-cookie auth, tenant + PUBLISHED filter, sanitized body, robots-noindex header. No worker / no chromium / no S3 — chosen over server-rendered PDFs because article export volume is low and the report-pdf-worker pattern is heavier than the use case warrants (#8).
• •GET /api/widget/v1/threads/:id/messages — extended with customer-safe SYSTEM-event projection. SYSTEM rows are now only surfaced to the portal when their systemEvent is in the allowlist; legacy NULL-tagged SYSTEM rows stay invisible (#6).

noteREST API

• •GET /api/v1/privacy/deletion-requests/pending-count — ADMIN-only, returns { pending, overdue } for the sidebar badge. Cheap two-COUNT query, tenant-scoped (#2).
• •GET /api/v1/billing/referrals — OWNER-only, aggregates real referral counts (Tenant.referredByCode = caller.referralCode) + summed Credit.amountCents where source = REFERRAL. Drops the zero-state stub that was carrying the prior placeholder copy (#7).

noteUI

• •apps/web/src/app/(agent)/settings/layout.tsx — pending-count badge on "Deletion approvals" nav entry. Tone flips blue → red when any approval window has elapsed (the worker will sweep it on its next hourly tick). Polls every 60s.
• •apps/web/src/components/settings/api-keys/EditKeyDialog.tsx — "Add custom cap" surface inside the existing edit modal. Posts to the alpha.42 /api/v1/api-keys/:id/rate-limits endpoint that previously had no UI (#3).
• •apps/web/src/app/(customer)/portal/tickets/[id]/page.tsx — Pusher client subscribes to private-portal-thread-{id} via the alpha.45 widget auth route. New messages render in real time; thread updates re-trigger the existing refetch. Graceful no-op when NEXT_PUBLIC_PUSHER_KEY is unset (#4).
• •apps/web/src/app/(customer)/portal/help/[slug]/page.tsx — "Save as PDF" button in the article header, opens the new /print endpoint in a new tab (#8).
• •apps/web/src/components/settings/billing/ReferralHero.tsx — hasStatsEndpoint flips to true now that the backing endpoint exists.

noteHooks

• •usePortalRealtime — small wrapper around pusher-js for the customer portal. Stable-ref callback pattern so the host page can re-render without resubscribing.

noteExplicitly deferred

• •#5 — server-side V5 view-as proxy. The current TEAM_LEAD+ read-only shell stays. A true hm_session-bridge proxy with cross-tenant safety + CSP carve-out is 1.5-2 dev-days and ships with the portal-hardening PR. apps/web/src/app/(agent)/customers/[id]/view-as/page.tsx carries a TODO(portal-hardening) comment with the rationale.
• •Template gallery side-sheet on `/settings/automations`. Belongs with the tier-3 integrations PR — the page's handleBrowseTemplates toast was updated to point reviewers there.

noteQuality

• •4 isolation tests added (pending-count, billing referrals, article print, systemEvent helper)
• •Zero new any, function size ≤30 lines, RTL via logical properties preserved, error responses generic with code fields

noteDecisions locked at kickoff

• •**Reuse /api/widget/v1/*** — explicitly NOT a parallel /api/portal/* namespace. The portal cookie shape, JWT-or-anon auth, tenant isolation, and Pusher channels all already match.
• •All 3 day-1 risks from scope §6 verified clear before code: tenant resolution at custom domain (already handled by server/middleware/tenant.ts), MessageType.NOTE (already in enum), Pusher auth gating (hole confirmed on existing /api/pusher/auth, closed by new widget-side route).

noteSchema (1 migration, additive)

• •ArticleVote table — idempotent helpful voting. voterHash = SHA-256(tenantId + customerId-or-sessionId). Unique on (articleId, voterHash) so a customer cannot inflate counts. Counter increments stay on Article for fast list rendering.
• •CSATResponse.@@unique([threadId, customerId]) — Risk #6. Existing duplicate rows pruned by migration before the index lands.
• •Migration: 20260512200000_customer_portal_pr.

note`@helpmesh/core` (validation + helpers)

• •schemas/widgetThreadFilters — ?status=&q=&limit= shape, PortalThreadStatusSchema excludes SPAM (never customer-visible).
• •schemas/widgetCsat — rating 1-5 + optional comment ≤2000.
• •schemas/widgetArticleFeedback — just helpful: bool. Identity derived server-side.
• •schemas/impersonateCustomer — customerId + reason. IMPERSONATION_SESSION_TTL_MIN = 30.
• •crypto/voterHash.articleVoterHash — SHA-256 with per-tenant salt. Server-only.

noteWidget API surface (3 extended + 8 new, all session-cookie auth + tenant-scoped)

• •Extended GET /api/widget/v1/threads — filters + csatPending flag for the "Rate this" chip.
• •Extended POST /api/widget/v1/threads — category (→ customFieldValues.category), priority, attachments[] (10×10MB), consentAccepted (upserts a Consent row).
• •New GET /api/widget/v1/threads/:id — ownership-gated detail with safe assignee profile (id+name+avatarUrl, NEVER email).
• •New POST /api/widget/v1/threads/:id/reopen — 14-day window from resolvedAt (Risk #9); CLOSED is final.
• •New POST /api/widget/v1/threads/:id/csat — translates Prisma P2002 to HM-CSAT-ALREADY-SUBMITTED (409).
• •New GET /api/widget/v1/articles/:slug — PUBLISHED only, sanitized body, computed readTimeMinutes (~240wpm) + helpfulPercent + related-articles (top 3 same Collection by viewCount).
• •New POST /api/widget/v1/articles/:slug/feedback — idempotent voting. New vote increments; same-flag re-vote no-ops; flip decrements old + increments new. Article counters stay authoritative.
• •New POST /api/widget/v1/uploads — presigned S3 PUT with key tenants/{id}/portal/{owner}/attachments/{uuid}/{name}. Stricter content-type allowlist than the agent surface (no zip / exe).
• •New POST /api/widget/v1/pusher/auth — P0 ownership gate. Whitelists only private-portal-thread-{id}. Identified-customer required. 404 (not 403) on foreign thread id. The existing agent-side /api/pusher/auth only checks "is logged in"; this is the customer-side equivalent done right.
• •New POST /api/v1/impersonate/customer — TEAM_LEAD+, 30-min TTL, self-impersonation blocked (HM-IMPERSONATE-SELF), AuditLog row in same transaction.
• •New DELETE /api/v1/impersonate/customer/:sessionId — only minter can end (HM-IMPERSONATE-NOT-OWNER).

noteUI (5 surfaces + chrome polish)

• •Chrome polish (portal/layout.tsx): brand-color CSS variable at the layout root so every descendant inherits tenant brand via --hm-blue-500 override. RTL via document.documentElement.dir based on branding.defaultLocale (ar/he/fa/ur). Wider main on /portal/help/* per scope §4.4. Help-center nav entry added.
• •V1 `/portal` REWRITE — server-side filters + 250ms debounced search, per-card priority pill (URGENT only), CSAT-pending chip on RESOLVED, empty-state branches with "Help yourself faster" 3-tile row pulled from GET /api/widget/v1/kb?limit=3.
• •V2 `/portal/new` REWRITE — inline KB suggestions (600ms debounce, dismissible), real uploads via the new /uploads endpoint (presign + PUT, serial for UX feedback), consent checkbox (upserts a Consent row), priority enum aligned to backend UPPER_CASE, inboxId resolved from /sessions (fixes the pre-existing inboxId: '' bug).
• •V3 `/portal/tickets/[id]` REWRITE — customer-right / agent-left / centered-system bubble layout, dedicated AI bubble (purple Sparkles), CSAT panel replaces composer on RESOLVED + un-rated, reopen button on RESOLVED + rated, deep-link #rate scrolls panel into view.
• •V4 `/portal/help/[slug]` NEW — full article page (breadcrumb + meta row + sanitized prose body + voter card + ticket-CTA + sticky related-articles sidebar). Plus /portal/help minimal index with debounced search (previously a 404).
• •V5 `/customers/[id]/view-as` NEW — TEAM_LEAD+ impersonation preview. Sticky orange banner with expiry countdown + Exit; "what's hidden" notice; read-only ticket list with per-card links to the agent inbox. Lives under (agent) route group (NOT /admin/* which is SUPER_ADMIN-only).

noteStability

• •+47 new tests (web 1033/1033 green; 988 → 1033). Core 457/457 unchanged. db typecheck clean. Lint clean.
• •No new external deps. No env var changes.

noteBehavior notes

• •The pre-existing inboxId: '' bug on the old /portal/new would have 400'd every customer-portal ticket submission. V2 fixes by fetching from /sessions on submit. Existing direct widget integrations are unaffected (they pass inboxId explicitly).
• •IP allowlist + rate-limit middleware do not gate the portal (session-cookie auth path, not API-key). No change here.
• •/portal/help/* lives under the X-Robots-Tag-blocked /portal namespace; AI crawlers are blocked. The marketing AEO surface remains /knowledge/{slug}.

noteTier-2 status

16/16 settings-core variants + 5/5 customer-portal variants shipped. Next: tier-3 queue (tenant-dashboard recommended first, smallest ~4d, 0 schema migrations). Customer-portal closeout.

noteUI (5 surfaces)

• •V1 `/settings/api-keys` REWRITE. Honesty banner, 4 StatCards (Active / Expiring ≤30d / Requests-24h honest empty / Revoked all-time), filter row (search / status / scopeGroup), KeysTable with computed badges (Quiet / Inactive / Expired / Revoked / Rotating), per-row Popover menu (Edit / Rotate / Set expiry / Revoke). EmptyState fallback.
• •V2 `/settings/api-keys/new` NEW dedicated route. 3-step Stepper:
• •V3 `/settings/rate-limits` REWRITE. Plan-tier banner, 4 StatCards (Requests 24h / 429s % of total / Active windows / Top offender API key), pure-CSS bar chart (no chart library), plan-defaults matrix from PLAN_RATE_LIMIT_DEFAULTS. Auto-refresh every 60s matching the rollup worker cadence.
• •V4 `/settings/ip-allowlist` NEW. Honesty banner (enforcement-on vs off), inline AddIpEntryForm with soft-warn at 40/50 cap, IpAllowlistTable (tenant-wide vs key-specific badge, last-seen, remove), IpDenialsTable (90-day log with Geo + Tor flag + one-click + Allowlist CTA that posts /32 or /128).
• •V5 `/settings/deletion-approvals` NEW. Tab strip (Pending / Approved / Rejected / Expired) with groupBy counts. DeletionRequestCard with scope summary 4-stat grid, expiry countdown, action column branching on self-requester (Cancel) vs other admin (Approve / Reject modal with reason). Single-admin tenant red banner.

1. Name (env auto-detected from NODE_ENV — Step 1 collapsed per scope §4.2 Q1) 2. Scopes + expiry: 3 quick presets (Read-only / Full integration / Webhook-only) + collapsible scope catalog (8 groups) + 4 expiry tiles + red admin-superscope warning 3. Reveal secret with auto-copy on mount, no re-show, no sessionStorage, beforeunload guard, zero-out on unmount, quickstart tabs (cURL / TypeScript SDK / Python / Node) via @helpmesh/core quickstartSnippet().

noteSidebar + redirects

• •apps/web/src/app/(agent)/settings/layout.tsx: Developer section grows from 3 → 5 entries (adds IP allowlist + Deletion approvals).
• •apps/web/src/app/(agent)/settings/developer/page.tsx: replaces the legacy tab page with a page-level redirect() (per feedback_next_config_redirects_shadow.md, never next.config.mjs). ?tab=webhooks|integrations|rate-limits preserved.

noteNew shared components (15 files)

• •components/settings/api-keys/: KeysTable, EditKeyDialog, RotateKeyDialog (auto-copy reveal), RevokeKeyDialog (type-name confirm), CreateKeyStep1Name, CreateKeyStep2Scopes, CreateKeyStep3Reveal.
• •components/settings/rate-limits/: RateLimitsChart, PlanDefaultsTable.
• •components/settings/ip-allowlist/: AddIpEntryForm, IpAllowlistTable, IpDenialsTable.
• •components/settings/deletion-approvals/: DeletionRequestCard.

noteStability

• •@helpmesh/web typechecks clean across 96 test files / 983 tests passing.
• •Lint clean apart from 2 pre-existing console warnings in lib/api-handler.ts + lib/logger.ts.
• •No new packages.

noteWhat's still pending

• •Pending-count badge on the Deletion approvals sidebar entry (needs a tenant-wide signal endpoint not currently exposed).
• •Daily worker for AWAITING_APPROVAL → EXPIRED transitions (cheap ~20 LoC follow-up; the gate already rejects approvals where expiresAt <= now via canApproveDeletion).
• •After this lands: customer-portal PR (locked scope, 5 surfaces).

noteWhy ship backend-only

• •Tenant.requireTwoAdminDelete defaults false for legacy tenants → /api/v1/privacy/delete keeps its synchronous behavior. No existing API consumer is broken.
• •IP allowlist has zero entries on every tenant → middleware no-ops for everyone until someone adds a CIDR (no UI to add one yet).
• •Approve/reject/cancel endpoints exist but are unused until the UI lands.

noteAdded — Schema (1 migration, additive only)

• •DataDeletionRequest: 7 new nullable fields for the two-admin approval gate (approvedById/At, rejectedById/At, rejectReason, scopeSummary JSON, expiresAt). Status vocabulary widened: AWAITING_APPROVAL | APPROVED | REJECTED | EXPIRED. Legacy PENDING + completedAt rows promoted to COMPLETED by the migration.
• •ApiKey.deprecatedAt (nullable) — set by the rotate endpoint for a 24h grace window; resolveTenant treats the key as revoked past this timestamp.
• •Tenant.requireTwoAdminDelete (bool, default false) — opt-in flag for the two-admin gate. Defaults false for legacy tenants, will be set true for new tenants when the create-tenant flow flips it (follow-up).
• •RateLimitUsage15Min (new table) — 15-min rollup of API request counts. Worker populates from Redis counters; 30-day TTL via the audit-log-retention sweep.
• •IpAllowlistDenial (new table) — append-only log of API-key requests rejected by the IP-allowlist middleware. 90-day TTL.

Migration: 20260512100000_settings_developer_pr. Zero application-side backfill.

noteAdded — `@helpmesh/core` (validation + helpers)

• •schemas/ipAllowlistEntry — CIDR v4+v6 via ipaddr.js (new MIT dep, 15kb gzip) + tenant caps (50 / 20).
• •schemas/apiKeyRateLimit — scope-group enum (read|write|ai|webhook|bulk|all), PLAN_RATE_LIMIT_DEFAULTS table, scopeGroupForPath() router.
• •schemas/deletionApproval — status vocabulary, list filter, reject reason, scope-summary JSON shape, 7-day expiry constant.
• •privacy/canApproveDeletion — single-source approval gate. Codes: HM-DELETION-NOT-PENDING | HM-DELETION-EXPIRED | HM-DELETION-SELF-APPROVAL | HM-DELETION-SINGLE-ADMIN.
• •api-keys/policy — computeKeyBadges() with thresholds (60d inactive-warn, 90d stale, 30d expiry-soon, 24h/72h grace).
• •api-keys/quickstart — cURL/TypeScript/Python/Node snippet templates for the create-key reveal screen.
• •security/cidr — ipInAnyRange() (v4/v6, no 4-in-6 coercion) + clientIpFromHeaders().

noteAdded — APIs (12 new + 2 modified, all ADMIN-gated, OpenAPI-registered)

• •GET /api/v1/api-keys (extended): ?status=active|expiring|expired|inactive|revoked, ?scopeGroup=, ?q=. Response now carries computed badges + a stats summary (activeCount, expiringSoonCount, revokedAllTimeCount; requests24h + throttled24h are null until the rollup table has data — honest empty-state).
• •PATCH /api/v1/api-keys/:id — edit name/scopes/expiresAt. Never returns raw key material.
• •POST /api/v1/api-keys/:id/rotate — issues a new secret, deprecates the old for graceHours (default 24h, max 72h). 409 if already mid-rotation.
• •GET /api/v1/rate-limits — plan defaults + 24h usage buckets + top-offender API key.
• •GET/POST /api/v1/api-keys/:id/rate-limits and PATCH/DELETE .../[rid] — per-key overrides. 409 on duplicate scopeGroup.
• •GET/POST /api/v1/ip-allowlist + DELETE /:id — CRUD with cap enforcement (HM-IP-ALLOWLIST-CAP).
• •GET /api/v1/ip-allowlist/denials — recent middleware-rejection log.
• •GET /api/v1/privacy/deletion-requests (extended): ?status= filter + per-status counts via groupBy.
• •POST /api/v1/privacy/deletion-requests/:id/approve | reject | cancel — three terminal transitions backed by canApproveDeletion.
• •POST /api/v1/privacy/delete (extended): when tenant.requireTwoAdminDelete is true, returns 202 + AWAITING_APPROVAL request row. Otherwise unchanged.

noteAdded — Middleware (IP allowlist enforcement)

• •server/middleware/ip-allowlist: cached snapshot of CIDRs by scope (tenant-wide vs per-key), 30s TTL, evicted on write.
• •lib/api-handler: calls checkIpAllowlist + logDenial only on the API-key auth branch (apiKeyScopes !== null). Browser sessions, super-admin impersonation, and subdomain-only flows skip the check. Session-bypass failsafe locked by a source-contract test so a future refactor can't move the check.
• •403 code: HM-AUTH-IP_NOT_ALLOWED. Per the kickoff Q: "admin can always log into helpmesh.io/inbox from any IP and fix a bad allowlist".

noteAdded — Worker (`apps/worker`)

• •rate-limit-rollup processor: every 60s SCANs Redis rl_count:* counters, GETDELs them, aggregates by tenant + apiKey + scopeGroup + 15-min bucket, and upserts into RateLimitUsage15Min. Lost-data-point is the safer failure mode than double-counting.
• •lib/api-handler + server/middleware/rate-limit.bumpUsageCounter: fire-and-forget INCR on every API request — separate suffix for throttled (429) vs OK paths.

noteTests

• •+123 new tests across @helpmesh/core (34: CIDR + deletion approval gate) and @helpmesh/web (89: source-contract isolation tests + 8 unit tests on checkIpAllowlist + 3 session-bypass guards + behavior contract on /privacy/delete).
• •All packages green: web 983/983, core 457/457, db 222/222, worker 66/66, auth 4/4.
• •Monorepo typecheck clean. Lint clean.

noteBehavior note (CHANGELOG-load-bearing)

• •/api/v1/privacy/delete semantics change is GATED by tenant.requireTwoAdminDelete defaulting false. New tenants will be created with it true once the tenant-create flow flips it; existing tenants keep the synchronous behavior until they opt in via the UI (not in this release).
• •IP allowlist enforcement is OFF for every tenant in this release because no tenant has entries. Adding any entry via the new POST /api/v1/ip-allowlist will start enforcing for that tenant's API-key callers — session auth always bypasses.

noteStill to ship (next PRs)

• •5 UI surfaces: API keys list redesign + Create-key 3-step flow + Rate limits page + IP allowlist page + Deletion approvals queue.
• •Settings sidebar: split Developer section into 5 entries + pending-count badge.
• •Legacy /settings/developer page → 301 redirect to /settings/api-keys (page-level, not next.config).
• •Worker for EXPIRED flips on DataDeletionRequest past expiresAt.
• •ECS one-shot migrate job before the code tag deploys (per feedback_deploy_does_not_run_migrations.md).

Per docs/plans/pr-settings-developer-scope.md. PR #101 on feat/settings-developer-pr.

noteLocked decisions (user-confirmed before kickoff)

• •Custom CSS textarea SHIPS in PR-E behind Growth+/Scale/Enterprise plan gate, with cssom-style sanitization + type-to-confirm modal + AuditLog on every write
• •"Live preview" rail SHIPS as a real iframe (postMessage handshake) — the marketing promise
• •Sub-processor 30-day pre-notice email worker SHIPS in PR-E (daily 02:00 UTC scheduler)
• •ZERO changes under apps/web/src/app/api/billing/ (Stripe contract untouched)
• •AI provider per-row attribution DEFERRED (clean implementation needs a different data model; billing UI shows aggregate "Total" only, honestly subtitled "Provider breakdown coming soon")

noteAdded — Schema (4 additive Tenant columns, 1 migration)

• •Tenant.brandingTokens (jsonb default '{}') — typography + dark-mode tokens, validated by BrandingTokensSchema
• •Tenant.customCss (text nullable) — tenant-supplied CSS, validated by CustomCssSchema (max 8KB, dangerous-token rejection: @import, external url(), expression(, behavior:, javascript:, vbscript:, <script, position: fixed/sticky). Render-time scoping to [data-tenant="<id>"] is a help-center concern (deferred).
• •Tenant.retentionPolicy (jsonb default '{}', DB-side backfilled from auditRetentionDays) — per-entity retention { closedTickets, attachments, auditLog, csat: { days, postExpiry: 'delete' | 'anonymize' | 'cold_storage' } }
• •Tenant.subProcessorAck (jsonb nullable) — { acknowledgedAt, version, byUserId }

Migration: 20260512090000_pr_e_foundation. Zero application-side backfill needed.

noteAdded — Zod schemas (4 new) + static data (3 new) in `@helpmesh/core`

• •BrandingTokensSchema — bodyFont/displayFont/allowDarkMode
• •CustomCssSchema + isCustomCssValid() helper
• •RetentionPolicySchema + DEFAULT_RETENTION_POLICY constant
• •SubProcessorAckSchema + SubProcessorAckRequestSchema
• •data/subProcessors.ts — SUB_PROCESSORS list + SUB_PROCESSOR_VERSION constant + isAckCurrent() helper. 6 entries: AWS, Anthropic, OpenAI, Postmark, Stripe, Pusher.
• •data/complianceStatus.ts — COMPLIANCE_STATUS array. Honest wording per CLAUDE.md: ISO 27001 "in progress · Type I targeted Q3 2026", SOC 2 "in progress · readiness ~64/100", GDPR/PDPL/DPDPA "in effect".
• •fixtures/sampleInvoice.ts — SAMPLE_INVOICE + sampleInvoiceTotalCents() for the branded-invoice-preview empty state

noteAdded — APIs (5 new + 1 extended)

• •PATCH /api/v1/tenant (EXTENDED, ADMIN) — accepts brandingTokens (full-shape JSON, validated) + customCss (Zod-validated, plan-gated 403 HM-PLAN-INSUFFICIENT when plan ∈ {TRIAL, STARTER}). Allowed: GROWTH | SCALE | ENTERPRISE. AuditLog auto-written by apiHandler.
• •GET/PATCH /api/v1/settings/retention (NEW) — PATCH is OWNER-tier (audit-retention impact). Enforces monotonic-up for closedTickets/attachments/csat (can only lengthen) and free range [30, 3650] for auditLog. Returns DEFAULT_RETENTION_POLICY for legacy tenants with {}.
• •GET /api/v1/settings/sub-processors (NEW, session) — returns { processors, version, ack, isCurrent }
• •POST /api/v1/settings/sub-processors/ack (NEW, ADMIN) — version match required (400 HM-VERSION-MISMATCH), stamps {acknowledgedAt, version, byUserId}
• •GET /api/v1/settings/compliance-status (NEW, session) — aggregator with live counts: open DataExportRequest (PENDING/PROCESSING), open DataDeletionRequest (PENDING/PROCESSING), open BreachIncident (OPEN/CONTAINED), DpoContact presence boolean
• •GET /api/v1/billing/ai-usage (NEW, session) — current period AI usage; honestly returns providers: [{ name: 'total', ... }] since per-provider attribution is deferred. Cost rates from @helpmesh/core/billing/ai-cost (estimateAiCostUsd, blended Sonnet+Haiku rates).
• •GET /api/v1/usage (EXTENDED) — additive optional aiByProvider field

noteUI (3 surfaces built in parallel by 3 sub-agents)

• •`/settings/branding` REWRITE (~765 lines page + 12 new component files ~1400 lines):
• •`/settings/data-privacy` NEW (~161 lines page + 5 components ~1000 lines):
• •`/settings/billing` REWRITE (951→506 lines page + 12 sub-components ~1370 lines):

- Logo & favicon (lifted into LogoUploadZone component — preserved S3 presigned 3-step dance verbatim) - Color palette + dark-mode toggle (writes brandingTokens.allowDarkMode) - Typography (writes brandingTokens.bodyFont + displayFont) - White-label section with custom-domain status row + reply signature + Powered-by toggle (plan-gated) - Live preview rail — real iframe at /preview/branding?surface=help|widget|email, postMessage handshake with strict origin check, hot-updates on form change. 3 client components render the surfaces. - Custom CSS section — advanced section, plan-gated, type-to-CONFIRM modal on first save - 3 compliance tiles from compliance-status endpoint - Retention table with client-side monotonic-up enforcement (number min={currentDays} for non-audit entities) - 2 customer-data-request cards (Export + Delete with type-to-DELETE modal) wiring to existing GDPR endpoints - Sub-processors table with conditional re-ack banner (only when isCurrent === false) and "Up to date" pill when current - 11 sections matching variant 18 preview - Zero Stripe contract changes — change-plan body shape preserved (buildChangePlanBody() is the sole producer, source-string regex test guards drift) - AI usage section honestly shows the single "Total" bar with "Provider breakdown coming soon" subtitle - Referral counts initialized to zero with hasStatsEndpoint={false} and TODO comment — no fake numbers - Branded invoice preview uses OWNER membership name (not viewer's) - Payment-method "Add new" opens Stripe portal in same tab (never embed Stripe Element)

noteAdded — Worker (sub-processor pre-notice job)

• •processSubProcessorNotice in apps/worker/src/processors/sub-processor-notice.ts (~140 lines)
• •Daily scheduler on the low-priority queue (pattern: '0 2 * * *' — 02:00 UTC)
• •For every ACTIVE tenant whose subProcessorAck.version is older than SUB_PROCESSOR_VERSION: enqueues an email-send critical job + writes an InAppNotification row, both idempotent
• •Notifies OWNER + ADMIN memberships only
• •Idempotency: noticeToken subproc-notice:{tenantId}:{version} used as BullMQ jobId AND as the InAppNotification title suffix for findFirst-dedupe

noteTests

• •+179 web tests (715 → 894)
• •+11 worker tests (55 → 66)
• •Repo total: 1419 → 1609 (net +190 across PR-E)
• •All 24 core test files (423), 5 db test files (222), 1 auth test file (4), 81 web test files (894), 6 worker test files (66) green

noteQuality gates

• •pnpm -r typecheck clean across all 12 packages
• •pnpm -r lint clean (only 2 pre-existing console warnings in api-handler.ts + logger.ts)
• •pnpm --filter @helpmesh/web build clean Next build
• •Stripe-untouched sanity: git diff main..HEAD -- apps/web/src/app/api/billing/ is EMPTY

noteOut of scope (deferred follow-ups)

• •AI provider per-row attribution (needs a different data model — child table or join key change that doesn't break the existing tenantId_period upsert). Billing UI honestly shows aggregate-only until this lands.
• •CSS render-time injection on /help/* pages (column is in place; the help-center page consuming it is a separate concern)
• •Stripe Element embed (PCI scope — portal-only stays)
• •Breach-notification admin UI (BreachIncident model exists; admin filing surface is a separate PR)
• •/api/v1/billing/referrals aggregator endpoint (page is wired with zeros and a TODO)
• •Multi-year sub-processor list expansion + per-jurisdiction sub-processor variants
• •Powered-by toggle gating UX polish (currently a tooltip + upgrade link)

noteAdded — Schema (1 new table, 2 indexes)

• •AutomationRun (NEW) — execution history rows. Columns: id, createdAt, tenantId, automationId, threadId?, status (matched|skipped|error), errorMessage?, durationMs, input(jsonb). Cascade-delete from both Tenant and Automation. 30-day retention is a worker concern (not part of this migration).
• •Composite index (tenantId, automationId, createdAt DESC) — tuned for the flow-editor recent-runs rail.
• •Composite index (automationId, status) — tuned for status filtering on the runs page.

Migration: 20260511020000_automation_run.

noteAdded — Zod schemas in `@helpmesh/core`

• •AutomationRunStatusSchema — 'matched' | 'skipped' | 'error'.
• •AutomationRunInputSchema — sanitized trigger snapshot { event: string; payload?: Record<string, unknown> }.
• •TestFireRequestSchema — body shape for the dry-run endpoint.

noteAdded — APIs (3 new + 1 restructured)

• •GET /api/v1/automations/:id/runs (NEW, session-tier) — cursor pagination, limit≤100, returns sanitized run rows (never the raw input payload per .claude/rules/data-handling.md). 404 on cross-tenant id (never 403).
• •POST /api/v1/automations/:id/test-fire (NEW, ADMIN) — dry-run only. Evaluates ConditionGroupSchema against the supplied event payload, writes an AutomationRun row, returns matched-action list. Never executes side effects (no webhook calls, no label writes, no assignments, no notifications). 12 operators supported: equals, not_equals, contains, not_contains, starts_with, ends_with, gt, gte, lt, lte, is_set, is_not_set. PII fields in payload are stripped at the API layer before persistence (15-key denylist: email, phone, body, bodyHtml, bodyText, customer, customerEmail, customerPhone, from, to, cc, bcc, apiKey, token, password).
• •GET/PATCH /api/v1/ai (RESTRUCTURED) — PATCH tier tightened from AGENT to ADMIN. Accepts BOTH legacy flat shape AND new nested { ai: AiSettingsInput } shape. GET returns both data.settings (flat, back-compat) and data.ai (nested) so the transitional deploy never breaks a client mid-flight. API key values never returned over the wire — only hasKey: boolean per provider. 5 flat keys still mirrored on nested writes because the worker + cost-tracker read them directly: aiEnabled, aiMonthlyBudgetUsd, aiDailyTokenLimit, aiProvider, aiModel.

noteUI built in parallel by 2 sub-agents

• •`/settings/ai` (REWRITTEN, ~900 lines, variant 10) — 2 stat tiles (Spent + Tokens; cache-hit tile hidden because the orchestrator doesn't track that metric — no fake stats), 3 provider cards (Anthropic / OpenAI / Gemini) with hasKey status + model select + disconnect, monthly budget cap + alert threshold, auto-draft (tone segmented + length slider + system prompt textarea), 5 per-feature toggles, 3 guardrail toggles. PATCH body uses nested shape.
• •`/settings/automations/[id]` (NEW, ~1100 lines, variant 12) — vertical canvas (trigger card → condition card → action chain), no graph library, no drag-to-connect, no multi-branch paths. Right rail (320px) shows selected-node config form + recent runs list. Sticky header with back link + name input + Live pill + Test fire button + Save. Test-fire modal validates synthetic JSON payload client-side, hits /test-fire, shows matched-action list. Disabled when id === 'new' (tooltip "Save the rule first").
• •Treats id === 'new' as create mode — POST on first save, router.replace to the persisted URL.

noteList page wiring

• •/settings/automations "New rule" button now navigates to /settings/automations/new (was a TODO toast).
• •Row chevrons already navigated to /settings/automations/{id} (shipped alpha.40); the destination page now exists.
• •"Browse templates" CTA still pending — pushed to PR-E.

noteTests

• •102 new tests across the 3 new/restructured routes (19 + 26 + 23 contract tests + 6 + 7 isolation tests + 23 ai route tests, includes pre-existing transform tests still green). Web test count: 634 → 715. Repo total: 1279 → 1419 (net +140 across PR-C tests, PR-D tests, PR-D-flow).
• •Tenant isolation tests follow the established source-string + Zod contract pattern (no live HTTP+DB harness exists in this repo today; a follow-up could build one).

noteBackwards compatibility

• •AI route accepts both shapes; GET returns both. The legacy /settings/ai page would still load and save correctly during the deploy window.
• •All schema additions are additive. AutomationRun is a brand-new table; nothing reads from it yet outside the new endpoints.
• •Disconnect UX caveat: when the user clicks Disconnect on a provider, hasKey: false saves but the underlying API key string is preserved in tenant.settings.<provider>ApiKey (because the route preserves on empty per preserveApiKeys()). The hasKey boolean correctly reads false on subsequent loads; the residual string is invisible to the UI. A proper explicit-clear path is a follow-up.

noteSynthetic-condition guard

The flow editor blocks Save with a toast when conditions are empty rather than smuggling a no-op {field:'_', operator:'is_set'} row past ConditionGroupSchema.conditions.min(1). Caught during integration review.

noteOut of scope (deferred to follow-ups)

• •AI test prompt comparison panel (scope doc §4.2 Q3 — defer to PR-E).
• •Per-provider usage attribution on TenantUsage (needs schema change; today the combined figure shows on the default provider card only).
• •Worker-side AutomationRun writes on real fires (worker untouched this PR; production fires still happen, just without history). Plumbing is intentionally one-sided: API can write, worker can't yet.
• •Real Slack integration delivery for the send_notification action (table doesn't exist).
• •Action drag-reorder within the canvas (action order is array-order on read).
• •Multi-branch condition paths (variant 12 single "Match" path only — branching is a v2).

noteAdded — Schema (3 columns + 1 index)

• •User.defaultReplyVisibility (text default 'reply')
• •NotificationPreference.eventChannels (jsonb nullable; null = legacy fallback)
• •Automation.runCount / errorCount (int default 0), lastFiredAt (timestamp), position (int default 0, backfilled via row_number() OVER (PARTITION BY tenantId ORDER BY createdAt))
• •Composite index Automation_tenantId_position_idx for the list query

Migration: 20260511010000_pr_d_settings_foundation.

noteAdded — Zod schemas (4 new + 2 extended) in `@helpmesh/core`

• •BusinessHoursSchema extended: dateEnd on holidays + slaPause/autoReply/showOnlineBadge optional booleans. Split-shifts deferred (would have broken computeDeadline.ts).
• •AiSettingsSchema (NEW) — providers, defaultProvider, budgetCapMonthly, features, autoDraft, guardrails. Ships now so PR-D-flow's AI route has a contract; no UI/API consumes it yet.
• •NotificationEventChannelsSchema (NEW) — full matrix shape, all required.
• •AutomationReorderSchema (NEW) — { ids: cuid[].min(1).max(500) }.
• •UserProfileSchema extended: accepts defaultReplyVisibility: 'reply' | 'note'.

noteAdded — APIs (5 new + 2 extended)

• •GET/PATCH /api/v1/settings/business-hours — wrapper around tenant businessHours; PATCH ADMIN, replace-not-merge.
• •PATCH /api/v1/automations/reorder — atomic transaction; tenant-scoped pre-flight count detects cross-tenant id smuggling.
• •GET /api/v1/me/availability/capacity — { used, max, autoPause }; counts open threads (status OPEN/PENDING).
• •GET /api/v1/me/availability/calendar — 90-day-capped strip; precedence ooo > holiday > working > closed.
• •PATCH /api/v1/users/me extended for defaultReplyVisibility.
• •GET/PATCH /api/v1/users/me/notifications extended for eventChannels (null clears via Prisma.JsonNull).

noteAI route REVERTED intentionally

Initial pass restructured PATCH validation to AiSettingsSchema + tightened AGENT→ADMIN, but writing only to settings.ai broke the existing /settings/ai page (still sends flat keys). Ships intact in PR-D-flow alongside the redesigned AI page.

noteUI built in parallel by 3 sub-agents

• •`/settings/business-hours` (NEW, 549 lines, variant 4) — time zone, weekly schedule, holidays with multi-day support, off-hours behavior toggles. UAE 2026 holiday import deferred.
• •`/settings/automations` (REDESIGNED, 501 lines, variant 11) — native HTML5 drag-drop reorder (no @dnd-kit dep), per-row run-count/last-fired/error pill, isActive toggle (immediate PATCH), delete with confirm. Inline create form removed.
• •TODO closures (3 files): real eventChannels matrix in notifications (Slack column added but DISABLED with tooltip — SlackIntegration table doesn't exist), defaultReplyVisibility persists in profile, capacity-used wired in availability banner, 60-day OOO calendar strip (CSS grid; green/gray/amber/red).

One integration fix post-agents: removed dead toggleChannel + ChannelKey from notifications.

noteBackwards compatibility

• •All schema additions nullable or have safe defaults; no existing row behaviour changes.
• •Notification matrix: when eventChannels is null, workers fall back to (events × channels) cross-product. Front-end writes the new shape on first save.
• •Automations: position backfilled from createdAt order — list order is stable.
• •AI route untouched; existing /settings/ai page works exactly as before.

noteOut of scope (deferred to PR-D-flow)

• •AI page redesign + AI route restructuring (variant 10)
• •Flow editor canvas (variant 12) + AutomationRun + /runs + /test-fire
• •BusinessHoursSchema split-shifts
• •Bundled UAE 2026 holiday data
• •Functional Slack DM delivery (column DISABLED for now)
• •Per-provider AI usage stat split

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •core 423 / db 222 / web 634 tests all pass (web was 526 = +108)
• •repo build ✓ (36s)

noteBuilt in parallel

1 API agent + 3 UI agents off centralized schema + APIs. Pattern proven in PR-C.

noteTests (+56)

• •users/me/route.contract.test.ts — 15 cases on the extended PATCH (UserProfileSchema): new fields accepted, empty-string-clears semantics, length bounds, silent stripping of email/role/tenantId.
• •me/availability/availability.contract.test.ts — 20 cases (UserAvailabilitySchema): partial bodies, ISO datetime parsing, workingHours empty/null/per-day shapes, capacity bounds, autoPause boolean, silent stripping.
• •csat/config/config.contract.test.ts — 21 cases (CsatConfigSchema): PATCH-as-PUT with empty body, scale + delayUnit enum validation, delayValue [0,720] + recentSurveyWindowDays [1,180] bounds, ADMIN-only verification.
• •All three import schemas directly from @helpmesh/core — no schema duplication. Suite runs in 2.44s.

docsDocs

• •docs/plans/pr-d-scope.md (263 lines) — covers the next tier-2 wave. 4 primary surfaces (business hours, AI, automations list, flow editor) + 4 PR-C TODO closures. Recommended sequence: split into PR-D (schema + APIs + 3 surfaces + 4 TODO closures, ~5d) and PR-D-flow (canvas editor + AutomationRun + /runs + /test-fire, ~4d). Honest decisions captured (per-event-channel JSON column vs relational, vertical-only flow render, test-fire dry-run only, AI route auth tightening).

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •web tests: 582 pass (was 526; +56 new)
• •Code-only PR — no schema, no migration. Ships via standard tag-push deploy.

noteAdded — Schema (User + Tenant)

• •User.displayName, User.personalTimezone — profile niceties.
• •User.outOfOfficeUntil, User.outOfOfficeMessage — single forward-looking OOO flag.
• •User.workingHours (Json) — per-user override of tenant business hours, validated by BusinessHoursSchema.
• •User.maxConcurrentTickets (Int default 0; 0 = unlimited), User.autoPauseAtCapacity (Bool default false) — capacity-aware round-robin foundation.
• •Tenant.csatConfig (Json default {}) — survey behavior config (delay, scale, skip rules, per-channel toggles).
• •Partial index on User.outOfOfficeUntil for the round-robin OOO filter.

noteMigration — `20260511000000_user_availability_and_csat_config`

• •7 new columns on User + 1 on Tenant. All nullable or have safe defaults — no backfill needed.

noteAdded — Zod schemas in `@helpmesh/core`

• •UserAvailabilitySchema — OOO + working hours + capacity.
• •UserProfileSchema — name + displayName + avatarUrl + personalTimezone + replySignature; never accepts email/role/tenantId.
• •CsatConfigSchema — enabled + delay + scale + skip rules + per-channel toggles. Enums CsatScale + CsatDelayUnit exported.

noteAdded — APIs

• •PATCH /api/v1/users/me extended: now accepts name, displayName, avatarUrl, personalTimezone (was replySignature only). Email/role still unwritable.
• •GET/PATCH /api/v1/me/availability — new. Self-managed, session-scoped.
• •GET/PATCH /api/v1/csat/config — new. PATCH is ADMIN-only. Full-shape replace (not partial-merge) to keep the contract simple.

noteUI redesigns (matching `docs/ui-previews/settings-core.html`)

• •`/settings/csat` — REWRITTEN as a config page (variant 9). Old stats dashboard concept moved out (a future /reports/csat-trends page picks it up). Sections: master switch, "When to ask", "Skip rules", "Channel-specific behavior" (Slack row disabled per preview).
• •`/settings/notifications` — Redesigned with locked PR-A primitives (variant 13). Sections: quick-toggle card, 3-channel × 6-event matrix, quiet hours.
• •`/settings/profile` — Redesigned (variant 14). Identity + Personal preferences fully wired. Security + Personal API tokens stubbed with TODOs (need new APIs).
• •`/settings/availability` — NEW page (variant 15). Status banner, working-hours editor (7 days), capacity + auto-pause, single-OOO schedule/end UI.

noteSchema-mismatches handled (TODOs in code)

• •Notifications: per-event-per-channel granularity → cells share column-master state. Slack DM column dropped (no Slack channel in API).
• •Notifications: 8-event preview list → only the 6 the API persists.
• •Profile: Security (MFA, sessions) + Personal API tokens stubbed.
• •Profile: Default reply visibility stored locally only.
• •Availability: 60-day calendar visualizer + capacity-used count + historical OOO list deferred (single-flag data model).

noteBackwards compatibility

• •Schema: only additions; existing rows behave as "inherit defaults".
• •PATCH /api/v1/users/me previously accepted only replySignature. New fields all optional. Existing callers unaffected.
• •Old CSAT data endpoints (/api/v1/csat, /api/v1/csat/stats) still respond. A future /reports/csat-trends page can re-render them.

noteBuilt in parallel

4 sub-agents redesigned the 4 pages in parallel against centralized schema + APIs. ~1900 lines of new/redesigned UI.

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •core 423 / db 222 / web 526 tests all pass
• •repo build ✓ (37s)

noteAdded — Worker reads from the table

• •apps/worker/src/processors/customer-welcome.ts now reads welcome-email content from the SystemEmailTemplate table (PR2.4a) instead of tenant.settings.customerWelcomeEmail JSON.
• •New resolveWelcomeTemplate({tenantId, customerLocale, tenantDefaultLocale, legacyJson}) returns {subject, body, source, locale}. source is one of table / json-fallback / defaults for telemetry.

noteAdded — Locale waterfall

• •customer.locale → tenant.defaultLocale → 'en'. Single Prisma query with IN [...] filter, then pick by candidate order to honor priority. Duplicate locales deduped before the query. enabled=true filter at the query layer; disabled rows are invisible.

noteAdded — Backfill-on-cache-miss

• •Cache miss for ALL three locale candidates → fall back to legacy JSON shape and lazy-upsert a row for the locale that won. The next send for the same (tenantId, locale) hits the table path. This closes the gap from PR2.4a's non-blocking dual-write.
• •Legacy flat JSON shape (pre-PR2.2 subject+body at root) is synthesized as an en row.
• •Backfill upsert failures are logged + non-fatal — the send still goes out using the JSON-derived content.

noteAdded — MJML rendering (worker-only)

• •New apps/worker/src/lib/render-email-html.ts. Async function returns {html, mjmlRendered}.
• •Three input shapes: MJML markup → compiled via mjml@5 (validationLevel: 'soft'); plain HTML (Tiptap output) → pass-through verbatim; plaintext → escape + paragraph-wrap (same logic the previous toHtml() used).
• •MJML compile errors fall back to a sanitized text-only render so the send still goes out.
• •Worker-only — keeps the ~3MB mjml@5 dependency out of the web bundle. Build verified: web bundle size unchanged.

noteTests (+22)

• •render-email-html.test.ts — 10 cases: MJML happy path, uppercase + leading whitespace detection, compile-error fallback, HTML pass-through (incl. merge tags), plaintext wrap (paragraph breaks, single-newline → <br>, char escaping, inline styles).
• •customer-welcome.test.ts — 12 new cases: customer locale wins, fall back to tenant default, fall back to en, locale candidate dedup, enabled=true filter, JSON per-locale fallback, lazy backfill triggered on cache miss, legacy flat JSON synthesis, defaults branch, null-on-disabled, swallow-and-warn on backfill failure.
• •8 existing resolveWelcomeFromHeader tests untouched and still pass.

noteDependencies

• •mjml@5.2.0 added to apps/worker (~3MB unpacked). Async API (mjml2html returns Promise<{html, json, errors}>).
• •@types/mjml not installed — mjml@5 ships its own types.
• •No web-side changes; web bundle unaffected.

noteBackwards compatibility

• •Legacy tenant.settings.customerWelcomeEmail JSON shape is still read as the cache-miss fallback. PR2.4c will retire it entirely.
• •The dual-write helper from PR2.4a is still active in PATCH /api/v1/tenant — it now races with the worker's lazy backfill, but upsert semantics make it idempotent.
• •No schema changes — code-only PR. Ships via the standard tag-push deploy. No migration required.

noteOut of scope (PR2.4c)

• •Remove the JSON shape from tenant.settings.customerWelcomeEmail
• •Drop the dual-write helper in PATCH /api/v1/tenant
• •Drop the JSON-fallback branch in resolveWelcomeTemplate

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •worker tests: 55 pass (was 33)
• •repo build ✓ (33s)

noteAdded — `SystemEmailTemplate` model

• •New table at packages/db/prisma/schema.prisma. One row per (tenantId, key, locale) with enabled, subject, preheader?, body. Composite unique on the three-tuple. Cascade delete on tenant.
• •key column accepts customer-welcome, agent-invite, or password-reset (validated by SystemEmailTemplateKeySchema at the API layer; the DB stays generic for future expansion).
• •Distinct from the existing user-authored tenant.settings.emailTemplates JSON which holds agent reply templates — different concern, different namespace.

noteMigration — `20260510140000_system_email_template`

• •CREATE TABLE + composite UNIQUE + tenant FK.
• •Backfills customer-welcome rows from each tenant's existing tenant.settings.customerWelcomeEmail JSON, locale=en (the only locale the legacy shape carried). Tenants with no JSON get no row.
• •agent-invite and password-reset rows are NOT pre-seeded — those consumers will lazy-create on first use.

noteAdded — Zod validation in `@helpmesh/core`

• •SystemEmailTemplateSchema (full create) and SystemEmailTemplateUpdateSchema (partial, key+locale required).
• •BCP-47 locale shape, RFC 5322 subject cap (998 chars), 50KB body cap, optional 200-char preheader.

noteAdded — Dual-write helper (non-blocking)

• •New mirrorCustomerWelcomeToTable helper at apps/web/src/app/api/v1/tenant/system-email-template-dual-write.ts wired into PATCH /api/v1/tenant. When customerWelcomeEmail is in the body, mirrors each filled locale into a SystemEmailTemplate row.
• •Failures don't block the JSON write — the legacy JSON shape stays authoritative through alpha.36, so a mirror miss only logs a warning. PR2.4b's read-flip will read-then-backfill on cache miss to close any gap.
• •Handles the legacy flat JSON shape (pre-PR2.2 subject+body at the root) by synthesizing an en row.
• •Defends against malformed locale keys from bad client payloads.

noteTenant isolation

• •SystemEmailTemplate added to TENANT_SCOPED_MODELS in the AsyncLocalStorage middleware so tenantId is auto-injected on every Prisma op.
• •Coverage suite expanded; also caught a pre-existing gap where BulkActionRun was in middleware but missing from the test fixture (fixed in the same diff to keep them in sync).

noteTests (+37)

• •@helpmesh/core — 29 Zod schema cases covering key enum, BCP-47 locale shape, length caps, partial-update shape.
• •@helpmesh/db — tenant-scope assertions auto-expanded across the new model (× 9 ops × 2 newly-added rows in the fixture).
• •@helpmesh/web — 8 dual-write helper cases (mock prisma): per-locale upsert, enabled flag persisted, legacy flat-shape synthesis, invalid-locale defense, preheader nulling, swallow-and-warn on upsert failure, no-op on empty payload.

noteBackwards compatibility

• •Reads still come from tenant.settings.customerWelcomeEmail JSON. PR2.4b will flip reads to the new table.
• •The worker (apps/worker/src/processors/customer-welcome.ts) is untouched — welcome-email sends continue to work exactly as in alpha.35.
• •The mirror helper degrades safely: if the table doesn't exist or upsert errors, the JSON write still succeeds.

noteOut of scope (deferred)

• •PR2.4b — MJML rendering in the worker + flip reads from JSON → table.
• •PR2.4c — retire the JSON shape entirely.

noteDeploy ordering

The migration ran via the helpmesh-migrate-prod ECS one-shot task after deploy.yml pushed the new :latest worker image. This is the canonical HelpMesh pattern — deploy.yml does NOT run migrations, and the migrate-prod task uses the :latest worker image so it must run after the new image is pushed.

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •core 423 / db 222 / web 526 tests all pass
• •build ✓ (47s)

fixFixed

• •apps/web/next.config.mjs carried 25 redirects from a pre-redesign "settings consolidation" that bounced flat /settings/* paths into a tabbed group wrapper (e.g. /settings/general → /settings/workspace?tab=general). Next.js processes config redirects BEFORE page components, so these silently overrode:
• •Removed all 25. Each canonical /settings/* path now serves its own redesigned page directly. Page-level redirect() calls in page components are unaffected by config rules and continue to work.

- PR-A's redesigned /settings/general and /settings/localization (alpha.32) - PR1's redirect() stub at /settings/welcome-email → /settings/email-templates/welcome (alpha.34)

noteBackwards compatibility

• •The legacy tabbed group pages (/settings/workspace, /settings/channels, /settings/people, /settings/content, /settings/automation, /settings/developer, /settings/notifications-audit) still exist on disk and remain reachable directly. Only the auto-bouncing stops.
• •Bookmarks to /settings/workspace?tab=general keep working unchanged.
• •Bookmarks to /settings/general now land on the redesigned page directly (the desired behavior since alpha.32).

noteDiscovered

During alpha.34 prod smoke test: /settings/welcome-email returned 307 → /settings/workspace?tab=welcome-email instead of the new welcome-email path. Investigating revealed /settings/general and /settings/localization were also being shadowed.

noteQuality gates

• •typecheck ✓
• •lint ✓ (only pre-existing warnings)
• •518 tests still pass

noteAdded — `/settings/email-templates/welcome` (PR1 → PR2.3)

• •Full visual lift — SettingsSection / SettingsFormRow / SettingsSaveBar primitives from PR-A; trigger toggle + sender + message + live preview sections; desktop/mobile preview toggle.
• •Route move — page lives at /settings/email-templates/welcome to match the sub-nav PR-A shipped (alpha.32). The legacy /settings/welcome-email path is now a redirect() stub so existing bookmarks resolve cleanly.
• •Tiptap body editor — bold / italic / lists / link toolbar + {{merge.tag}} insert dropdown. Direction-aware (rtl when active locale = ar). Persists sanitized HTML; legacy plaintext bodies migrate forward at read time.
• •Locale tabs — English (source) + Arabic + French. Each locale stores its own subject / preheader / body. Empty fields fall back to the source at send time per the published resolveLocale() contract. Per-locale completeness dot beside each non-source tab.
• •Send-test endpoint — POST /api/v1/email-templates/welcome/send-test (ADMIN+). Recipient locked to the authenticated session user — no caller-supplied recipient field. Rate-limited 5/hour/tenant. Audit-logged with locale + fellBackToSource + Postmark messageId. Wrapped in a 🧪 TEST banner so admins cannot confuse it with a customer-facing send.
• •`Send test` button in the Message section header — disabled while loading / dirty / in-flight.

noteAdded — `EmailSender.sendWelcomeTest()`

New method on packages/channels/src/email/outbound-sender.ts that takes the resolved (post-merge-tag, post-sanitize) subject + HTML body and sends via Postmark with Tag welcome-template-test, TrackOpens=false, TrackLinks='None'. Test sends don't pollute template analytics.

noteAdded — helpers + tests (+37 new)

• •render-merge-tags.ts (+ 7 vitest cases) — substitutes {{token}} / {{token.path}}; unknown tags preserved verbatim so authors notice typos in the live preview.
• •text-to-html.ts (+ 8 vitest cases) — legacy plaintext → HTML at read time. Paragraph breaks (\n\n) become <p>; single \n becomes <br>. Existing HTML passes through verbatim.
• •locale-helpers.ts (+ 10 vitest cases) — isLocaleFilled() (treats empty Tiptap output <p></p> as not filled) and resolveLocale() (per-field source fallback at send time).
• •build-locale.ts (+ 6 vitest cases) — extracts the legacy/new shape merge logic out of the send-test route so its contract gets dedicated coverage.
• •send-test.contract.test.ts (+ 6 vitest cases) — defends the recipient-lock + tenantId-strip security properties.

featureChanged

• •`CI` — .github/workflows/deploy-prod.yml (manual workflow_dispatch lever) renamed to Manual Deploy to Production so gh run list --workflow="Deploy to Production" resolves uniquely to deploy.yml (the active tag-triggered workflow). Behavior unchanged. (PR #88)

noteBackwards compatibility

• •Persistence shape lives under existing tenant.settings.customerWelcomeEmail. The new code reads BOTH the legacy flat shape (subject, body) AND the new per-locale map (locales.en, .ar, .fr), and writes the new shape on save. Existing tenants keep their content.
• •Plaintext bodies lift cleanly into Tiptap via textToHtml() at read time.
• •Empty AR/FR locales always fall back to the English source at send time, so existing tenants who never author translations stay safe.

noteTenant isolation

• •welcome/send-test route uses apiHandler middleware (tenantId injected server-side) and prisma.tenant.findUnique scoped to the resolved tenantId.
• •The body schema is locked to { locale: 'en' | 'ar' | 'fr' } — caller-supplied to / email / recipient / cc / tenantId fields are silently stripped by Zod, asserted by an explicit contract test.

noteQuality gates

• •typecheck ✓ across all 15 packages
• •lint ✓ (only pre-existing warnings)
• •apps/web: 518 passed (+37 vs alpha.33's 481)
• •packages/db: 202 · core: 394 · auth: 4 · ai: 35 · billing: 3 · reporting: 19 · worker: 34 · sdk: 11

noteStack rationale

The PR2 work was deliberately split into 4 stacked PRs (Tiptap → locales → send-test → schema/MJML) so each landed as a separable unit. PR2.4 (EmailTemplate Prisma model + Prisma migration + MJML rendering) is deferred to its own session because the schema migration must deploy via the ECS one-shot worker BEFORE the consuming code ships.

featureAdded

• •`/settings/email-domain` — Custom email domain (BYOD) status card + link to /settings/inboxes#byod where DNS records + verify flow live.
• •`/settings/channels/email` — Email channel summary listing connected email inboxes with per-inbox configure links.