# Migration Guide

Use `starwind migrate` when a project still has the old Astro copied-component setup. The command
migrates as much as it safely can in one guided run and leaves anything unresolved in config as
`source: "legacy"`.

```bash
starwind migrate
```

## What The Command Does

- Reads `starwind.config.json` and detects the legacy config shape.
- Inspects the public component directory, normally `src/components/starwind`.
- Offers to back up existing component folders to `src/components/starwind-legacy`.
- Creates a numbered backup such as `src/components/starwind-legacy-1` if the default backup path
already exists.
- Asks before overwriting folders that conflict with Runtime registry components.
- Leaves unrelated custom folders alone.
- Installs the package requirements declared by the Runtime registry.
- Writes a v2 config with `framework: "astro"` as the Runtime output target.

## Public Import Paths

Migration keeps the public component path at `src/components/starwind` by default. Existing imports
such as this should remain the normal public shape after migration:

```astro
```

## Backup And Overwrite Prompts

The backup prompt protects your old component source before replacement. If you accept it, the CLI
copies the current Starwind component folder before writing Runtime-backed styled components.

The overwrite prompt is per conflicting component folder. If you decline an overwrite, that folder
stays in place and the component remains recorded as `legacy-astro` in the final report.

## Migration Report

The final report separates the important outcomes:

- `Migrated`: Runtime-backed styled components written successfully.
- `Skipped`: Conflicting component folders that were not overwritten.
- `Backed up`: folders copied into a legacy backup directory.
- `Overwritten`: component folders replaced by the Runtime-backed registry artifact.
- `Custom`: folders in the Starwind directory that were not registry components.
- `Legacy`: unresolved entries that remain in config with `source: "legacy"`.

## After Migration

Use the normal Runtime CLI commands after migration:

```bash
starwind add button
starwind update button
starwind primitives add button
starwind docs button
```