Update docs for onboard and migrate-pr commands

- README: add onboard and migrate-pr to CLI reference
- Guide Step 5: add onboard as recommended Option A, move manual
  import/reset to Option B, document migrate-pr usage
- Guide "Adding a New Target": mention onboard as preferred path

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -68,6 +68,8 @@ josh-sync sync [--forward|--reverse] [--target NAME[,NAME]] [--branch BRANCH]
 josh-sync preflight
 josh-sync import <target>
 josh-sync reset <target>
+josh-sync onboard <target> [--restart]
+josh-sync migrate-pr <target> [PR#...] [--all]
 josh-sync status
 josh-sync state show <target> [branch]
 josh-sync state reset <target> [branch]

docs/guide.md

@@ -189,11 +189,61 @@ For a new monorepo before import, preflight may warn that subfolders don't exist
 
 ## Step 5: Import Existing Subrepos
 
-This is the critical onboarding step. For each existing subrepo, you run a three-step cycle: **import → merge → reset**.
+This is the critical onboarding step. There are two approaches:
+
+- **`josh-sync onboard`** (recommended) — interactive, resumable, preserves open PRs
+- **Manual `import` → merge → `reset`** — lower-level, for automation or when there are no open PRs to preserve
+
+### Option A: Onboard (recommended)
+
+The `onboard` command walks you through the entire process interactively, with checkpoint/resume at every step.
+
+**Before you start:**
+
+1. **Rename** the existing subrepo on your Git server (e.g., `stores/storefront` → `stores/storefront-archived`)
+2. **Create a new empty repo** at the original path (e.g., a new `stores/storefront` with no commits)
+
+The rename preserves the archived repo with all its history and open PRs. The new empty repo will receive josh-filtered history.
+
+**Run onboard:**
+
+```bash
+josh-sync onboard billing
+```
+
+The command will:
+1. **Verify prerequisites** — checks the new empty repo is reachable, asks for the archived repo URL
+2. **Import** — copies subrepo content into monorepo and creates import PRs (one per branch)
+3. **Wait for merge** — shows PR numbers and waits for you to merge them
+4. **Reset** — pushes josh-filtered history to the new subrepo (per-branch, with resume)
+5. **Done** — prints instructions for developers and PR migration
+
+If the process is interrupted at any point, re-run `josh-sync onboard billing` to resume from where it left off. Use `--restart` to start over.
+
+**Migrate open PRs:**
+
+After onboard completes, migrate PRs from the archived repo to the new one:
+
+```bash
+# Interactive — lists open PRs and lets you pick
+josh-sync migrate-pr billing
+
+# Migrate all open PRs at once
+josh-sync migrate-pr billing --all
+
+# Migrate specific PRs by number
+josh-sync migrate-pr billing 5 8 12
+```
+
+PR migration works by fetching the diff from the archived repo's PR, applying it to the new repo, and creating a new PR. File content is identical after reset, so patches apply cleanly.
+
+### Option B: Manual import → merge → reset
+
+Use this when the subrepo has no open PRs to preserve, or for scripted automation.
 
 > Do this **one target at a time** to keep PRs reviewable.
 
-### 5a. Import
+#### 5b-1. Import
 
 ```bash
 josh-sync import billing
@@ -208,13 +258,13 @@ This:
 
 Review the import PR — check for leaked credentials, environment-specific config, or files that shouldn't be in the monorepo.
 
-### 5b. Merge the import PR
+#### 5b-2. Merge the import PR
 
 Merge the PR using your Git platform's UI. This lands the subrepo content into the monorepo's main branch.
 
 > At this point, the monorepo has the content but the histories are disconnected. Sync will **not** work until you complete the reset step.
 
-### 5c. Reset
+#### 5b-3. Reset
 
 ```bash
 josh-sync reset billing
@@ -241,7 +291,7 @@ git checkout stage && git reset --hard origin/stage   # repeat for each branch
 
 Or simply delete and re-clone the subrepo. Local-only branches (not pushed to the remote) will be lost either way.
 
-### 5d. Repeat for each target
+#### 5b-4. Repeat for each target
 
 ```
 For each target:
@@ -250,9 +300,9 @@ For each target:
   3. josh-sync reset <target>
 ```
 
-### 5e. Verify
+### Verify
 
-After all targets are imported and reset:
+After all targets are imported and reset (whichever option you used):
 
 ```bash
 # Check all targets show state
@@ -444,8 +494,12 @@ To add a new subrepo after initial setup:
 1. Add the target to `.josh-sync.yml`
 2. Update the forward workflow's `paths:` list to include the new subfolder
 3. Commit and push
-4. Run the import-merge-reset cycle for the new target:
+4. Import the target:
    ```bash
+   # Recommended: interactive onboard (preserves open PRs)
+   josh-sync onboard new-target
+
+   # Or manual: import → merge PR → reset
    josh-sync import new-target
    # merge the PR
    josh-sync reset new-target