docs(readme,landing): clearer install guidance with first-launch unsigned-build FAQ (#212)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/landing/src/lib/links.ts

@@ -102,6 +102,12 @@ export interface DesktopInstaller {
   variant: string;
 }
 
+/** Named separately: the first-launch FAQ's chmod command quotes this exact file name. */
+const LINUX_APPIMAGE: DesktopInstaller = {
+  file: "penguin-desktop-linux-x86_64.AppImage",
+  variant: "AppImage",
+};
+
 /** Installers per platform card, in display order. */
 export const DESKTOP_INSTALLERS: Record<"mac" | "windows" | "linux", DesktopInstaller[]> = {
   mac: [
@@ -109,11 +115,18 @@ export const DESKTOP_INSTALLERS: Record<"mac" | "windows" | "linux", DesktopInst
     { file: "penguin-desktop-darwin-x64.dmg", variant: "Intel" },
   ],
   windows: [{ file: "penguin-desktop-win32-x64.exe", variant: "x64" }],
-  linux: [
-    { file: "penguin-desktop-linux-x86_64.AppImage", variant: "AppImage" },
-    { file: "penguin-desktop-linux-amd64.deb", variant: "deb" },
-  ],
+  linux: [LINUX_APPIMAGE, { file: "penguin-desktop-linux-amd64.deb", variant: "deb" }],
 };
 
 /** Checksum list covering every desktop installer of a release. */
 export const DESKTOP_SHA256SUMS = "SHA256SUMS.desktop";
+
+/**
+ * First-launch fixes for the unsigned desktop builds (the download page FAQ).
+ * Language-neutral, like the install commands above. The macOS one deletes the
+ * quarantine flag that makes Gatekeeper report the app as "damaged"; the Linux
+ * one restores the execute bit browsers strip from a downloaded AppImage.
+ */
+export const MAC_UNQUARANTINE_CMD =
+  "sudo xattr -rd com.apple.quarantine /Applications/PenguinHarness.app";
+export const LINUX_APPIMAGE_CHMOD_CMD = `chmod +x ${LINUX_APPIMAGE.file}`;

packages/landing/src/lib/strings-en.ts

@@ -105,8 +105,31 @@ export const en: Strings = {
     altOss: "Use the OSS mirror instead",
     checksums: "Checksums (SHA256SUMS.desktop)",
     allReleases: "All releases",
-    unsignedNote:
-      'Current builds are unsigned: on first launch use right-click → Open on macOS, and "More info → Run anyway" past Windows SmartScreen.',
+    /** First-launch FAQ: one collapsible item per platform, the visitor's own pre-expanded. */
+    faq: {
+      title: "First-launch FAQ",
+      intro:
+        "Current builds are not signed yet, so the system may block the very first launch — the fix for your platform below is needed only once.",
+      mac: {
+        question: "macOS says “PenguinHarness” is damaged and can’t be opened?",
+        why: "macOS quarantines files downloaded from the internet, and the missing signature makes that flag surface as a false “damaged” alert. Deleting the flag clears it:",
+        stepDrag: "Open the downloaded dmg and drag PenguinHarness into the Applications folder.",
+        stepTerminal: "Open Terminal (Launchpad → Other → Terminal).",
+        stepPaste:
+          "Paste this command into Terminal and press Enter, then type your login password (nothing shows while you type; press Enter when done):",
+        stepOpen: "Once it finishes, double-click the app — it now opens normally.",
+      },
+      windows: {
+        question: "Windows SmartScreen says “Windows protected your PC”?",
+        answer:
+          "The installer is not signed yet, so SmartScreen holds the first run: click “More info”, then “Run anyway” to continue installing — first run only.",
+      },
+      linux: {
+        question: "Nothing happens when double-clicking the AppImage on Linux?",
+        answer:
+          "Browsers download AppImages without the execute permission. Grant it once and the app starts normally from then on (the deb package installs through the package manager and is not affected):",
+      },
+    },
     cliHint: "Just need the CLI, or the Web UI in a browser?",
     cliHintLink: "See the quick start",
   },

packages/landing/src/lib/strings.ts

@@ -107,8 +107,30 @@ export const zh = {
     altOss: "改用 OSS 镜像下载",
     checksums: "校验和（SHA256SUMS.desktop）",
     allReleases: "全部版本",
-    unsignedNote:
-      "当前构建暂未签名：macOS 首次启动请右键 →「打开」；Windows 在 SmartScreen 提示中选「更多信息 → 仍要运行」。",
+    /** First-launch FAQ: one collapsible item per platform, the visitor's own pre-expanded. */
+    faq: {
+      title: "首次启动常见问题",
+      intro: "当前构建暂未签名，系统可能拦截首次启动——按对应系统的步骤解除即可，只需操作一次。",
+      mac: {
+        question: "macOS 提示「PenguinHarness」已损坏，无法打开？",
+        why: "macOS 会给从网络下载的文件加上隔离标记，应用未签名时会因此被误报「已损坏」。删除该标记即可解除：",
+        stepDrag: "打开下载的 dmg，把 PenguinHarness 拖入「应用程序（Applications）」文件夹。",
+        stepTerminal: "打开终端：「启动台 → 其他 → 终端」。",
+        stepPaste:
+          "在终端粘贴这条命令并回车，然后输入开机密码（输入时屏幕不显示字符，输完回车即可）：",
+        stepOpen: "执行完成后，双击即可正常打开应用。",
+      },
+      windows: {
+        question: "Windows SmartScreen 提示「Windows 已保护你的电脑」？",
+        answer:
+          "安装程序暂未签名，SmartScreen 会拦截首次运行：点「更多信息」，再点「仍要运行」即可继续安装，仅首次运行需要。",
+      },
+      linux: {
+        question: "Linux 双击 AppImage 没有反应？",
+        answer:
+          "浏览器下载的 AppImage 默认没有执行权限，赋权一次后即可正常启动（deb 包经包管理器安装，无此问题）：",
+      },
+    },
     cliHint: "只需要命令行或浏览器里的 Web 界面？",
     cliHintLink: "参见快速开始",
   },