From fc9787374e9b0c38bfdac6ff04787a2cb15f0ee4 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Mon, 12 Oct 2026 18:32:14 +1100
Subject: [PATCH] feat(identity): add one optional welcome email

---
 COPY.md                                       |   9 ++
 .../identity/app/pages/onboarding/email.vue   |  16 +-
 layers/identity/server/api/me/email.patch.ts  |  21 ++-
 layers/identity/server/api/unsubscribe.get.ts |   2 +-
 .../identity/server/api/unsubscribe.post.ts   |   2 +-
 .../server/api/unsubscribe/undo.post.ts       |   2 +-
 layers/identity/server/schemas/unsubscribe.ts |   2 +-
 .../identity/server/utils/account-deletion.ts |   1 +
 layers/identity/server/utils/email.ts         |  10 +-
 layers/identity/server/utils/unsubscribe.ts   |  37 +++--
 layers/identity/server/utils/welcome-email.ts |  74 +++++++++
 layers/identity/shared/contracts/account.ts   |   7 +-
 migrations/0156_welcome_email_delivery.sql    |  12 ++
 shared/welcome-email-copy.ts                  |  11 ++
 test/unit/account-deletion.nuxt.test.ts       |   2 +
 test/unit/digest-opt-in-address.test.ts       |  19 +++
 test/unit/email-form-submit.nuxt.test.ts      |  34 +++-
 test/unit/welcome-email.test.ts               | 151 ++++++++++++++++++
 18 files changed, 385 insertions(+), 27 deletions(-)
 create mode 100644 layers/identity/server/utils/welcome-email.ts
 create mode 100644 migrations/0156_welcome_email_delivery.sql
 create mode 100644 shared/welcome-email-copy.ts
 create mode 100644 test/unit/welcome-email.test.ts

diff --git a/COPY.md b/COPY.md
index 5d810367..29491f04 100644
--- a/COPY.md
+++ b/COPY.md
@@ -11,6 +11,15 @@ contradicts this file is a bug.
 
 ## Canonical assets
 
+The optional welcome email uses the subject "Your skilld account is ready".
+Its body is "Like Skills to find them again in your account." and "Watch the Repositories you use and see what changed."
+Its final line is "Your weekly and monthly email choices stay as you set them."
+Its one main action is "Open your account", linking to `/me`.
+Its footer is "Stop welcome emails", linking to a signed welcome unsubscribe URL.
+Onboarding offers an unchecked choice: "Send me one welcome email with account tips."
+The missing-address message is "Add an email address, or turn off all email choices."
+Welcome unsubscribe says "You will not get welcome emails. Your weekly and digest settings are unchanged."
+
 Skill validation in `/me` uses "Skill validation" and "Some of your Skills have validation issues."
 The action is "View validation issues". Source links use "Open SKILL.md".
 Email summaries use the subject "Your Skills have validation issues" and link to `/me?view=repositories`.
diff --git a/layers/identity/app/pages/onboarding/email.vue b/layers/identity/app/pages/onboarding/email.vue
index 26cb4ee3..b176a863 100644
--- a/layers/identity/app/pages/onboarding/email.vue
+++ b/layers/identity/app/pages/onboarding/email.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { IdentityEmailPatchBody, IdentityMutationResponse } from '../../../shared/contracts/account'
 import { signupEmailChoice } from '#shared/signup-analytics'
+import { WELCOME_EMAIL_COPY } from '#shared/welcome-email-copy'
 import { identityAccountQueries, identityAccountQueryOptions } from '../../queries/account'
 
 definePageMeta({ layout: 'auth', middleware: ['auth'] })
@@ -15,6 +16,7 @@ const email = ref(me.value?.digest_email || me.value?.email || '')
 const hasEmailChoices = computed(() => !!me.value?.onboarded_at || !!me.value?.digest_email)
 const optIn = ref(hasEmailChoices.value ? !!me.value?.email_opt_in : true)
 const weeklyOptIn = ref(hasEmailChoices.value ? !!me.value?.weekly_opt_in : true)
