diff --git a/.github/workflows/swift.yml b/.github/workflows/swift.yml
new file mode 100644
index 0000000..40b9e3f
--- /dev/null
+++ b/.github/workflows/swift.yml
@@ -0,0 +1,30 @@
+name: Swift
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: swift test (macOS)
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Select Xcode 15
+        run: sudo xcode-select -s /Applications/Xcode_15.4.app
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Build
+        run: swift build -v
+
+      - name: Test
+        run: swift test -v
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..eb941e3
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to HeatmapKit are documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] — 2026-05-01
+
+### Added
+- `.fitToWidth(minCellSize:)` — width-aware adaptive layout. Cells size to the container between `minCellSize` and `cellSize`; scroll fallback engages only when even the floor doesn't fit. Narrow renders snap to whole-week boundaries via `.scrollTargetBehavior(.viewAligned)` ([#8](https://github.com/jacklv-coder/HeatmapKit/pull/8)).
+- Runnable iOS demo app under `Demo/HeatmapKitDemo` — palette switching, tooltips, accessibility labels, share button via `snapshot(scale:background:)` ([#5](https://github.com/jacklv-coder/HeatmapKit/pull/5)).
+- Boards tab in the demo — Streaks-style habit cards built on `CalendarHeatmap` ([#9](https://github.com/jacklv-coder/HeatmapKit/pull/9)).
+
+### Changed
+- Built-in `.green` palette now mirrors github.com light/dark variants exactly; the other five palettes also pick up adaptive light/dark shades ([#6](https://github.com/jacklv-coder/HeatmapKit/pull/6)).
+- `todayHighlightColor` now defaults to `nil` (no outline), matching github.com. Opt back in with `.todayHighlightColor(.primary)` ([#7](https://github.com/jacklv-coder/HeatmapKit/pull/7)).
+
+### Fixed
+- Adaptive heatmap now sizes to actual content height, eliminating dead vertical space when `fitToWidth` is active ([#10](https://github.com/jacklv-coder/HeatmapKit/pull/10)).
+
+## [0.4.0] — 2026-04-30
+
+### Added
+- `.snapshot(scale:background:)` — renders the full grid (without its scroll wrapper) to a `CGImage`, ready for `ShareLink`, `Image(decorative:scale:)`, `UIImage(cgImage:)`, or `CGImageDestination` ([#4](https://github.com/jacklv-coder/HeatmapKit/pull/4)).
+
+## [0.3.0] — 2026-04-30
+
+### Added
+- Built-in detail tooltip on tap, customizable via `.tooltipOnTap { date, value in … }`. Tap the same cell again — or outside — to dismiss ([#3](https://github.com/jacklv-coder/HeatmapKit/pull/3)).
+
+## [0.2.0] — 2026-04-30
+
+### Added
+- Per-cell VoiceOver labels via `.accessibilityCellLabel { date, value in … }` ([#2](https://github.com/jacklv-coder/HeatmapKit/pull/2)).
+
+## [0.1.0] — 2026-04-30
+
+### Added
+- Initial release: `CalendarHeatmap` core — 7×N grid, horizontal scroll, 6 palettes (`.green`, `.orange`, `.blue`, `.purple`, `.red`, `.grayscale`), custom thresholds, tap callback, today highlight, locale-aware month/weekday labels.
+- Key-path initializer `CalendarHeatmap(data:dateKey:valueKey:aggregation:)` for arbitrary value types, with `.sum` / `.count` / `.max` / `.min` / `.average` aggregation.
+
+[0.5.0]: https://github.com/jacklv-coder/HeatmapKit/releases/tag/v0.5.0
+[0.4.0]: https://github.com/jacklv-coder/HeatmapKit/releases/tag/v0.4.0
+[0.3.0]: https://github.com/jacklv-coder/HeatmapKit/releases/tag/v0.3.0
+[0.2.0]: https://github.com/jacklv-coder/HeatmapKit/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jacklv-coder/HeatmapKit/releases/tag/v0.1.0
diff --git a/README.md b/README.md
index 9bd3bef..2efcefc 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
 
 > A modern SwiftUI calendar heatmap and contribution graph component — visualize time-series data the way GitHub shows your contributions.
 
+[![CI](https://github.com/jacklv-coder/HeatmapKit/actions/workflows/swift.yml/badge.svg)](https://github.com/jacklv-coder/HeatmapKit/actions/workflows/swift.yml)
 [![Swift](https://img.shields.io/badge/Swift-5.9+-orange.svg)](https://swift.org)
 [![Platforms](https://img.shields.io/badge/Platforms-iOS%2017%20%7C%20macOS%2014%20%7C%20watchOS%2010%20%7C%20tvOS%2017%20%7C%20visionOS%201-blue.svg)](https://github.com/jacklv-coder/HeatmapKit)
 [![SwiftPM](https://img.shields.io/badge/SwiftPM-Compatible-brightgreen.svg)](https://swift.org/package-manager)
@@ -15,8 +16,7 @@ Most existing heatmap libraries for Apple platforms target UIKit and have not be
 
 - 🍎 **Pure SwiftUI** — declarative API, no UIKit bridging
 - 📅 **Calendar heatmap** — GitHub-style 7×N grid, perfect for contributions / habits / activity
-- ↔️ **Horizontal scrolling** — long ranges scroll naturally; default-anchors to the most recent week
-- 📐 **Fit-to-width layout** — opt-in `.fitToWidth(minCellSize:)` adapts cell size to the container, only scrolling when even the floor doesn't fit
+- 📐 **Adaptive layout** — opt-in `.fitToWidth(minCellSize:)` sizes cells to the container; falls back to horizontal scrolling (anchored to the most recent week) when even the floor doesn't fit
 - 🎨 **6 built-in palettes** with auto light / dark variants (green mirrors github.com), plus full custom-color support
 - ⚖️ **Auto or custom thresholds** — let HeatmapKit bucket values from `data.max()`, or supply your own cutoffs
 - 🌍 **Localized labels** — month/weekday labels follow `Calendar.current.locale`
@@ -45,7 +45,7 @@ Add the dependency in `Package.swift`:
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/jacklv-coder/HeatmapKit", from: "0.1.0")
+    .package(url: "https://github.com/jacklv-coder/HeatmapKit", from: "0.5.0")
 ]
 ```
 
@@ -229,6 +229,16 @@ struct ShareableHeatmap: View {
 
 Issues and pull requests are welcome. The project is in its early days, so feedback on API shape is especially valuable.
 
+## Acknowledgements
+
+- The visual language — 7-row grid, light/dark palette, today outline behavior — is patterned on [GitHub's contribution graph](https://github.blog/2013-01-07-introducing-contributions/).
+- The Boards tab in the demo app is inspired by the habit-tracking UI of [Streaks](https://streaksapp.com).
+- Thanks to everyone filing issues and feedback during the 0.x series.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
 ## License
 
 [MIT](LICENSE) © 2026 jacklv-coder