docs: make the README describe the script that exists

With the simulation gate implemented, the safety model section is now
true, and says where the gate runs (inside convert, immediately before
the install) and what it writes. Plan mode is labelled advisory, because
that is what it is: it logs a simulation for a human to read and decides
nothing.

Removed four options the README documented that were never implemented:
--no-auto-fix, --overwrite-keyring, --recreate-keyring and
--no-purge-flavor. Documented --preserve-snap, which was implemented and
missing. Every flag now matches the parser in both directions.

Two troubleshooting sections described behaviour that does not exist.
Keyring recovery pointed at the two missing keyring flags; the real
mechanism is a check against the expected Mint key ID with --yes to
overwrite, which is worth stating since it is what makes the plain-HTTP
fallback safe. Flavor-package purging was never written, so the login
loop it referred to is now described as something to fix by hand.

Also removes --no-install-recommends from the usage text, which I added
in the previous commit believing it was a script flag. It is an apt
option inside apt_opts_common; the parser rejects it. That is the same
class of error this commit exists to fix, found by checking the flag
lists against the parser in both directions rather than trusting either.

README.md

@@ -29,8 +29,8 @@ This project is intended for experienced Linux admins who understand APT, repo p
   - Mint desktop stack is pinned high to avoid mixed-version dependency breakage
 - Includes guardrails:
   - APT/dpkg lock detection
-  - best-effort dpkg/apt repair (`--no-auto-fix` to disable)
+  - best-effort dpkg/apt repair (always on; there is no flag to disable it)
-  - simulation plan + safety checks (removal thresholds + critical package protection)
+  - a pre-install APT simulation that aborts on critical-package removal or too many removals
   - disables third-party sources by default (with allowlist heuristics for common corp repos)
   - backup + rollback support
   - post-conversion validation report written into the backup directory
@@ -82,6 +82,12 @@ It creates a **temporary Mint keyring** by downloading and extracting the `linux
 
 > Plan mode is for decision support. It does not modify `/etc/apt` or install Mint repos onto your live system.
 
+Plan mode is **advisory** — it writes the simulation to a log for you to
+read and does not decide anything. The check that can actually stop a
+conversion is the gate inside `convert` (see [Safety model](#safety-model-important)),
+which runs its own simulation against your real APT configuration
+immediately before installing.
+
 ### 3) Run conversion
 
 ```bash
