diff --git a/packages/zapier/CHANGELOG.md b/packages/zapier/CHANGELOG.md
new file mode 100644
index 0000000..b73a45a
--- /dev/null
+++ b/packages/zapier/CHANGELOG.md
@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.1.0
+
+Fixes the **Base** dropdown, which had started coming back empty and made it
+impossible to set up a new Zap.
+
+**Please reconnect your Teable account.** Teable tightened how permissions are
+granted to connected apps, and connections made before this release are missing
+the permission needed to list your bases. Reconnecting takes a few seconds, and
+your existing Zaps keep running in the meantime — only setting up or editing a
+Zap was affected.
+
+1. Fix the empty Base dropdown in trigger/new_record and trigger/new_or_updated_record
+2. Fix the empty Base dropdown in create/create_record, create/update_record, create/create_or_update_record and create/delete_record
+3. Fix the empty Base dropdown in search/find_record and search/find_record_by_id
+4. Update the Base dropdown to ask you to reconnect when the connection lacks permission, instead of showing an empty list with no explanation
+
+## 1.0.0
+
+Initial release to public.
diff --git a/packages/zapier/README.md b/packages/zapier/README.md
index c1fe364..286bc82 100644
--- a/packages/zapier/README.md
+++ b/packages/zapier/README.md
@@ -119,20 +119,26 @@ the full sequence; `push` alone leaves everyone on the old version.
 
 ```bash
 npx zapier-platform versions               # confirm state + Zap Users
+# add a `## <newversion>` section to CHANGELOG.md   <- promote fails without it
 # bump version in package.json, merge -> CI pushes the new version
 
-npx zapier-platform env:get <newversion>   # ← DO NOT SKIP (see below)
+npx zapier-platform env:get <newversion>   # confirm the three vars carried over
 npx zapier-platform promote <newversion>   # new users get it from here on
 npx zapier-platform migrate <old> <new> 100%   # move the users who already exist
+npx zapier-platform jobs                   # migration is async, 5-10 min
 ```
 
-Two traps, both silent:
-
-- **Env is per-version and does not follow a version bump.** A same-version push
-  preserves it, a new version starts from whatever is (not) set. Promoting a
-  version with no `CLIENT_ID` breaks OAuth for everyone, far worse than whatever
-  you were fixing. Always `env:get` first, and `env:set` the three vars if it
-  comes back empty.
+Three things that are easy to get wrong:
+
+- **`promote` refuses to run without a `CHANGELOG.md` entry for the version.**
+  It is a hard failure, and the changelog is user-facing — Zapier shows it to
+  people using the integration. Zapier parses lines starting with `Update` or
+  `Fix` and links identifiers of the form `<trigger|create|search>/<key>`, so
+  name the operations you actually touched.
+- **Env is per-version.** A push does carry the current values onto the new
+  version (verified on the 1.0.0 → 1.1.0 release), but it is worth one
+  `env:get` before promoting anyway: promoting a version with no `CLIENT_ID`
+  breaks OAuth for everyone, which is far worse than whatever you were fixing.
 - **`promote` does not move existing users** — it only decides what new users
   install. Without `migrate`, everyone already on the old version stays there,
   which usually means they never receive the fix you just shipped.