diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5688df3..4e840ae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-01
+
+Breaking: the selectors below build a different string than 1.0.0 did for the
+same input, so a suite that passed on 1.0.0 can fail on this version without
+changing a line.
+
+### Migrating from 1.0.0
+
+ - If you wrote a helper that normalized labels before handing them to
+   `table_cell_selector` / `table_header_selector` / `attributes_row_selector`,
+   delete it. The gem now makes the same `parameterize(separator: '_')` call
+   ActiveAdmin makes, so normalizing twice corrupts the result — the second
+   pass strips the `_` the first one inserted.
+ - Labels with no Latin-transliterable characters (`'Имя'`, `'名前'`, `'№'`)
+   now raise instead of silently matching every such row. Match on text, or
+   pass the attribute name.
+ - Rails 7.2 is no longer tested.
+
 ### Fixed
  - `attributes_table_selector`, `form_selector` and `table_selector` now ask the
    model for its DOM name (`model_name.singular` / `.plural`, the same source
@@ -52,8 +70,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  - `have_status_tag` matcher for status tag elements
 
 ### Changed
- - `within_sidebar` now scopes within the sidebar section directly using `ancestor`
- - `have_table_scope` now accepts an optional title as first positional argument and `selected:` keyword arg
+ - `have_table_scope` now accepts an optional title as first positional argument and `selected:` keyword arg.
+   **Breaking**, and not spelled out at the time: the `active:` key it replaced
+   is no longer consumed, so it falls through to `have_selector` and Capybara
+   rejects it with `ArgumentError: Invalid option(s) :active`. Rename
+   `active:` to `selected:`; the selector built is the same.
+ - `within_sidebar` now scopes within the sidebar section directly using `ancestor`.
+   **Breaking** for a block that relied on the old scope being the panel rather
+   than the whole `.sidebar_section`.
 
 ## [0.3.3] - 2020-04-17
 ### Changed
diff --git a/README.md b/README.md
index 4f3ecbc..f7359f4 100644
--- a/README.md
+++ b/README.md
@@ -94,6 +94,67 @@ end
 See `spec/support` for more user examples.
 See `capybara/active_admin/test_helpers.rb` for available DSL methods.
 
+## How labels become selectors
+
+Most helpers take the label you see on the page and build a CSS selector from
+it, because that is how ActiveAdmin names its own elements. Two derivations are
+worth knowing, since a mismatch shows up as "element not found" with no hint of
+why.
+
+### Column and row labels
+
+ActiveAdmin builds the class with `parameterize(separator: '_')` —
+`AttributesTable#row` and `TableFor::Column#html_class` — and so does this gem:
+
+| label | class ActiveAdmin renders |
+| --- | --- |
+| `'Full Name'` | `col-full_name` |
+| `:full_name` | `col-full_name` |
+| `'VAT / TAX Number'` | `col-vat_tax_number` |
+| `'E-mail'` | `col-e-mail` |
+| `"Customer's Name"` | `col-customer_s_name` |
+| `'# of DIDs'` | `col-of_dids` |
+
+So pass the label as it appears, and do **not** normalize it yourself first —
+doing it twice strips the separator the first pass inserted.
+
+Two cases have no class to match:
+
+```ruby
+# ActiveAdmin renders class="row" with no row-* at all when you give your own
+row :salary, class: 'money'
+
+# parameterize drops everything non-Latin, so AA renders a bare class="row row-"
+# for every such label and they cannot be told apart. The gem raises rather
+# than match the wrong one.
+row 'Имя'
+```
+
+Match on text in both cases, or pass the attribute name rather than the label.
+
+### Model and resource names
+
+`have_attributes_table(model:)` and `within_form_for` follow the **model
+class** — Arbre uses `model_name.singular`:
+
+```ruby
+have_attributes_table(model: Billing::Employee)     # div.attributes_table.billing_employee
+have_attributes_table(model: 'Billing::Employee')   # same
+```
+
+`have_table(resource_name:)` and `within_table_for` follow the name the
+resource was **registered** under, which `as:` detaches from the model:
+
+```ruby
+ActiveAdmin.register Billing::Employee, as: 'Business Employee'
+
+within_table_for('Business Employee') { ... }   # table#index_table_business_employees
+within_table_for(Billing::Employee)   { ... }   # table#index_table_billing_employees -- wrong
+```
+
+A renamed resource has to be addressed by its registered name; the class cannot
+know it.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
diff --git a/lib/capybara/active_admin/version.rb b/lib/capybara/active_admin/version.rb
index 8b540aa..7f25b26 100644
--- a/lib/capybara/active_admin/version.rb
+++ b/lib/capybara/active_admin/version.rb
@@ -2,6 +2,6 @@
 
 module Capybara
   module ActiveAdmin
-    VERSION = '1.0.0'
+    VERSION = '2.0.0'
   end
 end