+const welcomeEmail = ref(false)
 watch(me, (account, previous) => {
   if (account && !previous) {
     email.value = account.digest_email || account.email || ''
@@ -42,7 +44,7 @@ const finishOnboardingMutation = useNuxtMutation<void, IdentityMutationResponse>
 
 // Opting in needs somewhere to send the digest, so the address is required
 // exactly when the box is ticked.
-const missingAddress = computed(() => (optIn.value || weeklyOptIn.value)
+const missingAddress = computed(() => (optIn.value || weeklyOptIn.value || welcomeEmail.value)
   && !/^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(email.value.trim()))
 
 const submitting = computed(() => saveEmailMutation.pending.value || finishOnboardingMutation.pending.value)
@@ -53,6 +55,7 @@ async function finish() {
     digest_email: email.value,
     email_opt_in: optIn.value,
     weekly_opt_in: weeklyOptIn.value,
+    ...(welcomeEmail.value ? { welcome_email: true } : {}),
   })
   if (saved._tag === 'err') {
     recordSignup({ stage: 'email', outcome: 'failed', entry: 'onboarding' })
@@ -104,7 +107,7 @@ useSeoMeta({ title: 'Email opt-in', robots: 'noindex' })
           class="mt-2 min-h-11 w-full rounded-lg border border-default bg-default px-3 py-2 font-mono text-sm focus-visible:outline-2 focus-visible:outline-primary"
         >
         <p v-if="missingAddress" id="email-error" class="mt-1 text-xs text-error">
-          Add an email address, or turn off both emails.
+          {{ WELCOME_EMAIL_COPY.missingAddress }}
         </p>
       </div>
 
@@ -122,7 +125,14 @@ useSeoMeta({ title: 'Email opt-in', robots: 'noindex' })
         </span>
       </label>
 
-      <p v-if="!optIn && !weeklyOptIn" class="rounded-lg border border-default bg-elevated/50 p-3 text-xs text-muted">
+      <label class="flex min-h-11 items-start gap-3 cursor-pointer">
+        <input v-model="welcomeEmail" type="checkbox" :disabled="submitting" class="mt-0.5 size-4 accent-primary">
+        <span class="text-sm text-muted leading-relaxed">
+          {{ WELCOME_EMAIL_COPY.consent }}
+        </span>
+      </label>
+
+      <p v-if="!optIn && !weeklyOptIn && !welcomeEmail" class="rounded-lg border border-default bg-elevated/50 p-3 text-xs text-muted">
         You won't receive any emails. You can opt in later from your dashboard.
       </p>
     </form>
diff --git a/layers/identity/server/api/me/email.patch.ts b/layers/identity/server/api/me/email.patch.ts
index b7666841..a9dcb18b 100644
--- a/layers/identity/server/api/me/email.patch.ts
+++ b/layers/identity/server/api/me/email.patch.ts
@@ -6,6 +6,7 @@ import { planAccountSettings, updateAccountSettings } from '../../utils/account-
 import { sendEmailWithEnv, signUnsubToken } from '../../utils/email'
 import { sendSkillValidationSummary } from '../../utils/skill-validation-email'
 import { requireUserRow } from '../../utils/users'
+import { sendWelcomeEmail } from '../../utils/welcome-email'
 
 export default defineApiHandler({
   schema: identityEmailPatchBodySchema,
@@ -26,6 +27,22 @@ export default defineApiHandler({
     await updateAccountSettings(platform.db, u.id, plan.columns)
     const config = useRuntimeConfig(event)
     const updated = await requireUserRow(event)
+    const welcome = sendWelcomeEmail({
+      db: platform.db,
+      userId: updated.id,
+      // The request address owns this consent, even if another save races this one.
+      to: body.digest_email ?? '',
+      consent: body.welcome_email === true,
+      now: Math.floor(Date.now() / 1000),
+      attemptId: crypto.randomUUID(),
+      signUnsubscribe: userId => signUnsubToken(userId, config.tokenKey, 'welcome'),
+      send: input => sendEmailWithEnv(platform.env, { ...input, from: config.email.from }),
+    }).then((outcome) => {
+      if (outcome === 'rejected' || outcome === 'uncertain')
+        emitOperationalEvent(createWideEvent({ operation: 'welcome-email', outcome: 'failed' }))
+    }).catch(() => {
+      emitOperationalEvent(createWideEvent({ operation: 'welcome-email', outcome: 'failed' }))
+    })
     const summary = sendSkillValidationSummary({
       db: platform.db,
       user: updated,
@@ -40,9 +57,9 @@ export default defineApiHandler({
     })
     const context = (event.context as { cloudflare?: { context?: { waitUntil?: (p: Promise<unknown>) => void } } }).cloudflare?.context
     if (context?.waitUntil)
-      context.waitUntil(summary)
+      context.waitUntil(Promise.all([summary, welcome]))
     else
-      await summary
+      await Promise.all([summary, welcome])
     const current = session as unknown as UserSession | null
     if (current?.user && (body.email_opt_in !== undefined || body.weekly_opt_in !== undefined)) {
       await setUserSession(event, {
diff --git a/layers/identity/server/api/unsubscribe.get.ts b/layers/identity/server/api/unsubscribe.get.ts
index e74afab4..8e31559d 100644
--- a/layers/identity/server/api/unsubscribe.get.ts
+++ b/layers/identity/server/api/unsubscribe.get.ts
@@ -7,7 +7,7 @@ export default defineApiHandler({
   schema: UnsubQuery,
   handler: async ({ event, body }) => {
     const config = useRuntimeConfig(event)
-    const userId = await verifyUnsubToken(body.t, config.tokenKey as string)
+    const userId = await verifyUnsubToken(body.t, config.tokenKey as string, body.list === 'welcome' ? 'welcome' : 'recurring')
     if (!userId) {
       setResponseStatus(event, 400)
       setHeader(event, 'content-type', 'text/html; charset=utf-8')
diff --git a/layers/identity/server/api/unsubscribe.post.ts b/layers/identity/server/api/unsubscribe.post.ts
index a1e74d16..b5be34ca 100644
--- a/layers/identity/server/api/unsubscribe.post.ts
+++ b/layers/identity/server/api/unsubscribe.post.ts
@@ -20,7 +20,7 @@ export default defineApiHandler({
       setHeader(event, 'content-type', 'text/html; charset=utf-8')
       return renderUnsubscribePage({ _tag: 'invalid' })
     }
-    const userId = await verifyUnsubToken(parsed.data.t, config.tokenKey as string)
+    const userId = await verifyUnsubToken(parsed.data.t, config.tokenKey as string, parsed.data.list === 'welcome' ? 'welcome' : 'recurring')
     if (!userId) {
       setResponseStatus(event, 400)
       setHeader(event, 'content-type', 'text/html; charset=utf-8')
diff --git a/layers/identity/server/api/unsubscribe/undo.post.ts b/layers/identity/server/api/unsubscribe/undo.post.ts
index b7f21425..bb021c71 100644
--- a/layers/identity/server/api/unsubscribe/undo.post.ts
+++ b/layers/identity/server/api/unsubscribe/undo.post.ts
@@ -15,7 +15,7 @@ export default defineApiHandler({
     const userId = parsed.success
       ? await verifyUnsubToken(parsed.data.t, config.tokenKey as string)
       : null
-    if (!parsed.success || !userId) {
+    if (!parsed.success || !userId || parsed.data.list === 'welcome') {
       setResponseStatus(event, 400)
       setHeader(event, 'content-type', 'text/html; charset=utf-8')
       return renderUnsubscribePage({ _tag: 'invalid' })
diff --git a/layers/identity/server/schemas/unsubscribe.ts b/layers/identity/server/schemas/unsubscribe.ts
index 9623f813..c8c57fc3 100644
--- a/layers/identity/server/schemas/unsubscribe.ts
+++ b/layers/identity/server/schemas/unsubscribe.ts
@@ -10,5 +10,5 @@ export const UnsubQuery = z.object({
    * unsubscribe would turn off the digest instead, which is a different
    * promise from the one the reader clicked.
    */
-  list: z.enum(['weekly', 'digest']).default('digest'),
+  list: z.enum(['weekly', 'digest', 'welcome']).default('digest'),
 })
diff --git a/layers/identity/server/utils/account-deletion.ts b/layers/identity/server/utils/account-deletion.ts
index 3055f55b..b8dc016a 100644
--- a/layers/identity/server/utils/account-deletion.ts
+++ b/layers/identity/server/utils/account-deletion.ts
@@ -30,6 +30,7 @@ const ACCOUNT_ROW_DELETES = [
   `DELETE FROM weekly_runs WHERE user_id = ?1`,
   `DELETE FROM email_preference_events WHERE user_id = ?1`,
   `DELETE FROM skill_validation_email_deliveries WHERE user_id = ?1`,
+  `DELETE FROM welcome_email_deliveries WHERE user_id = ?1`,
   `DELETE FROM artifact_resolution_requesters WHERE account_id = ?1`,
   `DELETE FROM artifact_download_grants WHERE account_id = ?1`,
   `DELETE FROM private_artifact_attestations WHERE account_id = ?1`,
diff --git a/layers/identity/server/utils/email.ts b/layers/identity/server/utils/email.ts
index e180514b..82c65fc4 100644
--- a/layers/identity/server/utils/email.ts
+++ b/layers/identity/server/utils/email.ts
@@ -118,16 +118,16 @@ async function hmacKey(secret: string): Promise<CryptoKey> {
   return crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify'])
 }
 
-export async function signUnsubToken(userId: number, secret: string): Promise<string> {
+export async function signUnsubToken(userId: number, secret: string, scope: 'recurring' | 'welcome' = 'recurring'): Promise<string> {
   if (!secret)
     throw createError({ statusCode: 500, message: 'NUXT_TOKEN_KEY missing' })
-  const payload = b64urlEncode(enc.encode(JSON.stringify({ u: userId, exp: 0 })))
+  const payload = b64urlEncode(enc.encode(JSON.stringify({ u: userId, exp: 0, ...(scope === 'welcome' ? { scope } : {}) })))
   const key = await hmacKey(secret)
   const sig = await crypto.subtle.sign('HMAC', key, enc.encode(payload))
   return `${payload}.${b64urlEncode(sig)}`
 }
 
-export async function verifyUnsubToken(token: string, secret: string): Promise<number | null> {
+export async function verifyUnsubToken(token: string, secret: string, scope: 'recurring' | 'welcome' = 'recurring'): Promise<number | null> {
   if (!secret || !token.includes('.'))
     return null
   const [payload, sig] = token.split('.')
@@ -137,7 +137,9 @@ export async function verifyUnsubToken(token: string, secret: string): Promise<n
   const valid = await crypto.subtle.verify('HMAC', key, b64urlDecode(sig), enc.encode(payload))
   if (!valid)
     return null
-  const data = JSON.parse(dec.decode(b64urlDecode(payload))) as { u?: number, exp?: number }
+  const data = JSON.parse(dec.decode(b64urlDecode(payload))) as { u?: number, exp?: number, scope?: string }
+  if (scope === 'welcome' ? data.scope !== 'welcome' : data.scope !== undefined)
+    return null
   if (typeof data.u !== 'number')
     return null
   return data.u
diff --git a/layers/identity/server/utils/unsubscribe.ts b/layers/identity/server/utils/unsubscribe.ts
index 142a341d..f750c90f 100644
--- a/layers/identity/server/utils/unsubscribe.ts
+++ b/layers/identity/server/utils/unsubscribe.ts
@@ -1,4 +1,5 @@
 /// <reference types="@cloudflare/workers-types" />
+import { WELCOME_EMAIL_COPY } from '#shared/welcome-email-copy'
 
 /**
  * Turning off one list without touching the other.
@@ -7,7 +8,7 @@
  * unsubscribe and the GET half a person clicks run identical SQL.
  */
 
-export type UnsubList = 'weekly' | 'digest'
+export type UnsubList = 'weekly' | 'digest' | 'welcome'
 
 export interface UnsubOutcome {
   list: UnsubList
@@ -34,7 +35,7 @@ function weeklySetting(db: D1Database, userId: number, restored: boolean): D1Pre
 async function writePreference(
   db: D1Database,
   userId: number,
-  list: UnsubList,
+  list: Exclude<UnsubList, 'welcome'>,
   action: EmailPreferenceAction,
 ): Promise<void> {
   const value = action === 'restored'
@@ -53,6 +54,16 @@ export async function applyUnsubscribe(
   userId: number,
   list: UnsubList,
 ): Promise<UnsubOutcome> {
+  if (list === 'welcome') {
+    // Keep the row, so clicking this link cannot make a welcome eligible again.
+    await db.prepare(`INSERT INTO welcome_email_deliveries
+      (user_id, status, attempted_at, attempt_id, unsubscribed_at)
+      VALUES (?1, 'cancelled', unixepoch(), 'unsubscribe', unixepoch())
+      ON CONFLICT(user_id) DO UPDATE SET unsubscribed_at = unixepoch()`)
+      .bind(userId)
+      .run()
+    return { list, heading: 'Unsubscribed.', body: WELCOME_EMAIL_COPY.stopped }
+  }
   await writePreference(db, userId, list, 'unsubscribed')
   if (list === 'weekly') {
     return {
@@ -71,7 +82,7 @@ export async function applyUnsubscribe(
 export async function applyResubscribe(
   db: D1Database,
   userId: number,
-  list: UnsubList,
+  list: Exclude<UnsubList, 'welcome'>,
 ): Promise<UnsubOutcome> {
   await writePreference(db, userId, list, 'restored')
   return {
@@ -98,7 +109,7 @@ function esc(value: string): string {
 
 export function renderUnsubscribePage(input: UnsubscribePageInput): string {
   const list = input._tag === 'invalid' ? null : input.list
-  const label = list === 'weekly' ? 'weekly' : 'digest'
+  const label = list === 'welcome' ? 'welcome' : list === 'weekly' ? 'weekly' : 'digest'
   const title = input._tag === 'confirm'
     ? `Stop ${label} emails?`
     : input._tag === 'invalid'
@@ -106,20 +117,22 @@ export function renderUnsubscribePage(input: UnsubscribePageInput): string {
       : input.action === 'restored'
         ? 'Email restored'
         : 'Email stopped'
-  const body = input._tag === 'confirm'
-    ? `You can restore ${label} emails after this change.`
-    : input._tag === 'invalid'
-      ? 'Open the latest email and try its unsubscribe link again.'
-      : input.action === 'restored'
-        ? `You will get ${label} emails again.`
-        : `You will not get ${label} emails.`
+  const body = list === 'welcome'
+    ? input._tag === 'confirm' ? 'Your weekly and digest settings will stay unchanged.' : WELCOME_EMAIL_COPY.stopped
+    : input._tag === 'confirm'
+      ? `You can restore ${label} emails after this change.`
+      : input._tag === 'invalid'
+        ? 'Open the latest email and try its unsubscribe link again.'
+        : input.action === 'restored'
+          ? `You will get ${label} emails again.`
+          : `You will not get ${label} emails.`
   const action = input._tag === 'confirm'
     ? `<form method="post" action="/api/unsubscribe">
         <input type="hidden" name="t" value="${esc(input.token)}">
         <input type="hidden" name="list" value="${input.list}">
         <button type="submit">Stop ${label} emails</button>
       </form>`
-    : input._tag === 'complete' && input.action === 'unsubscribed'
+    : input._tag === 'complete' && input.action === 'unsubscribed' && list !== 'welcome'
       ? `<form method="post" action="/api/unsubscribe/undo">
           <input type="hidden" name="t" value="${esc(input.token)}">
           <input type="hidden" name="list" value="${input.list}">
diff --git a/layers/identity/server/utils/welcome-email.ts b/layers/identity/server/utils/welcome-email.ts
new file mode 100644
index 00000000..de0fe03e
--- /dev/null
+++ b/layers/identity/server/utils/welcome-email.ts
@@ -0,0 +1,74 @@
+import type { SendEmailInput, SendEmailResult } from './email'
+import { WELCOME_EMAIL_COPY as copy } from '#shared/welcome-email-copy'
+import { digestEmailHeaders } from './email'
+
+interface WelcomeEmailInput {
+  db: D1Database
+  userId: number
+  to: string
+  consent: boolean
+  now: number
+  attemptId: string
+  signUnsubscribe: (userId: number) => Promise<string>
+  send: (input: SendEmailInput) => Promise<SendEmailResult>
+}
+
+export function renderWelcomeEmail(unsubscribeUrl: string): Pick<SendEmailInput, 'subject' | 'html' | 'text'> {
+  const link = 'https://skilld.dev/me'
+  const safeUnsubscribeUrl = unsubscribeUrl.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+  return {
+    subject: copy.subject,
+    html: `<!doctype html><html lang="en"><head><meta name="viewport" content="width=device-width,initial-scale=1"><title>${copy.subject}</title></head>
+<body style="margin:0;background:#f5f4f2;color:#1c1917;font-family:Arial,sans-serif">
+<table role="presentation" style="width:100%;border-collapse:collapse"><tr><td style="padding:32px 16px">
+<table role="presentation" style="width:100%;max-width:560px;margin:auto;border-collapse:collapse"><tr><td style="padding:28px;background:#fff;border:1px solid #d6d3d1;border-radius:8px">
+<p style="margin:0 0 28px;font-family:monospace;font-size:20px;font-weight:bold">&gt; skilld<span style="color:#be123c">.</span></p>
+<h1 style="font-size:26px;line-height:1.25;margin:0 0 24px">${copy.subject}</h1>
+<p style="font-size:16px;line-height:1.6">${copy.skills}</p><p style="font-size:16px;line-height:1.6">${copy.watch}</p>
+<p style="font-size:14px;line-height:1.6;color:#57504b">${copy.choices}</p>
+<p style="margin:28px 0 0"><a href="${link}" style="display:inline-block;background:#be123c;color:#fff;text-decoration:none;font-weight:bold;padding:14px 20px;border-radius:8px">${copy.action}</a></p>
+</td></tr><tr><td style="padding:16px 0;font-size:12px"><a href="${safeUnsubscribeUrl}" style="color:#57504b">${copy.unsubscribe}</a></td></tr></table>
+</td></tr></table></body></html>`,
+    text: `${copy.skills}\n\n${copy.watch}\n\n${copy.choices}\n\n${copy.action}: ${link}\n\n${copy.unsubscribe}: ${unsubscribeUrl}`,
+  }
+}
+
+/** Only preparation can retry. Dispatch is terminal even if its receipt is lost. */
+export async function sendWelcomeEmail(input: WelcomeEmailInput): Promise<'skipped' | SendEmailResult['_tag']> {
+  if (!input.consent || !input.to.trim())
+    return 'skipped'
+  const { db, userId, now, attemptId } = input
+  const claimed = await db.prepare(`
+    INSERT INTO welcome_email_deliveries (user_id, status, recipient, consented_at, attempted_at, attempt_id)
+    VALUES (?1, 'claimed', ?2, ?3, ?3, ?4)
+    ON CONFLICT(user_id) DO UPDATE SET attempted_at = excluded.attempted_at,
+      attempt_id = excluded.attempt_id, recipient = excluded.recipient, consented_at = excluded.consented_at
+    WHERE welcome_email_deliveries.status = 'claimed'
+      AND welcome_email_deliveries.attempted_at < ?5
+      AND welcome_email_deliveries.unsubscribed_at IS NULL
+    RETURNING user_id
+  `).bind(userId, input.to.trim(), now, attemptId, now - 300).first<{ user_id: number }>()
+  if (!claimed)
+    return 'skipped'
+  const token = await input.signUnsubscribe(userId)
+  const unsubscribeUrl = `https://skilld.dev/api/unsubscribe?t=${encodeURIComponent(token)}&list=welcome`
+  const dispatch = await db.prepare(`UPDATE welcome_email_deliveries
+    SET status = 'uncertain', error = 'Delivery started without a confirmed receipt'
+    WHERE user_id = ?1 AND attempt_id = ?2 AND status = 'claimed' AND unsubscribed_at IS NULL
+    RETURNING user_id`).bind(userId, attemptId).first<{ user_id: number }>()
+  if (!dispatch)
+    return 'skipped'
+  const outcome = await input.send({
+    to: input.to.trim(),
+    ...renderWelcomeEmail(unsubscribeUrl),
+    headers: digestEmailHeaders(unsubscribeUrl, `skilld-welcome:${userId}`),
+  }).catch((error): SendEmailResult => ({
+    _tag: 'uncertain',
+    error: error instanceof Error ? error.message : String(error),
+  }))
+  await db.prepare(`UPDATE welcome_email_deliveries SET status = ?1, message_id = ?2, error = ?3
+    WHERE user_id = ?4 AND attempt_id = ?5 AND status = 'uncertain'`)
+    .bind(outcome._tag, outcome._tag === 'accepted' ? outcome.messageId : null, outcome._tag === 'accepted' ? null : outcome.error, userId, attemptId)
+    .run()
+  return outcome._tag
+}
diff --git a/layers/identity/shared/contracts/account.ts b/layers/identity/shared/contracts/account.ts
index 1e668f47..50ba18d1 100644
--- a/layers/identity/shared/contracts/account.ts
+++ b/layers/identity/shared/contracts/account.ts
@@ -15,10 +15,15 @@ export const identityEmailPatchBodySchema = z.object({
    * still requires consent, which a captured profile address never provides.
    */
   weekly_opt_in: z.boolean().optional(),
+  /** One welcome email, requested explicitly. It does not enroll either list. */
+  welcome_email: z.boolean().optional(),
 }).refine(
-  input => !(input.email_opt_in || input.weekly_opt_in)
+  input => !(input.email_opt_in || input.weekly_opt_in || input.welcome_email)
     || z.string().email().safeParse(input.digest_email).success,
   { path: ['digest_email'], message: 'Add a valid email address to receive emails' },
+).refine(
+  input => !input.welcome_email || (input.email_opt_in !== undefined && input.weekly_opt_in !== undefined),
+  { message: 'Choose weekly and monthly email settings before requesting a welcome email' },
 )
 
 export const identityMeSchema = z.object({
diff --git a/migrations/0156_welcome_email_delivery.sql b/migrations/0156_welcome_email_delivery.sql
new file mode 100644
index 00000000..1a021c42
--- /dev/null
+++ b/migrations/0156_welcome_email_delivery.sql
@@ -0,0 +1,12 @@
+-- A welcome is explicitly requested once. It never enrolls an existing account.
+CREATE TABLE welcome_email_deliveries (
+  user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  status TEXT NOT NULL CHECK (status IN ('claimed', 'accepted', 'rejected', 'uncertain', 'cancelled')),
+  recipient TEXT,
+  consented_at INTEGER,
+  attempted_at INTEGER NOT NULL,
+  attempt_id TEXT NOT NULL,
+  unsubscribed_at INTEGER,
+  message_id TEXT,
+  error TEXT
+);
diff --git a/shared/welcome-email-copy.ts b/shared/welcome-email-copy.ts
new file mode 100644
index 00000000..85e60889
--- /dev/null
+++ b/shared/welcome-email-copy.ts
@@ -0,0 +1,11 @@
+export const WELCOME_EMAIL_COPY = {
+  subject: 'Your skilld account is ready',
+  skills: 'Like Skills to find them again in your account.',
+  watch: 'Watch the Repositories you use and see what changed.',
+  choices: 'Your weekly and monthly email choices stay as you set them.',
+  action: 'Open your account',
+  unsubscribe: 'Stop welcome emails',
+  consent: 'Send me one welcome email with account tips.',
+  missingAddress: 'Add an email address, or turn off all email choices.',
+  stopped: 'You will not get welcome emails. Your weekly and digest settings are unchanged.',
+} as const
diff --git a/test/unit/account-deletion.nuxt.test.ts b/test/unit/account-deletion.nuxt.test.ts
index 71b17a69..ada69b74 100644
--- a/test/unit/account-deletion.nuxt.test.ts
+++ b/test/unit/account-deletion.nuxt.test.ts
@@ -151,6 +151,8 @@ function seedAccount(raw: DatabaseSync, account: Account, githubToken: string |
   )
   run(`INSERT INTO email_preference_events (user_id, list, action, occurred_at) VALUES (?, 'weekly', 'unsubscribed', ?)`, id, NOW)
   run(`INSERT INTO skill_validation_email_deliveries (user_id, status, attempted_at) VALUES (?, 'accepted', ?)`, id, NOW)
+  run(`INSERT INTO welcome_email_deliveries (user_id, status, recipient, consented_at, attempted_at, attempt_id)
+    VALUES (?, 'accepted', ?, ?, ?, ?)`, id, `${login}@example.com`, NOW, NOW, `welcome-${login}`)
 
   run(
     `INSERT INTO github_app_installations (installation_id, account_id, github_account_id, state, connected_at, verified_at)
diff --git a/test/unit/digest-opt-in-address.test.ts b/test/unit/digest-opt-in-address.test.ts
index 12153937..aaf5d954 100644
--- a/test/unit/digest-opt-in-address.test.ts
+++ b/test/unit/digest-opt-in-address.test.ts
@@ -7,6 +7,9 @@ import { identityEmailPatchBodySchema } from '../../layers/identity/shared/contr
 import { SIGNED_IN_HEADERS } from './helpers/session'
 
 const migrationPath = resolve(process.cwd(), 'migrations/0082_digest_opt_in_requires_address.sql')
+const welcomeSend = vi.hoisted(() => vi.fn().mockResolvedValue('skipped'))
+
+vi.mock('../../layers/identity/server/utils/welcome-email', () => ({ sendWelcomeEmail: welcomeSend }))
 
 vi.mock('../../layers/identity/server/utils/skill-validation-email', () => ({
   sendSkillValidationSummary: vi.fn().mockResolvedValue('skipped'),
@@ -113,6 +116,7 @@ describe('me email patch endpoint', () => {
   const establishSession = vi.fn()
 
   beforeEach(async () => {
+    welcomeSend.mockClear()
     vi.resetModules()
     establishSession.mockReset()
     vi.stubGlobal('defineEventHandler', (handler: EventHandler) => handler)
@@ -163,6 +167,21 @@ describe('me email patch endpoint', () => {
       .toEqual({ digest_email: 'harlan@example.com', email_opt_in: 1 })
   })
 
+  it('uses the address explicitly consented for welcome despite a racing account save', async () => {
+    sqlite.exec(`CREATE TRIGGER racing_address AFTER UPDATE OF digest_email ON users
+      BEGIN UPDATE users SET digest_email = 'other@example.com' WHERE id = NEW.id; END;`)
+    vi.stubGlobal('readBody', () => Promise.resolve({
+      digest_email: 'welcome@example.com',
+      welcome_email: true,
+      email_opt_in: false,
+      weekly_opt_in: false,
+    }))
+    await emailPatchHandler(patchEvent())
+    expect(welcomeSend).toHaveBeenCalledWith(expect.objectContaining({ consent: true, to: 'welcome@example.com' }))
+    expect(sqlite.prepare('SELECT email_opt_in, weekly_opt_out FROM users WHERE id = 1').get())
+      .toEqual({ email_opt_in: 0, weekly_opt_out: 1 })
+  })
+
   it('still saves a real address and unchanged weekly choice', async () => {
     vi.stubGlobal('readBody', () => Promise.resolve({ digest_email: 'New@Example.COM' }))
 
diff --git a/test/unit/email-form-submit.nuxt.test.ts b/test/unit/email-form-submit.nuxt.test.ts
index df5c10e8..b88fea0e 100644
--- a/test/unit/email-form-submit.nuxt.test.ts
+++ b/test/unit/email-form-submit.nuxt.test.ts
@@ -70,6 +70,38 @@ it('offers unfinished accounts a path back to email choices', async () => {
   wrapper.unmount()
 })
 
+it('offers one unchecked welcome and allows it without recurring emails', async () => {
+  const wrapper = await mountSuspended(OnboardingEmail, { attachTo: document.body, route: '/onboarding/email' })
+  const form = wrapper.get('#email-onboarding-form')
+  const choices = form.findAll('input[type="checkbox"]')
+  expect((choices[2]!.element as HTMLInputElement).checked).toBe(false)
+  await choices[0]!.setValue(false)
+  await choices[1]!.setValue(false)
+  await choices[2]!.setValue(true)
+  ;(form.element as HTMLFormElement).requestSubmit()
+  await flushPromises()
+  expect(mocks.execute).toHaveBeenCalledWith(expect.objectContaining({ path: '/api/me/email' }), {
+    digest_email: 'review@example.com',
+    email_opt_in: false,
+    weekly_opt_in: false,
+    welcome_email: true,
+  })
+  wrapper.unmount()
+})
+
+it('requires a valid address when only the welcome is selected', async () => {
+  const wrapper = await mountSuspended(OnboardingEmail, { attachTo: document.body, route: '/onboarding/email' })
+  const form = wrapper.get('#email-onboarding-form')
+  await form.get('input[type="email"]').setValue('broken@')
+  for (const [index, checkbox] of form.findAll('input[type="checkbox"]').entries())
+    await checkbox.setValue(index === 2)
+  ;(form.element as HTMLFormElement).requestSubmit()
+  await flushPromises()
+  expect(mocks.execute).not.toHaveBeenCalled()
+  expect(form.get('#email-error').text()).toBe('Add an email address, or turn off all email choices.')
+  wrapper.unmount()
+})
+
 describe.each(screens)('$name email submission', ({ component, form: selector }) => {
   async function mountForm() {
     const wrapper = await mountSuspended(component, { attachTo: document.body, route: component === Account ? '/me?view=email' : '/onboarding/email' })
@@ -114,7 +146,7 @@ describe.each(screens)('$name email submission', ({ component, form: selector })
       await flushPromises()
 
       expect(mocks.execute).not.toHaveBeenCalled()
-      expect(form.text()).toContain('turn off both emails')
+      expect(form.text()).toContain(component === OnboardingEmail ? 'turn off all email choices' : 'turn off both emails')
     }
     finally {
       wrapper.unmount()
diff --git a/test/unit/welcome-email.test.ts b/test/unit/welcome-email.test.ts
new file mode 100644
index 00000000..059df878
--- /dev/null
+++ b/test/unit/welcome-email.test.ts
@@ -0,0 +1,151 @@
+import type { SqliteD1 } from './helpers/d1-sqlite'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { planAccountSettings, updateAccountSettings } from '../../layers/identity/server/utils/account-settings'
+import { signUnsubToken, verifyUnsubToken } from '../../layers/identity/server/utils/email'
+import { applyUnsubscribe, renderUnsubscribePage } from '../../layers/identity/server/utils/unsubscribe'
+import { sendWelcomeEmail } from '../../layers/identity/server/utils/welcome-email'
+import { identityEmailPatchBodySchema } from '../../layers/identity/shared/contracts/account'
+import { allMigrations, createSqliteD1 } from './helpers/d1-sqlite'
+
+describe('one optional welcome email', () => {
+  let d1: SqliteD1
+  beforeEach(() => {
+    d1 = createSqliteD1(allMigrations())
+    d1.raw.exec(`INSERT INTO users (id, github_id, login, email, created_at, last_login_at)
+      VALUES (900001, 900001, 'new-account', 'account@example.com', 1, 1)`)
+  })
+  afterEach(() => d1.close())
+
+  function input(consent = true, now = 10, attemptId = 'first') {
+    return {
+      db: d1.db,
+      userId: 900001,
+      to: 'account@example.com',
+      consent,
+      now,
+      attemptId,
+      signUnsubscribe: async () => 'signed-token',
+      send: vi.fn().mockResolvedValue({ _tag: 'accepted', messageId: 'receipt' }),
+    }
+  }
+
+  it('requires an address when only the welcome email is selected', () => {
+    expect(identityEmailPatchBodySchema.safeParse({ welcome_email: true }).success).toBe(false)
+  })
+
+  it('requires explicit recurring choices and preserves a welcome-only opt-in', async () => {
+    expect(identityEmailPatchBodySchema.safeParse({ digest_email: 'account@example.com', welcome_email: true }).success).toBe(false)
+    const body = identityEmailPatchBodySchema.parse({ digest_email: 'account@example.com', welcome_email: true, weekly_opt_in: false, email_opt_in: false })
+    const plan = planAccountSettings({ email: 'account@example.com', digest_email: null }, {
+      email: body.digest_email,
+      weekly: body.weekly_opt_in,
+      digest: body.email_opt_in,
+    })
+    if (plan._tag !== 'Ok')
+      throw new Error('Expected valid email choices')
+    await updateAccountSettings(d1.db, 900001, plan.columns)
+    expect(d1.raw.prepare('SELECT email_opt_in, weekly_opt_out FROM users WHERE id = 900001').get())
+      .toMatchObject({ email_opt_in: 0, weekly_opt_out: 1 })
+  })
+
+  it('binds the welcome unsubscribe token to its own list', async () => {
+    const welcome = await signUnsubToken(900001, 'test-secret', 'welcome')
+    const recurring = await signUnsubToken(900001, 'test-secret')
+    expect(await verifyUnsubToken(welcome, 'test-secret', 'welcome')).toBe(900001)
+    expect(await verifyUnsubToken(welcome, 'test-secret')).toBeNull()
+    expect(await verifyUnsubToken(recurring, 'test-secret', 'welcome')).toBeNull()
+    expect(await verifyUnsubToken(recurring, 'test-secret')).toBe(900001)
+  })
+
+  it('records a thrown send as uncertain and prevents another dispatch', async () => {
+    const deps = input()
+    deps.send.mockRejectedValueOnce(new Error('receipt lost'))
+    expect(await sendWelcomeEmail(deps)).toBe('uncertain')
+    expect(await sendWelcomeEmail({ ...deps, attemptId: 'next' })).toBe('skipped')
+    expect(deps.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('never sends without its own consent', async () => {
+    const deps = input(false)
+    expect(await sendWelcomeEmail(deps)).toBe('skipped')
+    expect(deps.send).not.toHaveBeenCalled()
+  })
+
+  it('sends once despite concurrent saves and later requests', async () => {
+    const deps = input()
+    const outcomes = await Promise.all([sendWelcomeEmail(deps), sendWelcomeEmail({ ...deps, attemptId: 'second' })])
+    expect(outcomes.sort()).toEqual(['accepted', 'skipped'])
+    expect(await sendWelcomeEmail({ ...deps, now: 1000, attemptId: 'third' })).toBe('skipped')
+    expect(deps.send).toHaveBeenCalledTimes(1)
+    expect(deps.send).toHaveBeenCalledWith(expect.objectContaining({
+      to: 'account@example.com',
+      subject: 'Your skilld account is ready',
+      text: expect.stringContaining('https://skilld.dev/me'),
+      headers: expect.objectContaining({ 'List-Unsubscribe': '<https://skilld.dev/api/unsubscribe?t=signed-token&list=welcome>' }),
+    }))
+  })
+
+  it.each(['rejected', 'uncertain'] as const)('never repeats a dispatched %s send', async (outcome) => {
+    const deps = input()
+    deps.send.mockResolvedValueOnce({ _tag: outcome, error: 'unavailable' })
+    expect(await sendWelcomeEmail(deps)).toBe(outcome)
+    expect(await sendWelcomeEmail({ ...deps, attemptId: 'second' })).toBe('skipped')
+    expect(await sendWelcomeEmail({ ...deps, now: 1000, attemptId: 'third' })).toBe('skipped')
+    expect(deps.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps welcome unsubscribe separate from the two recurring emails', async () => {
+    await applyUnsubscribe(d1.db, 900001, 'welcome')
+    const deps = input()
+    expect(await sendWelcomeEmail(deps)).toBe('skipped')
+    expect(deps.send).not.toHaveBeenCalled()
+    expect(d1.raw.prepare('SELECT email_opt_in, weekly_opt_out FROM users WHERE id = 900001').get())
+      .toMatchObject({ email_opt_in: 0, weekly_opt_out: 0 })
+    const html = renderUnsubscribePage({ _tag: 'complete', token: 'token', list: 'welcome', action: 'unsubscribed' })
+    expect(html).toContain('Your weekly and digest settings are unchanged.')
+    expect(html).not.toContain('/api/unsubscribe/undo')
+  })
+
+  it('fences an expired worker before it can dispatch', async () => {
+    let release!: () => void
+    let entered!: () => void
+    const held = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    const reached = new Promise<void>((resolve) => {
+      entered = resolve
+    })
+    const deps = input()
+    const old = sendWelcomeEmail({ ...deps, signUnsubscribe: async () => {
+      entered()
+      await held
+      return 'token'
+    } })
+    await reached
+    expect(await sendWelcomeEmail({ ...deps, now: 1000, attemptId: 'new' })).toBe('accepted')
+    release()
+    expect(await old).toBe('skipped')
+    expect(deps.send).toHaveBeenCalledTimes(1)
+  })
+
+  it('honors unsubscribe while a claimed worker prepares its message', async () => {
+    const deps = input()
+    expect(await sendWelcomeEmail({ ...deps, signUnsubscribe: async () => {
+      await applyUnsubscribe(d1.db, 900001, 'welcome')
+      return 'token'
+    } })).toBe('skipped')
+    expect(deps.send).not.toHaveBeenCalled()
+  })
+
+  it('records the latest consent address and time after preparation fails', async () => {
+    const deps = input()
+    await expect(sendWelcomeEmail({ ...deps, signUnsubscribe: async () => {
+      throw new Error('signing unavailable')
+    } }))
+      .rejects
+      .toThrow('signing unavailable')
+    expect(await sendWelcomeEmail({ ...deps, now: 1000, attemptId: 'new', to: 'new@example.com' })).toBe('accepted')
+    expect(d1.raw.prepare('SELECT recipient, consented_at FROM welcome_email_deliveries WHERE user_id = 900001').get())
+      .toMatchObject({ recipient: 'new@example.com', consented_at: 1000 })
+  })
+})