feat(menu): priority-sorted menu groups, user-menu items, sidebar appearance toggle

Every main_menu entry moves from numeric group (1/2/3) to string-based group + group_label + priority. Groups now carry their own i18n label and child entries are sorted by an explicit priority field instead of config-array order, so module-contributed menu items can slot into any existing group at any position.

BootstrapController merges module-registered menu items into main_menu (previously they lived in a separate module_menu response key) and introduces a user_menu response key for items modules want to place in the avatar dropdown. The global store follows suit: moduleMenu becomes userMenu, menuGroups is a computed that sorts by priority, and hasActiveModules drops out.

New admin Appearance setting page with a single toggle for whether sidebar group labels render — so instances that prefer a compact sidebar can hide the Documents/Administration/Modules headings without losing the grouping itself. CompanyLayout watches route meta and re-bootstraps when the admin-mode flag flips so the sidebar repaints with the right menu on navigation across the admin boundary.

Test suites updated: module menu merging is asserted against main_menu (name: 'module-{slug}') rather than the old module_menu response; HelloWorldIntegrationTest verifies the schema translation path; CompanyModulesIndexTest covers the display_name attachment.

app/Http/Controllers/Company/General/BootstrapController.php

@@ -48,6 +48,7 @@ class BootstrapController extends Controller
             'admin_page_title',
             'copyright_text',
             'save_pdf_to_disk',
+            'show_sidebar_group_labels',
         ]);
 
         // Super admin mode — return admin-only menu with all companies listed
@@ -92,6 +93,20 @@ class BootstrapController extends Controller
         $main_menu = $this->generateMenu('main_menu', $current_user);
         $setting_menu = $this->generateMenu('setting_menu', $current_user);
 
+        // Merge module-registered menu items into the main menu so they
+        // participate in the unified group + priority ordering.
+        foreach (ModuleRegistry::allMenu() as $slug => $item) {
+            $main_menu[] = [
+                'title' => __($item['title']),
+                'link' => $item['link'],
+                'icon' => $item['icon'],
+                'name' => 'module-'.$slug,
+                'group' => $item['group'] ?? 'modules',
+                'group_label' => $item['group_label'] ?? 'navigation.modules',
+                'priority' => $item['priority'] ?? 100,
+            ];
+        }
+
         $current_company = Company::find($request->header('company'));
 
         if ((! $current_company) || ($current_company && ! $current_user->hasCompany($current_company->id))) {
@@ -119,7 +134,15 @@ class BootstrapController extends Controller
             'main_menu' => $main_menu,
             'setting_menu' => $setting_menu,
             'modules' => Module::where('enabled', true)->pluck('name'),
-            'module_menu' => array_values(ModuleRegistry::allMenu()),
+            'user_menu' => collect(ModuleRegistry::allUserMenu())
+                ->map(fn (array $item, string $slug) => [
+                    ...$item,
+                    'title' => __($item['title']),
+                    'name' => 'module-'.$slug,
+                ])
+                ->sortBy('priority')
+                ->values()
+                ->all(),
             'pending_invitations' => CompanyInvitationResource::collection($pendingInvitations),
         ]);
     }

app/Providers/AppServiceProvider.php

@@ -125,7 +125,8 @@ class AppServiceProvider extends ServiceProvider
             ->data('ability', $data['ability'])
             ->data('model', $data['model'])
             ->data('group', $data['group'])
-            ->data('group_label', $data['group_label'] ?? '');
+            ->data('group_label', $data['group_label'] ?? '')
+            ->data('priority', $data['priority'] ?? 100);
     }
 
     public function bootAuth()

app/Traits/GeneratesMenuTrait.php

@@ -20,6 +20,7 @@ trait GeneratesMenuTrait
                     'name' => $data->data['name'],
                     'group' => $data->data['group'],
                     'group_label' => $data->data['group_label'] ?? '',
+                    'priority' => $data->data['priority'] ?? 100,
                 ];
             }
         }

config/invoiceshelf.php

