# Creating the Capell 4.x Monorepo Branches

Use this guide when setting up a fresh Capell development workspace where the host repository and the first-party package repository need to work together on the `4.x` branch.

## Expected Layout

Keep both repositories as siblings:

```sh
~/Sites/packages/capell/
├── capell-4/
└── packages-repository/
```

`capell-4` is the host monorepo for `capell-app/core`, `capell-app/admin`, `capell-app/frontend`, and related host packages. `packages-repository` is the first-party add-on package repository.

## Clone Or Create The Repositories

Clone the host repository, then create a local `4.x` branch from the remote branch:

```sh
mkdir -p ~/Sites/packages/capell
cd ~/Sites/packages/capell

git clone git@github.com:capell-app/capell.git capell-4
cd capell-4
git fetch origin
git switch --track origin/4.x
```

If the host repository has no `4.x` branch yet, run this from `capell-4`:

```sh
git switch main && git pull --ff-only && git switch -c 4.x && git push -u origin 4.x
```

Clone the add-on packages repository beside it and switch to its `4.x` branch:

```sh
cd ~/Sites/packages/capell

git clone git@github.com:capell-app/packages.git packages-repository
cd packages-repository
git fetch origin
git switch --track origin/4.x
```

If the add-on packages repository has no `4.x` branch yet, run this from `packages-repository`:

```sh
git switch main && git pull --ff-only && git switch -c 4.x && git push -u origin 4.x
```

## Wire Composer To The Local Packages

In the Laravel application used for testing Capell, add path repositories that point to both local checkouts:

```json
"repositories": [
    { "type": "path", "url": "../packages/capell-4/packages/*", "symlink": true },
    { "type": "path", "url": "../packages/packages-repository/packages/*", "symlink": true }
]
```

The paths must be relative to the Laravel application root. Adjust the leading `../packages/` segment if your app lives elsewhere.

Then update the app dependencies:

```sh
composer update -W
composer dump-autoload
```

## Keep Both Repositories Aligned

Before working on a change that spans host and add-on packages:

```sh
cd ~/Sites/packages/capell/capell-4
git switch 4.x
git pull --ff-only

cd ~/Sites/packages/capell/packages-repository
git switch 4.x
git pull --ff-only
```

Create feature branches from `4.x` in whichever repository needs changes:

```sh
git switch -c feat/my-capell-change
```

Use the same branch name in both repositories when a change spans them. That keeps pull requests and CI easier to pair up.

## Verify The Workspace

From the host repository:

```sh
composer prepare
composer test
composer preflight
```

From the Laravel application, confirm Composer is using symlinks:

```sh
composer show capell-app/core -P
composer show capell-app/content-sections -P
```

Both commands should resolve to your local `capell-4` or `packages-repository` checkout rather than a Composer cache path.