diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..46baf69
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are listed here. Versions follow [Semantic Versioning](https://semver.org/).
+
+## [0.2.0](https://github.com/empty-sekai/ournotes-boxlens/compare/v0.1.0...v0.2.0) - 2026-10-04
+
+### Features
+
+- Add list-screen scene generator ([5233918](https://github.com/empty-sekai/ournotes-boxlens/commit/52339188ca5416cdb551f20eceb98cd477c140fe))
+- Add card-frame locator ([3dc4d79](https://github.com/empty-sekai/ournotes-boxlens/commit/3dc4d79fb76f925732a84484c5d2e9b78aa676bd))
+- Add per-kind open-set artwork encoders ([37ad3e5](https://github.com/empty-sekai/ournotes-boxlens/commit/37ad3e58429d911ac1976053f11e1a6f44bae102))
+- Add per-kind field and card-rank readers ([2a8f363](https://github.com/empty-sekai/ournotes-boxlens/commit/2a8f363d723bb11845dbfffdeae33d6a6abfc5ed))
+- Scan with the neural locator, per-kind encoders and field readers ([168e031](https://github.com/empty-sekai/ournotes-boxlens/commit/168e0318176c85093f8152eff034f70df0d18e8b))
+
+### Documentation
+
+- Document the 0.2.0 models, training data and evaluation ([348da8d](https://github.com/empty-sekai/ournotes-boxlens/commit/348da8d6a440c488b876df6704ad556432a2c9d0))
+
+### Other changes
+
+- Connect BoxLens review to version-bound Deck R3 recommendations ([6d3326d](https://github.com/empty-sekai/ournotes-boxlens/commit/6d3326da2a2e7ca9c041ca1add59ec83e18ac668))
+- Bind reviewed inventories across CLI and HTTP workspace reuse ([a0fb7b7](https://github.com/empty-sekai/ournotes-boxlens/commit/a0fb7b786eb9e2e91336c1ac1856d767266cb668))
+
+## [0.1.0](https://github.com/empty-sekai/ournotes-boxlens/releases/tag/v0.1.0) - 2026-09-27
+
+### Other changes
+
+- Prepare clean v0.1.0 release source ([2ea25d8](https://github.com/empty-sekai/ournotes-boxlens/commit/2ea25d8e2fdcbd3d1514b101a13b34d3e70d2ff1))
+
+
diff --git a/MANIFEST.in b/MANIFEST.in
index 038aea3..60506f1 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1 +1,2 @@
 include docs/DECK_PIPELINE.md
+include CHANGELOG.md
diff --git a/README.md b/README.md
index b17a4e9..418dd2f 100644
--- a/README.md
+++ b/README.md
@@ -83,3 +83,11 @@ python -m unittest discover -s tests -p "test_*.py"
 涵盖模型清单校验、跨图合并、同名不同来源、冲突保存、隐藏字段及裁切字段／图标等数据完整性回归。
 
 可用 `python -m pip install -e ".[test]"` 安装开发入口和 Schema 校验依赖，再执行 `python scripts/validate_contract.py box result/box.json`。安装后提供 `ournotes-boxlens` 命令，参数与 `python boxvision.py` 相同。
+
+## 版本记录
+
+每个版本的改动见 [CHANGELOG.md](CHANGELOG.md)，由 [git-cliff](https://git-cliff.org/) 根据提交（Conventional Commits）生成。发版时，改版本号的那个提交同时重新生成它：
+
+```bash
+git cliff --tag vX.Y.Z -o CHANGELOG.md
+```
diff --git a/cliff.toml b/cliff.toml
new file mode 100644
index 0000000..f66df99
--- /dev/null
+++ b/cliff.toml
@@ -0,0 +1,66 @@
+# git-cliff configuration: release notes and changelog from conventional commits.
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project are listed here. Versions follow [Semantic Versioning](https://semver.org/).\n
+"""
+body = """
+{%- macro commit_link(id) -%}
+[{{ id | truncate(length=7, end="") }}](https://github.com/empty-sekai/ournotes-boxlens/commit/{{ id }})
+{%- endmacro -%}
+{% if version %}\
+    {% if previous.version %}\
+        ## [{{ version | trim_start_matches(pat="v") }}](https://github.com/empty-sekai/ournotes-boxlens/compare/{{ previous.version }}...{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% else %}\
+        ## [{{ version | trim_start_matches(pat="v") }}](https://github.com/empty-sekai/ournotes-boxlens/releases/tag/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+    {% endif %}\
+{% else %}\
+    ## Unreleased
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}**{{ commit.scope }}:** {% endif %}\
+          {% if commit.breaking %}[**breaking**] {% endif %}\
+          {{ commit.message | upper_first }} ({{ self::commit_link(id=commit.id) }})\
+    {% endfor %}
+{% endfor %}\n
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+# The commits from before Conventional Commits were adopted are listed under "Other changes".
+filter_unconventional = false
+split_commits = false
+protect_breaking_commits = true
+filter_commits = false
+tag_pattern = "v[0-9].*"
+topo_order = false
+sort_commits = "oldest"
+commit_preprocessors = [
+    # link issue / pull request numbers
+    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/empty-sekai/ournotes-boxlens/issues/${2}))" },
+]
+commit_parsers = [
+    { message = "^Merge ", skip = true },
+    { message = "^feat", group = "<!-- 00 -->Features" },
+    { message = "^fix", group = "<!-- 01 -->Bug fixes" },
+    { message = "^perf", group = "<!-- 02 -->Performance" },
+    { message = "^refactor", group = "<!-- 03 -->Refactoring" },
+    { message = "^doc", group = "<!-- 04 -->Documentation" },
+    { message = "^test", group = "<!-- 05 -->Tests" },
+    { message = "^build", group = "<!-- 06 -->Build" },
+    { message = "^ci", group = "<!-- 07 -->CI" },
+    { message = "^chore\\(release\\)", skip = true },
+    { message = "^chore: release ", skip = true },
+    { message = "^chore", group = "<!-- 08 -->Miscellaneous" },
+    { message = "^style", group = "<!-- 08 -->Miscellaneous" },
+    { message = "^revert", group = "<!-- 09 -->Reverts" },
+    { body = ".*security", group = "<!-- 10 -->Security" },
+    { message = ".*", group = "<!-- 11 -->Other changes" },
+]