From 3d414b4aeb01ee914ac4727133c601063aee2e15 Mon Sep 17 00:00:00 2001
From: Rephl3x <zak.bearman@amslabs.net>
Date: Sat, 24 Jan 2026 19:15:43 +1300
Subject: [PATCH] Clarify how-it-works steps and fixes

---
 frontend/app/globals.css           | 85 ++++++++++++++++++++++++++++++
 frontend/app/how-it-works/page.tsx | 82 +++++++++++++++++++---------
 2 files changed, 141 insertions(+), 26 deletions(-)

diff --git a/frontend/app/globals.css b/frontend/app/globals.css
index 7156834..a7a71a1 100644
--- a/frontend/app/globals.css
+++ b/frontend/app/globals.css
@@ -1496,6 +1496,91 @@ button span {
   border: 1px solid var(--border);
 }
 
+.how-step-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+}
+
+.how-step-card {
+  border-radius: 18px;
+  padding: 18px;
+  border: 1px solid var(--border);
+  background: rgba(255, 255, 255, 0.06);
+  display: grid;
+  gap: 10px;
+  position: relative;
+  overflow: hidden;
+}
+
+.how-step-card::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  opacity: 0.35;
+  pointer-events: none;
+}
+
+.step-jellyseerr::before {
+  background: linear-gradient(135deg, rgba(255, 187, 92, 0.35), transparent 60%);
+}
+
+.step-arr::before {
+  background: linear-gradient(135deg, rgba(94, 204, 255, 0.35), transparent 60%);
+}
+
+.step-prowlarr::before {
+  background: linear-gradient(135deg, rgba(120, 255, 189, 0.35), transparent 60%);
+}
+
+.step-qbit::before {
+  background: linear-gradient(135deg, rgba(255, 133, 200, 0.35), transparent 60%);
+}
+
+.step-jellyfin::before {
+  background: linear-gradient(135deg, rgba(170, 140, 255, 0.35), transparent 60%);
+}
+
+.step-badge {
+  width: 38px;
+  height: 38px;
+  border-radius: 50%;
+  display: grid;
+  place-items: center;
+  font-weight: 700;
+  background: rgba(255, 255, 255, 0.12);
+  border: 1px solid var(--border);
+  color: var(--ink);
+}
+
+.step-note {
+  color: var(--ink-muted);
+  font-size: 14px;
+}
+
+.step-fix-title {
+  font-size: 13px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--ink-muted);
+}
+
+.step-fix-list {
+  list-style: none;
+  display: grid;
+  gap: 6px;
+  padding: 0;
+  margin: 0;
+}
+
+.step-fix-list li {
+  padding: 8px 10px;
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.08);
+  border: 1px solid var(--border);
+  font-size: 13px;
+}
+
 .how-callout {
   border-left: 4px solid var(--accent);
   padding: 16px 18px;
diff --git a/frontend/app/how-it-works/page.tsx b/frontend/app/how-it-works/page.tsx
index f25cbfc..83d2bc0 100644
--- a/frontend/app/how-it-works/page.tsx
+++ b/frontend/app/how-it-works/page.tsx
@@ -75,6 +75,62 @@ export default function HowItWorksPage() {
         </ol>
       </section>
 
+      <section className="how-flow">
+        <h2>Steps and fixes (simple and visual)</h2>
+        <div className="how-step-grid">
+          <article className="how-step-card step-jellyseerr">
+            <div className="step-badge">1</div>
+            <h3>Request sent</h3>
+            <p className="step-note">Jellyseerr holds your request and approval.</p>
+            <div className="step-fix-title">Fixes you can try</div>
+            <ul className="step-fix-list">
+              <li>Add to library queue (if it was approved but never added)</li>
+            </ul>
+          </article>
+
+          <article className="how-step-card step-arr">
+            <div className="step-badge">2</div>
+            <h3>Added to the library list</h3>
+            <p className="step-note">Sonarr/Radarr decide what quality to get.</p>
+            <div className="step-fix-title">Fixes you can try</div>
+            <ul className="step-fix-list">
+              <li>Search for releases (see options)</li>
+              <li>Search and auto-download (let it pick for you)</li>
+            </ul>
+          </article>
+
+          <article className="how-step-card step-prowlarr">
+            <div className="step-badge">3</div>
+            <h3>Searching for sources</h3>
+            <p className="step-note">Prowlarr checks your torrent providers.</p>
+            <div className="step-fix-title">Fixes you can try</div>
+            <ul className="step-fix-list">
+              <li>Search for releases (show a list to choose)</li>
+            </ul>
+          </article>
+
+          <article className="how-step-card step-qbit">
+            <div className="step-badge">4</div>
+            <h3>Downloading the file</h3>
+            <p className="step-note">qBittorrent downloads the selected match.</p>
+            <div className="step-fix-title">Fixes you can try</div>
+            <ul className="step-fix-list">
+              <li>Resume download (only if it already exists there)</li>
+            </ul>
+          </article>
+
+          <article className="how-step-card step-jellyfin">
+            <div className="step-badge">5</div>
+            <h3>Ready to watch</h3>
+            <p className="step-note">Jellyfin shows it in your library.</p>
+            <div className="step-fix-title">What to do next</div>
+            <ul className="step-fix-list">
+              <li>Open in Jellyfin (watch it)</li>
+            </ul>
+          </article>
+        </div>
+      </section>
+
       <section className="how-callout">
         <h2>Why Magent sometimes says "waiting"</h2>
         <p>
@@ -82,32 +138,6 @@ export default function HowItWorksPage() {
           That does not mean it is broken. It usually means the release is not available yet.
         </p>
       </section>
-
-      <section className="how-flow">
-        <h2>Fix buttons and what they do</h2>
-        <ul className="how-steps">
-          <li>
-            <strong>Search for releases</strong> checks the torrent sources (via Prowlarr) and shows
-            you a list you can choose from.
-          </li>
-          <li>
-            <strong>Download selected release</strong> sends the pick to Sonarr/Radarr so it can
-            download and import it correctly.
-          </li>
-          <li>
-            <strong>Search and auto-download</strong> asks Sonarr/Radarr to find the best match and
-            grab it automatically.
-          </li>
-          <li>
-            <strong>Resume download</strong> tells qBittorrent to continue a paused download when it
-            is already there.
-          </li>
-          <li>
-            <strong>Add to library queue</strong> re-adds the request into Sonarr/Radarr when it is
-            missing there.
-          </li>
-        </ul>
-      </section>
     </main>
   )
 }