An icon, a Check again that checks, and the auto-update rule written down

Three gaps found by being asked plain questions about it.

**The auto-update toggle was a promise nobody had checked.** offer_update()
answers even when the installed version is current, on the reasoning that the
answer has to land in WordPress's no_update list for the "Enable auto-updates"
link to exist at all. That was a comment and an intention; it is now an
assertion against the real WP_Plugins_List_Table, which is where the flag is
actually read:

    $plugin_data = array_merge( (array) $plugin_info->no_update[ $plugin_file ],
                               array( 'update-supported' => true ), $plugin_data );

A plugin in neither response nor no_update gets "Auto-updates are not available
for this plugin" while looking entirely healthy.

**An icon.** Without one, Dashboard → Updates shows a generic grey plug.
assets/icon.svg, handed over in the offer's icons key, served from the shop's
own copy rather than the release host — one fewer thing that must be reachable
for wp-admin to render, and it cannot go mixed content on an HTTPS shop. Drawn
as paths rather than <text>: an SVG that leans on a font renders differently on
every machine, and this one is shown at about 40px, which is the size where
that is the difference between a mark and a smudge.

**"Check again" now checks again.** The six-hour cache is right for the check
WordPress runs twice a day and wrong for a link whose whole promise is that it
looks now. Publishing a release and then clicking it showed nothing for up to
six hours, which reads exactly like a broken updater.

And docs/REUSE.md was missing all of this: it covered Update URI, where to
instantiate the updater and making the repo public, but not the one rule that
is genuinely easy to get wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/REUSE.md

@@ -52,6 +52,31 @@ and instantiate the updater **before** any "is WooCommerce active" gate — a
 shop with WooCommerce switched off for an afternoon must not quietly stop
 receiving fixes.
 
+Three things in that file are load-bearing and none of them look it:
+
+- 🔴 **`offer_update()` answers even when the installed version is already
+  current.** It is tempting to return `false` there — there is no update, after
+  all — and that one line is what silently removes the **Enable auto-updates**
+  link from the Plugins screen. `WP_Plugins_List_Table` sets
+  `update-supported` only for plugins it finds in the update transient's
+  `response` **or** `no_update` list; a plugin that stays silent is in neither,
+  and wp-admin says "Auto-updates are not available for this plugin." The
+  plugin looks perfectly configured and can never auto-update.
+  `tests/smoke.php` asserts the rendered table, not the intention.
+- **Set `icons`.** Without it Dashboard → Updates shows a generic grey plug.
+  Point it at the shop's own copy (`PLUGIN_URL . 'assets/icon.svg'`), not the
+  release host: one fewer thing that must be reachable for wp-admin to render,
+  and it cannot go mixed-content on an HTTPS shop.
+- **`Update URI` also switches wordpress.org off** for this plugin, from
+  WordPress 5.8. Remove the header and a .org plugin that happens to share the
+  slug could be pushed onto a shop running yours.
+
+The answer is cached for six hours, which is right for the check WordPress runs
+twice a day and wrong for the **Check again** link — so `forget_on_force_check()`
+drops the cache on `force-check`. Without it, someone who has just published a
+release clicks that link, sees nothing, and concludes the whole mechanism is
+broken.
+
 **6. Make the Gitea repository public**, or point `Update URI` at a separate
 public releases-only repository. Every shop reads that feed without
 credentials; `ci/publish-release.sh` fails the release with this instruction if
@@ -74,6 +99,9 @@ it cannot.
   credentials to prove a shop can download it.
 - `ci/update-smoke.sh` — install the previous version into a throwaway shop and
   let WordPress update it by itself. The only check that proves the whole chain.
+- Assertions that the **Enable auto-updates** link is actually offered, built
+  from the real `WP_Plugins_List_Table`, and that the update offer carries an
+  icon that exists in the release.
 - `ci/workflows-in-sync.sh` — fails when the two workflow roots drift, which is
   the only way to notice that a workflow stopped running on Gitea.
 

docs/TESTING-AND-RELEASES.md

@@ -155,11 +155,57 @@ That means all of this works with no extra code:
 
 - the update notice on **Plugins** and **Dashboard → Updates**
 - the **update now** link
-- the per-plugin **Enable auto-updates** link — WordPress builds that from the
-  plugins it has an answer for, which is why the updater answers even when the
-  installed version is already current
+- the per-plugin **Enable auto-updates** link
 - `wp plugin update woocommerce-email-discount-manager` over WP-CLI
 
+### Turning on automatic updates
+
+Plugins screen → the **Automatic updates** column on the right → **Enable
+auto-updates**. WordPress then installs new versions by itself on its
+twice-daily check.
+
+That link is not free for a plugin outside wordpress.org.
+`WP_Plugins_List_Table` marks a plugin as `update-supported` only if it finds
+it in the update transient's `response` list (an update is waiting) or its
+`no_update` list (we were asked, there is none):
+
+```php
+// wp-admin/includes/class-wp-plugins-list-table.php
+$plugin_data = array_merge( (array) $plugin_info->response[ $plugin_file ],  array( 'update-supported' => true ), $plugin_data );
+$plugin_data = array_merge( (array) $plugin_info->no_update[ $plugin_file ], array( 'update-supported' => true ), $plugin_data );
+} elseif ( empty( $plugin_data['update-supported'] ) ) {
+    $plugin_data['update-supported'] = false;
+```
+
+A plugin in neither list gets "Auto-updates are not available for this plugin"
+and no toggle — while looking entirely healthy otherwise. That is why
+`offer_update()` answers even when the installed version is already current:
+the answer lands in `no_update`, and the link stays. `tests/smoke.php` builds
+the real list table and asserts the flag rather than trusting the reasoning.
+
+### "Check again" really checks again
+
+The feed is cached for six hours. That is right for the check WordPress runs on
+its own twice a day, and wrong for a link whose entire promise is that it looks
+*now* — so the cache is dropped when wp-admin is loaded with `force-check`.
+Without that, publishing a release and then clicking **Check again** shows
+nothing for up to six hours, which reads exactly like a broken updater.
+
+From the command line, `wp transient delete wc_edm_release_feed` does the same.
+
+### The icon
+
+`assets/icon.svg`, handed to WordPress in the offer's `icons` key. Without it
+Dashboard → Updates shows a generic grey plug. WordPress takes the first of
+`svg`, `2x`, `1x`, `default` that is set.
+
+It is served from the shop's own copy of the plugin, not from the release host:
+one fewer thing that has to be reachable for wp-admin to render correctly, and
+it cannot go mixed-content on an HTTPS shop. The mark is drawn as paths rather
+than `<text>`, because an SVG that leans on a font renders differently
+everywhere — and this one is shown at about 40px, which is the size where that
+matters.
+
 `Update URI` earns its place a second way: since WordPress 5.8, a plugin that
 declares one is **never asked about on wordpress.org**. Without it, a .org
 plugin that happened to share this slug could be pushed onto a shop running