# Site Branch Preparation

This CMS should be treated as the reusable backend engine. Each website can live on its own branch with only the frontend theme, branding, content seed data, and site-specific assets changed.

## Recommended Flow

1. Start from the maintained CMS/base branch.
2. Create a new site branch:

```bash
git checkout -b site/client-name
```

3. Preview what theme cleanup would remove:

```bash
php artisan site:prepare-branch
```

4. Apply the cleanup:

```bash
php artisan site:prepare-branch --force
```

5. If the new site must replace the whole frontend asset skin, also clear `public/frontend`:

```bash
php artisan site:prepare-branch --force --clear-frontend
```

6. If the branch must also clear the old logo/favicon:

```bash
php artisan site:prepare-branch --force --clear-branding
```

7. Preview a new extracted frontend theme before copying anything:

```bash
php artisan site:stage-frontend-theme "C:\path\to\extracted-html-theme"
```

8. Copy the theme assets into `public/frontend` and save the root HTML files as reference pages:

```bash
php artisan site:stage-frontend-theme "C:\path\to\extracted-html-theme" --force
```

9. Replace the current `public/frontend` assets before copying the new theme:

```bash
php artisan site:stage-frontend-theme "C:\path\to\extracted-html-theme" --force --replace
```

10. Save only the reference HTML pages without copying assets:

```bash
php artisan site:stage-frontend-theme "C:\path\to\extracted-html-theme" --force --references-only
```

## What The Command Cleans

- Uploaded theme packages in `storage/app/public/themes`
- Temporary theme extraction files in `storage/app/temp/themes`
- Generated theme conversion candidates in `storage/app/theme-conversions`
- Theme conversion/settings records such as `theme_assets_*`, `theme_template_map_*`, `theme_content_map_*`, and `theme_customization_*`
- Theme-related media records

## What It Does Not Clean

- Admin/backend code
- Database content such as services, teams, projects, news, users, orders, or settings not related to uploaded themes
- Content uploads like team photos, service images, project images, documents, or media library files
- `public/frontend`, unless `--clear-frontend` is explicitly passed

This keeps the CMS maintainable: backend improvements can continue on the base branch, while each site branch carries only its own frontend and content changes.

## Frontend Theme Staging

`site:stage-frontend-theme` is for a theme that has already been extracted on disk. It does not convert the theme to Blade automatically. It gives the developer a clean starting point:

- Non-HTML files are copied into `public/frontend`, preserving their relative paths.
- Root `.html` files are copied into `storage/app/frontend-references/{theme_name}/pages`.
- A `manifest.json` is written beside the reference pages so the branch records what was staged.
- The command is dry-run by default.

The intended workflow is to keep the raw HTML as reference pages, then manually build the Blade frontend against CMS data while using `public/frontend` for the theme assets.