# Local Maestro CORE linking

Link a host Laravel app to a local **Maestro-new** checkout while developing the platform. Production and CI must always use registry lockfiles.

## Prerequisites

Clone both repositories side by side:

```
projects/
  Maestro-new/
  Build2APP/    # or any host app
```

## Link

From the host app:

```bash
php artisan maestro:link ../Maestro-new
rm -rf node_modules/.vite
composer run dev
```

This will:

- Add a Composer path repository (`maestro-local-path`) with symlink
- `composer require maestro/core:@dev`
- `npm install file:<abs-path-to-Maestro-new>`
- Write `.maestro-link.json` (gitignored)

PHP changes in Maestro-new are visible immediately via symlink. Vue changes hot-reload through Vite; restart the dev server after changing dependencies inside `@maestro/core`.

## Unlink (before commit / CI / deploy)

```bash
php artisan maestro:unlink
rm -rf node_modules/.vite
composer run dev
```

Restores registry versions from `composer.lock` / `package-lock.json`.

## Verify

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

Linked state reports **warn** on `maestro-linked`. CI uses `--fail-on-warn` so linked trees fail the pipeline.

## When not to link

- Host-only custom feature work (`make:custom-feature`) — use registry install only
- Before pushing host-app branches
- Production deploys

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Blank UI / dual Vue runtime | `rm -rf node_modules/.vite`, restart Vite |
| `quill-delta` export error | Ensure host `vite.config.js` includes `quill` + `quill-delta` in `optimizeDeps.include` |
| Stale managed shells | `php artisan core:install --force` |
