Added connect instructions to improve UX

web/src/css/style.css

@@ -204,6 +204,11 @@ h2 {
     box-shadow: var(--shadow);
 }
 
+#step-connect-instructions .disclaimer {
+    color: var(--text-secondary);
+    font-size: 0.80rem;
+}
+
 #mode-patches-hint {
     margin-top: 15px;
 }
@@ -925,6 +930,41 @@ select + .fallback-hint {
     margin-top: 0;
 }
 
+/* Connection instruction steps with numbered accent circles */
+.connect-steps {
+    list-style: none;
+    margin: 0.5rem 0 1rem;
+    padding-left: 2.35rem;
+    counter-reset: connect-step;
+}
+
+.connect-steps li {
+    padding: 0.4rem 0;
+    font-size: 0.88rem;
+    color: var(--text-secondary);
+    line-height: 1.6;
+    counter-increment: connect-step;
+    position: relative;
+}
+
+.connect-steps li::before {
+    content: counter(connect-step);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.6rem;
+    height: 1.6rem;
+    border-radius: 50%;
+    background: var(--primary);
+    color: #fff;
+    font-size: 0.78rem;
+    font-weight: 700;
+    line-height: 1;
+    position: absolute;
+    left: -2.35rem;
+    top: calc(0.55rem - 4px);
+}
+
 .install-steps {
     margin: 0.25rem 0 0 1.25rem;
     font-size: 0.88rem;

web/src/index.html

@@ -124,6 +124,23 @@
             </p>
         </section>
 
+        <!-- Step 1a (auto): Connection instructions -->
+        <section id="step-connect-instructions" class="step" hidden>
+            <h2>Connect your Kobo</h2>
+            <p>Your Kobo's model and version number can be automatically identified. Based on this information, certain options will be presented to you as part of the next step.</p>
+            <ol class="connect-steps">
+                <li>Connect your Kobo to this computer using a USB cable.</li>
+                <li>Your Kobo will show a <strong>"Computer detected"</strong> screen. Tap <strong>Connect</strong> to continue.</li>
+                <li>In <span id="connect-file-manager">your file manager</span>, you should now see <strong>KOBOeReader</strong> appear as a drive.</li>
+                <li>When you press the button below, your browser will open a folder picker. Select the <strong>KOBOeReader</strong> volume, then click <strong>"Allow"</strong> when your browser asks if you want to give this site permission to write to this folder.</li>
+            </ol>
+            <p class="disclaimer"><strong>Anything else I should know?</strong> Information about your device is <b>never</b> collected, it is only displayed on this page, temporarily. This website will <b>only</b> write to your device when you press the "Write to Kobo" button when you're done with the wizard. (You also have the option to download an archive instead of writing everything to your device, when you're done with all steps.)</p>
+            <div class="step-actions">
+                <button id="btn-connect-instructions-back" class="secondary">&#x2039; Back</button>
+                <button id="btn-connect-ready" class="primary">Select "KOBOeReader"</button>
+            </div>
+        </section>
+
         <!-- Step 1b (manual): Select device model + firmware for custom patches -->
         <section id="step-manual-version" class="step" hidden>
             <p class="fallback-hint">

web/src/js/app.js

@@ -88,6 +88,7 @@ fetch('/koreader/release.json')
 // =============================================================================
 
 const stepConnect = $('step-connect');
+const stepConnectInstructions = $('step-connect-instructions');
 const stepManualVersion = $('step-manual-version');
 const stepDevice = $('step-device');
 const stepMode = $('step-mode');
@@ -95,6 +96,8 @@ const stepPatches = $('step-patches');
 const stepError = $('step-error');
 
 const btnConnect = $('btn-connect');
+const btnConnectReady = $('btn-connect-ready');
+const btnConnectInstructionsBack = $('btn-connect-instructions-back');
 const btnManual = $('btn-manual');
 const btnManualConfirm = $('btn-manual-confirm');
 const btnManualVersionBack = $('btn-manual-version-back');
@@ -334,8 +337,28 @@ function displayDeviceInfo(info) {
     $('device-firmware').textContent = info.firmware;
 }
 
-btnConnect.addEventListener('click', async () => {
+// Detect the platform-specific file manager name for the connection instructions.
+{
+    const fileManagerEl = $('connect-file-manager');
+    const ua = navigator.userAgent;
+    if (/Windows/.test(ua)) fileManagerEl.textContent = 'File Explorer';
+    else if (/Mac/.test(ua)) fileManagerEl.textContent = 'Finder';
+    else fileManagerEl.textContent = 'your file manager';
+}
+
+// "Connect my Kobo" shows the instructions step first (not the file picker).
+btnConnect.addEventListener('click', () => {
     track('flow-start', { method: 'connect' });
+    showStep(stepConnectInstructions);
+});
+
+// Back from instructions → connect step.
+btnConnectInstructionsBack.addEventListener('click', () => {
+    showStep(stepConnect);
+});
+
+// "Select KOBOeReader folder" opens the file picker and proceeds.
+btnConnectReady.addEventListener('click', async () => {
     try {
         const info = await state.device.connect();
 

web/src/js/nav.js

@@ -16,7 +16,7 @@ const stepNav = $('step-nav');
 // Every step <div> in the app, in DOM order.
 // Used by showStep() to hide all steps except the active one.
 const allSteps = [
-    $('step-connect'), $('step-manual-version'), $('step-device'),
+    $('step-connect'), $('step-connect-instructions'), $('step-manual-version'), $('step-device'),
     $('step-mode'), $('step-nickelmenu'), $('step-nm-features'),
     $('step-nm-review'), $('step-nm-installing'), $('step-nm-done'),
     $('step-patches'), $('step-firmware'), $('step-building'), $('step-done'),