@fayz-ai/saas 0.8.0 → 0.8.2

package/src/app/AdminShell.tsx

@@ -13,28 +13,40 @@ import {
   DropdownItem,
   DropdownLabel,
   DropdownSeparator,
-  Avatar,
-  AvatarImage,
-  AvatarFallback,
+  Skeleton,
   useLayoutStore,
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
 } from '@fayz-ai/ui'
 import { CommandPalette, type CommandItem } from '../shell/components/layout/CommandPalette'
-import { useOrganizationStore } from '../org/store'
 import { useAuth } from '@fayz-ai/auth'
-import { AuthGate } from '@fayz-ai/plugin-auth'
+import { AuthGate, type LoginAmbassador } from '@fayz-ai/plugin-auth'
 import { usePluginRuntime, resolvePluginComponent, useTranslation } from '@fayz-ai/core'
-import type { PermissionAction, PluginNavigationEntry, PluginRouteDefinition, PluginSettingsTab } from '@fayz-ai/core'
+import type { PermissionAction, PluginNavigationEntry, PluginRouteDefinition, PluginSettingsTab, SystemPermission } from '@fayz-ai/core'
+
+/** Route/nav RBAC requirement (mirror of core's PluginPermissionRequirement,
+ *  which is not re-exported from the package index). */
+type PermissionRequirement = { feature: string; action: PermissionAction }
 import { useAdminPath, navigateTo, matchRoute, routeScore } from './routing'
 import type { CustomPage } from './config'
 import type { AuthProvider } from '@fayz-ai/core'
 import { setEntityRouteMap } from '../lib/entity-routes'
 import { usePermissionOptional } from '../permissions/context'
-import { SettingsPage } from '../shell/components/settings/SettingsPage'
+import { usePermissionsStore } from '../permissions'
+import { useTenantOptional } from '../org/context'
+import { WidgetSlot } from '../plugins/WidgetSlot'
+import { useNotifications } from '../shell/hooks/useNotifications'
+import { NotificationInbox } from '../shell/components/notifications/NotificationInbox'
+import { SettingsPage, useCoreSettingsTabs, type SettingsTab } from '../shell/components/settings/SettingsPage'
 import { TeamTab } from '../shell/components/organization/TeamTab'
 import { PermissionProfilesTab } from '../shell/components/organization/PermissionProfilesTab'
 import { LocationsCrudPage } from '../shell/components/settings/LocationsCrudPage'
 import { ConnectedFieldRulesSettings } from '../shell/components/settings/ConnectedFieldRulesSettings'
-import { MapPin, Puzzle, ShieldCheck, SlidersHorizontal, Users } from 'lucide-react'
+import { SubscriptionPage } from '../shell/components/billing/SubscriptionPage'
+import { UpgradePrompt, UpgradeModal, SoftLimitBanner, useAccessOptional, getPlanEntitlements } from '../shell/components/billing'
+import { useBillingStore, resolvePlanBadge } from '../billing'
+import { ArrowLeft, Bell, CreditCard, Crown, LogOut, MapPin, Puzzle, Settings as SettingsIcon, ShieldAlert, ShieldCheck, SlidersHorizontal, Sparkles, UserCog, Users } from 'lucide-react'
 import * as LucideIcons from 'lucide-react'
 
 // ---------------------------------------------------------------------------
