# Help4 Migration Runner (WP-CLI)

Use this runner for large migration operations when long `wp eval` payloads are unstable in hosting wrappers.

## Command

```bash
wp h4bs migrate validate --plan=/absolute/path/help4-plan.json
wp h4bs migrate run --plan=/absolute/path/help4-plan.json --dry-run=1
wp h4bs migrate run --plan=/absolute/path/help4-plan.json --dry-run=0
```

## Why this exists

- Avoids quote/newline parsing issues seen with long `wp eval` scripts.
- Uses JSON plans that are easier to review and version-control.
- Supports safe dry-runs before write operations.

## Plan format

Top-level keys:

- `meta` (optional object: name/version/notes)
- `steps` (required array)

Each step requires `action`.

Supported actions:

- `set_option`
  - `key` (string)
  - `value` (any JSON value)
- `set_post_meta`
  - `post_id` (int)
  - `meta_key` (string)
  - `value` (any JSON value)
- `set_builder_mode`
  - `post_id` (int)
  - `mode` (`help4` or `wp`)
  - `enabled` (`1` or `0`)
- `set_builder_layout`
  - `post_id` (int)
  - `layout` (array of block objects or JSON string)
  - Automatically sets mode to `help4` and enabled to `1`.

## Sample plan

See: `docs/migration-plan.sample.json`

## Operational checklist

1. Run `validate` first.
2. Run `run --dry-run=1` and review output.
3. Snapshot/backup database.
4. Run `run --dry-run=0`.
5. Re-run Insights report and visually verify key pages.
