feat(admin): per-port email/Documenso/branding/reminder settings + invitations

Centralizes everything operators need to configure into the admin panel,
each setting per-port with env fallback.

New admin pages
- /admin              landing page linking to every admin section as a card
- /admin/email        FROM name+address, reply-to, signature/footer HTML,
                      optional SMTP host/port/user/pass override
- /admin/documenso    API URL+key override, EOI Documenso template ID,
                      default EOI pathway (documenso-template vs inapp),
                      "Test connection" button
- /admin/branding     logo URL, primary color, app name, email
                      header/footer HTML
- /admin/reminders    port-level defaults for new interests +
                      port-wide daily-digest delivery window
- /admin/invitations  send / list / resend / revoke CRM invitations

Per-user reminder digest
- /notifications/preferences gains a Reminder digest card:
  immediate / daily / weekly / off, with HH:MM, day-of-week,
  IANA timezone fields. Stored in user_profiles.preferences.reminders.

Plumbing
- port-config.ts typed accessors (getPortEmailConfig, getPortDocumensoConfig,
  getPortBrandingConfig, getPortReminderConfig) — settings → env fallback.
- sendEmail accepts optional portId; resolves From/SMTP from settings
  when supplied.
- documensoFetch + downloadSignedPdf accept optional portId; each public
  function takes it through. checkDocumensoHealth() backs the test button.
- crm-invite.service gains listCrmInvites / revokeCrmInvite / resendCrmInvite
  with audit-log entries (revoke_invite, resend_invite added to AuditAction).
- AdminLandingPage card grid + shared SettingsFormCard component to remove
  per-page form boilerplate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/(dashboard)/[portSlug]/admin/branding/page.tsx

@@ -0,0 +1,69 @@
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
+
+const FIELDS: SettingFieldDef[] = [
+  {
+    key: 'branding_app_name',
+    label: 'App name',
+    description: 'Shown in the email subject prefix and the in-app header.',
+    type: 'string',
+    placeholder: 'Port Nimara CRM',
+    defaultValue: '',
+  },
+  {
+    key: 'branding_logo_url',
+    label: 'Logo URL',
+    description:
+      'Public HTTPS URL of the logo used in email headers and the branded auth shell. Recommended size: 240×80 PNG with transparent background.',
+    type: 'string',
+    placeholder: 'https://example.com/logo.png',
+    defaultValue: '',
+  },
+  {
+    key: 'branding_primary_color',
+    label: 'Primary color',
+    description: 'Used for buttons and links in transactional email templates.',
+    type: 'color',
+    defaultValue: '#1e293b',
+  },
+  {
+    key: 'branding_email_header_html',
+    label: 'Email header HTML',
+    description: 'Optional HTML rendered above each email body. Leave blank to use the default.',
+    type: 'html',
+    defaultValue: '',
+  },
+  {
+    key: 'branding_email_footer_html',
+    label: 'Email footer HTML',
+    description: 'Optional HTML rendered at the very bottom of each email (above the signature).',
+    type: 'html',
+    defaultValue: '',
+  },
+];
+
+export default function BrandingSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Branding</h1>
+        <p className="text-sm text-muted-foreground">
+          Logo, primary color, app name, and email header/footer HTML used by the branded auth shell
+          and outgoing email templates.
+        </p>
+      </div>
+      <SettingsFormCard
+        title="Identity"
+        description="App name, logo, and primary color."
+        fields={FIELDS.slice(0, 3)}
+      />
+      <SettingsFormCard
+        title="Email branding"
+        description="HTML fragments rendered around every transactional email."
+        fields={FIELDS.slice(3)}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/documenso/page.tsx

