Magent/frontend/app/how-it-works/page.tsx

'use client'

export default function HowItWorksPage() {
  return (
    <main className="card how-page">
      <header className="how-hero">
        <p className="eyebrow">How it works</p>
        <h1>How Magent works for users</h1>
        <p className="lede">
          Use Magent to find a request, watch it move through the pipeline, and know when it is
          ready without constantly refreshing the page.
        </p>
      </header>

      <section className="how-flow">
        <h2>What Magent is for</h2>
        <div className="how-grid">
          <article className="how-card">
            <h3>Track requests</h3>
            <p>
              Search by title, year, or request number to open the request page and see where an
              item is up to.
            </p>
          </article>
          <article className="how-card">
            <h3>See live progress</h3>
            <p>
              Request status, timeline events, and download progress update live while you are
              viewing the page.
            </p>
          </article>
          <article className="how-card">
            <h3>Know when it is ready</h3>
            <p>
              When the request is fully imported and available, Magent shows it as ready and links
              you through to Jellyfin.
            </p>
          </article>
        </div>
      </section>

      <section className="how-flow">
        <h2>The request pipeline</h2>
        <ol className="how-steps">
          <li>
            <strong>You request a movie or show</strong> through Seerr.
          </li>
          <li>
            <strong>Magent picks up the request</strong> and shows its current state.
          </li>
          <li>
            <strong>The automation stack searches and downloads it</strong> if it can find a valid
            release.
          </li>
          <li>
            <strong>The file is imported into the library</strong>.
          </li>
          <li>
            <strong>Jellyfin serves it</strong> once it is ready to watch.
          </li>
        </ol>
      </section>

      <section className="how-flow">
        <h2>What the statuses usually mean</h2>
        <div className="how-grid">
          <article className="how-card">
            <h3>Pending</h3>
            <p>The request exists, but it is still waiting for approval or the next step.</p>
          </article>
          <article className="how-card">
            <h3>Approved / Processing</h3>
            <p>The request has been accepted and the automation tools are working on it.</p>
          </article>
          <article className="how-card">
            <h3>Downloading</h3>
            <p>Magent can show live progress while the content is still being downloaded.</p>
          </article>
          <article className="how-card">
            <h3>Ready</h3>
            <p>The item has been imported and should now be available in Jellyfin.</p>
          </article>
          <article className="how-card">
            <h3>Partial / Waiting</h3>
            <p>
              Part of the workflow completed, but the request is still waiting on another service or
              on content becoming available.
            </p>
          </article>
          <article className="how-card">
            <h3>Declined</h3>
            <p>The request was rejected or cannot proceed in its current form.</p>
          </article>
        </div>
      </section>

      <section className="how-flow">
        <h2>Live updates you can expect</h2>
        <div className="how-step-grid">
          <article className="how-step-card step-seerr">
            <div className="step-badge">1</div>
            <h3>Recent requests refresh automatically</h3>
            <p className="step-note">
              Your request list and landing-page activity update automatically while you are signed
              in.
            </p>
          </article>
          <article className="how-step-card step-qbit">
            <div className="step-badge">2</div>
            <h3>Request pages update in real time</h3>
            <p className="step-note">
              State changes, timeline steps, and downloader progress are pushed to the page live.
            </p>
          </article>
          <article className="how-step-card step-jellyfin">
            <div className="step-badge">3</div>
            <h3>Ready state appears as soon as the import completes</h3>
            <p className="step-note">
              Once the content is actually available, Magent updates the request page without a hard
              refresh.
            </p>
          </article>
        </div>
      </section>

      <section className="how-flow">
        <h2>User actions you may see</h2>
        <div className="how-grid">
          <article className="how-card">
            <h3>Open request</h3>
            <p>Jump into the full request page to inspect the current state and activity.</p>
          </article>
          <article className="how-card">
            <h3>Open in Jellyfin</h3>
            <p>Appears when the request is ready and Magent can link you through for playback.</p>
          </article>
          <article className="how-card">
            <h3>Search + auto-download</h3>
            <p>
              Only appears for accounts that have been granted self-service download access by the
              admin team.
            </p>
          </article>
          <article className="how-card">
            <h3>My invites</h3>
            <p>
              If your account is allowed to invite others, you can create and manage invite links
              from your profile.
            </p>
          </article>
        </div>
      </section>

      <section className="how-flow">
        <h2>Invites and signup</h2>
        <ol className="how-steps">
          <li>
            <strong>You receive an invite link</strong> by email or directly from the person who
            invited you.
          </li>
          <li>
            <strong>You sign up through Magent</strong> and your account is linked into the media
            stack.
          </li>
          <li>
            <strong>Your account defaults apply</strong> based on the invite or your assigned
            profile.
          </li>
          <li>
            <strong>You sign in and track requests</strong> from the landing page and your request
            pages.
          </li>
        </ol>
      </section>

      <section className="how-callout">
        <h2>If a request looks stuck</h2>
        <p>
          A waiting request usually means no usable release has been found yet, the download is
          still in progress, or the import has not completed. Magent will keep updating as the
          underlying services move forward.
        </p>
      </section>
    </main>
  )
}