# Maestro host applications

A **host app** is a Laravel project that consumes `maestro/core` and `@maestro/core`. Each customer deployment is its own instance and database.

## Three zones

| Zone | Examples | `core:install --force` |
|------|----------|------------------------|
| **Package CORE** | `vendor/maestro/core`, `node_modules/@maestro/core` | Never edit |
| **Managed shells** | `app.js`, `vite.config.js`, `routes/web.php` | Overwrites when `@maestro-core-managed` |
| **Custom layer** | `app/Custom/Features/`, `modules/custom/`, `maestro/boot.js` | Never overwritten |

## Onboarding (macOS team)

1. Install PHP 8.3, Composer 2, Node 22 ([Laravel Herd](https://herd.laravel.com) recommended)
2. Clone the host repository
3. Run:

```bash
composer run setup
composer run dev
```

4. Read `.cursor/rules/maestro-host-custom-code.mdc` and `AGENTS.md`

## Daily workflows

### Custom feature (most developers)

```bash
php artisan make:custom-feature {Name} --slug={slug} --api-prefix={kebab}
composer run dev
composer test
composer run maestro-audit
```

### CORE platform work

```bash
git clone Maestro-new ../Maestro-new
php artisan maestro:link ../Maestro-new
# edit Maestro-new, test via host app
php artisan maestro:unlink
```

### Upgrade CORE version

```bash
composer update maestro/core
npm update @maestro/core
php artisan core:install --force
php artisan core:install --refresh-cursor-rules
php artisan migrate
rm -rf node_modules/.vite
npm run build
```

## Audits

```bash
php artisan maestro:host-integrity
composer run maestro-audit
```

Superadmin → **Installation health** includes a **Host integrity** group.

## CI

Host repos ship `scripts/check-no-maestro-link.sh` and `.github/workflows/maestro-host-ci.yml` via `core:install`.

## See also

- [LOCAL-LINKING.md](LOCAL-LINKING.md)
- Package README — creating a new host app
