post-1.0: version-aware migrations between docs-kit releases in docs_kit:install --sync

[mhenrixon]

Problem / Goal

rails g docs_kit:install --sync (#24, PR #39) is deliberately version-agnostic: it reconciles a site against the current gem template with no notion of which docs-kit version the site was last synced from. That was the right v1 call — it keeps the tool simple and there was no version history to migrate across yet.

Post-1.0, release-to-release migrations become a real need: when a future version renames a config knob, changes a route shape, or restructures a template, --sync should be able to apply the ordered migration steps between the site's last-synced version and the current one — not just diff against head.

Goal (to be designed for 1.0+)

• Record the docs-kit version a site was last synced at (e.g. a stamp in the initializer or a .docs-kit-version file).
• A migration registry: ordered, versioned transforms (1.2 → 1.3, 1.3 → 2.0, …) the generator applies in sequence.
• --sync detects the gap and runs only the applicable migrations, still warn-only for anything it can't safely automate (the fix(generator): idempotent install + a consumer re-sync guide #24 drift-report pattern).

Why deferred

• The gem is still 0.1.0 — no release history to migrate across.
• The current --sync + SyncReport drift detection covers the "adopt what's new" case well enough pre-1.0.

Context

• Current version-agnostic sync: lib/generators/docs_kit/install/install_generator.rb (--sync flag), lib/generators/docs_kit/install/sync_report.rb.
• Parent epic (delivered): [EPIC] DX overhaul: write less, document more, AI-native docs #8; originating issue: fix(generator): idempotent install + a consumer re-sync guide #24.

Filing against the 1.0 milestone so the intent isn't lost.

https://claude.ai/code/session_01FPQb6z3YwcKRMbvoJhdxnX