audit: 33-agent comprehensive audit + critical fixes

Full team audit run, all reports verbatim in docs/AUDIT-2026-05-12.md
(5900+ lines, 30+ critical findings). Already-fixed this commit:
- permission-overrides PUT: self-target block + RolePermissions allow-list + cross-tenant guard
- /api/auth/resolve-identifier: rate-limit + synthetic miss-email kill enumeration
- admin email-change: rotates account.accountId + revokes sessions
- middleware: token-gated email confirm/cancel routes whitelisted
- NAV_CATALOG: 10 dead-link sweeps to existing /admin/<x> targets

Feature work landing same commit: optional username sign-in
(migration 0054), per-user permission overrides (0055) with three-state
matrix tabbed inside UserForm, user disable button, role + outcome +
stage label normalisation across the platform, admin email-change
with auto-notification template.

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

src/app/(auth)/login/page.tsx

@@ -14,8 +14,12 @@ import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { BrandedAuthShell } from '@/components/shared/branded-auth-shell';
 
+// `identifier` accepts either an email address or a username (3–30 lowercase
+// letters / digits / dot / underscore / hyphen). The page resolves usernames
+// to the canonical Better-Auth email via /api/auth/resolve-identifier before
+// the actual sign-in call.
 const loginSchema = z.object({
-  email: z.string().email('Please enter a valid email address'),
+  identifier: z.string().min(1, 'Email or username is required'),
   password: z.string().min(1, 'Password is required'),
 });
 
@@ -36,13 +40,29 @@ export default function LoginPage() {
   async function onSubmit(data: LoginFormData) {
     setIsLoading(true);
     try {
+      // Resolve username → email when the input isn't already an email.
+      // The endpoint always returns SOMETHING (the input itself on miss)
+      // so the auth call below fails uniformly with "invalid credentials"
+      // either way — no username enumeration.
+      const identifier = data.identifier.trim();
+      let email = identifier;
+      if (!identifier.includes('@')) {
+        const res = await fetch('/api/auth/resolve-identifier', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ identifier }),
+        });
+        const payload = (await res.json().catch(() => ({}))) as { email?: string };
+        email = payload.email?.trim() || identifier;
+      }
+
       const result = await authClient.signIn.email({
-        email: data.email,
+        email,
         password: data.password,
       });
 
       if (result.error) {
-        toast.error(result.error.message ?? 'Invalid email or password');
+        toast.error(result.error.message ?? 'Invalid credentials');
         return;
       }
 
@@ -63,17 +83,21 @@ export default function LoginPage() {
 
       <form onSubmit={handleSubmit(onSubmit)} className="space-y-4" noValidate>
         <div className="space-y-1.5">
-          <Label htmlFor="email">Email</Label>
+          <Label htmlFor="identifier">Email or username</Label>
           <Input
-            id="email"
-            type="email"
-            autoComplete="email"
-            placeholder="you@example.com"
+            id="identifier"
+            type="text"
+            autoComplete="username"
+            autoCapitalize="none"
+            spellCheck={false}
+            placeholder="you@example.com  or  yourname"
             disabled={isLoading}
-            className={cn(errors.email && 'border-destructive focus-visible:ring-destructive')}
-            {...register('email')}
+            className={cn(errors.identifier && 'border-destructive focus-visible:ring-destructive')}
+            {...register('identifier')}
           />
-          {errors.email && <p className="text-sm text-destructive">{errors.email.message}</p>}
+          {errors.identifier && (
+            <p className="text-sm text-destructive">{errors.identifier.message}</p>
+          )}
         </div>
 
         <div className="space-y-1.5">

src/app/api/auth/resolve-identifier/route.ts

@@ -0,0 +1,93 @@
+/**
+ * Resolves an email-or-username sign-in identifier to a canonical email
+ * that Better Auth's email/password flow accepts.
+ *
+ * Public endpoint by design — the login form calls it BEFORE the user is
+ * authenticated, so it can't sit behind `withAuth`.
+ *
+ * **Anti-enumeration:** the response shape is identical for hit and
+ * miss. On a miss we return a synthetic `@auth.invalid` email derived
+ * from the input so Better Auth's `signIn.email` call fails uniformly
+ * with "invalid credentials" — an attacker can't tell whether the
+ * username exists from this endpoint's response. (Previously a miss
+ * returned the bare input string, which lacked an `@` and was visibly
+ * different from a hit's real email.)
+ *
+ * **Rate limiting:** shares the `auth` bucket (5/15min/ip), so an
+ * attacker can't iterate a wordlist faster than they could brute-force
+ * passwords directly.
+ */
+import { NextResponse, type NextRequest } from 'next/server';
+import { sql } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { user, userProfiles } from '@/lib/db/schema/users';
+import { eq } from 'drizzle-orm';
+import { checkRateLimit, rateLimitHeaders, rateLimiters } from '@/lib/rate-limit';
+
+const EMAIL_HINT = /@/;
+
+/** Synthetic, definitively-invalid email used for the miss path. The
+ *  `.invalid` TLD is reserved by RFC 2606 — no real domain can use it,
+ *  so a downstream signIn call always fails as "invalid credentials"
+ *  without ever leaking the lookup outcome. */
+function syntheticEmail(raw: string): string {
+  const slug = raw.replace(/[^a-z0-9._-]/gi, '').slice(0, 30) || 'unknown';
+  return `${slug}@auth.invalid`;
+}
+
+function clientIp(req: NextRequest): string {
+  return (
+    req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??
+    req.headers.get('x-real-ip') ??
+    'unknown'
+  );
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    // Rate-limit on IP — same 5/15min bucket the actual sign-in uses.
+    // Without this an attacker can wordlist usernames at full HTTP
+    // bandwidth and only funnel the validated emails into the slower
+    // signIn flow.
+    const ip = clientIp(req);
+    const rl = await checkRateLimit(ip, rateLimiters.auth);
+    if (!rl.allowed) {
+      return NextResponse.json(
+        { email: '' },
+        { status: 429, headers: rateLimitHeaders(rl) },
+      );
+    }
+
+    const body = (await req.json().catch(() => ({}))) as { identifier?: string };
+    const raw = (body.identifier ?? '').trim();
+    if (!raw) return NextResponse.json({ email: syntheticEmail('empty') });
+
+    // Looks like an email → already canonical. Hand it straight back.
+    if (EMAIL_HINT.test(raw)) {
+      return NextResponse.json({ email: raw });
+    }
+
+    // Otherwise treat the input as a username and look up the linked
+    // Better Auth email. Case-insensitive match against the
+    // `LOWER(username)` unique index.
+    const normalized = raw.toLowerCase();
+    const rows = await db
+      .select({ email: user.email })
+      .from(userProfiles)
+      .innerJoin(user, eq(userProfiles.userId, user.id))
+      .where(sql`LOWER(${userProfiles.username}) = ${normalized}`)
+      .limit(1);
+
+    if (rows.length === 0) {
+      // Synthetic `.invalid` email — indistinguishable from a hit in
+      // shape (has `@`, has a tld), guaranteed to fail downstream auth.
+      return NextResponse.json({ email: syntheticEmail(normalized) });
+    }
+
+    return NextResponse.json({ email: rows[0]!.email });
+  } catch {
+    // Defensive — never expose internals from a public endpoint.
+    return NextResponse.json({ email: syntheticEmail('error') }, { status: 200 });
+  }
+}

src/app/api/v1/admin/users/[id]/permission-overrides/route.ts

