diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d361777
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-04-22
+
+First release published to [crates.io](https://crates.io/crates/termdown).
+
+### Added
+- Interactive TUI mode (`--tui`) with vim-style navigation, forward search
+  (`/`, `n`, `N`), Table of Contents panel (`t`), keyboard-shortcut help
+  overlay (`?`), link-follow navigation across Markdown files (`Enter`, `o`,
+  `i`), and Kitty-protocol heading images inside the TUI viewport.
+- Side-by-side README screenshots showing direct-render and TUI modes.
+- `repository`, `homepage`, `rust-version`, and `exclude` metadata in
+  `Cargo.toml` for the crates.io release.
+
+### Changed
+- Build, lint, format, and test now route through a shared `Makefile` that
+  CI and local workflows both invoke — no drift between environments.
+- README installation section leads with `cargo install termdown`.
+
+### Fixed
+- Markdown renderer: collapsed nested `if` into `match` guards, improving
+  readability and branch coverage.
+
+## [0.3.0] - prior to crates.io
+
+### Added
+- HTML block and inline HTML rendering in the Markdown pipeline.
+- Markdown feature coverage audit documenting supported/unsupported syntax.
+- GitHub Actions CI and auto-release workflows; cross-compilation support
+  for `aarch64-unknown-linux-gnu` via `cross`.
+- Install and uninstall shell scripts for prebuilt binary releases.
+
+### Fixed
+- Install `fontconfig` in the cross container so aarch64 builds succeed.
+- Rustfmt and system-deps issues on CI.
+
+## [0.2.0] - prior to crates.io
+
+### Added
+- Theme auto-detection (OSC 11) with explicit `--theme light|dark|auto`.
+- Task list checkbox rendering.
+- CLI integration tests and markdown edge-case tests.
+- Emoji fallback for image-rendered headings.
+- Architecture documentation.
+
+### Fixed
+- Nested list text loss in the Markdown renderer.
+
+## [0.1.0] - prior to crates.io
+
+Initial release: direct-output Markdown renderer with H1–H3 headings
+rasterized to PNG and painted via the Kitty graphics protocol.
+
+[0.4.0]: https://github.com/rrbe/termdown/releases/tag/v0.4.0
+[0.3.0]: https://github.com/rrbe/termdown/releases/tag/v0.3.0
+[0.2.0]: https://github.com/rrbe/termdown/releases/tag/v0.2.0
+[0.1.0]: https://github.com/rrbe/termdown/releases/tag/v0.1.0
diff --git a/Cargo.toml b/Cargo.toml
index 4e33cbf..c1c6483 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,6 +8,19 @@ readme = "README.md"
 authors = ["shawn <shineoutgx@gmail.com>"]
 keywords = ["markdown", "terminal", "kitty", "cli", "renderer"]
 categories = ["command-line-utilities", "text-processing"]
+repository = "https://github.com/rrbe/termdown"
+homepage = "https://github.com/rrbe/termdown"
+rust-version = "1.95"
+exclude = [
+    "CLAUDE.md",
+    "TODO.md",
+    "TEST_PLAN.md",
+    "docs/",
+    ".github/",
+    "install.sh",
+    "uninstall.sh",
+    "Cross.toml",
+]
 
 [dependencies]
 ab_glyph = "0.2"
diff --git a/README.md b/README.md
index 98aedf5..1ea6e58 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,8 @@ Render Markdown with large-font headings in the terminal using the Kitty graphic
 
 <table>
 <tr>
-<td><img src="docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown rendering the Chinese README" /></td>
-<td><img src="docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown --tui rendering the English README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown rendering the Chinese README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown --tui rendering the English README" /></td>
 </tr>
 </table>
 
@@ -26,7 +26,15 @@ H4-H6 headings always fall back to ANSI bold text.
 
 ## Installation
 
-### Install script
+### From crates.io (recommended, requires Rust)
+
+```sh
+cargo install termdown
+```
+
+Installs into `~/.cargo/bin/`. Requires Rust 1.95+.
+
+### Prebuilt binary (no Rust toolchain needed)
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/rrbe/termdown/master/install.sh | bash
@@ -51,14 +59,12 @@ sudo mv termdown /usr/local/bin/
 
 </details>
 
-### Install from source
+### From git (latest development snapshot)
 
 ```sh
 cargo install --git https://github.com/rrbe/termdown
 ```
 
-Installs into `~/.cargo/bin/`.
-
 ## Uninstall
 
 ```sh
diff --git a/README_CN.md b/README_CN.md
index 96f11e0..3d6fc1a 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -4,8 +4,8 @@
 
 <table>
 <tr>
-<td><img src="docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown 渲染中文 README" /></td>
-<td><img src="docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown --tui 渲染英文 README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_cn_demo.png" width="380" alt="termdown 渲染中文 README" /></td>
+<td><img src="https://raw.githubusercontent.com/rrbe/termdown/v0.4.0/docs/screenshots/termdown_render_en_tui_demo.png" width="380" alt="termdown --tui 渲染英文 README" /></td>
 </tr>
 </table>
 
diff --git a/TODO.md b/TODO.md
index 5cf9b71..9934d3b 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,3 +1,11 @@
 - [ ] 测试 html 标签支持
 - [ ] 图片支持
 - [ ] 长文本换行时缩进的处理
+<<<<<<< Updated upstream
+- [ ] 找出真实 MSRV 并下调 `rust-version`(当前 `1.95` 是跟本地对齐,触达面窄)
+  - 本地跑 `cargo install cargo-msrv && cargo msrv find`,二分出最低能编译的版本
+  - 同步更新 `Cargo.toml` 的 `rust-version` 和 `README.md` 里的 "Requires Rust X.Y+"
+  - 在 `.github/workflows/ci.yml` 加一个 `msrv` job(`cargo check --all-targets` on pinned toolchain),防止以后 PR 悄悄抬高 MSRV
+=======
+- [ ] 测试 markdown metadata 支持
+>>>>>>> Stashed changes