---
description: Standard workflow for introducing a new Maestro CORE feature module (deploy, DB, Superadmin)
alwaysApply: true
---

# Maestro CORE — New module rollout (always follow)

When adding **any** optional feature module (`src/Modules/{Pascal}`, matching SPA + APIs), implement and ship in this **order**:

1. **Deploy gate — `config('core.modules.{slug}')`**
   - Add the slug to **`config/core.php`** (and host publish merge).
   - Register the module **`{Name}ModuleServiceProvider`** in **`CoreServiceProvider::loadModules()`** only when the flag resolves to **`true`** (mirror **Customers**). When **`false`**, the provider must not register (no routes, no **`loadMigrationsFrom`** participation).

2. **PHP module package**
   - Provider: **`loadMigrationsFrom`**, **`loadRoutesFrom`** (e.g. **`routes/modules/{slug}.php`**), **`boot()` early return** when config flag off.
   - Protect module APIs with middleware **`maestro.module:{slug}`** where **`EnsureMaestroModuleEnabled`** applies.

3. **Database**
   - Migrations live under the module; they run **only after** the host enables the slug and **`php artisan migrate`** has been executed on that deployment.

4. **Runtime registry & navigation**
   - Ensure a **`maestro_modules`** row for the **`slug`** (typically **`ModuleAndNavigationSeeder`** or an **idempotent migration** if you must not purge the nav tree).
   - Add/adjust **`NavigationNode`** entries (module-linked or permission-based) so the sidebar matches **`meta.module`** / permissions on the Vue side.

5. **Vue SPA**
   - Routes under the authenticated layout with **`meta.module`** = same **`slug`** as **`MaestroModule`** / **`enabled_module_slugs`**.

6. **Superadmin**
   - **Feature toggles**: operators use Superadmin › **Modules** for **`maestro_modules.is_enabled`** (runtime on/off).
   - **Installation health**: extend **`InstallationHealthService`** with checks for new slugs when the checklist should surface misconfiguration (tables vs config vs DB toggle).

7. **Ops (never replace with risky HTTP-triggered Artisan)**
   - Fresh or upgraded instances: **`php artisan migrate`** and seed (e.g. **`ModuleAndNavigationSeeder`** / **`DatabaseSeeder`**) remain **CLI / deploy**.
   - **Superadmin › Installation health** is **read-only guidance** plus suggested commands — not execution.

Cross-references: **`maestro-php-backend.mdc`** (implementation details), **`maestro-vue-spa.mdc`** (`meta.module`), **`maestro-overview.mdc`** (layout).
