# Maestro host app — AI agent guide

This Laravel app consumes **maestro/core** (PHP) and **@maestro/core** (Vue SPA). Follow these rules on every change.

## Zones

| Zone | Path | Rule |
|------|------|------|
| Package CORE | `vendor/maestro/core`, `node_modules/@maestro/core` | **Never edit** |
| Managed shells | `app.js`, `vite.config.js`, `routes/web.php`, … (`@maestro-core-managed`) | No business logic; refreshed by `core:install --force` |
| Custom layer | `app/Custom/Features/`, `resources/js/modules/custom/`, `resources/js/maestro/boot.js` | All host-specific code |

## New feature

```bash
php artisan make:custom-feature {Name} --slug={slug} --api-prefix={kebab}
```

Do not hand-create folders under `app/Http` or `resources/js/views` for business features.

## Before commit

```bash
composer test
composer run maestro-audit
```

## CORE vs custom decision

- **Database / Superadmin** — branding, modules, navigation, public page settings
- **Custom feature** — one-customer workflows, integrations, unique business rules
- **Maestro CORE PR** — reusable across all Maestro deployments

See `.cursor/rules/maestro-core-vs-custom.mdc` for the full decision tree.

## Local CORE development

Only when working on the platform package:

```bash
php artisan maestro:link ../Maestro-new
# … work …
php artisan maestro:unlink
```

Never commit `.maestro-link.json` or path-based lockfile entries.
