ux(first-touch): welcome email on org.created + Help link in nav

Two small but visible fixes for the brand-new-customer experience.
Empty-state dashboard already had a 3-step welcome hero, but the
two complementary gaps were:

1. Welcome email on org creation
   ──────────────────────────────
   The Clerk `organization.created` webhook was being processed but
   emitted nothing — no email, no inbox notification.  First-touch
   silence ("did anything happen?" gap).

   New `welcome` notification kind:
   - Inbox setting key `welcome_notifications` (default ON)
   - Email setting key `email_welcome` (default ON, no UI today —
     operators flip via direct DB write to suppress on internal
     test orgs)
   - Audience `admin` — resolves to the org creator (who's
     auto-added as the first admin by Clerk)
   - Severity `info` (green bar in email layout)
   - Linked to `/dashboard` so the natural next click is the
     workspace itself

   Templates:
   - `welcome.subject.txt.j2` — friendly subject mentioning the
     three-step path so even unread inbox previews are useful
   - `welcome.body.txt.j2` — plain-text body with copy-pasteable
     install one-liner + dashboard URL
   - `welcome.body.html.j2` — branded layout, three-step rounded
     card, single primary CTA to /dashboard

   Webhook handler (`organization.created` branch in webhooks.py):
   wraps the create_notification call in try/except so a transient
   Clerk recipient-lookup outage doesn't cause Svix to retry the
   webhook and double-email on each retry.

2. Help link in the authenticated app header
   ────────────────────────────────────────
   Layout.jsx had Dashboard / Settings / Admin / MCP / Sentinel /
   Pricing — `/docs` was reachable only by direct URL or via the
   landing page.  Added "Help" between Sentinel and Pricing
   (matches the secondary-nav cluster other SaaS apps use).
   Skipped the support `mailto:` for now since
   support.sourceboxsentry.com isn't provisioned — adding a
   bounce-bound link would be worse than no link at all.

Tests (6 new in tests/test_welcome_email.py):
  - inbox row written on org.created
  - EmailOutbox row enqueued with templates rendered + recipient
    resolved via the stubbed Clerk call
  - global EMAIL_ENABLED kill-switch off → inbox written, email
    skipped (matches every other kind)
  - per-org `email_welcome=false` → inbox written, email skipped
    (the operator-suppression path)
  - create_notification raising → webhook still returns 200 (Svix
    must not retry forever on a partial failure)
  - template content guard — three-step CloudNode + camera mention
    survives in both text + HTML bodies (catches a refactor that
    silently strips the actionable content)

Total: 484 passed (was 478, +6), ruff clean, frontend builds.

Author: Sbussiso

backend/app/api/notifications.py

@@ -79,6 +79,12 @@
     "member_added":        ("member_audit_notifications", True),
     "member_role_changed": ("member_audit_notifications", True),
     "member_removed":      ("member_audit_notifications", True),
+    # First-touch onboarding — fired once when an org is created.
+    # Has its own setting key (no UI toggle today) so a future
+    # "marketing email opt-out" change has somewhere to land
+    # without conflating with the operational kinds above.  Default
+    # True because welcome is a one-time event, not a stream.
+    "welcome": ("welcome_notifications", True),
 }
 
 
@@ -150,6 +156,12 @@
     # event volume.
     "motion":        ("email_motion", False),
     "motion_digest": ("email_motion", False),
+    # First-touch welcome on org creation.  Own setting key with no UI
+    # toggle today — operators can flip via direct DB write if they
+    # need to suppress (e.g. an internal test org).  Default True
+    # because the whole point of the kind is to introduce the product;
+    # an opt-in default would make the gap we're closing reappear.
+    "welcome": ("email_welcome", True),
 }
 # Note: ``disk_critical`` is intentionally NOT in this map.  Disk-full
 # is platform infrastructure state (our Fly volume) — irrelevant to

backend/app/api/webhooks.py

@@ -323,6 +323,48 @@ async def clerk_webhook(request: Request, db: Session = Depends(get_db)):
                     org_id,
                 )
 
+    # ── Organization created ──────────────────────────────────────
+    # First-touch welcome — fires once when a user creates an org via
+    # Clerk's CreateOrganization modal (on signup or later).  The
+    # creator is automatically the org's first admin, so the
+    # ``audience="admin"`` recipient resolution lands the email on
+    # them.  Wrapped in try/except — a recipient-lookup race or a
+    # template-render bug must NOT cause Svix to retry the webhook
+    # forever (the org IS created either way; we'd just keep
+    # double-emailing on each retry).
+    elif event_type == "organization.created":
+        org_id = data.get("id")
+        org_name = data.get("name") or "your organization"
+        if org_id:
+            try:
+                from app.api.notifications import create_notification
+                create_notification(
+                    org_id=org_id,
+                    kind="welcome",
+                    title=f"Welcome to SourceBox Sentry, {org_name}",
+                    body=(
+                        "Your SourceBox Sentry workspace is ready.  "
+                        "Three steps to your first live feed: install "
+                        "CloudNode on the host where your cameras live, "
+                        "wait ~30 seconds for it to register, then add "
+                        "your first camera from Settings → Cameras.  "
+                        "Full docs at /docs."
+                    ),
+                    severity="info",
+                    audience="admin",
+                    link="/dashboard",
+                    meta={
+                        "org_name": org_name,
+                        "created_by": data.get("created_by"),
+                    },
+                    db=db,
+                )
+            except Exception:
+                logger.exception(
+                    "[ClerkWebhook] welcome notification failed for org=%s",
+                    org_id,
+                )
+
     # ── Organization deleted ───────────────────────────────────────
     elif event_type == "organization.deleted":
         org_id = data.get("id")

