docs: clarify mid vs mid2 offline license key compatibility (#5404) (#5424)

* docs: clarify mid vs mid2 offline license key compatibility

The download-offline-license Maven goal always generates a mid2 machine
ID, but Vaadin 24.9 and earlier only accept mid keys. This causes
confusing "Invalid offline key" errors.

Add a version compatibility table to the offline license section, a
warning that the Maven goal only works for Vaadin 25+, and improve the
related troubleshooting entry in the knowledge base.

* Apply suggestions from code review



---------

Co-authored-by: Marco Collovati <marco@vaadin.com>
Co-authored-by: Mikhail Shabarov <61410877+mshabarov@users.noreply.github.com>

Author: 3 people

articles/flow/configuration/licenses/index.adoc

@@ -105,6 +105,23 @@ If your local development environment is offline and can't reach `vaadin.com`, y
 
 Each offline license key is tied to the machine ID, in the form of `mid-xxxxxxxx-xxxxxxxx` (License Checker version 2 or earlier) or `mid2-xxxxxxxx-xxxxxxxx` (`V2` key, since License Checker version 3). You'll have to submit that to `https://vaadin.com/myaccount/licenses`, so as to download an offline license key.
 
+The machine ID format you need depends on your Vaadin version:
+
+[cols="1,1,1"]
+|===
+|Machine ID Format |Key File |Vaadin Version
+
+|`mid-xxxxxxxx-xxxxxxxx`
+|[filename]`offlineKey`
+|24.9 and earlier
+
+|`mid2-xxxxxxxx-xxxxxxxx`
+|[filename]`offlineKeyV2`
+|24.10 and later
+|===
+
+Using the wrong key type causes an "Invalid offline key" error. If you work with both old and new Vaadin versions, download both key types.
+
 Once you've downloaded the [filename]`offlineKey` or [filename]`offlineKeyV2` file -- remove any [filename]`.txt` suffix-- you should place it in your home directory:
 
 [.example]
@@ -135,6 +152,16 @@ You can find the URL to download the offline key in the logs when you try to use
 mvn com.vaadin:vaadin-maven-plugin:download-offline-license
 ----
 
+[IMPORTANT]
+====
+The `download-offline-license` goal is only available in the Vaadin 24.10+ Maven plugin and always generates a `mid2` machine ID. This key does not work with Vaadin 24.9 or earlier.
+
+For **Vaadin 24.9 or earlier** projects, you must obtain the `mid` machine ID manually:
+
+. Attempt to build or run your project with a commercial component while offline. The `mid` machine ID is printed in the build error output.
+. Use that `mid` machine ID to download the correct offline key from https://vaadin.com/myaccount/licenses.
+====
+
 
 [[server-license-key]]
 == Validation on CI/CD or Build Server

articles/flow/kb/index.adoc

@@ -140,8 +140,12 @@ Verify that you have a valid license by going to https://vaadin.com/myaccount/li
 .+++<h3>Invalid Offline Key</h3>+++
 [%collapsible]
 ====
-Either `offlineKey` is invalid or you are running License Checker 2 with a version 2 offline key (`mid2-xxxxxxxx-xxxxxxxx`).
-Go to https://vaadin.com/myaccount/licenses#offline-license-key and download and install a proper version 1 key.
+This error can occur in the following situations:
+
+- **Version mismatch**: The offline key type does not match your Vaadin version. Vaadin 24.10 and later require a `mid2` (v2) key, while Vaadin 24.9 and earlier require a `mid` (v1) key. For Vaadin 24.10 or later, run `mvn com.vaadin:vaadin-maven-plugin:download-offline-license` to obtain the `mid2` machine ID. For Vaadin 24.9 or earlier, obtain the `mid` machine ID from the build error output and download the correct key from https://vaadin.com/myaccount/licenses.
+- **Wrong key file**: The [filename]`offlineKey` or [filename]`offlineKeyV2` file contains an invalid or corrupted key.
+
+See <<{articles}/flow/configuration/licenses#offline-license-key,Offline License Key>> for details on which key type to use for your Vaadin version.
 ====
 
 // end::licenses[]