@@ -0,0 +1,73 @@
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
+import { DocumensoTestButton } from '@/components/admin/documenso/documenso-test-button';
+
+const API_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'documenso_api_url_override',
+    label: 'API URL override',
+    description: 'Optional. Falls back to DOCUMENSO_API_URL env when blank.',
+    type: 'string',
+    placeholder: 'https://documenso.example.com',
+    defaultValue: '',
+  },
+  {
+    key: 'documenso_api_key_override',
+    label: 'API key override',
+    description: 'Optional. Falls back to DOCUMENSO_API_KEY env when blank. Stored in plain text.',
+    type: 'password',
+    defaultValue: '',
+  },
+];
+
+const EOI_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'documenso_eoi_template_id',
+    label: 'EOI Documenso template ID',
+    description: 'Numeric template ID used by the Documenso EOI pathway.',
+    type: 'string',
+    placeholder: '12345',
+    defaultValue: '',
+  },
+  {
+    key: 'eoi_default_pathway',
+    label: 'Default EOI pathway',
+    description:
+      'Which pathway is used when an EOI is generated without an explicit choice. Documenso = signed via Documenso, In-app = filled locally with pdf-lib.',
+    type: 'select',
+    options: [
+      { value: 'documenso-template', label: 'Documenso template' },
+      { value: 'inapp', label: 'In-app (pdf-lib)' },
+    ],
+    defaultValue: 'documenso-template',
+  },
+];
+
+export default function DocumensoSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Documenso & EOI</h1>
+        <p className="text-sm text-muted-foreground">
+          API credentials and default EOI generation pathway. Use the test-connection button to
+          verify a saved configuration before relying on it.
+        </p>
+      </div>
+
+      <SettingsFormCard
+        title="Documenso API"
+        description="Per-port API credentials. Leave blank to use the global env defaults."
+        fields={API_FIELDS}
+        extra={<DocumensoTestButton />}
+      />
+
+      <SettingsFormCard
+        title="EOI generation"
+        description="Default pathway and template used when an interest's EOI is generated."
+        fields={EOI_FIELDS}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/email/page.tsx

@@ -0,0 +1,101 @@
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
+
+const FIELDS: SettingFieldDef[] = [
+  {
+    key: 'email_from_name',
+    label: 'From name',
+    description: 'Display name shown in the From: header on outgoing email.',
+    type: 'string',
+    placeholder: 'Port Nimara',
+    defaultValue: '',
+  },
+  {
+    key: 'email_from_address',
+    label: 'From address',
+    description: 'Sender email address. Falls back to SMTP_FROM env when blank.',
+    type: 'string',
+    placeholder: 'noreply@example.com',
+    defaultValue: '',
+  },
+  {
+    key: 'email_reply_to',
+    label: 'Reply-to address',
+    description: 'Optional Reply-To: header for replies (e.g. sales@example.com).',
+    type: 'string',
+    placeholder: 'sales@example.com',
+    defaultValue: '',
+  },
+  {
+    key: 'email_signature_html',
+    label: 'Default signature (HTML)',
+    description: 'Appended to the bottom of system-generated emails.',
+    type: 'html',
+    placeholder: '<p>—<br>The Port Nimara team</p>',
+    defaultValue: '',
+  },
+  {
+    key: 'email_footer_html',
+    label: 'Email footer (HTML)',
+    description: 'Legal/contact footer rendered at the very bottom of all emails.',
+    type: 'html',
+    placeholder: '<p style="font-size:11px;color:#888;">© Port Nimara · ul. ...</p>',
+    defaultValue: '',
+  },
+  {
+    key: 'smtp_host_override',
+    label: 'SMTP host override',
+    description: 'Optional. Falls back to SMTP_HOST env when blank.',
+    type: 'string',
+    placeholder: 'mail.example.com',
+    defaultValue: '',
+  },
+  {
+    key: 'smtp_port_override',
+    label: 'SMTP port override',
+    description: 'Optional. Falls back to SMTP_PORT env when blank.',
+    type: 'number',
+    placeholder: '587',
+    defaultValue: null,
+  },
+  {
+    key: 'smtp_user_override',
+    label: 'SMTP username override',
+    description: 'Optional. Falls back to SMTP_USER env when blank.',
+    type: 'string',
+    defaultValue: '',
+  },
+  {
+    key: 'smtp_pass_override',
+    label: 'SMTP password override',
+    description: 'Optional. Stored in plain text — only set when overriding env credentials.',
+    type: 'password',
+    defaultValue: '',
+  },
+];
+
+export default function EmailSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Email Settings</h1>
+        <p className="text-sm text-muted-foreground">
+          Per-port outgoing email configuration. SMTP credentials and the From address default to
+          environment variables when these fields are blank.
+        </p>
+      </div>
+      <SettingsFormCard
+        title="From address & signature"
+        description="Identity headers and shared HTML used by system-generated emails."
+        fields={FIELDS.slice(0, 5)}
+      />
+      <SettingsFormCard
+        title="SMTP transport overrides"
+        description="Optional per-port SMTP credentials. Leave blank to use the global env defaults."
+        fields={FIELDS.slice(5)}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/invitations/page.tsx

