Combine installation guides with restored explanations and screenshots

components/screenshot.tsx

@@ -4,11 +4,13 @@ export function Screenshot({
   alt,
   caption,
   width,
+  lang = "en",
 }: {
   src?: string
   alt: string
   caption?: string
   width?: number
+  lang?: string
 }) {
   return (
     <figure className="not-prose my-5" style={{ maxWidth: width ?? 520 }}>
@@ -17,7 +19,8 @@ export function Screenshot({
         <img src={src} alt={alt} loading="lazy" className="w-full rounded-lg border shadow-sm" />
       ) : (
         <div className="flex min-h-40 items-center justify-center rounded-lg border-2 border-dashed p-6 text-center text-sm text-fd-muted-foreground">
-          Screenshot needed: {alt}
+          {{ en: "Screenshot needed", ru: "Нужен скриншот", es: "Falta una captura" }[lang] ?? "Screenshot needed"}:{" "}
+          {alt}
         </div>
       )}
       {caption && <figcaption className="mt-2 text-sm text-fd-muted-foreground">{caption}</figcaption>}

components/tool-installation-intro.tsx

@@ -1,5 +1,7 @@
+import { Accordion, Accordions } from "fumadocs-ui/components/accordion"
 import Link from "next/link"
 import { InstallTool } from "@/components/install-tool"
+import { Screenshot } from "@/components/screenshot"
 import { CopyText } from "@/components/text-snippet"
 import type { Tool } from "@/lib/shared"
 import { toolInstallationGuide } from "@/lib/tool-installation"
@@ -29,17 +31,45 @@ export function ToolInstallationIntro({ tool, lang }: { tool: Tool; lang: string
           {section.steps && (
             <ol>
               {section.steps.map((step) => (
-                <li key={step}>{step}</li>
+                <li key={step.text}>
+                  {step.text}
+                  {step.screenshots.map((image) => (
+                    <Screenshot key={image.target} {...image} lang={lang} />
+                  ))}
+                </li>
               ))}
             </ol>
           )}
           {section.fallback && (
-            <>
-              <h4>{section.fallback.title}</h4>
-              {section.fallback.paragraphs.map((paragraph) => (
-                <p key={paragraph}>{paragraph}</p>
+            <div data-installation-login-help>
+              <Accordions>
+                <Accordion title={section.fallback.title}>
+                  {section.fallback.command && <CopyText lang={lang} text={section.fallback.command} />}
+                  {section.fallback.steps.length > 0 && (
+                    <ol>
+                      {section.fallback.steps.map((step) => (
+                        <li key={step.text}>
+                          {step.text}
+                          {step.screenshots.map((image) => (
+                            <Screenshot key={image.target} {...image} lang={lang} />
+                          ))}
+                        </li>
+                      ))}
+                    </ol>
+                  )}
+                  {section.fallback.paragraphs.map((paragraph) => (
+                    <p key={paragraph}>{paragraph}</p>
+                  ))}
+                </Accordion>
+              </Accordions>
+            </div>
+          )}
+          {section.recovery && (
+            <ul>
+              {section.recovery.map((item) => (
+                <li key={item}>{item}</li>
               ))}
-            </>
+            </ul>
           )}
           {section.links.map((link) => (
             <p key={link.href}>

docs/screenshots-to-capture.md

@@ -1,53 +1,49 @@
-# Screenshots to capture for "Install and log in"
-
-The page `content/docs/installation.mdx` shows a dashed "Screenshot needed" box in each place still
-missing. Save each file under `public/screenshots/` with the exact name given; then the box is
-replaced with the image.
-
-## How to get a fresh login on screen
-
-Run, from this folder:
-
-```sh
-bin/login-screenshot tg
-```
-
-or `bin/login-screenshot max`. The script runs `setup` with empty throwaway folders, so the CLI
-behaves like a first install and cannot see your real login, archive or settings. Your real login
-keeps working. At the end it logs the test device out and deletes the folders.
-
-One thing stays behind on Telegram: if you finish the test login, the app ID and hash are saved in
-your system keyring under an entry named after the deleted folder. It is harmless.
-
-## Before you start
-
-- Publish a QR screenshot only after confirming that its code has expired or been used successfully; otherwise cover the entire QR before sharing it.
-- **Blur** phone numbers, names, usernames, the api_hash, login codes and chat titles.
-- PNG or JPG. Phone screenshots at the phone's own size; terminal screenshots with a normal-width
-  window (about 100 columns).
-- Crop to the part that matters: the prompt, the message, the menu item.
-
-## Telegram
-
-| # | File | What it must show | Status |
-|---|---|---|---|
-| 1 | `telegram/code-message.jpg` | The message from **Telegram** with the code for my.telegram.org | ✅ done |
-| 2 | `telegram/terminal-qr.png` | The terminal during `bin/login-screenshot tg`, showing the QR code | needed |
-| 3 | `telegram/add-device.jpg` | **Settings → Devices** with the **Add Device** button | ✅ done |
-
-## MAX
-
-| # | File | What it must show | Status |
-|---|---|---|---|
-| 4 | `max/terminal-qr.png` | The terminal during `max setup`, showing the QR code and completed setup | ✅ done |
-| 5 | `max/devices-scanner.png` | MAX on your phone: **Settings → Devices**, with the button that opens the QR scanner | needed |
-
-## Optional
-
-| File | What it must show |
-|---|---|
-| `telegram/phone-prompt.png` | The terminal asking "phone number, international format:" (number blurred if typed) |
-| `telegram/logged-in.png` | The end of setup: "Telegram is ready" and the five chats (names blurred) |
-| `max/logged-in.png` | The end of `max setup`: the account line and the five chats (names blurred) |
-
-When the files are in place, tell me and I switch each placeholder to its image.
+# Installation screenshots
+
+The Telegram and MAX installation guides show screenshots beside the relevant login steps:
+`/{en,ru,es}/docs/tg/installation` and `/{en,ru,es}/docs/max/installation`.
+The general installation page explains the shared setup and links to these guides.
+
+`lib/installation-screenshots.ts` owns placements, localized descriptions and capture filenames.
+`components/screenshot.tsx` renders existing images or a localized dashed placeholder. The same
+images and placeholder descriptions appear in the guides' Markdown counterparts.
+
+After saving a reviewed image under `public/screenshots/`, set its slot's `src` in
+`lib/installation-screenshots.ts` to its target path. Saving the file alone does not replace a
+placeholder. Check all three locales and mobile rendering before publishing.
+
+## Captures and placement
+
+| File | Placement | Status |
+| --- | --- | --- |
+| `telegram/code-message.jpg` | Code for my.telegram.org, before account QR login | Existing, restored |
+| `telegram/terminal-qr.png` | Telegram account-login QR in the terminal | Needed |
+| `telegram/add-device.jpg` | Phone Settings → Devices → Add Device | Existing, restored |
+| `telegram/my-telegram-login.png` | Browser fallback: phone number and confirmation code | Existing, restored |
+| `telegram/my-telegram-api-tools.png` | Browser fallback: API development tools | Existing, restored |
+| `telegram/my-telegram-credentials.png` | Browser fallback: App api_id and App api_hash | Existing, restored |
+| `max/terminal-qr-current.png` | Current MAX setup's account-login QR | Fresh capture needed |
+| `max/devices-scanner.png` | MAX phone Settings → Devices, QR scanner | Needed |
+
+The older `max/terminal-qr.png` remains available as historical material. Its terminal output
+uses earlier setup wording and step labels, so the current guide does not present it as the current
+setup screen. Capture its replacement from the current supported tool.
+
+## Capture procedure
+
+With authorization to perform a live account login, run `bin/login-screenshot tg` or
+`bin/login-screenshot max` from this repository. The script runs setup in throwaway folders,
+keeps the existing login/archive/settings separate, and logs the test device out at the end.
+Review the script's cleanup, including any application registration retained in the system
+keyring, before a live capture. This documentation edit does not itself perform a login.
+
+Before publishing:
+
+- Confirm a QR code is expired or already used; otherwise cover the entire QR.
+- Hide phone numbers, names, usernames, app hashes, login codes and private chat titles.
+- Crop to the step the image explains, retaining the relevant label or prompt.
+- Use PNG/JPG; preserve phone screenshots' proportions and a readable terminal width.
+- Check the text against the current tool's supported commands and setup sequence.
+
+Optional later captures: `telegram/phone-prompt.png`, `telegram/logged-in.png` and
+`max/logged-in.png`. These are not required to replace the current login placeholders.

lib/installation-screenshots.ts

@@ -0,0 +1,80 @@
+export type InstallationScreenshot = {
+  src?: string
+  target: string
+  alt: string
+  width?: number
+}
+
+const descriptions = {
+  en: [
+    "Telegram message with the login code for my.telegram.org",
+    "Terminal showing the Telegram account-login QR code",
+    "Telegram Settings → Devices, with Add Device highlighted",
+    "my.telegram.org form for entering the phone number and confirmation code",
+    "my.telegram.org menu with API development tools highlighted",
+    "App configuration with App api_id and App api_hash highlighted",
+    "Terminal showing the MAX login QR code during setup",
+    "MAX Settings → Devices, with the QR scanner button",
+  ],
+  ru: [
+    "Сообщение Telegram с кодом для входа на my.telegram.org",
+    "Терминал с QR-кодом для входа в аккаунт Telegram",
+    "Telegram: Настройки → Устройства, выделена кнопка Add Device",
+    "Форма my.telegram.org для номера телефона и кода подтверждения",
+    "Меню my.telegram.org, выделен пункт API development tools",
+    "App configuration, выделены App api_id и App api_hash",
+    "Терминал с QR-кодом для входа в MAX при настройке",
+    "MAX: Настройки → Устройства, кнопка сканера QR-кода",
+  ],
+  es: [
+    "Mensaje de Telegram con el código para acceder a my.telegram.org",
+    "Terminal con el QR de inicio de sesión de Telegram",
+    "Telegram: Configuración → Dispositivos, con Add Device resaltado",
+    "Formulario de my.telegram.org para el teléfono y el código de confirmación",
+    "Menú de my.telegram.org con API development tools resaltado",
+    "App configuration con App api_id y App api_hash resaltados",
+    "Terminal con el QR de inicio de sesión de MAX durante la configuración",
+    "MAX: configuración y dispositivos, con el botón del escáner QR",
+  ],
+}
+
+export function installationScreenshots(tool: string, lang: string) {
+  const labels = descriptions[lang === "ru" || lang === "es" ? lang : "en"]
+  const image = (file: string, index: number, width?: number): InstallationScreenshot => ({
+    src: `/screenshots/${file}`,
+    target: `/screenshots/${file}`,
+    alt: labels[index],
+    width,
+  })
+  const slot = (file: string, index: number, width?: number): InstallationScreenshot => ({
+    target: `/screenshots/${file}`,
+    alt: labels[index],
+    width,
+  })
+  return tool === "tg"
+    ? {
+        login: {
+          1: [image("telegram/code-message.jpg", 0, 360)],
+          2: [slot("telegram/terminal-qr.png", 1)],
+          3: [image("telegram/add-device.jpg", 2, 360)],
+        } as Record<number, InstallationScreenshot[]>,
+        browser: {
+          0: [image("telegram/my-telegram-login.png", 3)],
+          1: [image("telegram/my-telegram-api-tools.png", 4)],
+          3: [image("telegram/my-telegram-credentials.png", 5)],
+        } as Record<number, InstallationScreenshot[]>,
+      }
+    : {
+        login: {
+          0: [slot("max/terminal-qr-current.png", 6, 1000)],
+          1: [slot("max/devices-scanner.png", 7, 360)],
+        } as Record<number, InstallationScreenshot[]>,
+        browser: {} as Record<number, InstallationScreenshot[]>,
+      }
+}
+
+export function screenshotMarkdown(screenshot: InstallationScreenshot, lang: string) {
+  if (screenshot.src) return `![${screenshot.alt}](${screenshot.src})`
+  const label = { en: "Screenshot needed", ru: "Нужен скриншот", es: "Falta una captura" }[lang] ?? "Screenshot needed"
+  return `*${label}: ${screenshot.alt}*`
+}