@@ -285,7 +285,9 @@ return [
     'main_menu' => [
         [
             'title' => 'navigation.dashboard',
-            'group' => 1,
+            'group' => 'main',
+            'group_label' => '',
+            'priority' => 10,
             'link' => '/admin/dashboard',
             'icon' => 'HomeIcon',
             'name' => 'Dashboard',
@@ -295,7 +297,9 @@ return [
         ],
         [
             'title' => 'navigation.customers',
-            'group' => 1,
+            'group' => 'main',
+            'group_label' => '',
+            'priority' => 20,
             'link' => '/admin/customers',
             'icon' => 'UserIcon',
             'name' => 'Customers',
@@ -305,7 +309,9 @@ return [
         ],
         [
             'title' => 'navigation.items',
-            'group' => 1,
+            'group' => 'main',
+            'group_label' => '',
+            'priority' => 30,
             'link' => '/admin/items',
             'icon' => 'StarIcon',
             'name' => 'Items',
@@ -315,7 +321,9 @@ return [
         ],
         [
             'title' => 'navigation.estimates',
-            'group' => 2,
+            'group' => 'documents',
+            'group_label' => 'navigation.documents',
+            'priority' => 10,
             'link' => '/admin/estimates',
             'icon' => 'DocumentIcon',
             'name' => 'Estimates',
@@ -325,7 +333,9 @@ return [
         ],
         [
             'title' => 'navigation.invoices',
-            'group' => 2,
+            'group' => 'documents',
+            'group_label' => 'navigation.documents',
+            'priority' => 20,
             'link' => '/admin/invoices',
             'icon' => 'DocumentTextIcon',
             'name' => 'Invoices',
@@ -335,7 +345,9 @@ return [
         ],
         [
             'title' => 'navigation.payments',
-            'group' => 2,
+            'group' => 'documents',
+            'group_label' => 'navigation.documents',
+            'priority' => 30,
             'link' => '/admin/payments',
             'icon' => 'CreditCardIcon',
             'name' => 'Payments',
@@ -345,7 +357,9 @@ return [
         ],
         [
             'title' => 'navigation.expenses',
-            'group' => 2,
+            'group' => 'documents',
+            'group_label' => 'navigation.documents',
+            'priority' => 40,
             'link' => '/admin/expenses',
             'icon' => 'CalculatorIcon',
             'name' => 'Expenses',
@@ -355,7 +369,9 @@ return [
         ],
         [
             'title' => 'navigation.modules',
-            'group' => 3,
+            'group' => 'admin',
+            'group_label' => 'navigation.admin',
+            'priority' => 10,
             'link' => '/admin/modules',
             'icon' => 'PuzzlePieceIcon',
             'name' => 'Modules',
@@ -365,7 +381,9 @@ return [
         ],
         [
             'title' => 'navigation.members',
-            'group' => 3,
+            'group' => 'admin',
+            'group_label' => 'navigation.admin',
+            'priority' => 20,
             'link' => '/admin/members',
             'icon' => 'UsersIcon',
             'name' => 'Members',
@@ -375,7 +393,9 @@ return [
         ],
         [
             'title' => 'navigation.reports',
-            'group' => 3,
+            'group' => 'admin',
+            'group_label' => 'navigation.admin',
+            'priority' => 30,
             'link' => '/admin/reports',
             'icon' => 'ChartBarIcon',
             'name' => 'Reports',
@@ -385,7 +405,9 @@ return [
         ],
         [
             'title' => 'navigation.settings',
-            'group' => 3,
+            'group' => 'admin',
+            'group_label' => 'navigation.admin',
+            'priority' => 40,
             'link' => '/admin/settings',
             'icon' => 'CogIcon',
             'name' => 'Settings',

lang/en.json

@@ -14,6 +14,8 @@
     "users": "Users",
     "members": "Members",
     "modules": "Modules",
+    "documents": "Documents",
+    "admin": "Administration",
     "administration": "Administration",
     "companies": "Companies",
     "all_users": "Users"
@@ -773,6 +775,7 @@
     "no_modules_installed": "No Modules Installed Yet!",
     "disable_warning": "All the settings for this particular will be reverted.",
     "what_you_get": "What you get",
+    "screenshots": "Screenshots",
     "sign_up_and_get_token": "Sign up & Get Token",
     "index": {
       "description": "Modules activated by your administrator on this instance. Each company configures its own settings independently.",
@@ -911,7 +914,14 @@
       "notes": "Record Notes",
       "exchange_rate": "Exchange Rate",
       "address_information": "Address Information",
-      "pdf_generation": "PDF Generation"
+      "pdf_generation": "PDF Generation",
+      "appearance": "Appearance"
+    },
+    "appearance": {
+      "title": "Appearance",
+      "description": "Customize how the application looks and feels.",
+      "sidebar_group_labels": "Show sidebar group labels",
+      "sidebar_group_labels_desc": "Display section headers like Documents, Administration, and Modules in the sidebar navigation."
     },
     "address_information": {
       "section_description": "  You can update Your Address information using form below."

resources/scripts/api/services/bootstrap.service.ts

@@ -12,23 +12,10 @@ export interface MenuItem {
   icon: string
   group: string
   group_label?: string
+  priority?: number
   ability?: string
 }
 
-/**
- * Sidebar item registered by an active module via
- * \InvoiceShelf\Modules\Registry::registerMenu() in the module's ServiceProvider::boot().
- *
- * Distinct shape from MenuItem because module entries are namespaced (i18n
- * keys come from the module's lang files) and don't carry group/ability —
- * they always render under the dynamic "Modules" sidebar section.
- */
-export interface ModuleMenuItem {
-  title: string
-  link: string
-  icon: string
-}
-
 export interface BootstrapResponse {
   current_user: User
   current_user_settings: Record<string, string>
@@ -42,7 +29,7 @@ export interface BootstrapResponse {
   config: Record<string, unknown>
   global_settings: Record<string, string>
   modules: string[]
-  module_menu?: ModuleMenuItem[]
+  user_menu?: Array<{ title: string; link: string; icon: string; priority: number; name: string }>
   admin_mode?: boolean
   pending_invitations?: Array<{
     token: string

resources/scripts/features/admin/routes.ts

@@ -14,6 +14,7 @@ const AdminBackupView = () => import('./views/settings/AdminBackupView.vue')
 const AdminFileDiskView = () => import('./views/settings/AdminFileDiskView.vue')
 const AdminFontView = () => import('./views/settings/AdminFontView.vue')
 const AdminUpdateAppView = () => import('./views/settings/AdminUpdateAppView.vue')
+const AdminAppearanceView = () => import('./views/settings/AdminAppearanceView.vue')
 
 export const adminRoutes: RouteRecordRaw[] = [
   {
@@ -126,6 +127,14 @@ export const adminRoutes: RouteRecordRaw[] = [
             },
             component: AdminUpdateAppView,
           },
+          {
+            path: 'appearance',
+            name: 'admin.settings.appearance',
+            meta: {
+              isSuperAdmin: true,
+            },
+            component: AdminAppearanceView,
+          },
         ],
       },
     ],

resources/scripts/features/admin/views/AdminSettingsView.vue

@@ -98,6 +98,11 @@ const menuItems = computed<SettingsMenuItem[]>(() => [
     link: '/admin/administration/settings/update-app',
     icon: 'ArrowPathIcon',
   },
+  {
+    title: t('settings.menu_title.appearance'),
+    link: '/admin/administration/settings/appearance',
+    icon: 'PaintBrushIcon',
+  },
 ])
 
 watchEffect(() => {

resources/scripts/features/admin/views/settings/AdminAppearanceView.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useGlobalStore } from '@/scripts/stores/global.store'
+
+const { t } = useI18n()
+const globalStore = useGlobalStore()
+
+const showSidebarGroupLabels = computed<boolean>({
+  get: () => globalStore.globalSettings?.show_sidebar_group_labels === 'YES',
+  set: async (enabled) => {
+    await globalStore.updateGlobalSettings({
+      data: {
+        settings: {
+          show_sidebar_group_labels: enabled ? 'YES' : 'NO',
+        },
+      },
+      message: t('general.setting_updated'),
+    })
+  },
+})
+</script>
+
+<template>
+  <BaseSettingCard
+    :title="$t('settings.appearance.title')"
+    :description="$t('settings.appearance.description')"
+  >
+    <div class="mt-14">
+      <BaseSwitchSection
+        v-model="showSidebarGroupLabels"
+        :title="$t('settings.appearance.sidebar_group_labels')"
+        :description="$t('settings.appearance.sidebar_group_labels_desc')"
+      />
+    </div>
+  </BaseSettingCard>
+</template>

resources/scripts/layouts/CompanyLayout.vue

@@ -29,7 +29,7 @@
 
 <script setup lang="ts">
 import { useI18n } from 'vue-i18n'
-import { onMounted, computed } from 'vue'
+import { onMounted, computed, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useGlobalStore } from '@/scripts/stores/global.store'
 import { useUserStore } from '@/scripts/stores/user.store'
@@ -63,6 +63,10 @@ const hasCompany = computed<boolean>(() => {
   return !!companyStore.selectedCompany || companyStore.isAdminMode
 })
 
+const usesAdminBootstrap = computed<boolean>(() => {
+  return route.meta.usesAdminBootstrap === true
+})
+
 async function initializeLayout(): Promise<void> {
   const meta = route.meta as RouteMeta
   const res = await globalStore.bootstrap({
@@ -102,4 +106,10 @@ async function initializeLayout(): Promise<void> {
 onMounted(() => {
   void initializeLayout()
 })
+
+watch(usesAdminBootstrap, (isAdminBootstrap, previousValue) => {
+  if (previousValue !== undefined && isAdminBootstrap !== previousValue) {
+    void initializeLayout()
+  }
+})
 </script>

resources/scripts/layouts/partials/SiteHeader.vue

@@ -144,13 +144,30 @@
             </BaseDropdownItem>
           </router-link>
 
+          <router-link
+            v-for="item in globalStore.userMenu"
+            :key="item.name"
+            :to="item.link"
+          >
+            <BaseDropdownItem>
+              <BaseIcon
+                :name="item.icon"
+                class="w-5 h-5 mr-3 text-subtle group-hover:text-muted"
+                aria-hidden="true"
+              />
+              {{ item.title }}
+            </BaseDropdownItem>
+          </router-link>
+
+          <div class="my-1 border-t border-line-light" />
+
           <BaseDropdownItem @click="logout">
             <BaseIcon
               name="ArrowRightOnRectangleIcon"
-              class="w-5 h-5 mr-3 text-subtle group-hover:text-muted"
+              class="w-5 h-5 mr-3 text-red-400"
               aria-hidden="true"
             />
-            {{ $t('navigation.logout') }}
+            <span class="text-red-600">{{ $t('navigation.logout') }}</span>
           </BaseDropdownItem>
         </BaseDropdown>
       </li>

resources/scripts/layouts/partials/SiteSidebar.vue

@@ -99,34 +99,6 @@
                 {{ $t(item.title) }}
               </router-link>
             </nav>
-
-            <!-- Dynamic Modules section (one entry per active module's registered settings link) -->
-            <nav v-if="globalStore.hasActiveModules" class="mt-5 space-y-1">
-              <div class="px-4 mt-6 mb-2 text-xs font-semibold text-subtle uppercase tracking-wider">
-                {{ $t('modules.sidebar.section_title') }}
-              </div>
-              <router-link
-                v-for="(item, idx) in globalStore.moduleMenu"
-                :key="`module-${idx}`"
-                :to="item.link"
-                :class="[
-                  hasActiveUrl(item.link)
-                    ? 'text-primary-600 bg-primary-50 font-semibold'
-                    : 'text-body hover:bg-hover',
-                  'cursor-pointer mx-3 px-3 py-2.5 flex items-center rounded-lg text-sm not-italic font-medium transition-colors',
-                ]"
-                @click="globalStore.setSidebarVisibility(false)"
-              >
-                <BaseIcon
-                  :name="item.icon"
-                  :class="[
-                    hasActiveUrl(item.link) ? 'text-primary-500' : 'text-subtle',
-                    'mr-3 shrink-0 h-5 w-5',
-                  ]"
-                />
-                {{ $t(item.title) }}
-              </router-link>
-            </nav>
           </div>
         </div>
       </TransitionChild>
@@ -154,16 +126,18 @@
       :key="index"
       class="p-0 m-0 mt-4 list-none"
     >
-      <div
+      <template v-if="menu[0] && menu[0].group_label">
-        v-if="menu[0] && menu[0].group_label && !globalStore.isSidebarCollapsed"
+        <div
-        class="px-6 mt-6 mb-2 text-xs font-semibold text-subtle uppercase tracking-wider whitespace-nowrap"
+          v-if="showGroupLabels && !globalStore.isSidebarCollapsed"
-      >
+          class="px-6 mt-6 mb-2 text-xs font-semibold text-subtle uppercase tracking-wider whitespace-nowrap"
-        {{ $t(menu[0].group_label) }}
+        >
-      </div>
+          {{ $t(menu[0].group_label) }}
-      <div
+        </div>
-        v-else-if="menu[0] && menu[0].group_label && globalStore.isSidebarCollapsed"
+        <div
-        class="mx-3 my-2 border-t border-line-light"
+          v-else-if="globalStore.isSidebarCollapsed"
-      />
+          class="mx-3 my-2 border-t border-line-light"
+        />
+      </template>
       <router-link
         v-for="item in menu"
         :key="item.name"
@@ -196,49 +170,6 @@
       </router-link>
     </div>
 
-    <!-- Dynamic Modules section: one shortcut per active module's registered
-         settings link. Hidden when no modules are active. -->
-    <div
-      v-if="globalStore.hasActiveModules"
-      class="p-0 m-0 mt-4 list-none"
-    >
-      <div
-        v-if="!globalStore.isSidebarCollapsed"
-        class="px-6 mt-6 mb-2 text-xs font-semibold text-subtle uppercase tracking-wider whitespace-nowrap"
-      >
-        {{ $t('modules.sidebar.section_title') }}
-      </div>
-      <div
-        v-else
-        class="mx-3 my-2 border-t border-line-light"
-      />
-      <router-link
-        v-for="(item, idx) in globalStore.moduleMenu"
-        :key="`module-desktop-${idx}`"
-        :to="item.link"
-        v-tooltip="globalStore.isSidebarCollapsed ? { content: $t(item.title), placement: 'right' } : null"
-        :class="[
-          hasActiveUrl(item.link)
-            ? 'text-primary-600 bg-primary-50 font-semibold'
-            : 'text-body hover:bg-hover',
-          globalStore.isSidebarCollapsed
-            ? 'cursor-pointer mx-2 px-0 py-2.5 group flex items-center justify-center rounded-lg text-sm font-medium transition-colors'
-            : 'cursor-pointer mx-3 px-3 py-2.5 group flex items-center rounded-lg text-sm not-italic font-medium transition-colors',
-        ]"
-      >
-        <BaseIcon
-          :name="item.icon"
-          :class="[
-            hasActiveUrl(item.link) ? 'text-primary-500' : 'text-subtle group-hover:text-body',
-            globalStore.isSidebarCollapsed ? 'shrink-0 h-6 w-6' : 'mr-3 shrink-0 h-5 w-5',
-          ]"
-        />
-        <span v-if="!globalStore.isSidebarCollapsed" class="whitespace-nowrap">
-          {{ $t(item.title) }}
-        </span>
-      </router-link>
-    </div>
-
     <!-- Bottom toolbar -->
     <div class="mt-auto sticky bottom-0 border-t border-white/10 bg-surface/80 backdrop-blur-xl p-2 flex flex-col items-center gap-1">
       <button
@@ -267,6 +198,7 @@ import {
   TransitionChild,
   TransitionRoot,
 } from '@headlessui/vue'
+import { computed } from 'vue'
 import { useRoute } from 'vue-router'
 import { useGlobalStore } from '@/scripts/stores/global.store'
 import MainLogo from '@/scripts/components/icons/MainLogo.vue'
@@ -282,7 +214,20 @@ interface MenuItemData {
 const route = useRoute()
 const globalStore = useGlobalStore()
 
+const showGroupLabels = computed<boolean>(() => {
+  return globalStore.globalSettings?.show_sidebar_group_labels === 'YES'
+})
+
+const activeMenuLink = computed<string | null>(() => {
+  const allLinks = globalStore.menuGroups.flat().map((item) => item.link)
+  const matches = allLinks.filter(
+    (url) => route.path === url || route.path.startsWith(url + '/'),
+  )
+  // Return the longest (most specific) match
+  return matches.sort((a, b) => b.length - a.length)[0] ?? null
+})
+
 function hasActiveUrl(url: string): boolean {
-  return route.path.indexOf(url) > -1
+  return url === activeMenuLink.value
 }
 </script>

resources/scripts/stores/global.store.ts

@@ -2,7 +2,7 @@ import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
 import groupBy from 'lodash/groupBy'
 import { bootstrapService } from '@/scripts/api/services/bootstrap.service'
-import type { MenuItem, ModuleMenuItem, BootstrapResponse } from '@/scripts/api/services/bootstrap.service'
+import type { MenuItem, BootstrapResponse } from '@/scripts/api/services/bootstrap.service'
 import { settingService } from '@/scripts/api/services/setting.service'
 import type {
   DateFormat,
@@ -25,7 +25,7 @@ export const useGlobalStore = defineStore('global', () => {
   const config = ref<Record<string, unknown> | null>(null)
   const globalSettings = ref<Record<string, string> | null>(null)
 
-  const timeZones = ref<string[]>([])
+  const timeZones = ref<Array<{ key: string; value: string }>>([])
   const dateFormats = ref<DateFormat[]>([])
   const timeFormats = ref<TimeFormat[]>([])
   const currencies = ref<Currency[]>([])
@@ -35,8 +35,7 @@ export const useGlobalStore = defineStore('global', () => {
 
   const mainMenu = ref<MenuItem[]>([])
   const settingMenu = ref<MenuItem[]>([])
-  const moduleMenu = ref<ModuleMenuItem[]>([])
+  const userMenu = ref<Array<{ title: string; link: string; icon: string; name: string }>>([])
-
   const isAppLoaded = ref<boolean>(false)
   const isSidebarOpen = ref<boolean>(false)
   const isSidebarCollapsed = ref<boolean>(localStore.getBoolean('sidebarCollapsed'))
@@ -46,11 +45,13 @@ export const useGlobalStore = defineStore('global', () => {
 
   // Getters
   const menuGroups = computed<MenuItem[][]>(() => {
-    return Object.values(groupBy(mainMenu.value, 'group'))
+    const sorted = [...mainMenu.value].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
+    const groups = groupBy(sorted, 'group')
+    return Object.values(groups).sort(
+      (a, b) => (a[0]?.priority ?? 100) - (b[0]?.priority ?? 100)
+    )
   })
 
-  const hasActiveModules = computed<boolean>(() => moduleMenu.value.length > 0)
-
   // Actions
   async function bootstrap(options?: { adminMode?: boolean }): Promise<BootstrapResponse> {
     const companyStore = useCompanyStore()
@@ -62,7 +63,7 @@ export const useGlobalStore = defineStore('global', () => {
 
       mainMenu.value = response.main_menu
       settingMenu.value = response.setting_menu
-      moduleMenu.value = response.module_menu ?? []
+      userMenu.value = response.user_menu ?? []
 
       config.value = response.config
       globalSettings.value = response.global_settings
@@ -196,7 +197,7 @@ export const useGlobalStore = defineStore('global', () => {
     }
   }
 
-  async function fetchTimeZones(): Promise<string[]> {
+  async function fetchTimeZones(): Promise<Array<{ key: string; value: string }>> {
     if (timeZones.value.length) {
       return timeZones.value
     }
@@ -290,7 +291,7 @@ export const useGlobalStore = defineStore('global', () => {
     fiscalYears,
     mainMenu,
     settingMenu,
-    moduleMenu,
+    userMenu,
     isAppLoaded,
     isSidebarOpen,
     isSidebarCollapsed,
@@ -298,7 +299,6 @@ export const useGlobalStore = defineStore('global', () => {
     downloadReport,
     // Getters
     menuGroups,
-    hasActiveModules,
     // Actions
     bootstrap,
     fetchCurrencies,

tests/Feature/Company/Modules/BootstrapModuleMenuTest.php

@@ -24,7 +24,7 @@ afterEach(function () {
     Registry::flush();
 });
 
-test('bootstrap returns module_menu populated from Registry', function () {
+test('bootstrap merges module menu items into main_menu', function () {
     Registry::registerMenu('sales-tax-us', [
         'title' => 'sales_tax_us::menu.title',
         'link' => '/admin/modules/sales-tax-us/settings',
@@ -33,18 +33,43 @@ test('bootstrap returns module_menu populated from Registry', function () {
 
     $response = getJson('api/v1/bootstrap')->assertOk();
 
-    $response->assertJsonPath('module_menu.0.title', 'sales_tax_us::menu.title');
+    $mainMenu = collect($response->json('main_menu'));
-    $response->assertJsonPath('module_menu.0.link', '/admin/modules/sales-tax-us/settings');
+    $moduleItem = $mainMenu->firstWhere('name', 'module-sales-tax-us');
-    $response->assertJsonPath('module_menu.0.icon', 'CalculatorIcon');
+
+    expect($moduleItem)->not->toBeNull();
+    expect($moduleItem['link'])->toBe('/admin/modules/sales-tax-us/settings');
+    expect($moduleItem['icon'])->toBe('CalculatorIcon');
+    expect($moduleItem['group'])->toBe('modules');
 });
 
-test('bootstrap returns empty module_menu when nothing is registered', function () {
+test('module items support custom group and priority', function () {
-    getJson('api/v1/bootstrap')
+    Registry::registerMenu('sales-tax-us', [
-        ->assertOk()
+        'title' => 'sales_tax_us::menu.title',
-        ->assertJsonPath('module_menu', []);
+        'link' => '/admin/modules/sales-tax-us/settings',
+        'icon' => 'CalculatorIcon',
+        'group' => 'documents',
+        'priority' => 25,
+    ]);
+
+    $response = getJson('api/v1/bootstrap')->assertOk();
+
+    $mainMenu = collect($response->json('main_menu'));
+    $moduleItem = $mainMenu->firstWhere('name', 'module-sales-tax-us');
+
+    expect($moduleItem['group'])->toBe('documents');
+    expect($moduleItem['priority'])->toBe(25);
 });
 
-test('admin-mode bootstrap does not include module_menu', function () {
+test('bootstrap has no module items when nothing is registered', function () {
+    $response = getJson('api/v1/bootstrap')->assertOk();
+
+    $mainMenu = collect($response->json('main_menu'));
+    $moduleItems = $mainMenu->filter(fn ($item) => str_starts_with($item['name'], 'module-'));
+
+    expect($moduleItems)->toBeEmpty();
+});
+
+test('admin-mode bootstrap does not include module items', function () {
     Registry::registerMenu('sales-tax-us', [
         'title' => 'sales_tax_us::menu.title',
         'link' => '/admin/modules/sales-tax-us/settings',
@@ -53,7 +78,8 @@ test('admin-mode bootstrap does not include module_menu', function () {
 
     $response = getJson('api/v1/bootstrap?admin_mode=1');
 
-    // Super-admin branch should not include the dynamic Modules sidebar group —
+    $mainMenu = collect($response->json('main_menu'));
-    // that surface only exists in the company context.
+    $moduleItems = $mainMenu->filter(fn ($item) => str_starts_with($item['name'] ?? '', 'module-'));
-    $response->assertJsonMissingPath('module_menu');
+
+    expect($moduleItems)->toBeEmpty();
 });

tests/Feature/Company/Modules/CompanyModulesIndexTest.php

@@ -93,6 +93,7 @@ test('includes registered menu entry for active modules', function () {
 
     $response = getJson('api/v1/company-modules')->assertOk();
 
+    $response->assertJsonPath('data.0.display_name', 'Menu Module');
     $response->assertJsonPath('data.0.menu.title', 'menu_module::menu.title');
     $response->assertJsonPath('data.0.menu.icon', 'CalculatorIcon');
 });

tests/Feature/Company/Modules/HelloWorldIntegrationTest.php

@@ -4,7 +4,6 @@ use App\Models\CompanySetting;
 use App\Models\Module;
 use App\Models\User;
 use Illuminate\Support\Facades\Artisan;
-use InvoiceShelf\Modules\Registry;
 use Laravel\Sanctum\Sanctum;
 
 use function Pest\Laravel\getJson;
@@ -14,7 +13,7 @@ use function Pest\Laravel\putJson;
  * Integration test that exercises the real Modules/HelloWorld module end-to-end
  * — no Registry mocking. Proves that when an active module's ServiceProvider
  * registers menu + settings via InvoiceShelf\Modules\Registry, the host app's
- * bootstrap, company-modules index, and settings controllers all surface it.
+ * company-modules index and settings controllers surface it consistently.
  *
  * The HelloWorld module's provider boots automatically because nwidart sees
  * it in `storage/app/modules_statuses.json` (set to enabled when the module
@@ -39,18 +38,19 @@ beforeEach(function () {
     );
 });
 
-test('HelloWorld registers a menu entry visible in bootstrap', function () {
+test('bootstrap merges HelloWorld into main_menu under modules group', function () {
     $response = getJson('api/v1/bootstrap')->assertOk();
 
-    $menu = collect($response->json('module_menu'));
+    $mainMenu = collect($response->json('main_menu'));
-    $entry = $menu->firstWhere('link', '/admin/modules/hello-world/settings');
+    $helloWorld = $mainMenu->firstWhere('name', 'module-hello-world');
 
-    expect($entry)->not->toBeNull();
+    expect($helloWorld)->not->toBeNull();
-    expect($entry['title'])->toBe('helloworld::menu.title');
+    expect($helloWorld['link'])->toBe('/admin/modules/hello-world/dashboard');
-    expect($entry['icon'])->toBe('HandRaisedIcon');
+    expect($helloWorld['icon'])->toBe('HandRaisedIcon');
+    expect($helloWorld['group'])->toBe('modules');
 });
 
-test('HelloWorld appears in the company Active Modules index with has_settings flag', function () {
+test('HelloWorld appears in the company Active Modules index with translated display name', function () {
     $response = getJson('api/v1/company-modules')->assertOk();
 
     // The DB row stores PascalCase but the controller normalizes to kebab-case
@@ -58,20 +58,23 @@ test('HelloWorld appears in the company Active Modules index with has_settings f
     $row = collect($response->json('data'))->firstWhere('slug', 'hello-world');
     expect($row)->not->toBeNull();
     expect($row['name'])->toBe('HelloWorld');
+    expect($row['display_name'])->toBe('Hello World');
     expect($row['has_settings'])->toBeTrue();
+    expect($row['menu']['title'])->toBe('Hello World');
     expect($row['menu']['icon'])->toBe('HandRaisedIcon');
 });
 
-test('GET module settings returns the HelloWorld schema with defaults', function () {
+test('GET module settings returns the translated HelloWorld schema with defaults', function () {
     $response = getJson('api/v1/modules/hello-world/settings')->assertOk();
 
     $sections = $response->json('schema.sections');
     expect($sections)->toHaveCount(2);
-    expect($sections[0]['title'])->toBe('helloworld::settings.greeting_section');
+    expect($sections[0]['title'])->toBe('Greeting');
 
     $fields = collect($sections[0]['fields'])->keyBy('key');
     expect($fields)->toHaveKeys(['greeting', 'recipient', 'show_emoji']);
     expect($fields['greeting']['type'])->toBe('text');
+    expect($fields['greeting']['label'])->toBe('Greeting message');
     expect($fields['greeting']['rules'])->toContain('required');
 
     // Defaults flow through when nothing has been saved yet

tests/Feature/Company/Modules/ModuleMakeStubTest.php

@@ -48,6 +48,7 @@ test('module:make generates a ServiceProvider that uses InvoiceShelf\\Modules\\R
     $contents = File::get($providerPath);
 
     expect($contents)->toContain('use InvoiceShelf\\Modules\\Registry as ModuleRegistry;');
+    expect($contents)->toContain('use InvoiceShelf\\Modules\\Support\\ModuleServiceProvider;');
     expect($contents)->toContain('ModuleRegistry::registerMenu(');
     expect($contents)->toContain('ModuleRegistry::registerSettings(');
     expect($contents)->toContain("protected string \$name = '{$this->scaffoldModule}';");