From dc8b9d84bee6a116e4738f9588fde6caa6297d8b Mon Sep 17 00:00:00 2001
From: Brian <brian@brianhaas.li>
Date: Sat, 31 Jan 2026 11:56:23 +0100
Subject: [PATCH 1/2] Clarify TOTP setup instructions - draft

---
 providers/class-two-factor-totp.php | 34 +++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 7 deletions(-)

diff --git a/providers/class-two-factor-totp.php b/providers/class-two-factor-totp.php
index b5286fdc..63d77918 100644
--- a/providers/class-two-factor-totp.php
+++ b/providers/class-two-factor-totp.php
@@ -289,8 +289,19 @@ public function user_two_factor_options( $user ) {
 
 			?>
 			<p>
-				<?php esc_html_e( 'Please scan the QR code or manually copy the shared secret key from below to your Authenticator app:', 'two-factor' ); ?>
-			</p>
+                <?php esc_html_e( 'Please follow these steps in order to complete setup:', 'two-factor' ); ?>
+            </p>
+
+            <ol class="totp-steps">
+                <li>
+                    <?php esc_html_e( 'Install an authenticator app on your desktop/laptop and/or phone. Popular examples are Microsoft Authenticator, Google Authenticator and Authy.', 'two-factor' ); ?>
+                </li>
+                <li>
+                    <?php esc_html_e( 'Scan this QR code using the app you installed:', 'two-factor' ); ?>
+                    <?php /* QR image intentionally omitted. */ ?>
+                </li>
+            </ol>
+
 			<p id="two-factor-qr-code">
 				<a href="<?php echo esc_url( $totp_url ); ?>">
 					<?php esc_html_e( 'Loading…', 'two-factor' ); ?>
@@ -341,12 +352,21 @@ public function user_two_factor_options( $user ) {
 			</script>
 
 			<p>
-				<?php esc_html_e( 'Shared secret key:', 'two-factor' ); ?> <code><?php echo esc_html( $key ); ?></code>
-			</p>
+                <?php
+                    esc_html_e(
+                        'If scanning isn’t possible or doesn’t work, use the secret key shown below to manually add the account to your chosen app:',
+                        'two-factor'
+                    );
+                ?>
+                <br />
+                <code><?php echo esc_html( $key ); ?></code>
+            </p>
 			<hr />
-			<p>
-				<?php esc_html_e( 'Enter the code generated by the Authenticator app to complete the setup:', 'two-factor' ); ?>
-			</p>
+            <ol class="totp-steps" start="3">
+                <li>
+                    <?php esc_html_e( 'Enter the code generated by the Authenticator app to complete the setup:', 'two-factor' ); ?>
+                </li>
+            </ol>
 			<p>
 				<input type="hidden" id="two-factor-totp-key" name="two-factor-totp-key" value="<?php echo esc_attr( $key ); ?>" />
 				<label for="two-factor-totp-authcode">

From 3604e2dcc80e188c7dcdb2b5744d18211808dc17 Mon Sep 17 00:00:00 2001
From: Brian <brian@brianhaas.li>
Date: Mon, 9 Feb 2026 20:08:15 +0100
Subject: [PATCH 2/2] rework semantic

---
 providers/class-two-factor-totp.php | 37 ++++++++++++++---------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/providers/class-two-factor-totp.php b/providers/class-two-factor-totp.php
index 0babc980..4ac39655 100644
--- a/providers/class-two-factor-totp.php
+++ b/providers/class-two-factor-totp.php
@@ -323,16 +323,26 @@ public function user_two_factor_options( $user ) {
                 </li>
                 <li>
                     <?php esc_html_e( 'Scan this QR code using the app you installed:', 'two-factor' ); ?>
-                    <?php /* QR image intentionally omitted. */ ?>
+
+                    <p id="two-factor-qr-code">
+                        <a href="<?php echo esc_url( $totp_url, array( 'otpauth' ) ); ?>">
+                            <?php esc_html_e( 'Loading…', 'two-factor' ); ?>
+                            <img src="<?php echo esc_url( admin_url( 'images/spinner.gif' ) ); ?>" alt="" />
+                        </a>
+                    </p>
+
+                    <p>
+                        <?php
+                            esc_html_e(
+                                'If scanning isn’t possible or doesn’t work, use the secret key shown below to manually add the account to your chosen app:',
+                                'two-factor'
+                            );
+                        ?>
+                        <br />
+                        <code><?php echo esc_html( $key ); ?></code>
+                    </p>
                 </li>
             </ol>
-
-			<p id="two-factor-qr-code">
-				<a href="<?php echo esc_url( $totp_url, array( 'otpauth' ) ); ?>">
-					<?php esc_html_e( 'Loading…', 'two-factor' ); ?>
-					<img src="<?php echo esc_url( admin_url( 'images/spinner.gif' ) ); ?>" alt="" />
-				</a>
-			</p>
 			<style>
 				#two-factor-qr-code {
 					/* The size of the image will change based on the length of the URL inside it. */
@@ -375,17 +385,6 @@ public function user_two_factor_options( $user ) {
 					}
 				})();
 			</script>
-
-			<p>
-                <?php
-                    esc_html_e(
-                        'If scanning isn’t possible or doesn’t work, use the secret key shown below to manually add the account to your chosen app:',
-                        'two-factor'
-                    );
-                ?>
-                <br />
-                <code><?php echo esc_html( $key ); ?></code>
-            </p>
 			<hr />
             <ol class="totp-steps" start="3">
                 <li>