diff --git a/quantecon/.gitignore b/quantecon/.gitignore
index b82e852f3..de862353f 100644
--- a/quantecon/.gitignore
+++ b/quantecon/.gitignore
@@ -5,3 +5,4 @@
 *
 !.gitignore
 !README.md
+!VERSION.yml
diff --git a/quantecon/README.md b/quantecon/README.md
index f68e633e7..c721163c8 100644
--- a/quantecon/README.md
+++ b/quantecon/README.md
@@ -2,7 +2,19 @@
 
 This fork lets QuantEcon develop and use new `mystmd` features before they land in `jupyter-book/mystmd`. Features are developed on feature branches, squash-merged into this fork's `main`, and the same feature branches are kept alive so they can be opened as upstream PRs whenever the upstream team is ready to review them.
 
-> **About this folder.** `quantecon/` doubles as a local scratch space for planning docs, demo books, and experiments. Everything except this `README.md` is gitignored — feel free to drop PLAN docs, demo `myst.yml` projects, etc. here without worrying about accidental commits. To track something new intentionally, add it to the allow-list in [.gitignore](.gitignore).
+> **About this folder.** `quantecon/` doubles as a local scratch space for planning docs, demo books, and experiments. Everything except [`README.md`](README.md) and [`VERSION.yml`](VERSION.yml) is gitignored — feel free to drop PLAN docs, demo `myst.yml` projects, etc. here without worrying about accidental commits. To track something new intentionally, add it to the allow-list in [.gitignore](.gitignore).
+
+## Build identifier
+
+[`VERSION.yml`](VERSION.yml) records which QuantEcon-specific features are merged into this fork's `main`, identified by a `qe-vN` tag that's also a git tag on the corresponding squash-merge commit. It's a diagnostic/traceability artifact, not a release version — lecture builds can cat the file to log what fork state they're using.
+
+When landing a new feature:
+
+1. Squash-merge the feature PR into `main`
+2. Tag the resulting commit: `git tag qe-v<N+1> <sha> -m "qe-v<N+1>: feature/<name> merged via #<pr>"` then `git push origin qe-v<N+1>`
+3. Append the feature to `merged_features` in `VERSION.yml` and bump `qe_version`
+
+When upstream merges one of our features, update the entry's `upstream` block rather than deleting it — `VERSION.yml` doubles as an upstreaming tracker.
 
 ## How it works — the key idea
 
diff --git a/quantecon/VERSION.yml b/quantecon/VERSION.yml
new file mode 100644
index 000000000..72df520e9
--- /dev/null
+++ b/quantecon/VERSION.yml
@@ -0,0 +1,39 @@
+# QuantEcon mystmd build identifier
+#
+# This file is the canonical diagnostic record of which QuantEcon-specific
+# features are in this fork's `main`. The `qe_version` field corresponds to
+# a git tag of the same name on the commit that landed the latest feature.
+#
+# Update this file as part of the "land a feature" workflow:
+#   1. Squash-merge the feature PR into main
+#   2. Tag the resulting commit with the next `qe-vN`
+#   3. Append the feature to `merged_features` and bump `qe_version`
+#
+# When upstream merges one of our features, update its `upstream` block
+# rather than deleting the entry — the history is useful.
+
+qe_version: qe-v2
+upstream_base: 1.9.0
+
+merged_features:
+  - id: 1
+    name: myst-to-ipynb
+    description: CommonMark ipynb export + image attachment embedding
+    local_pr: 16
+    merge_sha: a045d57d
+    tag: qe-v1
+    upstream:
+      status: pending      # pending | open | merged
+      pr: null
+      merged_sha: null
+
+  - id: 2
+    name: book-numbering
+    description: Book-style numbering — format, label, section-tagged TOC, auto-prefix
+    local_pr: 22
+    merge_sha: 032957c2
+    tag: qe-v2
+    upstream:
+      status: pending
+      pr: null
+      merged_sha: null