#87 feat(generator): 1.1 → 1.2 upgrade migration + upgrade notes

Summary

This adds upgrade instructions for the 1.2 release before it goes out. Some are automated, some are written down.

Automated: bin/rails g docs_kit:install --sync now runs its first release migration (Migrations::V1_2_0). A value is rewritten only when it's exactly what an older docs-kit generated, so it can't be a hand edit. A hand-picked older value is printed as a warning, and a newer value is left alone.

Site file	--sync does
Dockerfile ARG BUN_VERSION=1.3.2	Bumps it to 1.4.2
package.json tailwindcss / @tailwindcss/cli ^4.1.18, daisyui ^5.6.0	Raises them to ^4.3.3 / ^5.7.47. Only the "name": "value" pair is edited; everything else stays byte-for-byte.
.ruby-version / ARG RUBY_VERSION below 3.3	Warns (docs-kit 1.2 requires Ruby >= 3.3)
deploy-docs.yml calling deploy.yml@<tag or SHA>	Warns that the Node 24 / ubuntu-26.04 deploy is only on @main

Written:

• The CHANGELOG now opens with an "Upgrading from 1.1" block: the commands, then what --sync does and what's left to you.
• The CHANGELOG was never split per release; Unreleased held everything since 1.0. Entries that shipped in 1.1.1 or earlier now sit under their own heading, so Unreleased is only what 1.2 adds. I checked this against git diff v1.1.1 -- CHANGELOG.md. The missing #72 entry (gitignoring tailwind.sources.css) is added.
• The README's "Version-aware migrations" section no longer says the registry is empty. It has a per-release table of what --sync does and what you do.

Test plan

• spec/generators/migrations/v1_2_0_spec.rb has 14 examples covering:
  • Each rewrite, each warning, and newer values staying untouched.
  • A site with none of these files.
  • Byte-for-byte preservation of package.json.
  • That the migration is registered, via applicable("1.1.1", upto: "1.2.0").
• The spec caught a real bug on its first run. tailwindcss and @tailwindcss/cli share the value "^4.1.18", so substituting on the bare value rewrote the wrong key. The migration now rewrites the whole pair.
• Dogfooded on a copy of docs/, deliberately set back to old values. It bumped Bun 1.3.2 and daisyui ^5.6.0, only warned about Ruby 3.2.8 and a hand-picked tailwind ^4.2.0, and said nothing about the @main deploy caller.
• bundle exec rake: 994 examples, 0 failures, 92.56% coverage, RuboCop clean.

Deviations & judgment calls

• The migration only takes effect once version.rb is 1.2.0. The registry has an upto: DocsKit::VERSION ceiling, so it starts applying when the release bumps the version. The specs call it directly and pass upto: "1.2.0" for the registry check.
• Auto-edits aren't printed. The Migration contract returns warnings only. The upgrade notes say to review the result with git diff.
• Ruby is warn-only. --sync can't pick a Ruby version for you. In practice bundle update already refuses docs-kit 1.2 on Ruby 3.2, which is why the notes say to move Ruby first.
• ## [Unreleased] stays unversioned. Rename it at release time (or tell me the version and I'll do it).

https://claude.ai/code/session_0198Mg9hhdrd7MAUa5DkMddi

---

Summary by cubic

Adds the first release migration to bin/rails g docs_kit:install --sync for upgrading a 1.1 site to 1.2, plus written upgrade notes. The migration raises the Bun and Tailwind/daisyUI floors that 1.1 scaffolded and warns about Ruby below 3.3 and deploy workflow pins off @main.

• A value is rewritten only when it is exactly what an older docs-kit generated; a hand-picked older value is warned about, and a newer value is left alone.
• The CHANGELOG gains an "Upgrading from 1.1" block, and entries shipped in 1.1.1 or earlier move under their own release heading.
• The README's migration section now lists a per-release table of what --sync does and what stays manual.
• The migration spec now requires the registry itself, so it runs standalone instead of only in the full suite.