"#"

README.md

@@ -85,6 +85,7 @@ CI workflows pin to a floating major tag (e.g. `@v1`). A breaking change bumps t
 josh-sync sync [--forward|--reverse] [--force] [--target NAME[,NAME]] [--branch BRANCH]
 josh-sync preflight
 josh-sync import <target>
+josh-sync adopt <target> [--restart]
 josh-sync reset <target>
 josh-sync onboard <target> [--restart]
 josh-sync migrate-pr <target> [PR#...] [--all]
@@ -97,6 +98,7 @@ josh-sync state reset <target> [branch]
 
 - **Forward sync** (mono → subrepo): pushes directly if clean, creates conflict PR if not. Uses `--force-with-lease` for safety.
 - **Reverse sync** (subrepo → mono): creates a PR by default. Add `--force` to bypass the PR and push directly to the mono branch (destructive).
+- **Adoption**: existing active subrepos can be connected to josh-sync with a normal fast-forward merge commit, preserving old subrepo history and avoiding force-push.
 - **File exclusion**: `exclude` patterns are embedded inline in the josh-proxy URL. Excluded files exist only in the monorepo.
 - **Filter reconciliation**: Changing the exclude list auto-creates a merge commit that connects old and new histories — no force-push needed.
 - **Loop prevention**: `Josh-Sync-Origin:` git trailer filters out bot commits.