@@ -0,0 +1,16 @@
+import { InvitationsManager } from '@/components/admin/invitations/invitations-manager';
+
+export default function InvitationsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Invitations</h1>
+        <p className="text-sm text-muted-foreground">
+          Send a single-use invitation to a new CRM user. The recipient sets their own password via
+          the link in the email.
+        </p>
+      </div>
+      <InvitationsManager />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/page.tsx

@@ -0,0 +1,196 @@
+import Link from 'next/link';
+import {
+  Bell,
+  Briefcase,
+  Database,
+  FileText,
+  HardDrive,
+  Key,
+  LayoutDashboard,
+  Mail,
+  Palette,
+  ScrollText,
+  Settings,
+  Shield,
+  Sliders,
+  Tag,
+  Upload,
+  Users,
+  Webhook,
+} from 'lucide-react';
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+
+interface AdminSection {
+  href: string;
+  label: string;
+  description: string;
+  icon: typeof Settings;
+}
+
+const SECTIONS: AdminSection[] = [
+  {
+    href: 'users',
+    label: 'Users',
+    description: 'CRM accounts, role assignments, and per-user residential access toggles.',
+    icon: Users,
+  },
+  {
+    href: 'invitations',
+    label: 'Invitations',
+    description: 'Send invitations, track pending invites, and resend or revoke them.',
+    icon: Mail,
+  },
+  {
+    href: 'roles',
+    label: 'Roles & Permissions',
+    description: 'Default permission sets and per-port role overrides.',
+    icon: Shield,
+  },
+  {
+    href: 'audit',
+    label: 'Audit Log',
+    description: 'Searchable log of every authenticated mutation in the system.',
+    icon: ScrollText,
+  },
+  {
+    href: 'email',
+    label: 'Email Settings',
+    description: 'From address, signatures, and per-port SMTP overrides.',
+    icon: Mail,
+  },
+  {
+    href: 'documenso',
+    label: 'Documenso & EOI',
+    description: 'API credentials, EOI template, and default in-app vs Documenso pathway.',
+    icon: FileText,
+  },
+  {
+    href: 'reminders',
+    label: 'Reminders',
+    description: 'Default reminder behaviour and the daily-digest delivery window.',
+    icon: Bell,
+  },
+  {
+    href: 'branding',
+    label: 'Branding',
+    description: 'App name, logo, primary color, and email header/footer HTML.',
+    icon: Palette,
+  },
+  {
+    href: 'settings',
+    label: 'System Settings',
+    description: 'Generic key/value configuration store for advanced flags.',
+    icon: Settings,
+  },
+  {
+    href: 'webhooks',
+    label: 'Webhooks',
+    description: 'Outgoing webhook subscriptions, secrets, and delivery log.',
+    icon: Webhook,
+  },
+  {
+    href: 'forms',
+    label: 'Forms',
+    description: 'Form templates used by client-facing inquiry and intake flows.',
+    icon: Sliders,
+  },
+  {
+    href: 'templates',
+    label: 'Document Templates',
+    description: 'PDF + email templates with merge-field placeholders.',
+    icon: FileText,
+  },
+  {
+    href: 'tags',
+    label: 'Tags',
+    description: 'Color-coded tags applied to clients, yachts, companies, and interests.',
+    icon: Tag,
+  },
+  {
+    href: 'custom-fields',
+    label: 'Custom Fields',
+    description: 'Tenant-defined fields for clients, yachts, and reservations.',
+    icon: Key,
+  },
+  {
+    href: 'reports',
+    label: 'Reports',
+    description: 'Saved analytics views and ad-hoc query results.',
+    icon: LayoutDashboard,
+  },
+  {
+    href: 'monitoring',
+    label: 'Queue Monitoring',
+    description: 'BullMQ queue health, throughput, and retry diagnostics.',
+    icon: Database,
+  },
+  {
+    href: 'import',
+    label: 'Bulk Import',
+    description: 'CSV-driven imports for clients, yachts, and reservations.',
+    icon: Upload,
+  },
+  {
+    href: 'backup',
+    label: 'Backup & Restore',
+    description: 'Database snapshots and on-demand exports.',
+    icon: HardDrive,
+  },
+  {
+    href: 'ports',
+    label: 'Ports',
+    description: 'Manage the marinas/ports this installation serves.',
+    icon: Briefcase,
+  },
+  {
+    href: 'onboarding',
+    label: 'Onboarding',
+    description: 'Initial-setup wizard for fresh ports.',
+    icon: LayoutDashboard,
+  },
+];
+
+export default async function AdminLandingPage({
+  params,
+}: {
+  params: Promise<{ portSlug: string }>;
+}) {
+  const { portSlug } = await params;
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Administration</h1>
+        <p className="text-sm text-muted-foreground">
+          Per-port configuration and system administration. Each card below opens a dedicated
+          settings page.
+        </p>
+      </div>
+      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+        {SECTIONS.map((s) => {
+          const Icon = s.icon;
+          return (
+            <Link
+              key={s.href}
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              href={`/${portSlug}/admin/${s.href}` as any}
+              className="block group"
+            >
+              <Card className="h-full transition-colors group-hover:border-primary/50 group-hover:bg-muted/30">
+                <CardHeader className="flex flex-row items-start gap-3 space-y-0 pb-2">
+                  <Icon className="h-5 w-5 mt-0.5 text-muted-foreground group-hover:text-primary" />
+                  <div className="flex-1">
+                    <CardTitle className="text-base">{s.label}</CardTitle>
+                  </div>
+                </CardHeader>
+                <CardContent>
+                  <CardDescription>{s.description}</CardDescription>
+                </CardContent>
+              </Card>
+            </Link>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/admin/reminders/page.tsx

@@ -0,0 +1,78 @@
+import {
+  SettingsFormCard,
+  type SettingFieldDef,
+} from '@/components/admin/shared/settings-form-card';
+
+const DEFAULT_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'reminder_default_enabled',
+    label: 'Enable reminders by default on new interests',
+    description:
+      'When on, newly-created interests inherit reminderEnabled=true. Users can still toggle it on a per-interest basis.',
+    type: 'boolean',
+    defaultValue: false,
+  },
+  {
+    key: 'reminder_default_days',
+    label: 'Default inactivity days',
+    description:
+      "Default value for an interest's reminderDays field. Reminders fire after this many days of no contact.",
+    type: 'number',
+    placeholder: '7',
+    defaultValue: 7,
+  },
+];
+
+const DIGEST_FIELDS: SettingFieldDef[] = [
+  {
+    key: 'reminder_digest_enabled',
+    label: 'Batch reminders into a daily digest',
+    description:
+      'Off (default): reminders fire as soon as the threshold is hit. On: pending reminders are accumulated and delivered once per day at the digest time.',
+    type: 'boolean',
+    defaultValue: false,
+  },
+  {
+    key: 'reminder_digest_time',
+    label: 'Digest delivery time',
+    description: '24-hour HH:MM in the digest timezone.',
+    type: 'string',
+    placeholder: '09:00',
+    defaultValue: '09:00',
+  },
+  {
+    key: 'reminder_digest_timezone',
+    label: 'Digest timezone',
+    description: 'IANA timezone name used to interpret the delivery time (e.g. Europe/Warsaw).',
+    type: 'string',
+    placeholder: 'Europe/Warsaw',
+    defaultValue: 'Europe/Warsaw',
+  },
+];
+
+export default function ReminderSettingsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h1 className="text-2xl font-semibold">Reminders</h1>
+        <p className="text-sm text-muted-foreground">
+          Default reminder behaviour for new interests and the optional daily-digest delivery
+          window. Individual users can still configure their own digest preferences in Notifications
+          → Preferences.
+        </p>
+      </div>
+
+      <SettingsFormCard
+        title="Defaults for new interests"
+        description="Applied when an interest is created without an explicit reminder configuration."
+        fields={DEFAULT_FIELDS}
+      />
+
+      <SettingsFormCard
+        title="Daily digest"
+        description="Optional batching window so reminder notifications go out once per day instead of as they fire."
+        fields={DIGEST_FIELDS}
+      />
+    </div>
+  );
+}

src/app/(dashboard)/[portSlug]/notifications/preferences/page.tsx

@@ -1,15 +1,17 @@
 import { NotificationPreferencesForm } from '@/components/notifications/notification-preferences-form';
+import { ReminderDigestForm } from '@/components/notifications/reminder-digest-form';
 
 export default function NotificationPreferencesPage() {
   return (
-    <div className="max-w-2xl mx-auto py-6">
-      <div className="mb-6">
+    <div className="max-w-2xl mx-auto py-6 space-y-6">
+      <div>
         <h1 className="text-2xl font-bold">Notification Preferences</h1>
         <p className="text-sm text-muted-foreground">
           Choose which notifications you receive and how.
         </p>
       </div>
       <NotificationPreferencesForm />
+      <ReminderDigestForm />
     </div>
   );
 }

src/app/api/v1/admin/documenso/health/route.ts

@@ -0,0 +1,20 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { checkDocumensoHealth } from '@/lib/services/documenso-client';
+
+/**
+ * Admin probe — calls Documenso /api/v1/health using the port's effective
+ * config. Used by the "Test connection" button on /admin/documenso.
+ */
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx) => {
+    try {
+      const result = await checkDocumensoHealth(ctx.portId);
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/invitations/[id]/resend/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { resendCrmInvite } from '@/lib/services/crm-invite.service';
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      const id = params.id ?? '';
+      const result = await resendCrmInvite(id, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/invitations/[id]/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { errorResponse } from '@/lib/errors';
+import { revokeCrmInvite } from '@/lib/services/crm-invite.service';
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      const id = params.id ?? '';
+      await revokeCrmInvite(id, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/invitations/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createCrmInvite, listCrmInvites } from '@/lib/services/crm-invite.service';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, _ctx) => {
+    try {
+      const data = await listCrmInvites();
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+const createInviteSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(200).optional(),
+  isSuperAdmin: z.boolean().optional().default(false),
+});
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_users', async (req, _ctx) => {
+    try {
+      const body = await parseBody(req, createInviteSchema);
+      const result = await createCrmInvite(body);
+      return NextResponse.json({ data: result }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/users/me/preferences/route.ts

@@ -0,0 +1,47 @@
+import { eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import { withAuth } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { userProfiles, type UserPreferences } from '@/lib/db/schema/users';
+import { errorResponse } from '@/lib/errors';
+import { updateUserPreferencesSchema } from '@/lib/validators/user-preferences';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    const profile = await db.query.userProfiles.findFirst({
+      where: eq(userProfiles.userId, ctx.userId),
+    });
+    return NextResponse.json({ data: profile?.preferences ?? {} });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+
+export const PATCH = withAuth(async (req, ctx) => {
+  try {
+    const patch = await parseBody(req, updateUserPreferencesSchema);
+
+    const profile = await db.query.userProfiles.findFirst({
+      where: eq(userProfiles.userId, ctx.userId),
+    });
+    if (!profile) {
+      return NextResponse.json({ error: 'Profile not found' }, { status: 404 });
+    }
+
+    const next: UserPreferences = {
+      ...(profile.preferences ?? {}),
+      ...patch,
+    };
+
+    await db
+      .update(userProfiles)
+      .set({ preferences: next })
+      .where(eq(userProfiles.userId, ctx.userId));
+
+    return NextResponse.json({ data: next });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});