@@ -0,0 +1,260 @@
+/**
+ * GET / PUT per-user permission overrides for the current port.
+ *
+ * GET returns the effective baseline (role + port-role-overrides + residential
+ * toggle) AND the current user-specific override map so the UI can render
+ * three states per leaf: inherit, force-grant, force-deny.
+ *
+ * PUT accepts a Partial<RolePermissions> map (use null at a leaf to clear an
+ * override) and upserts it onto user_permission_overrides for (userId, portId).
+ * Permission `admin.manage_users` is required — same gate as the user-edit
+ * drawer that hosts the matrix.
+ */
+import { and, eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import {
+  portRoleOverrides,
+  roles,
+  userPermissionOverrides,
+  userPortRoles,
+  userProfiles,
+  type RolePermissions,
+} from '@/lib/db/schema';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, ForbiddenError, NotFoundError, ValidationError } from '@/lib/errors';
+import { z } from 'zod';
+
+/**
+ * Mirrors `RolePermissions` in src/lib/db/schema/users.ts. Used as the
+ * allow-list for the PUT body so a client can't write arbitrary keys
+ * that the resolver would happily merge into the effective permission
+ * map. Keep this in sync when RolePermissions gains a leaf.
+ */
+const ALLOWED_RESOURCE_ACTIONS: Record<string, Set<string>> = {
+  clients: new Set(['view', 'create', 'edit', 'delete', 'merge', 'export']),
+  interests: new Set([
+    'view',
+    'create',
+    'edit',
+    'delete',
+    'change_stage',
+    'override_stage',
+    'generate_eoi',
+    'export',
+  ]),
+  berths: new Set(['view', 'edit', 'import', 'manage_waiting_list']),
+  documents: new Set([
+    'view',
+    'create',
+    'edit',
+    'send_for_signing',
+    'upload_signed',
+    'delete',
+    'manage_folders',
+  ]),
+  expenses: new Set(['view', 'create', 'edit', 'delete', 'export', 'scan_receipt']),
+  invoices: new Set(['view', 'create', 'edit', 'delete', 'send', 'record_payment', 'export']),
+  files: new Set(['view', 'upload', 'edit', 'delete', 'manage_folders']),
+  email: new Set(['view', 'send', 'configure_account']),
+  reminders: new Set(['view_own', 'view_all', 'create', 'edit_own', 'edit_all', 'assign_others']),
+  calendar: new Set(['connect', 'view_events']),
+  reports: new Set(['view_dashboard', 'view_analytics', 'export']),
+  document_templates: new Set(['view', 'generate', 'manage']),
+  yachts: new Set(['view', 'create', 'edit', 'delete', 'transfer']),
+  companies: new Set(['view', 'create', 'edit', 'delete']),
+  memberships: new Set(['view', 'manage']),
+  reservations: new Set(['view', 'create', 'activate', 'cancel']),
+  admin: new Set([
+    'manage_users',
+    'view_audit_log',
+    'manage_settings',
+    'manage_webhooks',
+    'manage_reports',
+    'manage_custom_fields',
+    'manage_forms',
+    'manage_tags',
+    'system_backup',
+    'permanently_delete_clients',
+  ]),
+  residential_clients: new Set(['view', 'create', 'edit', 'delete']),
+  residential_interests: new Set(['view', 'create', 'edit', 'delete', 'change_stage']),
+};
+
+const updateOverridesSchema = z.object({
+  /** Partial<RolePermissions> — passthrough JSON. Validated structurally
+   *  by limiting depth + leaf type below. */
+  overrides: z.record(z.string(), z.record(z.string(), z.boolean())).default({}),
+});
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_users', async (_req, ctx, params) => {
+    try {
+      const targetUserId = params.id!;
+      const portId = ctx.portId;
+
+      const profile = await db.query.userProfiles.findFirst({
+        where: eq(userProfiles.userId, targetUserId),
+      });
+      if (!profile) throw new NotFoundError('User');
+
+      // Resolve the role's baseline + port-role override (super-admin
+      // edge-case: no role row, so the matrix is empty / not editable).
+      let baseline: RolePermissions | null = null;
+      if (!profile.isSuperAdmin) {
+        const portRole = await db.query.userPortRoles.findFirst({
+          where: and(
+            eq(userPortRoles.userId, targetUserId),
+            eq(userPortRoles.portId, portId),
+          ),
+        });
+        if (portRole) {
+          const role = await db.query.roles.findFirst({
+            where: eq(roles.id, portRole.roleId),
+          });
+          baseline = (role?.permissions as RolePermissions | null) ?? null;
+
+          const portOverride = await db.query.portRoleOverrides.findFirst({
+            where: and(
+              eq(portRoleOverrides.portId, portId),
+              eq(portRoleOverrides.roleId, portRole.roleId),
+            ),
+          });
+          if (baseline && portOverride?.permissionOverrides) {
+            // Cheap structural merge — same shape as helpers.ts's deepMerge.
+            baseline = mergePerms(baseline, portOverride.permissionOverrides);
+          }
+        }
+      }
+
+      const userOverride = await db.query.userPermissionOverrides.findFirst({
+        where: and(
+          eq(userPermissionOverrides.userId, targetUserId),
+          eq(userPermissionOverrides.portId, portId),
+        ),
+      });
+
+      return NextResponse.json({
+        data: {
+          baseline,
+          overrides: userOverride?.permissionOverrides ?? {},
+          isSuperAdmin: profile.isSuperAdmin,
+        },
+      });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PUT = withAuth(
+  withPermission('admin', 'manage_users', async (req, ctx, params) => {
+    try {
+      const targetUserId = params.id!;
+      const portId = ctx.portId;
+
+      // CRITICAL: refuse self-target. Without this an admin with
+      // admin.manage_users can grant themselves every permission leaf
+      // (incl. permanently_delete_clients, system_backup, etc.) and the
+      // override layer in withAuth resolves it on the very next request.
+      if (targetUserId === ctx.userId) {
+        throw new ForbiddenError('You cannot edit your own permission overrides.');
+      }
+
+      // Reject overrides for users that aren't actually assigned to this
+      // port — prevents cross-tenant pollution where an admin in port A
+      // writes a row keyed on (userIdFromPortB, portA). The withAuth
+      // resolver scopes lookups to the caller's port so the row would
+      // never apply, but it still consumes a unique slot and confuses
+      // future audits.
+      const targetPortRole = await db.query.userPortRoles.findFirst({
+        where: and(
+          eq(userPortRoles.userId, targetUserId),
+          eq(userPortRoles.portId, portId),
+        ),
+      });
+      if (!targetPortRole) {
+        throw new NotFoundError('User not assigned to this port');
+      }
+
+      const { overrides } = await parseBody(req, updateOverridesSchema);
+
+      // Strip anything outside the canonical RolePermissions allow-list.
+      // The Zod schema only enforces shape (string → string → boolean);
+      // here we drop unknown resources/actions so a malicious client
+      // can't seed garbage keys that a future resolver might accidentally
+      // honour.
+      const sanitized: Record<string, Record<string, boolean>> = {};
+      for (const [resource, actions] of Object.entries(overrides)) {
+        const allowed = ALLOWED_RESOURCE_ACTIONS[resource];
+        if (!allowed) continue;
+        const cleaned: Record<string, boolean> = {};
+        for (const [action, value] of Object.entries(actions)) {
+          if (!allowed.has(action)) continue;
+          if (typeof value !== 'boolean') {
+            throw new ValidationError(
+              `permission override for ${resource}.${action} must be true or false`,
+            );
+          }
+          cleaned[action] = value;
+        }
+        if (Object.keys(cleaned).length > 0) sanitized[resource] = cleaned;
+      }
+
+      const existing = await db.query.userPermissionOverrides.findFirst({
+        where: and(
+          eq(userPermissionOverrides.userId, targetUserId),
+          eq(userPermissionOverrides.portId, portId),
+        ),
+      });
+
+      if (existing) {
+        await db
+          .update(userPermissionOverrides)
+          .set({ permissionOverrides: sanitized, updatedAt: new Date() })
+          .where(eq(userPermissionOverrides.id, existing.id));
+      } else {
+        await db.insert(userPermissionOverrides).values({
+          userId: targetUserId,
+          portId,
+          permissionOverrides: sanitized,
+        });
+      }
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId,
+        action: 'update',
+        entityType: 'user',
+        entityId: targetUserId,
+        oldValue: { permissionOverrides: existing?.permissionOverrides ?? {} },
+        newValue: { permissionOverrides: sanitized },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: { overrides: sanitized } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+/** Local shallow-merge by resource (matches the RolePermissions shape:
+ *  one-level-deep map of resource → action map). Same semantics the
+ *  withAuth resolver uses; copied here to avoid pulling that file into
+ *  a route module. */
+function mergePerms(
+  base: RolePermissions,
+  patch: Partial<RolePermissions> | Record<string, Record<string, boolean>>,
+): RolePermissions {
+  const out = { ...(base as unknown as Record<string, Record<string, boolean>>) };
+  for (const [resource, actions] of Object.entries(patch)) {
+    if (!actions) continue;
+    out[resource] = { ...(out[resource] ?? {}), ...(actions as Record<string, boolean>) };
+  }
+  return out as unknown as RolePermissions;
+}

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

@@ -5,13 +5,28 @@ import { withAuth, type AuthContext } from '@/lib/api/helpers';
 import { parseBody } from '@/lib/api/route-helpers';
 import { db } from '@/lib/db';
 import { userProfiles } from '@/lib/db/schema';
-import { errorResponse, NotFoundError, ValidationError } from '@/lib/errors';
+import { ConflictError, errorResponse, NotFoundError, ValidationError } from '@/lib/errors';
+import { isReservedUsername, USERNAME_REGEX } from '@/lib/validators/username';
+import { sql } from 'drizzle-orm';
 import { z } from 'zod';
 
 const updateProfileSchema = z.object({
   firstName: z.string().min(1).max(120).nullable().optional(),
   lastName: z.string().min(1).max(120).nullable().optional(),
   displayName: z.string().min(1).max(200).optional(),
+  /**
+   * Optional sign-in alias. `null` clears the existing value; a string
+   * must match the 2–30 lowercase shape pinned by USERNAME_REGEX (also
+   * enforced by `chk_user_profiles_username_shape` in migration 0054).
+   * Uniqueness is checked below before the UPDATE — collisions surface
+   * as a 409 with a friendly message.
+   */
+  username: z
+    .union([
+      z.string().transform((s) => s.trim().toLowerCase()),
+      z.null(),
+    ])
+    .optional(),
   phone: z.string().nullable().optional(),
   // Refuse `javascript:` / `data:` schemes — z.string().url() lets them
   // through and `<a href={avatarUrl}>` would otherwise be a stored-XSS
@@ -64,6 +79,7 @@ export const GET = withAuth(async (_req, ctx: AuthContext) => {
       firstName: true,
       lastName: true,
       displayName: true,
+      username: true,
     },
   });
 
@@ -82,6 +98,7 @@ export const GET = withAuth(async (_req, ctx: AuthContext) => {
         firstName: profile?.firstName ?? null,
         lastName: profile?.lastName ?? null,
         displayName: profile?.displayName ?? null,
+        username: profile?.username ?? null,
       },
     },
   });
@@ -102,6 +119,32 @@ export const PATCH = withAuth(async (req, ctx: AuthContext) => {
     if (body.displayName !== undefined) updates.displayName = body.displayName;
     if (body.phone !== undefined) updates.phone = body.phone;
     if (body.avatarUrl !== undefined) updates.avatarUrl = body.avatarUrl;
+    if (body.username !== undefined) {
+      // null clears; non-null must match the shape + not be reserved +
+      // be unique (case-insensitive) across all users in the install.
+      if (body.username === null || body.username === '') {
+        updates.username = null;
+      } else {
+        const candidate = body.username;
+        if (!USERNAME_REGEX.test(candidate)) {
+          throw new ValidationError(
+            'Username must be 2–30 lowercase letters, digits, dot, underscore, or hyphen.',
+          );
+        }
+        if (isReservedUsername(candidate)) {
+          throw new ValidationError('That username is reserved. Please pick another.');
+        }
+        const taken = await db
+          .select({ userId: userProfiles.userId })
+          .from(userProfiles)
+          .where(sql`LOWER(${userProfiles.username}) = ${candidate}`)
+          .limit(1);
+        if (taken.length > 0 && taken[0]!.userId !== ctx.userId) {
+          throw new ConflictError('That username is already taken.');
+        }
+        updates.username = candidate;
+      }
+    }
     if (body.preferences !== undefined) {
       // Allow-list — only retain keys defined in the strict schema. Pre-
       // strict rows may carry extra keys from when the schema was
@@ -136,6 +179,7 @@ export const PATCH = withAuth(async (req, ctx: AuthContext) => {
         firstName: updated!.firstName,
         lastName: updated!.lastName,
         displayName: updated!.displayName,
+        username: updated!.username,
         phone: updated!.phone,
         avatarUrl: updated!.avatarUrl,
         preferences: updated!.preferences,

src/components/admin/admin-sections-browser.tsx

@@ -70,7 +70,14 @@ const GROUPS: AdminGroup[] = [
         label: 'Users',
         description: 'CRM accounts, role assignments, and per-user residential access toggles.',
         icon: Users,
-        keywords: ['accounts', 'staff', 'team', 'disable user', 'reset password', 'residential access'],
+        keywords: [
+          'accounts',
+          'staff',
+          'team',
+          'disable user',
+          'reset password',
+          'residential access',
+        ],
       },
       {
         href: 'invitations',

src/components/admin/users/user-card.tsx

@@ -1,15 +1,6 @@
 'use client';
 
-import {
-  Clock,
-  Mail,
-  MoreHorizontal,
-  Pencil,
-  Power,
-  PowerOff,
-  Shield,
-  Trash2,
-} from 'lucide-react';
+import { Clock, Mail, MoreHorizontal, Pencil, Power, PowerOff, Shield, Trash2 } from 'lucide-react';
 import { formatDistanceToNow } from 'date-fns';
 
 import { formatRole } from '@/lib/constants';

src/components/admin/users/user-form.tsx

@@ -2,7 +2,6 @@
 import { formatErrorBanner } from '@/lib/api/toast-error';
 
 import { useState, useEffect } from 'react';
-import Link from 'next/link';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
@@ -15,6 +14,8 @@ import {
 } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetFooter } from '@/components/ui/sheet';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { UserPermissionMatrix } from './user-permission-matrix';
 import {
   AlertDialog,
   AlertDialogAction,
@@ -26,7 +27,6 @@ import {
   AlertDialogTitle,
 } from '@/components/ui/alert-dialog';
 import { PhoneInput, type PhoneInputValue } from '@/components/shared/phone-input';
-import { useUIStore } from '@/stores/ui-store';
 import { apiFetch } from '@/lib/api/client';
 import { formatRole } from '@/lib/constants';
 
@@ -69,7 +69,6 @@ export function UserForm({ open, onOpenChange, user, onSuccess }: UserFormProps)
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  const portSlug = useUIStore((s) => s.currentPortSlug);
   const isEdit = !!user;
   const fullName = `${firstName} ${lastName}`.trim();
 
@@ -192,7 +191,28 @@ export function UserForm({ open, onOpenChange, user, onSuccess }: UserFormProps)
           <SheetTitle>{isEdit ? 'Edit User' : 'New User'}</SheetTitle>
         </SheetHeader>
 
-        <form onSubmit={handleSubmit} className="mt-6 space-y-4">
+        <Tabs defaultValue="profile" className="mt-6">
+          <TabsList className="w-full">
+            <TabsTrigger value="profile" className="flex-1">
+              Profile &amp; role
+            </TabsTrigger>
+            <TabsTrigger value="permissions" className="flex-1" disabled={!isEdit}>
+              Permissions
+            </TabsTrigger>
+          </TabsList>
+
+          <TabsContent value="permissions" className="mt-4">
+            {isEdit ? (
+              <UserPermissionMatrix userId={user.userId} />
+            ) : (
+              <p className="text-sm text-muted-foreground">
+                Save the new user first, then return here to fine-tune their permissions.
+              </p>
+            )}
+          </TabsContent>
+
+          <TabsContent value="profile" className="mt-4">
+        <form onSubmit={handleSubmit} className="space-y-4">
           <div className="grid grid-cols-2 gap-3">
             <div className="space-y-2">
               <Label htmlFor="user-first-name">First name</Label>
@@ -320,23 +340,6 @@ export function UserForm({ open, onOpenChange, user, onSuccess }: UserFormProps)
             </div>
           )}
 
-          {isEdit && portSlug && (
-            <div className="rounded-lg border bg-muted/30 p-3">
-              <p className="text-sm font-medium">Fine-tuned permissions</p>
-              <p className="text-xs text-muted-foreground">
-                The selected role grants a baseline. To add or remove a specific permission for
-                this user only, open the role &amp; permissions page.
-              </p>
-              <Link
-                /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-                href={`/${portSlug}/admin/roles?focusUser=${user.userId}` as any}
-                className="mt-2 inline-block text-xs font-medium text-primary hover:underline"
-              >
-                Manage permissions →
-              </Link>
-            </div>
-          )}
-
           {error && <p className="whitespace-pre-line text-sm text-destructive">{error}</p>}
 
           <SheetFooter>
@@ -353,6 +356,8 @@ export function UserForm({ open, onOpenChange, user, onSuccess }: UserFormProps)
             </Button>
           </SheetFooter>
         </form>
+          </TabsContent>
+        </Tabs>
 
         <AlertDialog open={emailConfirmOpen} onOpenChange={setEmailConfirmOpen}>
           <AlertDialogContent>

src/components/admin/users/user-list.tsx

@@ -157,9 +157,7 @@ export function UserList() {
                   ) : (
                     <Power className="h-4 w-4" />
                   )}
-                  <span className="sr-only">
-                    {row.original.isActive ? 'Disable' : 'Enable'}
-                  </span>
+                  <span className="sr-only">{row.original.isActive ? 'Disable' : 'Enable'}</span>
                 </Button>
               }
               title={row.original.isActive ? 'Disable user' : 'Enable user'}

src/components/admin/users/user-permission-matrix.tsx

@@ -0,0 +1,301 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@/components/ui/accordion';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';
+
+/**
+ * Three-state per-user permission editor.
+ *
+ * For every leaf in RolePermissions we render an Inherit / Grant / Deny
+ * toggle. "Inherit" leaves the leaf out of the user_permission_overrides
+ * map so the role + port-role-override baseline wins. "Grant" / "Deny"
+ * write `true` / `false` and override the baseline.
+ *
+ * Baseline comes from the GET endpoint which already merges role + port-
+ * role override + residential toggle, so the inherit-state label matches
+ * what `withAuth` would resolve to today.
+ */
+
+const GROUP_LABELS: Record<string, string> = {
+  clients: 'Clients',
+  interests: 'Interests / Pipeline',
+  berths: 'Berths',
+  documents: 'Documents',
+  expenses: 'Expenses',
+  invoices: 'Invoices',
+  files: 'Files',
+  email: 'Email',
+  reminders: 'Reminders',
+  calendar: 'Calendar',
+  reports: 'Reports',
+  document_templates: 'Document Templates',
+  yachts: 'Yachts',
+  companies: 'Companies',
+  memberships: 'Company Memberships',
+  reservations: 'Reservations',
+  admin: 'Administration',
+  residential_clients: 'Residential Clients',
+  residential_interests: 'Residential Interests',
+};
+
+// Mirrors RolePermissions in src/lib/db/schema/users.ts — used as the
+// canonical leaf list so the matrix shows every action even when the
+// baseline JSON omits a key (older roles, partial overrides).
+const PERMISSION_LEAVES: Record<string, string[]> = {
+  clients: ['view', 'create', 'edit', 'delete', 'merge', 'export'],
+  interests: [
+    'view',
+    'create',
+    'edit',
+    'delete',
+    'change_stage',
+    'override_stage',
+    'generate_eoi',
+    'export',
+  ],
+  berths: ['view', 'edit', 'import', 'manage_waiting_list'],
+  documents: [
+    'view',
+    'create',
+    'edit',
+    'send_for_signing',
+    'upload_signed',
+    'delete',
+    'manage_folders',
+  ],
+  expenses: ['view', 'create', 'edit', 'delete', 'export', 'scan_receipt'],
+  invoices: ['view', 'create', 'edit', 'delete', 'send', 'record_payment', 'export'],
+  files: ['view', 'upload', 'edit', 'delete', 'manage_folders'],
+  email: ['view', 'send', 'configure_account'],
+  reminders: ['view_own', 'view_all', 'create', 'edit_own', 'edit_all', 'assign_others'],
+  calendar: ['connect', 'view_events'],
+  reports: ['view_dashboard', 'view_analytics', 'export'],
+  document_templates: ['view', 'generate', 'manage'],
+  yachts: ['view', 'create', 'edit', 'delete', 'transfer'],
+  companies: ['view', 'create', 'edit', 'delete'],
+  memberships: ['view', 'manage'],
+  reservations: ['view', 'create', 'activate', 'cancel'],
+  admin: [
+    'manage_users',
+    'view_audit_log',
+    'manage_settings',
+    'manage_webhooks',
+    'manage_reports',
+    'manage_custom_fields',
+    'manage_forms',
+    'manage_tags',
+    'system_backup',
+    'permanently_delete_clients',
+  ],
+  residential_clients: ['view', 'create', 'edit', 'delete'],
+  residential_interests: ['view', 'create', 'edit', 'delete', 'change_stage'],
+};
+
+function formatAction(action: string): string {
+  return action.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+type Overrides = Record<string, Record<string, boolean>>;
+type Baseline = Record<string, Record<string, boolean>> | null;
+
+interface PermissionMatrixResponse {
+  data: {
+    baseline: Baseline;
+    overrides: Overrides;
+    isSuperAdmin: boolean;
+  };
+}
+
+interface UserPermissionMatrixProps {
+  userId: string;
+}
+
+export function UserPermissionMatrix({ userId }: UserPermissionMatrixProps) {
+  const [baseline, setBaseline] = useState<Baseline>(null);
+  const [overrides, setOverrides] = useState<Overrides>({});
+  // Tracked so future revisions can surface a dirty-state indicator; the
+  // ui-ux audit recommended one. Setter is wired now to capture the
+  // server-canonical baseline post-save.
+  const [, setOriginalOverrides] = useState<Overrides>({});
+  const [isSuperAdmin, setIsSuperAdmin] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [message, setMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      setLoading(true);
+      try {
+        const res = await apiFetch<PermissionMatrixResponse>(
+          `/api/v1/admin/users/${userId}/permission-overrides`,
+        );
+        if (cancelled) return;
+        setBaseline(res.data.baseline);
+        const fetched = res.data.overrides ?? {};
+        setOverrides(fetched);
+        setOriginalOverrides(fetched);
+        setIsSuperAdmin(res.data.isSuperAdmin);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [userId]);
+
+  function getState(resource: string, action: string): 'inherit' | 'grant' | 'deny' {
+    const v = overrides[resource]?.[action];
+    if (v === true) return 'grant';
+    if (v === false) return 'deny';
+    return 'inherit';
+  }
+
+  function setState(resource: string, action: string, next: 'inherit' | 'grant' | 'deny') {
+    setOverrides((prev) => {
+      const copy: Overrides = { ...prev, [resource]: { ...(prev[resource] ?? {}) } };
+      if (next === 'inherit') {
+        delete copy[resource]![action];
+        if (Object.keys(copy[resource]!).length === 0) delete copy[resource];
+      } else {
+        copy[resource]![action] = next === 'grant';
+      }
+      return copy;
+    });
+  }
+
+  function baselineFor(resource: string, action: string): boolean {
+    return baseline?.[resource]?.[action] === true;
+  }
+
+  async function save() {
+    setSaving(true);
+    setMessage(null);
+    try {
+      await apiFetch(`/api/v1/admin/users/${userId}/permission-overrides`, {
+        method: 'PUT',
+        body: { overrides },
+      });
+      setOriginalOverrides(overrides);
+      setMessage('Overrides saved.');
+    } catch (err: unknown) {
+      setMessage(err instanceof Error ? err.message : 'Failed to save overrides');
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  if (loading) {
+    return (
+      <div className="py-6 text-center text-sm text-muted-foreground">Loading permissions…</div>
+    );
+  }
+
+  if (isSuperAdmin) {
+    return (
+      <div className="rounded-md border bg-muted/30 p-4 text-sm text-muted-foreground">
+        Super-admin users bypass per-port permission checks. Overrides don&apos;t apply here —
+        revoke the super-admin flag on the Profile tab first.
+      </div>
+    );
+  }
+
+  if (!baseline) {
+    return (
+      <div className="rounded-md border bg-amber-50 p-4 text-sm text-amber-900">
+        This user isn&apos;t assigned to this port, so the role baseline isn&apos;t resolvable.
+        Assign them a role on the Profile tab before editing per-user permissions.
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-xs text-amber-900">
+        <p>
+          Permission overrides save <strong>on the button below</strong>, separately from the
+          Profile &amp; role tab. Switching tabs or closing the drawer without clicking
+          <strong> Save overrides</strong> drops your changes.
+        </p>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Each toggle defaults to <strong>Inherit</strong> (role + port override decide). Switch to
+        <strong> Grant</strong> or <strong>Deny</strong> to force the value for this user only.
+      </p>
+
+      <ScrollArea className="h-[420px] rounded-md border">
+        <Accordion type="multiple" className="px-3">
+          {Object.entries(PERMISSION_LEAVES).map(([resource, leaves]) => (
+            <AccordionItem key={resource} value={resource}>
+              <AccordionTrigger className="text-sm">
+                {GROUP_LABELS[resource] ?? resource}
+              </AccordionTrigger>
+              <AccordionContent>
+                <div className="space-y-2 pl-2 pb-2">
+                  {leaves.map((action) => {
+                    const state = getState(resource, action);
+                    const inherited = baselineFor(resource, action);
+                    return (
+                      <div
+                        key={action}
+                        className="flex flex-wrap items-center justify-between gap-2 rounded-md border bg-background px-2 py-1.5"
+                      >
+                        <div className="text-sm">
+                          <Label className="text-sm">{formatAction(action)}</Label>
+                          <p className="text-[11px] text-muted-foreground">
+                            Inherits: {inherited ? 'granted' : 'denied'}
+                          </p>
+                        </div>
+                        <div
+                          className="inline-flex rounded-md border bg-muted/30 p-0.5"
+                          role="radiogroup"
+                          aria-label={`${formatAction(action)} permission override`}
+                        >
+                          {(['inherit', 'grant', 'deny'] as const).map((opt) => (
+                            <button
+                              key={opt}
+                              type="button"
+                              role="radio"
+                              aria-checked={state === opt}
+                              onClick={() => setState(resource, action, opt)}
+                              className={cn(
+                                'rounded px-2 py-0.5 text-xs font-medium transition-colors',
+                                state === opt
+                                  ? opt === 'grant'
+                                    ? 'bg-emerald-600 text-white'
+                                    : opt === 'deny'
+                                      ? 'bg-rose-600 text-white'
+                                      : 'bg-foreground text-background'
+                                  : 'text-muted-foreground hover:text-foreground',
+                              )}
+                            >
+                              {opt[0]!.toUpperCase() + opt.slice(1)}
+                            </button>
+                          ))}
+                        </div>
+                      </div>
+                    );
+                  })}
+                </div>
+              </AccordionContent>
+            </AccordionItem>
+          ))}
+        </Accordion>
+      </ScrollArea>
+
+      <div className="flex items-center gap-3">
+        <Button size="sm" onClick={save} disabled={saving}>
+          {saving ? 'Saving…' : 'Save overrides'}
+        </Button>
+        {message && <span className="text-xs text-muted-foreground">{message}</span>}
+      </div>
+    </div>
+  );
+}

src/components/clients/client-columns.tsx

@@ -15,7 +15,7 @@ import {
 import { Badge } from '@/components/ui/badge';
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { getCountryName } from '@/lib/i18n/countries';
-import { stageDotClass, stageLabel, formatSource } from '@/lib/constants';
+import { stageDotClass, stageLabel, formatSource, formatOutcome } from '@/lib/constants';
 import { cn } from '@/lib/utils';
 import type { ColumnPickerOption } from '@/components/shared/column-picker';
 
@@ -249,7 +249,7 @@ export function getClientColumns({
                         <span className="font-medium text-foreground">{b.mooringNumber}</span>
                         <span className="text-xs text-muted-foreground">
                           {b.outcome
-                            ? `${stageLabel(b.stage)} · ${b.outcome.replace(/_/g, ' ')}`
+                            ? `${stageLabel(b.stage)} · ${formatOutcome(b.outcome) ?? b.outcome}`
                             : stageLabel(b.stage)}
                         </span>
                       </Link>
@@ -342,7 +342,7 @@ function BerthInterestChip({
 }) {
   const isClosed = berth.outcome !== null;
   const label = isClosed
-    ? `${stageLabel(berth.stage)} · ${berth.outcome!.replace(/_/g, ' ')}`
+    ? `${stageLabel(berth.stage)} · ${formatOutcome(berth.outcome) ?? berth.outcome}`
     : stageLabel(berth.stage);
   return (
     <Link

src/components/interests/interest-detail-header.tsx

@@ -26,6 +26,7 @@ import { InterestForm } from '@/components/interests/interest-form';
 import { InlineStagePicker } from '@/components/interests/inline-stage-picker';
 import { InterestOutcomeDialog } from '@/components/interests/interest-outcome-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { formatOutcome } from '@/lib/constants';
 import { cn } from '@/lib/utils';
 
 const OUTCOME_BADGE: Record<string, { label: string; className: string }> = {
@@ -46,7 +47,7 @@ function resolveOutcomeBadge(outcome: string | null | undefined) {
   if (known) return known;
   const isLoss = outcome.startsWith('lost');
   return {
-    label: outcome.replace(/_/g, ' ').replace(/\b\w/g, (m) => m.toUpperCase()),
+    label: formatOutcome(outcome) ?? outcome,
     className: isLoss ? 'bg-rose-100 text-rose-700' : 'bg-slate-200 text-slate-700',
   };
 }

src/components/search/command-search.tsx

@@ -39,6 +39,7 @@ import {
 import { apiFetch } from '@/lib/api/client';
 import { cn } from '@/lib/utils';
 import { formatCurrency } from '@/lib/utils/currency';
+import { STAGE_LABELS, formatOutcome, type PipelineStage } from '@/lib/constants';
 import {
   useSearch,
   type BucketType,
@@ -929,11 +930,15 @@ export function buildFlatRows(args: BuildFlatRowsArgs): FlatRow[] {
       const badges: ResultBadge[] = [];
       if (i.outcome) {
         badges.push({
-          label: i.outcome.replace(/_/g, ' '),
+          label: formatOutcome(i.outcome) ?? i.outcome,
           tone: i.outcome === 'won' ? 'success' : 'neutral',
         });
       } else {
-        badges.push({ label: i.pipelineStage.replace(/_/g, ' '), tone: 'warning' });
+        badges.push({
+          label:
+            STAGE_LABELS[i.pipelineStage as PipelineStage] ?? i.pipelineStage.replace(/_/g, ' '),
+          tone: 'warning',
+        });
       }
       rows.push({
         kind: 'result',
@@ -956,7 +961,8 @@ export function buildFlatRows(args: BuildFlatRowsArgs): FlatRow[] {
         bucket: 'residentialInterests',
         icon: TrendingUp,
         label: i.clientName,
-        sub: i.pipelineStage.replace(/_/g, ' '),
+        sub:
+          STAGE_LABELS[i.pipelineStage as PipelineStage] ?? i.pipelineStage.replace(/_/g, ' '),
         href: `/${portSlug}/residential/interests/${i.id}`,
       });
     }

src/components/settings/user-settings.tsx

@@ -28,6 +28,7 @@ interface MeResponse {
     firstName?: string | null;
     lastName?: string | null;
     displayName?: string | null;
+    username?: string | null;
   };
 }
 
@@ -35,6 +36,9 @@ export function UserSettings() {
   const [firstName, setFirstName] = useState('');
   const [lastName, setLastName] = useState('');
   const [displayName, setDisplayName] = useState('');
+  const [username, setUsername] = useState('');
+  const [originalUsername, setOriginalUsername] = useState('');
+  const [usernameMsg, setUsernameMsg] = useState<string | null>(null);
   const [phone, setPhone] = useState('');
   const [email, setEmail] = useState('');
   const [originalEmail, setOriginalEmail] = useState('');
@@ -75,6 +79,8 @@ export function UserSettings() {
     setDisplayName(res.data.profile?.displayName ?? res.data.user?.name ?? '');
     setEmail(res.data.user?.email ?? '');
     setOriginalEmail(res.data.user?.email ?? '');
+    setUsername(res.data.profile?.username ?? '');
+    setOriginalUsername(res.data.profile?.username ?? '');
     setCountry(res.data.preferences?.country ?? null);
     // Fall back to the browser-detected zone when no value has been saved
     // yet — first-time users land on a sensible default rather than an
@@ -149,6 +155,25 @@ export function UserSettings() {
     }
   }
 
+  async function saveUsername() {
+    if (username.trim().toLowerCase() === originalUsername.toLowerCase()) return;
+    setSaving('username');
+    setUsernameMsg(null);
+    try {
+      const next = username.trim().toLowerCase() || null;
+      await apiFetch('/api/v1/me', { method: 'PATCH', body: { username: next } });
+      setOriginalUsername(next ?? '');
+      setUsername(next ?? '');
+      setUsernameMsg(
+        next ? `Username updated. You can now sign in with @${next} or your email.` : 'Username cleared.',
+      );
+    } catch (err: unknown) {
+      setUsernameMsg(err instanceof Error ? err.message : 'Failed to save username');
+    } finally {
+      setSaving(null);
+    }
+  }
+
   async function saveEmail() {
     if (email === originalEmail) return;
     setSaving('email');
@@ -328,6 +353,38 @@ export function UserSettings() {
           </CardHeader>
           <CardContent className="space-y-4">
             <div className="space-y-2">
+              <Label htmlFor="settings-username">
+                Username <span className="text-muted-foreground">(optional)</span>
+              </Label>
+              <Input
+                id="settings-username"
+                value={username}
+                onChange={(e) => setUsername(e.target.value.toLowerCase())}
+                placeholder="yourname"
+                autoCapitalize="none"
+                spellCheck={false}
+                pattern="^[a-z0-9._-]{2,30}$"
+              />
+              <div className="flex items-center gap-3">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={saveUsername}
+                  disabled={
+                    saving === 'username' ||
+                    username.trim().toLowerCase() === originalUsername.toLowerCase()
+                  }
+                >
+                  {saving === 'username' ? 'Saving…' : 'Save username'}
+                </Button>
+                {usernameMsg && <span className="text-xs text-muted-foreground">{usernameMsg}</span>}
+              </div>
+              <p className="text-xs text-muted-foreground">
+                Optional alias you can use to sign in instead of your email. 2–30 lowercase
+                letters, digits, dot, underscore, or hyphen.
+              </p>
+            </div>
+            <div className="space-y-2 pt-2 border-t">
               <Label htmlFor="settings-email">Email</Label>
               <Input
                 id="settings-email"

src/components/shared/interest-picker.tsx

@@ -16,6 +16,7 @@ import {
 import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
 import { useDebounce } from '@/hooks/use-debounce';
 import { apiFetch } from '@/lib/api/client';
+import { stageLabel } from '@/lib/constants';
 import { cn } from '@/lib/utils';
 
 interface InterestOption {
@@ -71,7 +72,7 @@ export function InterestPicker({
   const labelFor = (o: InterestOption) => {
     const parts = [o.clientName ?? 'Unknown client'];
     if (o.berthMooringNumber) parts.push(`Berth ${o.berthMooringNumber}`);
-    parts.push(o.pipelineStage.replace(/_/g, ' '));
+    parts.push(stageLabel(o.pipelineStage));
     return parts.join(' · ');
   };
 

src/components/shared/realtime-toasts.tsx

@@ -4,7 +4,7 @@ import { useEffect } from 'react';
 import { toast } from 'sonner';
 
 import { useSocket } from '@/providers/socket-provider';
-import { stageLabel } from '@/lib/constants';
+import { stageLabel, formatOutcome } from '@/lib/constants';
 
 /**
  * App-wide subscriber that surfaces high-signal sales events as sonner
@@ -62,9 +62,9 @@ export function RealtimeToasts() {
     function onOutcomeSet(payload: { outcome?: string }) {
       if (!payload?.outcome) return;
       const isWon = payload.outcome === 'won';
-      const label = payload.outcome.replace(/_/g, ' ');
+      const label = formatOutcome(payload.outcome) ?? payload.outcome;
       const fn = isWon ? toast.success : toast.message;
-      fn(`Interest closed - ${label}`);
+      fn(`Interest closed — ${label}`);
     }
 
     socket.on('interest:stageChanged', onStageChanged);

src/components/yachts/yacht-tabs.tsx

@@ -11,6 +11,7 @@ import { EntityActivityFeed } from '@/components/shared/entity-activity-feed';
 import { ReservationList, type ReservationRow } from '@/components/reservations/reservation-list';
 import { YachtOwnershipHistory } from '@/components/yachts/yacht-ownership-history';
 import { apiFetch } from '@/lib/api/client';
+import { stageLabel } from '@/lib/constants';
 
 type YachtPatchField =
   | 'name'
@@ -283,7 +284,7 @@ function YachtInterestsTab({ yachtId }: { yachtId: string }) {
           className="flex items-center gap-3 rounded-md border bg-muted/30 p-3 text-sm"
         >
           <span className="w-36 shrink-0 text-xs font-medium uppercase text-muted-foreground">
-            {i.pipelineStage.replace(/_/g, ' ')}
+            {stageLabel(i.pipelineStage)}
           </span>
           <span className="flex-1 truncate">{i.clientName ?? '-'}</span>
           {i.berthMooringNumber && (

src/lib/api/helpers.ts

@@ -5,7 +5,13 @@ import { NextRequest, NextResponse } from 'next/server';
 
 import { auth } from '@/lib/auth';
 import { db } from '@/lib/db';
-import { portRoleOverrides, ports, userPortRoles, userProfiles } from '@/lib/db/schema';
+import {
+  portRoleOverrides,
+  ports,
+  userPermissionOverrides,
+  userPortRoles,
+  userProfiles,
+} from '@/lib/db/schema';
 import { type RolePermissions } from '@/lib/db/schema/users';
 import { createAuditLog } from '@/lib/audit';
 import { errorResponse, ForbiddenError } from '@/lib/errors';
@@ -213,6 +219,23 @@ export function withAuth<TParams extends RouteParams = Record<string, string>>(
                 },
               };
             }
+
+            // Per-user permission overrides. Final layer in the chain so
+            // they win over role + port-role-override. Most users will
+            // never have a row here; admins flip individual leaves from
+            // the user-edit drawer's Permissions tab.
+            const userOverride = await db.query.userPermissionOverrides.findFirst({
+              where: and(
+                eq(userPermissionOverrides.userId, profile.userId),
+                eq(userPermissionOverrides.portId, portId),
+              ),
+            });
+            if (userOverride?.permissionOverrides && permissions) {
+              permissions = deepMerge(
+                permissions as unknown as Record<string, unknown>,
+                userOverride.permissionOverrides as Record<string, unknown>,
+              ) as RolePermissions;
+            }
           } else if (profile.isSuperAdmin && portId) {
             const port = await db.query.ports.findFirst({
               where: eq(ports.id, portId),

src/lib/constants.ts

@@ -268,6 +268,33 @@ export function formatRole(role: string | null | undefined): string {
     .join(' ');
 }
 
+// ─── Interest outcomes ───────────────────────────────────────────────────────
+// Mirrors INTEREST_OUTCOMES in src/lib/validators/interests.ts. Lives here
+// so render sites can format outcome strings without pulling in the
+// validator (which would drag zod into RSC bundles). Validator → enforces
+// the set; here → labels for humans.
+
+export const OUTCOME_LABELS: Record<string, string> = {
+  won: 'Won',
+  lost_other_marina: 'Lost — chose another marina',
+  lost_unqualified: 'Lost — not qualified',
+  lost_no_response: 'Lost — no response',
+  lost_other: 'Lost — other',
+  cancelled: 'Cancelled',
+};
+
+/** Returns the human label for a stored outcome value. Falls back to a
+ *  pretty Title-Case rendering for any new values added at the validator
+ *  before this map catches up. */
+export function formatOutcome(outcome: string | null | undefined): string | null {
+  if (!outcome) return null;
+  if (outcome in OUTCOME_LABELS) return OUTCOME_LABELS[outcome]!;
+  return outcome
+    .split('_')
+    .map((part) => (part ? part[0]!.toUpperCase() + part.slice(1) : part))
+    .join(' ');
+}
+
 // ─── Document Types ──────────────────────────────────────────────────────────
 
 export const DOCUMENT_TYPES = ['eoi', 'contract', 'nda', 'reservation_agreement', 'other'] as const;

src/lib/db/migrations/0054_user_profiles_username.sql

@@ -0,0 +1,31 @@
+-- 0054_user_profiles_username.sql
+-- ----------------------------------------------------------------------------
+-- Optional username as a sign-in alternative to email. Stored alongside the
+-- canonical first/last name on user_profiles so the rest of the auth/profile
+-- code keeps a single place to look. The Better-Auth `user` table stays the
+-- source of truth for email + password; the username is a thin alias the
+-- login form looks up to resolve to the matching email before delegating
+-- to better-auth's email/password flow.
+--
+-- Constraints (enforced application-side AND in SQL):
+--   - 2..30 characters
+--   - lowercase letters, digits, dot, underscore, hyphen
+--   - case-insensitive uniqueness per install (no per-port scoping —
+--     reps move between ports and a global username keeps URLs stable)
+--
+-- The column is nullable; existing users keep email-only sign-in until they
+-- pick one.
+
+ALTER TABLE user_profiles
+  ADD COLUMN IF NOT EXISTS username TEXT;
+
+-- Shape check at the DB level catches anything that slipped past the API
+-- (raw SQL inserts in tests, scripts, etc.).
+ALTER TABLE user_profiles
+  ADD CONSTRAINT chk_user_profiles_username_shape
+    CHECK (username IS NULL OR username ~ '^[a-z0-9._-]{2,30}$');
+
+-- Case-insensitive uniqueness. Partial so multiple NULLs are allowed.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_profiles_username_unique
+  ON user_profiles (LOWER(username))
+  WHERE username IS NOT NULL;

src/lib/db/migrations/0055_user_permission_overrides.sql

@@ -0,0 +1,26 @@
+-- 0055_user_permission_overrides.sql
+-- ----------------------------------------------------------------------------
+-- Per-user permission overrides layered on top of the role's baseline.
+-- Effective permission = role[resource][action]
+--                        |> apply port_role_overrides for that port
+--                        |> apply user_permission_overrides for (user, port)
+--
+-- A user override entry is OPTIONAL — most users will never have one.
+-- When present, the JSONB blob is a Partial<RolePermissions> map where any
+-- explicitly-set leaf wins over the inherited value (true forces grant,
+-- false forces deny, missing → inherit).
+
+CREATE TABLE IF NOT EXISTS user_permission_overrides (
+  id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  user_id TEXT NOT NULL,
+  port_id TEXT NOT NULL REFERENCES ports(id) ON DELETE CASCADE,
+  permission_overrides JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_user_perm_overrides_user_port
+  ON user_permission_overrides (user_id, port_id);
+
+CREATE INDEX IF NOT EXISTS idx_user_perm_overrides_user
+  ON user_permission_overrides (user_id);

src/lib/db/schema/users.ts

@@ -244,6 +244,14 @@ export const userProfiles = pgTable(
     firstName: text('first_name'),
     lastName: text('last_name'),
     displayName: text('display_name').notNull(),
+    /**
+     * Optional sign-in alias. Lowercase a-z0-9 plus dot/underscore/hyphen,
+     * 3–30 chars (shape pinned by `chk_user_profiles_username_shape`).
+     * Case-insensitive uniqueness is enforced by a partial unique index on
+     * LOWER(username); NULL allows the column to coexist with users who
+     * still sign in by email. See migration 0054.
+     */
+    username: text('username'),
     avatarUrl: text('avatar_url'),
     /** FK into the polymorphic `files` table — the avatar is stored
      *  via getStorageBackend() so an S3↔filesystem swap carries it
@@ -278,6 +286,42 @@ export const roles = pgTable('roles', {
   updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 });
 
+/**
+ * Per-user permission overrides layered on top of the role's baseline for
+ * a specific port. Each row carries a `Partial<RolePermissions>` map; any
+ * explicitly-set leaf wins over the role + port-role-override chain. Most
+ * users will never have a row here — it exists for the rare "give Alice
+ * the same role as her team but let her run permanent deletes" case.
+ *
+ * Effective permission resolution lives in `getEffectivePermissions` in
+ * src/lib/services/permissions.service.ts.
+ */
+export const userPermissionOverrides = pgTable(
+  'user_permission_overrides',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    userId: text('user_id').notNull(),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id, { onDelete: 'cascade' }),
+    permissionOverrides: jsonb('permission_overrides')
+      .$type<Partial<RolePermissions>>()
+      .notNull()
+      .default({}),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('idx_user_perm_overrides_user_port').on(table.userId, table.portId),
+    index('idx_user_perm_overrides_user').on(table.userId),
+  ],
+);
+
+export type UserPermissionOverride = typeof userPermissionOverrides.$inferSelect;
+export type NewUserPermissionOverride = typeof userPermissionOverrides.$inferInsert;
+
 export const portRoleOverrides = pgTable(
   'port_role_overrides',
   {

src/lib/pdf/templates/reports/pipeline-report.ts

@@ -1,6 +1,7 @@
 import type { Template } from '@pdfme/common';
 
 import type { PipelineData } from '@/lib/services/report-generators';
+import { stageLabel } from '@/lib/constants';
 
 export const pipelineReportTemplate: Template = {
   basePdf: 'BLANK_PDF' as unknown as string,
@@ -69,8 +70,7 @@ export function buildPipelineInputs(
   const summaryLines = stageOrder
     .filter((stage) => (data.stageCounts[stage] ?? 0) > 0)
     .map((stage) => {
-      const label = stage.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-      return `${label}: ${data.stageCounts[stage] ?? 0} interest(s)`;
+      return `${stageLabel(stage)}: ${data.stageCounts[stage] ?? 0} interest(s)`;
     });
 
   // Include stages not in standard order

src/lib/pdf/templates/reports/revenue-report.ts

@@ -1,6 +1,7 @@
 import type { Template } from '@pdfme/common';
 
 import type { RevenueData } from '@/lib/services/report-generators';
+import { stageLabel } from '@/lib/constants';
 
 export const revenueReportTemplate: Template = {
   basePdf: 'BLANK_PDF' as unknown as string,
@@ -74,12 +75,11 @@ export function buildRevenueInputs(data: RevenueData, portName?: string): Record
     breakdownLines.push('No revenue data available.');
   } else {
     for (const stage of orderedStages) {
-      const label = stage.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
       const amount = Number(data.stageRevenue[stage] ?? 0).toLocaleString(undefined, {
         minimumFractionDigits: 2,
         maximumFractionDigits: 2,
       });
-      breakdownLines.push(`${label}: ${amount}`);
+      breakdownLines.push(`${stageLabel(stage)}: ${amount}`);
     }
   }
 

src/lib/queue/workers/ai.ts

@@ -5,6 +5,7 @@ import type { ConnectionOptions } from 'bullmq';
 import { logger } from '@/lib/logger';
 import { attachWorkerAudit } from '@/lib/queue/audit-helpers';
 import { QUEUE_CONFIGS } from '@/lib/queue';
+import { stageLabel } from '@/lib/constants';
 
 // ─── Email draft generation ───────────────────────────────────────────────────
 
@@ -280,7 +281,7 @@ function buildTemplateDraft(opts: {
     },
     stage_update: {
       subject: `Update on your application – ${clientName}`,
-      body: `Dear ${clientName},\n\nWe are pleased to inform you that your application for ${berthText} has progressed to the "${pipelineStage.replace(/_/g, ' ')}" stage.\n\nWe will be in touch shortly with the next steps.\n\nKind regards,\nPort Nimara Team`,
+      body: `Dear ${clientName},\n\nWe are pleased to inform you that your application for ${berthText} has progressed to the "${stageLabel(pipelineStage)}" stage.\n\nWe will be in touch shortly with the next steps.\n\nKind regards,\nPort Nimara Team`,
     },
     general: {
       subject: `Message from Port Nimara – ${clientName}`,

src/lib/services/interests.service.ts

@@ -850,8 +850,7 @@ export async function changeInterestStage(
       ? (STAGE_LABELS[oldStage as PipelineStage] ?? oldStage.replace(/_/g, ' '))
       : 'unknown';
     const toLabel =
-      STAGE_LABELS[data.pipelineStage as PipelineStage] ??
-      data.pipelineStage.replace(/_/g, ' ');
+      STAGE_LABELS[data.pipelineStage as PipelineStage] ?? data.pipelineStage.replace(/_/g, ' ');
     await createNotification({
       portId,
       userId: meta.userId,

src/lib/services/next-in-line-notify.service.ts

@@ -16,6 +16,7 @@ import { db } from '@/lib/db';
 import { userPortRoles, roles, type RolePermissions } from '@/lib/db/schema/users';
 import { logger } from '@/lib/logger';
 import { createNotification } from '@/lib/services/notifications.service';
+import { STAGE_LABELS, type PipelineStage } from '@/lib/constants';
 
 export interface BerthReleaseNotificationInput {
   portId: string;
@@ -59,8 +60,9 @@ export async function notifyNextInLine(input: BerthReleaseNotificationInput): Pr
   // 2. Build a single description listing the next interests so the
   //    rep can act on it without opening the berth detail page first.
   const previewLines = input.nextInLineInterests.slice(0, 5).map((i) => {
-    const days = i.pipelineStage.replace(/_/g, ' ');
-    return `${i.clientName ?? '(unknown)'} — ${days}`;
+    const stageLabel =
+      STAGE_LABELS[i.pipelineStage as PipelineStage] ?? i.pipelineStage.replace(/_/g, ' ');
+    return `${i.clientName ?? '(unknown)'} — ${stageLabel}`;
   });
   const more =
     input.nextInLineInterests.length > 5

src/lib/services/search-nav-catalog.ts

@@ -58,8 +58,12 @@ export const NAV_CATALOG: NavCatalogEntry[] = [
     category: 'settings',
     keywords: ['preferences', 'configuration', 'config'],
   },
+  // The granular settings cards below redirect to the `/admin/<x>` routes
+  // that actually exist — the catalog previously listed `/settings/<x>`
+  // paths that have never had route folders. We keep the keyword aliases
+  // so the cmd-K search still finds them under the right destination.
   {
-    href: '/:portSlug/settings/email',
+    href: '/:portSlug/admin/email',
     label: 'Email accounts (SMTP / IMAP)',
     category: 'settings',
     keywords: [
@@ -75,47 +79,47 @@ export const NAV_CATALOG: NavCatalogEntry[] = [
     requires: 'admin.manage_settings',
   },
   {
-    href: '/:portSlug/settings/branding',
+    href: '/:portSlug/admin/branding',
     label: 'Branding (per-port logo, colors, copy)',
     category: 'settings',
     keywords: ['logo', 'theme', 'colors', 'tenant brand', 'white-label'],
     requires: 'admin.manage_settings',
   },
   {
-    href: '/:portSlug/settings/templates',
+    href: '/:portSlug/admin/templates',
     label: 'Document templates',
     category: 'settings',
     keywords: ['eoi', 'documenso', 'pdf templates', 'template merge fields'],
     requires: 'admin.manage_settings',
   },
   {
-    href: '/:portSlug/settings/storage',
+    href: '/:portSlug/admin/storage',
     label: 'File storage backend',
     category: 'settings',
     keywords: ['s3', 'minio', 'filesystem', 'storage'],
     requires: 'admin.manage_settings',
   },
   {
-    href: '/:portSlug/settings/recommender',
+    href: '/:portSlug/admin/settings',
     label: 'Berth recommender weights',
     category: 'settings',
     keywords: ['ranking', 'tier ladder', 'heat', 'fallthrough', 'recommend'],
     requires: 'admin.manage_settings',
   },
   {
-    href: '/:portSlug/settings/tags',
+    href: '/:portSlug/admin/tags',
     label: 'Tags',
     category: 'settings',
     keywords: ['labels', 'categories', 'classification'],
   },
   {
-    href: '/:portSlug/settings/notifications',
+    href: '/:portSlug/settings/profile',
     label: 'Notification preferences',
     category: 'settings',
-    keywords: ['alerts', 'email digest', 'in-app', 'push'],
+    keywords: ['alerts', 'email digest', 'in-app', 'push', 'reminders digest'],
   },
   {
-    href: '/:portSlug/user-settings',
+    href: '/:portSlug/settings/profile',
     label: 'My profile & preferences',
     category: 'settings',
     keywords: [
@@ -159,7 +163,7 @@ export const NAV_CATALOG: NavCatalogEntry[] = [
     requires: 'admin.manage_users',
   },
   {
-    href: '/:portSlug/admin/audit-log',
+    href: '/:portSlug/admin/audit',
     label: 'Audit log',
     category: 'admin',
     keywords: ['activity', 'history', 'events', 'who did what', 'compliance'],
@@ -172,7 +176,7 @@ export const NAV_CATALOG: NavCatalogEntry[] = [
     keywords: ['enquiries', 'leads', 'contact form', 'eoi requests', 'website'],
   },
   {
-    href: '/:portSlug/admin/error-events',
+    href: '/:portSlug/admin/errors',
     label: 'Platform errors',
     category: 'admin',
     keywords: ['errors', 'exceptions', 'incidents', 'failures'],

src/lib/services/users.service.ts

@@ -1,7 +1,7 @@
 import { and, eq } from 'drizzle-orm';
 
 import { db } from '@/lib/db';
-import { user, userProfiles, userPortRoles, roles, ports } from '@/lib/db/schema';
+import { account, session, user, userProfiles, userPortRoles, roles, ports } from '@/lib/db/schema';
 import { auth } from '@/lib/auth';
 import { createAuditLog, type AuditMeta } from '@/lib/audit';
 import { ConflictError, NotFoundError, ValidationError } from '@/lib/errors';
@@ -247,6 +247,25 @@ export async function updateUser(
     await db.update(user).set(userUpdates).where(eq(user.id, userId));
   }
 
+  if (wantsEmailChange) {
+    const newEmailLower = data.email!.toLowerCase();
+    // Better Auth's credential provider authenticates by
+    // `account.accountId` (the email captured at sign-up), NOT by
+    // `user.email`. Without this update the user can't sign in with
+    // either address — old fails because user.email no longer matches,
+    // new fails because there's no account.accountId row for it.
+    await db
+      .update(account)
+      .set({ accountId: newEmailLower, updatedAt: new Date() })
+      .where(and(eq(account.userId, userId), eq(account.providerId, 'credential')));
+
+    // Revoke every active session — the admin just changed the identity
+    // the user authenticates with, so existing sessions are effectively
+    // orphaned and a security risk if the account is being rotated due
+    // to compromise. The user re-authenticates with the new address.
+    await db.delete(session).where(eq(session.userId, userId));
+  }
+
   if (wantsEmailChange && previousEmail) {
     // Best-effort notification — failure to send doesn't roll back the
     // change because Better Auth's primary identity has already moved.

src/lib/validators/username.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+
+/**
+ * Canonical username shape.
+ *
+ *  - 2..30 characters (yes, 2 — initials like "dm" are real and the
+ *    director uses them)
+ *  - lowercase letters, digits, `.`, `_`, `-`
+ *  - case-insensitive uniqueness is enforced by a partial unique index on
+ *    LOWER(username) in migration 0054.
+ *
+ * The same regex lives on the DB CHECK constraint, so any insert that
+ * slips past the API still gets rejected at the DB layer.
+ */
+export const USERNAME_REGEX = /^[a-z0-9._-]{2,30}$/;
+
+export const usernameSchema = z
+  .string()
+  .transform((s) => s.trim().toLowerCase())
+  .refine(
+    (s) => USERNAME_REGEX.test(s),
+    'Use 2–30 lowercase letters, digits, dot, underscore, or hyphen.',
+  );
+
+/** Reserved names that the API rejects even if the regex would accept them.
+ *  Keeps obvious confusables out of customer-facing URLs / mentions. */
+export const RESERVED_USERNAMES = new Set([
+  'admin',
+  'administrator',
+  'root',
+  'system',
+  'support',
+  'noreply',
+  'no-reply',
+  'help',
+  'security',
+  'me',
+  'self',
+  'api',
+  'auth',
+  'login',
+  'logout',
+  'signin',
+  'signup',
+  'register',
+  'undefined',
+  'null',
+]);
+
+export function isReservedUsername(username: string): boolean {
+  return RESERVED_USERNAMES.has(username.trim().toLowerCase());
+}

src/middleware.ts

@@ -17,6 +17,12 @@ const PUBLIC_PATHS: string[] = [
   '/scan',
   '/portal/',
   '/api/portal/',
+  // Token-gated email-change endpoints. The confirm/cancel links land in
+  // a fresh browser (the user may not be signed in on this device), so
+  // they need to bypass the session 401 gate. The endpoints validate a
+  // signed sha256-hashed token instead — that's the auth.
+  '/api/v1/me/email/confirm/',
+  '/api/v1/me/email/cancel/',
 ];
 
 function isPublicPath(pathname: string): boolean {