@@ -117,7 +123,7 @@ After conversion:
 ## Usage
 
 ```text
-sudo bash ubuntu-to-mint-convert-v3.sh doctor [--no-auto-fix]
+sudo bash ubuntu-to-mint-convert-v3.sh doctor
 sudo bash ubuntu-to-mint-convert-v3.sh plan [options]
 sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk [options]
 sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS
@@ -152,27 +158,20 @@ sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYY
   Allow installation of recommended packages (default: off for safety).
 
 * `--max-removals N`
-  Abort if APT simulation removes more than N packages (default: `40`).
+  Abort if the pre-install simulation would remove more than N packages
+  (default: `40`). Critical packages abort regardless of this number.
+
+* `--preserve-snap`
+  Keep `snapd` and reinstall it after the Mint stack (this is the default).
 
 * `--yes`
-  Skip most interactive prompts.
+  Skip most interactive prompts, and allow overwriting an existing Mint
-  (Does **not** bypass the `convert` disclaimer gate or `--i-accept-the-risk` requirement.)
+  keyring that does not match the expected key.
+  (Does **not** bypass the `convert` disclaimer gate or `--i-accept-the-risk`.)
 
-* `--no-auto-fix`
+> There is no flag to disable the dpkg/apt repair pre-flight — it always
-  Disable best-effort dpkg/apt repair pre-flight.
+> runs. Nor is there flavor-package purging; if a conflicting Ubuntu flavor
-
+> meta-package causes a login loop, remove it by hand.
-### Keyring handling
-
-* `--overwrite-keyring`
-  If `/usr/share/keyrings/linuxmint-repo.gpg` exists, overwrite it.
-
-* `--recreate-keyring`
-  Back up and delete the keyring then recreate it.
-
-### Flavor / meta package conflict handling
-
-* `--no-purge-flavor`
-  Disable best-effort purging of conflicting Ubuntu flavor packages (e.g., `ubuntucinnamon-*`) that can cause session crashes/login loops.
 
 
 
@@ -182,12 +181,15 @@ Guardrails included to reduce “brick your system” outcomes:
 
 * Refuses to run unless on supported Ubuntu bases
 * Detects and blocks active APT/dpkg locks
-* Attempts to repair basic dpkg/apt broken states (unless `--no-auto-fix`)
+* Attempts to repair basic dpkg/apt broken states before doing anything else
 * Disables PPAs by default during conversion (unless `--keep-ppas`)
-* Runs an APT simulation and aborts if:
+* Runs an APT simulation **during `convert`, immediately before the real install**, and aborts if:
 
-  * APT wants to remove critical packages (e.g., `sudo`, `systemd`, `network-manager`, kernel meta packages)
+  * APT wants to remove a critical package — `sudo`, `systemd`, `libc6`, `apt`, `dpkg`, `network-manager`, `grub-*`, the kernel meta packages, `openssh-server`. There is no threshold at which removing these is acceptable, so any hit aborts outright.
-  * too many removals are detected (default threshold `40`)
+  * more than `--max-removals` packages would be removed (default `40`)
+  * APT cannot resolve the install at all
+
+  Nothing is installed when the gate trips. The full simulation is written to `/var/log/ubuntu-to-mint/simulate-YYYYMMDD-HHMMSS.txt`.
 * Creates a backup directory for rollback
 * Post-conversion validation writes a report into the backup directory (always created)
 
@@ -269,15 +271,27 @@ This version avoids keyservers by default. It prefers:
 * a locally installed `linuxmint-keyring` package, or
 * downloading the latest `linuxmint-keyring_*.deb` from the Mint mirror and extracting the keyring
 
-If your existing keyring is corrupt:
+The extracted key is checked against the expected Mint key ID
+(`A6616109451BBBF2`) and the run aborts if it is not present, so a
+substituted keyring fails rather than being trusted.
 
-* rerun with `--recreate-keyring` or `--overwrite-keyring`
+If your existing keyring does not match, the script stops and tells you to
+either re-run with `--yes` to overwrite it, or delete
+`/usr/share/keyrings/linuxmint-repo.gpg` by hand and re-run.
 
 ### Known dpkg overwrite conflict (mintupdate)
 
-Some environments will hit a file conflict between `mintupdate` and `software-properties-gtk`
+Some environments hit a file conflict between `mintupdate` and
-over an icon file. The script installs the Mint stack with a guarded dpkg overwrite option
+`software-properties-gtk` over an icon file. The script applies a dpkg
-to prevent conversion from halting.
+diversion for that file before installing, and retries the install once
+with remediation if it still fails.
+
+### Login loop after conversion
+
+A leftover Ubuntu flavor meta-package (`ubuntucinnamon-desktop` and
+friends) can fight the Mint session and produce a login loop. The script
+does **not** purge these — check for them from a TTY and remove them
+manually if the desktop will not start.
 
 ### Corporate VPN/EDR breaks
 

ubuntu-to-mint-convert-v3.sh

@@ -169,7 +169,6 @@ Options:
   --keep-ppas                      Do not disable third-party sources (not recommended)
   --preserve-snap                  Keep snapd (default: enabled)
   --with-recommends                Allow recommended packages (default: off)
-  --no-install-recommends          Force --no-install-recommends (this is the default)
   --max-removals N                 Abort if the simulation removes more than N
                                    packages (default: ${MAX_REMOVALS})
   --yes                            Non-interactive / auto-confirm