@@ -55,6 +67,8 @@ export interface AdminShellProps {
   loginDescription?: string
   loginLogo?: React.ReactNode
   loginLayout?: 'split' | 'centered'
+  loginAmbassadors?: LoginAmbassador[]
+  loginAmbassadorsLabel?: string
   showOAuth?: boolean
   oauthProviders?: Exclude<AuthProvider, 'email'>[]
   showSettings?: boolean
@@ -82,26 +96,61 @@ export interface AdminShellProps {
 
 // ---------------------------------------------------------------------------
 // WorkspaceSwitcher — sub-account / workspace selector at the sidebar top.
-// Reads the native org store (the one AdminProviders populates).
+// Drives the native tenant context (useTenant). switchOrg re-hydrates the org
+// (getOrg + members + permission profiles), so picking a workspace actually
+// reloads the members list, role dropdowns and permission checks — the old
+// setCurrentOrg(partial) path only swapped the name and left stores stale.
 // ---------------------------------------------------------------------------
 
-function WorkspaceSwitcher() {
-  const currentOrg = useOrganizationStore((s) => s.currentOrg)
-  const userOrgs = useOrganizationStore((s) => s.userOrgs)
-  const setCurrentOrg = useOrganizationStore((s) => s.setCurrentOrg)
-  if (!currentOrg) return null
+function WorkspaceSwitcher({ variant = 'sidebar' }: { variant?: 'sidebar' | 'topbar' }) {
+  const tenant = useTenantOptional()
+  const currentOrg = tenant?.org ?? null
+  const t = useTranslation()
+  if (!tenant) return null
+  // Org still hydrating → hold the slot with a trigger-shaped skeleton instead
+  // of collapsing to nothing and popping in later (layout shift in the bar).
+  if (!currentOrg) {
+    if (!tenant.loading) return null
+    return (
+      <div
+        className={
+          variant === 'topbar'
+            ? 'flex w-[180px] items-center gap-2 rounded-md border border-sidebar-border/60 bg-sidebar-accent/30 px-2 py-1.5'
+            : 'flex w-full items-center gap-2 rounded-md border border-sidebar-border/60 bg-sidebar-accent/30 px-2 py-1.5'
+        }
+      >
+        <Skeleton className="h-6 w-6 shrink-0 rounded bg-sidebar-accent" />
+        <Skeleton className="h-4 flex-1 rounded bg-sidebar-accent" />
+      </div>
+    )
+  }
 
+  const { userOrgs, switchOrg, loading } = tenant
   const Building = LucideIcons.Building2
   const Chevron = LucideIcons.ChevronsUpDown
   const Check = LucideIcons.Check
   const options = userOrgs.length
     ? userOrgs
     : [{ orgId: currentOrg.id, orgName: currentOrg.name, orgSlug: currentOrg.slug }]
+  const isSingle = options.length <= 1
+  const tr = (key: string, fallback: string) => {
+    const v = t(key)
+    return !v || v === key ? fallback : v
+  }
 
   return (
     <Dropdown>
       <DropdownTrigger asChild>
-        <button className="flex w-full items-center gap-2 rounded-md border border-sidebar-border/60 bg-sidebar-accent/30 px-2 py-1.5 text-left transition-colors hover:bg-sidebar-accent">
+        <button
+          className={
+            variant === 'topbar'
+              // Inline beside the topbar logo (same bg-sidebar surface): compact,
+              // capped width instead of filling the row.
+              ? 'flex max-w-[220px] items-center gap-2 rounded-md border border-sidebar-border/60 bg-sidebar-accent/30 px-2 py-1.5 text-left transition-colors hover:bg-sidebar-accent disabled:opacity-70'
+              : 'flex w-full items-center gap-2 rounded-md border border-sidebar-border/60 bg-sidebar-accent/30 px-2 py-1.5 text-left transition-colors hover:bg-sidebar-accent disabled:opacity-70'
+          }
+          disabled={loading}
+        >
           <span className="flex h-6 w-6 shrink-0 items-center justify-center rounded bg-sidebar-accent text-sidebar-accent-foreground">
             <Building className="h-3.5 w-3.5" />
           </span>
@@ -109,19 +158,26 @@ function WorkspaceSwitcher() {
           <Chevron className="h-3.5 w-3.5 shrink-0 text-sidebar-muted" />
         </button>
       </DropdownTrigger>
-      <DropdownContent align="start" className="w-56 bg-sidebar text-sidebar-foreground border-sidebar-border">
-        <DropdownLabel className="text-sidebar-muted">Workspaces</DropdownLabel>
-        <DropdownSeparator className="bg-sidebar-border" />
+      {/* Plain popover-toned dropdown (light in light mode) — only the TRIGGER
+          matches the dark sidebar/topbar surface it sits on. */}
+      <DropdownContent align="start" className="w-56">
+        <DropdownLabel>{tr('organization.workspaces', 'Workspaces')}</DropdownLabel>
+        <DropdownSeparator />
         {options.map((m) => (
           <DropdownItem
             key={m.orgId}
-            onClick={() => setCurrentOrg({ id: m.orgId, name: m.orgName, slug: m.orgSlug, createdAt: '', updatedAt: '' })}
-            className="flex items-center gap-2 focus:bg-sidebar-accent focus:text-sidebar-accent-foreground"
+            onClick={() => { if (m.orgId !== currentOrg.id) void switchOrg(m.orgId) }}
+            className="flex items-center gap-2"
           >
             <span className="min-w-0 flex-1 truncate">{m.orgName}</span>
             {currentOrg.id === m.orgId && <Check className="h-4 w-4 shrink-0" />}
           </DropdownItem>
         ))}
+        {isSingle && (
+          <p className="px-2 py-1.5 text-xs text-muted-foreground">
+            {tr('organization.onlyWorkspace', 'This is your only workspace.')}
+          </p>
+        )}
       </DropdownContent>
     </Dropdown>
   )
@@ -131,49 +187,157 @@ function WorkspaceSwitcher() {
 // AdminUserMenu — user dropdown rendered in the sidebar bottom row.
 // ---------------------------------------------------------------------------
 
+/** Small plan pill shown next to the user across both menus. */
+function PlanBadge({ badge }: { badge: { label: string; paid: boolean } }) {
+  return (
+    <span
+      className={
+        badge.paid
+          ? 'inline-flex items-center gap-1 rounded-full border border-amber-400/40 bg-amber-400/15 px-2 py-0.5 text-[10px] font-semibold text-amber-600 dark:text-amber-300'
+          : 'inline-flex items-center gap-1 rounded-full border border-border bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground'
+      }
+    >
+      {badge.paid ? <Crown className="h-3 w-3" /> : <Sparkles className="h-3 w-3" />}
+      {badge.label}
+    </span>
+  )
+}
+
 function AdminUserMenu({
   user,
+  planBadge,
   onProfile,
   onSettings,
+  onBilling,
   onSignOut,
+  profileLabel,
+  settingsLabel,
+  subscriptionLabel,
+  signOutLabel,
 }: {
   user?: { fullName?: string; email: string; avatarUrl?: string }
+  planBadge?: { label: string; paid: boolean } | null
   onProfile?: () => void
   onSettings?: () => void
+  onBilling?: () => void
   onSignOut?: () => void
+  profileLabel: string
+  settingsLabel: string
+  subscriptionLabel: string
+  signOutLabel: string
 }) {
   if (!user) return null
-  const name = user.fullName ?? user.email
-  const initials = name.replace(/[^A-Za-z0-9]/g, ' ').trim().split(/\s+/).map((w) => w[0]).slice(0, 2).join('').toUpperCase() || '?'
+  const name = user.fullName?.trim() || user.email
+  const initials =
+    name.replace(/[^A-Za-z0-9]/g, ' ').trim().split(/\s+/).map((w) => w[0]).slice(0, 2).join('').toUpperCase() ||
+    (user.email[0]?.toUpperCase() ?? '?')
   return (
     <Dropdown>
       <DropdownTrigger asChild>
-        <button className="flex min-w-0 flex-1 items-center gap-2 rounded-md px-1.5 py-1 text-left transition-colors hover:bg-sidebar-accent/50">
-          <Avatar className="h-7 w-7 shrink-0">
-            {user.avatarUrl && <AvatarImage src={user.avatarUrl} alt={name} />}
-            <AvatarFallback>{initials}</AvatarFallback>
-          </Avatar>
-          <span className="min-w-0 truncate text-xs font-medium text-sidebar-foreground">{name}</span>
+        <button className="flex w-full min-w-0 items-center gap-2.5 rounded-lg px-2 py-1.5 text-left transition-colors hover:bg-sidebar-accent">
+          <span className="flex h-8 w-8 shrink-0 items-center justify-center overflow-hidden rounded-full bg-sidebar-accent text-xs font-semibold text-sidebar-accent-foreground">
+            {user.avatarUrl ? (
+              <img src={user.avatarUrl} alt="" className="h-full w-full object-cover" />
+            ) : (
+              initials
+            )}
+          </span>
+          <span className="min-w-0 flex-1 truncate text-xs font-medium text-sidebar-foreground">{name}</span>
         </button>
       </DropdownTrigger>
-      <DropdownContent align="start" className="w-56 bg-sidebar text-sidebar-foreground border-sidebar-border">
+      <DropdownContent align="start" className="w-60 bg-sidebar text-sidebar-foreground border-sidebar-border">
         <DropdownLabel className="truncate text-sidebar-muted">{user.email}</DropdownLabel>
         <DropdownSeparator className="bg-sidebar-border" />
         {onProfile && (
-          <DropdownItem onClick={onProfile} className="focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">Profile</DropdownItem>
+          <DropdownItem onClick={onProfile} className="flex items-center gap-2 focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">
+            <UserCog className="h-4 w-4 shrink-0" />
+            <span className="flex-1">{profileLabel}</span>
+          </DropdownItem>
         )}
         {onSettings && (
-          <DropdownItem onClick={onSettings} className="focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">Settings</DropdownItem>
+          <DropdownItem onClick={onSettings} className="flex items-center gap-2 focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">
+            <SettingsIcon className="h-4 w-4 shrink-0" />
+            <span className="flex-1">{settingsLabel}</span>
+          </DropdownItem>
+        )}
+        {onBilling && (
+          <DropdownItem onClick={onBilling} className="flex items-center gap-2 focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">
+            <CreditCard className="h-4 w-4 shrink-0" />
+            <span className="flex-1">{subscriptionLabel}</span>
+            {planBadge && <PlanBadge badge={planBadge} />}
+          </DropdownItem>
         )}
         <DropdownSeparator className="bg-sidebar-border" />
         {onSignOut && (
-          <DropdownItem onClick={onSignOut} className="focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">Sign out</DropdownItem>
+          <DropdownItem onClick={onSignOut} className="flex items-center gap-2 focus:bg-sidebar-accent focus:text-sidebar-accent-foreground">
+            <LogOut className="h-4 w-4 shrink-0" />
+            <span className="flex-1">{signOutLabel}</span>
+          </DropdownItem>
         )}
       </DropdownContent>
     </Dropdown>
   )
 }
 
+// ---------------------------------------------------------------------------
+// AccessDenied — rendered in place of a page/plugin route whose declared
+// permission the current user does not hold (RBAC route guard).
+// ---------------------------------------------------------------------------
+
+function AccessDenied({ tr }: { tr: (key: string, fallback: string) => string }) {
+  return (
+    <div className="flex h-full flex-col items-center justify-center p-12 text-center">
+      <ShieldAlert className="mb-3 h-10 w-10 text-muted-foreground" />
+      <p className="text-lg font-semibold text-foreground">
+        {tr('shell.accessDenied.title', 'Access restricted')}
+      </p>
+      <p className="mt-1 max-w-sm text-sm text-muted-foreground">
+        {tr('shell.accessDenied.message', "You don't have permission to view this page.")}
+      </p>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// AdminNotifications — the sidebar notification bell. Fetches once on mount
+// (degrades to an empty inbox if the notifications table/store is unavailable)
+// and opens a functional inbox popover with mark-read / mark-all-read wired.
+// ---------------------------------------------------------------------------
+
+function AdminNotifications() {
+  const { notifications, unreadCount, fetchNotifications, markAsRead, markAllAsRead } = useNotifications()
+  const [open, setOpen] = React.useState(false)
+  const fetchedRef = React.useRef(false)
+  React.useEffect(() => {
+    if (fetchedRef.current) return
+    fetchedRef.current = true
+    void fetchNotifications()
+  }, [fetchNotifications])
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          className="relative inline-flex shrink-0 items-center justify-center rounded-md p-2 text-sidebar-muted transition-colors hover:bg-sidebar-accent/50 hover:text-sidebar-accent-foreground"
+          aria-label={unreadCount > 0 ? `${unreadCount} unread notifications` : 'Notifications'}
+        >
+          <Bell className="h-4 w-4" />
+          {unreadCount > 0 && (
+            <span className="absolute right-1 top-1 h-2 w-2 rounded-full bg-destructive" />
+          )}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="end" sideOffset={8} className="w-80 p-0">
+        <NotificationInbox
+          notifications={notifications}
+          onMarkRead={markAsRead}
+          onMarkAllRead={markAllAsRead}
+        />
+      </PopoverContent>
+    </Popover>
+  )
+}
+
 function navEntryToItem(entry: PluginNavigationEntry): NavigationItem {
   return {
     id: entry.id ?? `${entry.route}`,
@@ -182,16 +346,29 @@ function navEntryToItem(entry: PluginNavigationEntry): NavigationItem {
     route: entry.route,
     section: entry.section,
     badge: entry.badge,
+    permission: entry.permission as NavigationItem['permission'],
   }
 }
 
-type OrderedNavigationItem = NavigationItem & { position: number }
+type OrderedNavigationItem = NavigationItem & { position: number; indexChild?: boolean }
+
+/**
+ * Children list a parent starts with once it adopts its first sub-path child:
+ * normally a self-link so the parent's own route stays reachable, but empty
+ * when the entry opted out via `indexChild: false`.
+ */
+function seedChildren(parent: OrderedNavigationItem): OrderedNavigationItem[] {
+  if (parent.indexChild === false) return []
+  return [{ ...parent, id: `${parent.id}:index`, children: undefined, position: -1 }]
+}
 
 interface RouteEntry {
   path: string
   Component: React.ComponentType<Record<string, unknown>>
   /** Render edge-to-edge with no page padding wrapper (chat, kanban, canvas). */
   fullBleed?: boolean
+  /** RBAC guard — when set and unsatisfied the route renders <AccessDenied>. */
+  permission?: PermissionRequirement
 }
 
 function registerEntityRoute(
@@ -263,8 +440,9 @@ function collectPageRoutes(
         ;(page.component as any).__crudBasePath = page.path
         registerEntityRoute(page.component, page.path, entityRouteMap)
       }
-      out.push({ path: page.path, Component: page.component as React.ComponentType<Record<string, unknown>> })
-      out.push({ path: `${page.path}/*`, Component: page.component as React.ComponentType<Record<string, unknown>> })
+      const Component = page.component as React.ComponentType<Record<string, unknown>>
+      out.push({ path: page.path, Component, permission: page.permission })
+      out.push({ path: `${page.path}/*`, Component, permission: page.permission })
     }
     if (page.children?.length) collectPageRoutes(page.children, out, entityRouteMap)
   }
@@ -274,18 +452,43 @@ function collectPageRoutes(
 function buildSettingsTabs(
   pluginTabs: PluginSettingsTab[],
   can: (feature: string, action?: PermissionAction) => boolean,
+  hasSystem: (perm: SystemPermission) => boolean,
   t: (key: string, params?: Record<string, string | number>) => string,
   showOrgSettings: boolean,
-): { id: string; label: string; icon?: React.ReactNode; component: React.ReactNode }[] {
-  const settingsTabs: { id: string; label: string; icon?: React.ReactNode; component: React.ReactNode }[] = []
+  hasBilling: boolean,
+): SettingsTab[] {
+  const settingsTabs: SettingsTab[] = []
+
+  // Subscription — present whenever billing is configured, gated (like the other
+  // org tabs) on the system `manage_billing` permission. Route: /settings/subscription.
+  if (hasBilling && hasSystem('manage_billing')) {
+    const subLabel = t('settings.subscription')
+    settingsTabs.push({
+      id: 'subscription',
+      label: subLabel === 'settings.subscription' ? 'Subscription' : subLabel,
+      // CreditCard everywhere the LINK appears (menus + settings nav) — Crown
+      // is reserved for the paid-plan badge. 'Crown' also isn't in the
+      // sidebar ICON_MAP, which made the settings rail fall back to Home.
+      icon: <CreditCard className="h-4 w-4" />,
+      iconName: 'CreditCard',
+      component: <SubscriptionPage />,
+    })
+  }
 
   if (showOrgSettings) {
-    settingsTabs.push(
-      { id: 'team', label: t('settings.team'), icon: <Users className="h-4 w-4" />, component: <TeamTab /> },
-      { id: 'permissions', label: t('settings.permissions'), icon: <ShieldCheck className="h-4 w-4" />, component: <PermissionProfilesTab /> },
-      { id: 'locations', label: t('settings.locations'), icon: <MapPin className="h-4 w-4" />, component: <LocationsCrudPage /> },
-      { id: 'field-rules', label: t('settings.fieldRules'), icon: <SlidersHorizontal className="h-4 w-4" />, component: <ConnectedFieldRulesSettings /> },
-    )
+    // Org-management tabs are gated on the profile's SYSTEM permissions (the
+    // grants-based can() has no team/permissions/locations feature). Owner and
+    // no-RBAC profiles pass hasSystem() through, so the owner is never blocked.
+    if (hasSystem('manage_team'))
+      settingsTabs.push({ id: 'team', label: t('settings.team'), icon: <Users className="h-4 w-4" />, iconName: 'Users', component: <TeamTab /> })
+    if (hasSystem('manage_permissions'))
+      settingsTabs.push({ id: 'permissions', label: t('settings.permissions'), icon: <ShieldCheck className="h-4 w-4" />, iconName: 'ShieldCheck', component: <PermissionProfilesTab /> })
+    if (hasSystem('manage_settings')) {
+      settingsTabs.push(
+        { id: 'locations', label: t('settings.locations'), icon: <MapPin className="h-4 w-4" />, iconName: 'MapPin', component: <LocationsCrudPage /> },
+        { id: 'field-rules', label: t('settings.fieldRules'), icon: <SlidersHorizontal className="h-4 w-4" />, iconName: 'SlidersHorizontal', component: <ConnectedFieldRulesSettings /> },
+      )
+    }
   }
 
   for (const tab of pluginTabs) {
@@ -299,10 +502,11 @@ function buildSettingsTabs(
       id: tab.id,
       label: translated === labelKey ? tab.label : translated,
       icon: React.createElement(IconComp as React.ComponentType<{ className?: string }>, { className: 'h-4 w-4' }),
+      iconName: tab.icon ?? 'Puzzle',
       component: React.createElement(tab.component),
       // Flag plugin-contributed tabs so SettingsPage draws the core/plugins divider.
       isPlugin: true,
-    } as any)
+    })
   }
 
   return settingsTabs
@@ -312,6 +516,22 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
   const runtime = usePluginRuntime()
   const t = useTranslation()
   const can = usePermissionOptional()
+  // Composed access (role × plan). Nav + route guard use this to distinguish a
+  // role denial (hide / AccessDenied) from a plan denial (Crown badge / UpgradePrompt).
+  const access = useAccessOptional()
+  const currentProfile = usePermissionsStore((s) => s.currentProfile)
+  // Org-management (system) permission check. A null profile (owner / no RBAC
+  // loaded) passes through so the owner is never blocked — the grants-based
+  // owner bypass lives in permissions/context.tsx and is not duplicated here.
+  const hasSystem = React.useCallback(
+    (perm: SystemPermission) => {
+      if (!currentProfile) return true
+      // Owner is never blocked (mirrors the owner bypass in permissions/context).
+      if (currentProfile.id === 'owner' || currentProfile.name?.toLowerCase() === 'owner') return true
+      return currentProfile.systemPermissions?.includes(perm) ?? false
+    },
+    [currentProfile],
+  )
   const tr = (key: string, fallback: string) => {
     const v = t(key)
     return !v || v === key ? fallback : v
@@ -319,12 +539,47 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
   const path = useAdminPath()
   const { user, signOut } = useAuth()
 
+  // Billing surface — plans are seeded into the store from `config.billing` (see
+  // BillingInitializer). A non-empty plan list is the signal that billing is
+  // configured: it drives the Subscription settings tab, the user-menu item, and
+  // the current-plan badge shown next to the user.
+  const billingPlans = useBillingStore((s) => s.plans)
+  const hasBilling = billingPlans.length > 0
+  const orgPlan = useTenantOptional()?.org?.plan
+  const planBadge = React.useMemo(
+    () => (hasBilling ? resolvePlanBadge(orgPlan, billingPlans) : null),
+    [hasBilling, orgPlan, billingPlans],
+  )
+  // Soft-limit monitoring — every limit key the active plan declares. The banner
+  // only surfaces a key whose usage EXCEEDS its cap (used > max), the Notion-style
+  // overshoot path (e.g. public bookings pushing clients past the free cap).
+  const softLimitKeys = React.useMemo(() => {
+    const plan = billingPlans.find((p) => p.id === (orgPlan || 'free'))
+    return Object.keys(getPlanEntitlements(plan)?.limits ?? {})
+  }, [billingPlans, orgPlan])
+
   // Navigation: plugin entries + custom pages (deduped, plugin order preserved).
   const navigation = React.useMemo<NavigationItem[]>(() => {
-    const items: OrderedNavigationItem[] = runtime.navigation.map((entry) => ({
-      ...navEntryToItem(entry),
-      position: entry.position,
-    }))
+    // Plugin entries whose route is a sub-path of another plugin entry nest as
+    // its children (same rule pages get below) — e.g. the courses modules
+    // (/courses/members, /courses/sales…) group under /courses instead of
+    // scattering across the rail. Sort by position first so parents land
+    // before their children.
+    const flat = runtime.navigation
+      .map((entry) => ({ ...navEntryToItem(entry), position: entry.position, indexChild: entry.indexChild }))
+      .sort(compareNavigation)
+    const items: OrderedNavigationItem[] = []
+    for (const item of flat) {
+      const parent = findModuleParent(item, items)
+      if (parent) {
+        const children = parent.children ?? seedChildren(parent)
+        if (!children.some((child) => child.route === item.route)) {
+          parent.children = [...children, item].sort(compareNavigation)
+        }
+        continue
+      }
+      items.push(item)
+    }
     for (const [index, page] of pages.entries()) {
       // `nav: false` routes the page but keeps it out of the sidebar/topbar nav
       // (mobile-only pages reached via bottomNav/avatar). Routes are still built
@@ -335,12 +590,7 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
 
       const parent = findModuleParent(item, items)
       if (parent) {
-        const children = parent.children ?? [{
-          ...parent,
-          id: `${parent.id}:index`,
-          children: undefined,
-          position: -1,
-        }]
+        const children = parent.children ?? seedChildren(parent)
         if (!children.some((child) => child.route === item.route)) {
           parent.children = [...children, item].sort(compareNavigation)
         }
@@ -349,8 +599,30 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
 
       items.push(item)
     }
-    return items.sort(compareNavigation)
-  }, [runtime.navigation, pages])
+    // Access-aware nav gating. Role denial hides the entry (owner/no-profile pass
+    // through). Plan denial KEEPS it (freemium discovery) with a Crown badge that
+    // leads to the route's UpgradePrompt. Children follow the same rule.
+    const decide = (perm?: NavigationItem['permission']): { keep: boolean; premium: boolean } => {
+      if (!perm) return { keep: true, premium: false }
+      const d = access.can(perm.feature, perm.action)
+      if (!d.allowed && d.reason === 'role') return { keep: false, premium: false }
+      return { keep: true, premium: !d.allowed && d.reason === 'plan' }
+    }
+    return items
+      .map((item): OrderedNavigationItem | null => {
+        const dec = decide(item.permission)
+        if (!dec.keep) return null
+        const children = item.children
+          ?.map((child): NavigationItem | null => {
+            const cd = decide(child.permission)
+            return cd.keep ? { ...child, premium: cd.premium } : null
+          })
+          .filter((c): c is NavigationItem => c !== null)
+        return { ...item, premium: dec.premium, children }
+      })
+      .filter((item): item is OrderedNavigationItem => item !== null)
+      .sort(compareNavigation)
+  }, [runtime.navigation, pages, access])
 
   // Command palette (⌘K + the topbar Search button). The palette owns the ⌘K
   // key listener, so it must be MOUNTED for the shortcut to work — the topbar
@@ -376,8 +648,15 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
     for (const r of runtime.routes as PluginRouteDefinition[]) {
       const Component = resolvePluginComponent(r) as React.ComponentType<Record<string, unknown>> | undefined
       if (Component) {
-        list.push({ path: r.path, Component, fullBleed: r.fullBleed })
-        list.push({ path: `${r.path}/*`, Component, fullBleed: r.fullBleed })
+        // Same treatment custom pages get in collectPageRoutes: a generated CRUD
+        // page needs to know the path it was mounted at, otherwise its "new" and
+        // "edit" links resolve against '/' (e.g. /new instead of /shop/products/new).
+        if ((Component as any).__isCrudPage) {
+          ;(Component as any).__crudBasePath = r.path
+          registerEntityRoute(Component, r.path, entityRouteMap)
+        }
+        list.push({ path: r.path, Component, fullBleed: r.fullBleed, permission: r.permission })
+        list.push({ path: `${r.path}/*`, Component, fullBleed: r.fullBleed, permission: r.permission })
       }
     }
     if (showSettings) list.push({ path: '/settings/*', Component: SettingsPage as React.ComponentType<Record<string, unknown>> })
@@ -405,8 +684,53 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
   const ActiveComponent = match?.route.Component
   const activeParams = match?.params ?? {}
   const settingsTabs = React.useMemo(
-    () => buildSettingsTabs(runtime.settingsTabs as PluginSettingsTab[], can, t, showOrgSettings),
-    [runtime.settingsTabs, can, t, showOrgSettings],
+    () => buildSettingsTabs(runtime.settingsTabs as PluginSettingsTab[], can, hasSystem, t, showOrgSettings, hasBilling),
+    [runtime.settingsTabs, can, hasSystem, t, showOrgSettings, hasBilling],
+  )
+
+  // Resolved chrome routes: profile lands on a dedicated /perfil|/profile page
+  // if one is registered, else the Settings → Profile tab; billing only when a
+  // matching route actually exists (no dead nav item otherwise).
+  const profileRoute = React.useMemo(() => {
+    const explicit = routes.find((r) => r.path === '/perfil' || r.path === '/profile')
+    if (explicit) return explicit.path
+    return showSettings ? '/settings/profile' : null
+  }, [routes, showSettings])
+  const onProfile = profileRoute ? () => navigateTo(profileRoute) : undefined
+  // Subscription lives at the always-present /settings/subscription tab whenever
+  // billing is configured — no need to hunt for a standalone billing route.
+  const onBilling = hasBilling && showSettings ? () => navigateTo('/settings/subscription') : undefined
+
+  // Contextual /settings sidebar (desktop sidebar layout only): the app rail is
+  // replaced by "← Back to home" + the settings links, so settings isn't a menu
+  // inside a menu. `coreSettingsTabs` mirrors what SettingsPage renders.
+  const coreSettingsTabs = useCoreSettingsTabs({ showCompany: showBranding, showBranding })
+  const allSettingsTabs = React.useMemo(
+    () => [...coreSettingsTabs, ...settingsTabs],
+    [coreSettingsTabs, settingsTabs],
+  )
+  const inSettings = showSettings && layout === 'sidebar' && (path === '/settings' || path.startsWith('/settings/'))
+  const homeRoute = navigation[0]?.route ?? '/'
+  // With the contextual sidebar the shell owns settings navigation, so it also
+  // owns the active tab: parse it from the URL and drive SettingsPage as a
+  // controlled component (bare /settings → first tab). This is what makes
+  // clicking another settings link actually swap the content.
+  const activeSettingsTab = inSettings
+    ? (path === '/settings'
+        ? allSettingsTabs[0]?.id
+        : path.slice('/settings/'.length).split('/')[0])
+    : undefined
+  const settingsNavigation = React.useMemo<NavigationItem[]>(
+    () => allSettingsTabs.map((tab) => ({
+      id: `settings:${tab.id}`,
+      label: tab.label,
+      icon: tab.iconName ?? 'Settings',
+      route: `/settings/${tab.id}`,
+      // Plugin tabs land in the second group so the sidebar can head them
+      // "Plugins", matching the divider the in-page nav used to draw.
+      section: tab.isPlugin ? 'secondary' : 'main',
+    })),
+    [allSettingsTabs],
   )
 
   const shellUser = user
@@ -430,35 +754,85 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
     return hit?.label ?? candidates.find((n) => n.route === '/')?.label ?? ''
   }, [navigation, path, tr])
 
+  // Access-aware route guard. A role denial renders <AccessDenied>; a plan denial
+  // renders a full-page <UpgradePrompt> for the route's feature ("Premium feature"
+  // + upgrade cards) instead of pretending the page doesn't exist.
+  const routeDecision = match?.route.permission
+    ? access.can(match.route.permission.feature, match.route.permission.action)
+    : { allowed: true as const }
   const activeContent = ActiveComponent ? (
-    match.route.path === '/settings' || match.route.path === '/settings/*'
-      ? <SettingsPage extraTabs={settingsTabs} showCompany={showBranding} showBranding={showBranding} />
-      : <ActiveComponent {...activeParams} />
+    !routeDecision.allowed ? (
+      routeDecision.reason === 'plan' ? (
+        <UpgradePrompt feature={match!.route.permission!.feature} />
+      ) : (
+        <AccessDenied tr={tr} />
+      )
+    ) : match.route.path === '/settings' || match.route.path === '/settings/*' ? (
+      <SettingsPage tabs={allSettingsTabs} showCompany={showBranding} showBranding={showBranding} hideNav={inSettings} activeTabId={activeSettingsTab} />
+    ) : (
+      <ActiveComponent {...activeParams} />
+    )
   ) : null
 
+  const settingsBackLink = (
+    <button
+      onClick={() => navigateTo(homeRoute)}
+      className="flex w-full items-center gap-2 rounded-md px-2.5 py-1.5 text-[13px] font-medium text-sidebar-foreground/80 transition-colors hover:bg-sidebar-accent/60 hover:text-sidebar-accent-foreground"
+    >
+      <ArrowLeft className="h-4 w-4 shrink-0" />
+      <span className="truncate">{tr('settings.backToHome', 'Back to home')}</span>
+    </button>
+  )
+
   return (
     <ModuleLayoutProvider variant={moduleVariant}>
     <AppShell
       variant={layout}
       contentFrame={contentFrame}
-      navigation={navigation}
+      navigation={inSettings ? settingsNavigation : navigation}
+      sidebarSectionLabels={inSettings ? {
+        main: tr('settings.navLinks', 'Settings links'),
+        secondary: tr('common.plugins', 'Plugins'),
+      } : undefined}
+      // Entering settings pushes forward (new rail in from the right); going
+      // back to the app rail reverses it.
+      sidebarNavKey={inSettings ? 'settings' : 'app'}
+      sidebarNavDirection={inSettings ? 'forward' : 'back'}
       logo={logo ?? <span className="text-lg font-bold">{appName}</span>}
       user={shellUser}
       pageTitle={activePageTitle}
-      currentPath={path}
+      // Bare /settings renders the first tab, so highlight it in the rail too.
+      currentPath={inSettings && path === '/settings' ? `/settings/${allSettingsTabs[0]?.id ?? ''}` : path}
       bottomNav={bottomNav}
       onBottomNavAction={onBottomNavAction}
       mobileHeader={mobileHeader}
       onNavigate={(route) => navigateTo(route)}
       onSignOut={() => { void signOut() }}
-      onProfile={() => navigateTo('/perfil')}
+      onProfile={onProfile}
+      onBilling={onBilling}
       onSettings={() => navigateTo('/settings')}
-      sidebarTopContent={showOrgSwitcher ? <WorkspaceSwitcher /> : undefined}
+      userPlan={planBadge ? { label: planBadge.label, paid: planBadge.paid } : undefined}
+      billingLabel={tr('settings.subscription', 'Subscription')}
+      sidebarTopContent={inSettings ? settingsBackLink : showOrgSwitcher ? <WorkspaceSwitcher /> : undefined}
+      // Topbar layout has no sidebar top slot — the switcher rides beside the
+      // logo instead (and in the mobile drawer). Sidebar layout keeps using
+      // sidebarTopContent above, so this stays undefined there (no double render).
+      orgSwitcher={layout === 'topbar' && !inSettings && showOrgSwitcher ? <WorkspaceSwitcher variant="topbar" /> : undefined}
+      topbarStart={<WidgetSlot zone="shell.topbar.start" />}
+      topbarEnd={<WidgetSlot zone="shell.topbar.end" />}
+      notificationSlot={<AdminNotifications />}
       userMenuSlot={
         <AdminUserMenu
           user={shellUser}
+          planBadge={planBadge}
+          onProfile={onProfile}
           onSettings={() => navigateTo('/settings')}
+          onBilling={onBilling}
           onSignOut={() => { void signOut() }}
+          profileLabel={tr('settings.profile', 'Profile')}
+          settingsLabel={tr('settings.title', 'Settings')}
+          subscriptionLabel={tr('settings.subscription', 'Subscription')}
+          signOutLabel={tr('auth.signOut', 'Sign out')}
         />
       }
     >
@@ -469,7 +843,12 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
         >
           {match?.route.fullBleed
             ? <div className="h-full min-h-0 overflow-hidden">{activeContent}</div>
-            : <div className="space-y-4 p-3 md:space-y-6 md:p-6">{activeContent}</div>}
+            : (
+              <div className="space-y-4 p-3 md:space-y-6 md:p-6">
+                {softLimitKeys.length > 0 && <SoftLimitBanner keys={softLimitKeys} />}
+                {activeContent}
+              </div>
+            )}
         </PageTransition>
       ) : (
         <div className="flex h-full flex-col items-center justify-center p-12 text-center">
@@ -492,6 +871,8 @@ function AdminShellInner({ appName, layout = 'sidebar', logo, pages = [], showSe
       open={commandPaletteOpen}
       onOpenChange={setCommandPaletteOpen}
     />
+    {/* Global upgrade dialog — opened imperatively by LimitGate / useLimitGuard. */}
+    <UpgradeModal />
     </ModuleLayoutProvider>
   )
 }
@@ -507,6 +888,8 @@ export function AdminShell(props: AdminShellProps) {
       layout={props.loginLayout}
       tagline={props.loginTagline}
       description={props.loginDescription}
+      loginAmbassadors={props.loginAmbassadors}
+      loginAmbassadorsLabel={props.loginAmbassadorsLabel}
       showOAuth={props.showOAuth}
       oauthProviders={props.oauthProviders}
     >