Update docs, changelog, examples, and add ADRs for v1.2

- Add v1.1.0 and v1.2.0 changelog entries
- Add exclude field to config reference and example config
- Add ADRs documenting all major design decisions
- Fix step numbering in reverse_sync()
- Fix action.yml to copy VERSION file
- Add dist/ and .env to .gitignore
- Use refs/tags/ format for Nix flake tag refs

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

docs/adr/010-onboard-checkpoint-resume.md

@@ -0,0 +1,76 @@
+# ADR-010: Onboard Workflow with Checkpoint/Resume
+
+**Status:** Accepted
+**Date:** 2026-02
+
+## Context
+
+Onboarding an existing subrepo into the monorepo is a multi-step process that involves human interaction (renaming repos, merging PRs). The full flow is:
+
+1. Prerequisites: rename existing repo, create new empty repo
+2. Import: copy subrepo content into monorepo, create import PR(s)
+3. Wait: human merges the import PR(s)
+4. Reset: force-push josh-filtered history to the new empty repo
+5. (Optional) Migrate open PRs from archived repo
+
+Each step can fail or be interrupted. The process may span hours or days (waiting for PR review). If interrupted, restarting from scratch wastes work and can create duplicate PRs.
+
+### Alternatives considered
+
+1. **Single-shot script**: Run all steps in sequence. If interrupted, must restart from scratch. Duplicate PRs if import step is re-run.
+
+2. **Manual step-by-step commands**: `import`, then manually run `reset`. Simple but error-prone — users may forget steps or run them out of order.
+
+3. **Checkpoint/resume with persistent state**: Track the current step and intermediate results (PR numbers, reset branches) in persistent state. On re-run, resume from the last completed step.
+
+## Decision
+
+Implement `josh-sync onboard` as a checkpoint/resume workflow with state stored on the `josh-sync-state` branch at `<target>/onboard.json`.
+
+### State machine
+
+```
+start → importing → waiting-for-merge → resetting → complete
+```
+
+Each transition is persisted before proceeding. Re-running `josh-sync onboard <target>` reads the current step and resumes.
+
+### State schema
+
+```json
+{
+  "step": "waiting-for-merge",
+  "archived_api": "https://host/api/v1/repos/org/repo-archived",
+  "archived_url": "git@host:org/repo-archived.git",
+  "archived_auth": "ssh",
+  "import_prs": { "main": 42 },
+  "reset_branches": ["main"],
+  "migrated_prs": [
+    { "old_number": 5, "new_number": 12, "title": "Fix login" }
+  ],
+  "timestamp": "2026-02-10T14:30:00Z"
+}
+```
+
+### Per-branch progress
+
+Import and reset both iterate over branches. Progress is saved after each branch, so interruption mid-iteration resumes at the next unprocessed branch.
+
+### PR migration
+
+`josh-sync migrate-pr` is a separate command that reads onboard state (for the archived repo URL) and tracks migrated PRs. It uses `git apply --3way` for resilient patch application — the subrepo's content is identical after reset, so patches apply cleanly.
+
+## Consequences
+
+**Positive:**
+- Safe to interrupt at any point — no duplicate work on resume
+- Per-branch tracking prevents duplicate import PRs or redundant resets
+- Archived repo URL stored in state — `migrate-pr` can operate independently
+- `--restart` flag allows starting over if state is corrupted
+- Human-friendly — prints instructions at each step
+
+**Negative:**
+- State management adds complexity (read/write onboard state, step validation)
+- Interactive steps (`read -r`) are not suitable for fully automated pipelines
+- Onboard state persists on the state branch even after completion (minor clutter)
+- The step machine is linear — cannot skip steps or run them out of order