"#"

docs/guide.md

@@ -224,14 +224,40 @@ 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. There are two approaches:
+This is the critical onboarding step. There are three 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
+- **`josh-sync adopt`** (recommended for active existing subrepos) — non-destructive, resumable, preserves existing subrepo history
+- **`josh-sync onboard`** — destructive replacement-repo workflow for teams that intentionally archive the old repo
+- **Manual `import` → merge → `reset`** — lower-level destructive path for automation or empty replacement repos
 
-### Option A: Onboard (recommended)
+### Option A: Adopt (recommended for active subrepos)
 
-The `onboard` command walks you through the entire process interactively, with checkpoint/resume at every step.
+Use `adopt` when the subrepo already exists, developers already clone it, or open PR branches should remain based on existing history.
+
+```bash
+josh-sync adopt billing
+```
+
+The command will:
+1. **Import** — copies current subrepo content into the monorepo and creates import PRs (one per branch)
+2. **Wait for merge** — shows PR numbers and waits for you to merge them
+3. **Verify trees** — requires the existing subrepo tree to match the Josh-filtered monorepo tree
+4. **Adopt** — creates a merge commit on the subrepo with Josh-filtered HEAD as parent 1 and existing subrepo HEAD as parent 2
+5. **Push** — pushes the adoption merge with a normal fast-forward push, never force-push
+
+The adoption merge preserves the old subrepo history while giving Josh a first-parent path back to the monorepo. If interrupted, re-run `josh-sync adopt billing` to resume. Use `--restart` to start over.
+
+After adoption, developers can update existing clones with a normal fast-forward:
+
+```bash
+git fetch origin
+git checkout main
+git merge --ff-only origin/main
+```
+
+### Option B: Onboard with replacement repo
+
+The `onboard` command walks through the destructive replacement-repo process interactively, with checkpoint/resume at every step.
 
 **Before you start:**
 
@@ -272,13 +298,13 @@ 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
+### Option C: Manual import → merge → reset
 
-Use this when the subrepo has no open PRs to preserve, or for scripted automation.
+Use this for scripted automation or when you intentionally want to replace subrepo history.
 
 > Do this **one target at a time** to keep PRs reviewable.
 
-#### 5b-1. Import
+#### 5c-1. Import
 
 ```bash
 josh-sync import billing
@@ -293,13 +319,13 @@ This:
 
 Review the import PR — check for leaked credentials, environment-specific config, or files that shouldn't be in the monorepo.
 
-#### 5b-2. Merge the import PR
+#### 5c-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.
 
-#### 5b-3. Reset
+#### 5c-3. Reset
 
 ```bash
 josh-sync reset billing
@@ -326,7 +352,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.
 
-#### 5b-4. Repeat for each target
+#### 5c-4. Repeat for each target
 
 ```
 For each target:
@@ -337,13 +363,13 @@ For each target:
 
 ### Verify
 
-After all targets are imported and reset (whichever option you used):
+After all targets are adopted or reset:
 
 ```bash
 # Check all targets show state
 josh-sync status
 
-# Test forward sync — should return "skip" (trees are identical after reset)
+# Test forward sync — should return "skip" (trees are identical after adoption/reset)
 josh-sync sync --forward --target billing
 
 # Test reverse sync — should return "skip" (no new human commits)
@@ -620,9 +646,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. Import the target:
+4. Import or adopt the target:
    ```bash
-   # Recommended: interactive onboard (preserves open PRs)
+   # Recommended for an existing active subrepo
+   josh-sync adopt new-target
+
+   # Replacement-repo workflow
    josh-sync onboard new-target
 
    # Or manual: import → merge PR → reset