backend/app/templates/emails/welcome.body.html.j2

@@ -0,0 +1,62 @@
+<h2 style="margin:0 0 16px;font-size:22px;font-weight:600;color:#111;line-height:1.3;">
+  Welcome to SourceBox Sentry
+</h2>
+
+<p style="margin:0 0 20px;font-size:15px;line-height:1.6;color:#374151;">
+  Your workspace is ready.  This is the command center — a
+  self-hosted-camera-feeds dashboard, AI-aware via the MCP
+  integration, with motion detection + incident reports baked in.
+</p>
+
+<p style="margin:0 0 12px;font-size:14px;color:#6b7280;font-weight:600;letter-spacing:0.04em;text-transform:uppercase;">
+  Three steps to your first live feed
+</p>
+
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 24px;width:100%;">
+  <tr>
+    <td style="padding:14px 16px;background:#f9fafb;border-radius:6px 6px 0 0;border-bottom:1px solid #e5e5e9;font-size:14px;line-height:1.6;color:#374151;">
+      <strong style="color:#111;">1. Install CloudNode</strong> on the machine where
+      your cameras live.  One-liner for Linux/macOS:
+      <pre style="margin:8px 0 0;padding:10px 12px;background:#0a0a0f;color:#22c55e;border-radius:4px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12px;overflow-x:auto;">curl -fsSL {{ dashboard_url }}/install.sh | bash</pre>
+    </td>
+  </tr>
+  <tr>
+    <td style="padding:14px 16px;background:#f9fafb;border-bottom:1px solid #e5e5e9;font-size:14px;line-height:1.6;color:#374151;">
+      <strong style="color:#111;">2. Wait ~30 seconds.</strong> CloudNode auto-registers with
+      your org and shows up under Settings → CloudNode panel.
+    </td>
+  </tr>
+  <tr>
+    <td style="padding:14px 16px;background:#f9fafb;border-radius:0 0 6px 6px;font-size:14px;line-height:1.6;color:#374151;">
+      <strong style="color:#111;">3. Add your first camera</strong> (RTSP / ONVIF / HTTP
+      MJPEG) from Settings → Cameras.  The live grid populates
+      immediately.
+    </td>
+  </tr>
+</table>
+
+<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px;">
+  <tr>
+    <td style="background:#22c55e;border-radius:6px;">
+      <a href="{{ dashboard_url }}/dashboard"
+         style="display:inline-block;padding:12px 22px;font-size:15px;font-weight:600;color:#0a0a0f;text-decoration:none;">
+        Open dashboard →
+      </a>
+    </td>
+  </tr>
+</table>
+
+<p style="margin:0 0 8px;font-size:14px;color:#6b7280;font-weight:600;">
+  Need a hand?
+</p>
+<p style="margin:0;font-size:14px;line-height:1.6;color:#374151;">
+  The full documentation lives at
+  <a href="{{ dashboard_url }}/docs" style="color:#22c55e;text-decoration:none;">{{ dashboard_url }}/docs</a>.
+  Start with <em>Getting Started</em> or jump straight to <em>CloudNode setup</em>
+  if you've already got the install running.
+</p>
+
+<p style="margin:24px 0 0;font-size:13px;color:#9ca3af;line-height:1.5;">
+  This is a one-time welcome.  No recurring marketing email — only
+  operational alerts you've opted into.
+</p>

backend/app/templates/emails/welcome.body.txt.j2

@@ -0,0 +1,35 @@
+{{ notification.title }}
+
+Your SourceBox Sentry workspace is ready.  This is the command
+center — a self-hosted-camera-feeds dashboard, AI-aware via the
+MCP integration, with motion detection + incident reports baked in.
+
+Three steps to your first live feed:
+
+  1. Install CloudNode on the machine where your cameras live.
+     One-liner for Linux/macOS:
+       curl -fsSL {{ dashboard_url }}/install.sh | bash
+     Windows: download the installer from
+       {{ dashboard_url }}/downloads/windows/x64
+
+  2. The CloudNode auto-registers with your org and shows up under
+     Settings → CloudNode panel within ~30 seconds of starting.
+
+  3. Add your first camera (RTSP / ONVIF / HTTP MJPEG) from
+     Settings → Cameras.  The live grid populates immediately.
+
+Open the dashboard:
+  {{ dashboard_url }}/dashboard
+
+Need a hand?  The full documentation lives at
+{{ dashboard_url }}/docs.  Start with "Getting Started" or jump
+straight to "CloudNode setup" if you've already got the install
+running.
+
+——
+You're receiving this because you just created an organization at
+SourceBox Sentry.  This is a one-time welcome — there's no
+recurring marketing email.
+Manage email alerts: {{ dashboard_url }}/settings#settings-notifications
+Unsubscribe from welcome emails (won't affect operational alerts):
+  {{ unsubscribe_url }}

backend/app/templates/emails/welcome.subject.txt.j2

@@ -0,0 +1 @@
+Welcome to SourceBox Sentry — let's get your first camera online