From 03926c3b2e7e7638addefc0d5d37f13d020f7f30 Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 17:25:36 -0500
Subject: [PATCH 1/6] fix(export): resolve the audio codec against what the
 platform can encode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every mp4 export template asks for AAC, and the encoder took that as a
demand. In WebCodecs, AAC is the platform's encoder — AudioToolbox on
macOS, Media Foundation on Windows — so Chromium on Linux has none, and
an export failed after the video track had already started encoding.

The codec asked for is now a preference: resolveAudioCodec keeps it when
the container takes it and the browser can encode it, and otherwise
picks the container's next encodable choice (Opus, which mp4 takes and
Chromium bundles everywhere). It is resolved at the three places an
export starts — the export panel, the dapi handler, and the encoder
itself — so the progress panel, the echoed dapi config, and the file all
name the same codec. The audio picker offers only codecs this machine
can actually encode.

Nothing changes where AAC exists: it is encodable, so it is what is
used.
---
 .../inspector/export-templates.ts             |  1 +
 .../sidebar-right/inspector/export.tsx        | 45 ++++++++++++++---
 apps/web/src/context/dapi/export.ts           | 26 ++++++++--
 apps/web/src/context/export.tsx               | 24 ++++++++-
 packages/encoder/src/codecs.ts                | 50 +++++++++++++++++++
 packages/encoder/src/encoder.ts               | 23 ++++++++-
 packages/encoder/src/format.ts                | 13 +++--
 packages/encoder/src/index.ts                 |  1 +
 packages/encoder/src/interfaces.ts            |  4 +-
 reference/export.md                           |  4 +-
 10 files changed, 172 insertions(+), 19 deletions(-)
 create mode 100644 packages/encoder/src/codecs.ts

diff --git a/apps/web/src/components/sidebar-right/inspector/export-templates.ts b/apps/web/src/components/sidebar-right/inspector/export-templates.ts
index 56f96473..03deda29 100644
--- a/apps/web/src/components/sidebar-right/inspector/export-templates.ts
+++ b/apps/web/src/components/sidebar-right/inspector/export-templates.ts
@@ -23,6 +23,7 @@ export const RESOLUTION_OPTIONS: number[] = [720, 1080, 1440, 2160];
 export const VIDEO_CODEC_OPTIONS: VideoCodec[] = ["avc", "hevc", "vp9", "av1", "vp8"];
 export const VIDEO_FORMAT_OPTIONS: ContainerFormat[] = ["mp4", "webm", "ogg", "mov"];
 export const FRAME_RATE_OPTIONS: number[] = [24, 25, 29.97, 30, 48, 50, 59.94, 60];
+/** The codecs the audio picker offers, less the ones a machine cannot encode (see `ExportPanel`). */
 export const AUDIO_CODEC_OPTIONS: AudioCodec[] = ["aac", "opus"];
 export const SAMPLE_RATE_OPTIONS: number[] = [44100, 48000, 96000];
 
diff --git a/apps/web/src/components/sidebar-right/inspector/export.tsx b/apps/web/src/components/sidebar-right/inspector/export.tsx
index 76dcb346..be8b4648 100644
--- a/apps/web/src/components/sidebar-right/inspector/export.tsx
+++ b/apps/web/src/components/sidebar-right/inspector/export.tsx
@@ -3,8 +3,8 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import { Show, createMemo, createResource, createSignal } from "solid-js";
-import { canEncodeVideo } from "mediabunny";
-import { computeOutputSize } from "@diffusionstudio/encoder";
+import { canEncodeVideo, getEncodableAudioCodecs } from "mediabunny";
+import { audioCodecsForFormat, computeOutputSize, resolveAudioCodec } from "@diffusionstudio/encoder";
 import { PanelSection } from "@/components/ui/panel-section";
 import { Button } from "@/components/ui/button";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
@@ -158,6 +158,28 @@ export function ExportPanel(props: ExportPanelProps) {
     ({ codec, bitrate, width, height }) => canEncodeVideo(codec, { width, height, bitrate }),
   );
 
+  // Which audio codecs are worth offering: those the container takes and
+  // this browser can encode. AAC is a platform encoder in WebCodecs
+  // (AudioToolbox on macOS, Media Foundation on Windows) and simply absent
+  // on Linux, so offering it there would only fail the export.
+  const [audioCodecs] = createResource(
+    () => {
+      const current = settings();
+      return {
+        format: current?.format ?? ("mp4" as const),
+        sampleRate: current?.audio?.sampleRate,
+        bitrate: current?.audio?.bitrate,
+      };
+    },
+    async ({ format, ...options }) => {
+      const [supported, encodable] = await Promise.all([
+        audioCodecsForFormat(format),
+        getEncodableAudioCodecs([...AUDIO_CODEC_OPTIONS], options),
+      ]);
+      return encodable.filter((codec) => supported.includes(codec));
+    },
+  );
+
   // Audio-only exports always encode
   const exportSupported = createMemo(() => {
     const current = settings();
@@ -180,14 +202,21 @@ export function ExportPanel(props: ExportPanelProps) {
     void config()?.setExport(entity(), value);
   };
 
-  // Replaces the settings with a preset's, wholesale.
-  const applyTemplate = (id: string) => {
+  // Replaces the settings with a preset's, wholesale. A preset names AAC for
+  // mp4, which is a preference rather than a demand — what is written is the
+  // codec this browser can encode into the container.
+  const applyTemplate = async (id: string) => {
     const next = templateSettings(id);
-    if (next) write(next);
+    if (!next) return;
+    const codec = await resolveAudioCodec(next.format, next.audio?.codec, {
+      sampleRate: next.audio?.sampleRate,
+      bitrate: next.audio?.bitrate,
+    });
+    write(codec ? { ...next, audio: { ...next.audio, codec } } : next);
   };
 
   const addSettings = () => {
-    applyTemplate(DEFAULT_EXPORT_TEMPLATE_ID);
+    void applyTemplate(DEFAULT_EXPORT_TEMPLATE_ID);
     setIsInspectorOpen(true);
   };
 
@@ -294,6 +323,7 @@ export function ExportPanel(props: ExportPanelProps) {
             settings={current()}
             resolutionOptions={resolutionOptions()}
             selectedResolution={selectedResolution()}
+            audioCodecOptions={audioCodecs() ?? AUDIO_CODEC_OPTIONS}
             anchorRef={inspectorAnchorRef}
             onClose={() => setIsInspectorOpen(false)}
             onSelectTemplate={applyTemplate}
@@ -309,6 +339,7 @@ type ExportInspectorProps = {
   settings: ProjectExportConfig;
   resolutionOptions: ResolutionOption[];
   selectedResolution: ResolutionOption | null;
+  audioCodecOptions: AudioCodec[];
   anchorRef: HTMLDivElement | undefined;
   onClose: () => void;
   onSelectTemplate: (id: string) => void;
@@ -507,7 +538,7 @@ function ExportInspector(props: ExportInspectorProps) {
             <ControlRow label="Codec">
               <Select
                 value={config().audio?.codec ?? "aac"}
-                options={[...AUDIO_CODEC_OPTIONS]}
+                options={[...props.audioCodecOptions]}
                 onChange={(value) => value && write({ audio: { codec: value } })}
                 itemComponent={(itemProps) => (
                   <SelectItem item={itemProps.item}>{itemProps.item.rawValue.toUpperCase()}</SelectItem>
diff --git a/apps/web/src/context/dapi/export.ts b/apps/web/src/context/dapi/export.ts
index a2a6536e..dfb98109 100644
--- a/apps/web/src/context/dapi/export.ts
+++ b/apps/web/src/context/dapi/export.ts
@@ -3,7 +3,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import { canEncodeVideo } from "mediabunny";
-import { computeOutputSize } from "@diffusionstudio/encoder";
+import { computeOutputSize, resolveAudioCodec } from "@diffusionstudio/encoder";
 import { Computed, FrameRate, getParentNode, isScene, Source, Workarea } from "@diffusionstudio/runtime";
 
 import { renderOverlay, renderScene } from "@/context/render";
@@ -95,6 +95,26 @@ export function handleExport(session: () => EditorSession) {
       }
     }
 
+    // Same for audio, except that the codec asked for is a preference: AAC
+    // is the platform's encoder in WebCodecs and absent on Linux, so export
+    // with what this machine can encode into the container and echo that
+    // back, rather than failing a render that got as far as the audio track.
+    const audioEnabled = format === "ogg" || settings.audio?.enabled !== false;
+    let audio = settings.audio;
+    if (audioEnabled) {
+      const codec = await resolveAudioCodec(format, settings.audio?.codec, {
+        sampleRate: settings.audio?.sampleRate,
+        bitrate: settings.audio?.bitrate,
+      });
+      if (!codec) {
+        throw new Error(
+          `Cannot encode audio into ${format.toUpperCase()}. ` +
+            "Set another format, or turn audio off in the scene's export entry.",
+        );
+      }
+      audio = { ...settings.audio, codec };
+    }
+
     const workarea = scene.get(Workarea);
     const frames = workarea ? workarea.end - workarea.start : computed?.duration ?? 0;
     const duration = frames / (world.get(FrameRate)?.value || 30);
@@ -112,7 +132,7 @@ export function handleExport(session: () => EditorSession) {
       const result = await renderScene(engine, {
         scene,
         target: handle,
-        config: { ...settings, format },
+        config: { ...settings, format, audio },
         dir: project.dir(),
       });
       if (result.type === "canceled") throw new Error("Export canceled in the app");
@@ -128,7 +148,7 @@ export function handleExport(session: () => EditorSession) {
       source: target,
     });
 
-    const config: ExportSettings = { format, video: settings.video, audio: settings.audio };
+    const config: ExportSettings = { format, video: settings.video, audio };
     return {
       path: target,
       width: videoEnabled ? width : 0,
diff --git a/apps/web/src/context/export.tsx b/apps/web/src/context/export.tsx
index 43054dd6..fc57d4bf 100644
--- a/apps/web/src/context/export.tsx
+++ b/apps/web/src/context/export.tsx
@@ -6,7 +6,7 @@ import { createContext, useContext, onCleanup, onMount } from "solid-js";
 import { toast } from "somoto";
 import { canEncodeVideo } from "mediabunny";
 import { useWorld } from "@diffusionstudio/koota-solid";
-import { computeOutputSize } from "@diffusionstudio/encoder";
+import { computeOutputSize, resolveAudioCodec } from "@diffusionstudio/encoder";
 import { Computed, FrameRate, getActiveEntity } from "@diffusionstudio/runtime";
 import { assert, downloadObject, isInputTarget } from "@/utils";
 import { useEngineContext } from "@/engine";
@@ -73,6 +73,28 @@ export function ExportProvider(props: { children: JSX.Element }) {
       }
     }
 
+    // AAC is a platform encoder in WebCodecs (AudioToolbox on macOS, Media
+    // Foundation on Windows), so it is simply absent on Linux — pick what
+    // this browser can encode into the container and export with that, so
+    // the progress panel and the file agree on the codec.
+    const audioEnabled = format === "ogg" || config.audio?.enabled !== false;
+    if (audioEnabled) {
+      const codec = await resolveAudioCodec(format, config.audio?.codec, {
+        numberOfChannels: config.audio?.numberOfChannels,
+        sampleRate: config.audio?.sampleRate,
+        bitrate: config.audio?.bitrate,
+      });
+      if (!codec) {
+        toast.error("Export not supported", {
+          description:
+            `This browser cannot encode audio into ${format.toUpperCase()}. ` +
+            "Choose another format, or turn audio off.",
+        });
+        return;
+      }
+      config = { ...config, audio: { ...config.audio, codec } };
+    }
+
     const name = project.name().replace(/\s+/g, "-").toLowerCase();
 
     let target: FileSystemFileHandle;
diff --git a/packages/encoder/src/codecs.ts b/packages/encoder/src/codecs.ts
new file mode 100644
index 00000000..92f290ac
--- /dev/null
+++ b/packages/encoder/src/codecs.ts
@@ -0,0 +1,50 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { getFirstEncodableAudioCodec } from 'mediabunny';
+
+import { createOutputFormat } from './format';
+
+import type { AudioCodec } from 'mediabunny';
+import type { ContainerFormat } from './types';
+
+/** The parameters an audio codec has to be encodable at to be worth offering. */
+export type AudioEncodingOptions = {
+	numberOfChannels?: number;
+	sampleRate?: number;
+	bitrate?: number;
+};
+
+/** The audio codecs a container accepts, ordered by encoding preference. */
+export async function audioCodecsForFormat(format?: ContainerFormat): Promise<AudioCodec[]> {
+	const output = await createOutputFormat(format);
+	return output.getSupportedAudioCodecs();
+}
+
+/**
+ * The audio codec an export can actually be written with: the one asked for
+ * when the container takes it and this browser can encode it, else the
+ * container's next best encodable choice — `null` when there is none.
+ *
+ * Which codecs a browser can encode is not the same everywhere: WebCodecs
+ * hands AAC off to the platform (AudioToolbox on macOS, Media Foundation on
+ * Windows), so Chromium on Linux has no AAC encoder at all, while Opus is
+ * bundled everywhere. An mp4 asked for with AAC is therefore written with
+ * Opus there — which mp4 takes — rather than failing mid-encode.
+ */
+export async function resolveAudioCodec(
+	format?: ContainerFormat,
+	requested?: AudioCodec,
+	options?: AudioEncodingOptions,
+): Promise<AudioCodec | null> {
+	const supported = await audioCodecsForFormat(format);
+
+	// The asked-for codec goes first, the container's own preference order
+	// (aac, opus, mp3, …, pcm) decides the rest.
+	const candidates = requested && supported.includes(requested)
+		? [requested, ...supported.filter((codec) => codec !== requested)]
+		: supported;
+
+	return getFirstEncodableAudioCodec(candidates, options);
+}
diff --git a/packages/encoder/src/encoder.ts b/packages/encoder/src/encoder.ts
index 71afb36e..7fa30f22 100644
--- a/packages/encoder/src/encoder.ts
+++ b/packages/encoder/src/encoder.ts
@@ -23,6 +23,7 @@ import {
 } from '@diffusionstudio/runtime';
 
 import { TargetBuffer } from './buffer';
+import { resolveAudioCodec } from './codecs';
 import { createOutputFormat } from './format';
 import { computeOutputSize, createRenderEventDetail } from './utils';
 
@@ -96,7 +97,7 @@ export async function createEncoder(world: World, config: EncoderConfig) {
 	const sampleRate = config.audio?.sampleRate ?? 48000;
 	const audioBitrate = config.audio?.bitrate ?? 128e3;
 	const videoBitrate = config.video?.bitrate ?? 10e6;
-	const audioCodec = config.audio?.codec ?? 'aac';
+	const requestedAudioCodec = config.audio?.codec ?? 'aac';
 	const videoCodec = config.video?.codec ?? 'avc';
 	const containerFormat = config.format ?? 'mp4';
 	const resolution = config.video?.resolution ?? 1080;
@@ -116,6 +117,24 @@ export async function createEncoder(world: World, config: EncoderConfig) {
 		);
 	}
 
+	// Same, for audio: what a browser can encode depends on the platform
+	// underneath it (no AAC encoder on Linux, where WebCodecs has no system
+	// one to hand it to), so the codec asked for is only a preference — the
+	// container's next encodable choice is written instead of failing.
+	const audioCodec = audioEnabled
+		? await resolveAudioCodec(containerFormat, requestedAudioCodec, {
+			numberOfChannels,
+			sampleRate,
+			bitrate: audioBitrate,
+		})
+		: requestedAudioCodec;
+
+	assert(
+		audioCodec,
+		`This browser cannot encode audio into ${containerFormat.toUpperCase()}. ` +
+		'Choose another format, or turn audio off.',
+	);
+
 	const canvas = world.get(RenderSurface)?.canvas;
 	assert(canvas instanceof HTMLCanvasElement, 'The capture world has no canvas to draw into');
 	canvas.width = width;
@@ -146,7 +165,7 @@ export async function createEncoder(world: World, config: EncoderConfig) {
 
 	// Set up mediabunny output
 	const buffer = await TargetBuffer.create(config.target);
-	const format = await createOutputFormat(buffer, config.format);
+	const format = await createOutputFormat(config.format, { fastStart: buffer.fastStart });
 	const output = new Output({ format, target: buffer.target });
 
 	if (config.comment) {
diff --git a/packages/encoder/src/format.ts b/packages/encoder/src/format.ts
index 1b831363..3d09b300 100644
--- a/packages/encoder/src/format.ts
+++ b/packages/encoder/src/format.ts
@@ -2,13 +2,18 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-import type { TargetBuffer } from './buffer';
 import type { ContainerFormat } from './types';
 
 /**
- * Lazily imports the output format based on the format specified
+ * Lazily imports the output format based on the format specified.
+ *
+ * `fastStart` is the ISOBMFF option the target dictates (see `TargetBuffer`);
+ * it is nothing to a query of what the container supports, so it is optional.
  */
-export async function createOutputFormat(buffer: TargetBuffer, format?: ContainerFormat) {
+export async function createOutputFormat(
+  format?: ContainerFormat,
+  options?: { fastStart?: false | 'in-memory' },
+) {
   if (format == 'webm') {
     const { WebMOutputFormat } = await import('mediabunny');
     return new WebMOutputFormat();
@@ -20,6 +25,6 @@ export async function createOutputFormat(buffer: TargetBuffer, format?: Containe
     return new MovOutputFormat();
   } else {
     const { Mp4OutputFormat } = await import('mediabunny');
-    return new Mp4OutputFormat({ fastStart: buffer.fastStart });
+    return new Mp4OutputFormat({ fastStart: options?.fastStart ?? false });
   }
 }
diff --git a/packages/encoder/src/index.ts b/packages/encoder/src/index.ts
index ab8b77dd..8ab6a7c1 100644
--- a/packages/encoder/src/index.ts
+++ b/packages/encoder/src/index.ts
@@ -3,6 +3,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 export * from './buffer';
+export * from './codecs';
 export * from './contact-sheet';
 export * from './encoder';
 export * from './format';
diff --git a/packages/encoder/src/interfaces.ts b/packages/encoder/src/interfaces.ts
index 0038343f..13e2d930 100644
--- a/packages/encoder/src/interfaces.ts
+++ b/packages/encoder/src/interfaces.ts
@@ -31,7 +31,9 @@ export interface AudioConfig {
 	bitrate?: number;
 
 	/**
-	 * Defines the codec to use for the audio
+	 * Defines the codec to use for the audio. A preference rather than a
+	 * demand: a codec the container or this browser cannot encode is replaced
+	 * with the container's next encodable choice (see `resolveAudioCodec`).
 	 * @default 'aac'
 	 */
 	codec?: AudioCodec;
diff --git a/reference/export.md b/reference/export.md
index f3823172..0b682049 100644
--- a/reference/export.md
+++ b/reference/export.md
@@ -30,7 +30,7 @@ The scene's entry under `diffusion.export.<id>` in the project's `package.json`:
         },
         "audio": {
           "enabled": true,
-          "codec": "aac",                   // aac | opus
+          "codec": "aac",                   // aac | opus — a preference: see below
           "sampleRate": 48000,
           "bitrate": 128000
         }
@@ -42,6 +42,8 @@ The scene's entry under `diffusion.export.<id>` in the project's `package.json`:
 
 Every field is optional; the encoder fills what the entry leaves out. A scene without an entry exports with the defaults — 1080p H.264 MP4 with AAC audio, the app's default template. `resolution` scales the scene uniformly until its shorter side reaches the number, so a portrait 1080×1920 scene at `2160` encodes as 2160×3840.
 
+The audio `codec` is a preference rather than a demand: which codecs a machine can encode is not the same everywhere — AAC is the platform's encoder in WebCodecs (AudioToolbox on macOS, Media Foundation on Windows) and absent on Linux, while Opus is bundled everywhere — so a codec this machine cannot encode into the container is replaced with the container's next encodable choice. The echoed `config` names the codec the file was actually written with.
+
 ## Output
 
 One JSON object once the file is written:

From 6b23da6a5b25409c4c09b0cc6c09f2fe5cee5f16 Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 17:36:51 -0500
Subject: [PATCH 2/6] feat(desktop): package and run on Linux
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`npm run make` only had a darwin ZIP and the DMG, so a Linux checkout
could be packaged but never made into an installable artifact. Adds deb
and rpm makers plus a Linux ZIP, and scopes the DMG to darwin. The
FreeDesktop entry both packages share registers `x-scheme-handler/diffusion`,
which is what the auth and checkout deep links arrive on — the macOS
bundle gets that from packagerConfig.protocols.

The Linux build also renames the executable to `diffusion-studio`:
electron-packager keeps the space from `name`, which is fine inside a
.app bundle but not for the binary the packages symlink into /usr/bin.
The name stays untouched on macOS, where the CLI wrapper and the signing
pass both address `Contents/MacOS/Diffusion Studio`.

Two runtime gaps go with it: Chromium needs `--ozone-platform-hint=auto`
or it runs through XWayland on Wayland sessions, and `setupAppMenu` used
to return early off darwin, leaving the dapi installer unreachable
behind Electron's stock menu.

The release workflow gains a publish-linux job so the artifacts reach
the same draft release; it carries no Apple secrets.
---
 .github/workflows/release.yml   |  36 +++
 apps/desktop/forge.config.ts    |  65 +++-
 apps/desktop/package.json       |   2 +
 apps/desktop/src/main.ts        |   9 +
 apps/desktop/src/menu.ts        |  41 ++-
 apps/web/src/lib/desktop-app.ts |   8 +-
 package-lock.json               | 511 ++++++++++++++++++++++++++++++++
 7 files changed, 644 insertions(+), 28 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e9f04121..0ea703a5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -54,3 +54,39 @@ jobs:
           APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
         run: npm run publish --workspace=@diffusionstudio/desktop
+
+  publish-linux:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Check versions match tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          for PKG in package.json apps/desktop/package.json apps/cli/package.json apps/web/package.json; do
+            V="$(node -p "require('./$PKG').version")"
+            if [ "$V" != "$TAG" ]; then
+              echo "Version mismatch in $PKG: $V, tag is $TAG"
+              exit 1
+            fi
+          done
+
+      - run: npm ci
+
+      - name: Provide client env for web build
+        run: cp apps/web/.env.example apps/web/.env
+
+      - name: Install packaging tools
+        run: sudo apt-get update && sudo apt-get install -y dpkg-dev fakeroot rpm
+
+      - name: Build and publish draft release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npm run publish --workspace=@diffusionstudio/desktop
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index 5cfa8ce6..f788b423 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -3,7 +3,9 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import type { ForgeConfig } from '@electron-forge/shared-types';
+import { MakerDeb, type MakerDebConfig } from '@electron-forge/maker-deb';
 import { MakerDMG } from '@electron-forge/maker-dmg';
+import { MakerRpm, type MakerRpmConfig } from '@electron-forge/maker-rpm';
 import { MakerZIP } from '@electron-forge/maker-zip';
 import { PublisherGithub } from '@electron-forge/publisher-github';
 import { readFileSync } from 'node:fs';
@@ -11,9 +13,35 @@ import { join } from 'node:path';
 
 const { version } = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf8'));
 
+// electron-packager derives the executable name from `name` and keeps the space
+// in it, which is fine inside a .app bundle but not for a binary on $PATH. The
+// deb and rpm packages symlink this into /usr/bin and the staged CLI wrapper
+// execs it, so both sides agree on the lowercase form.
+const LINUX_EXECUTABLE = 'diffusion-studio';
+
+// FreeDesktop metadata shared by both Linux packages. The mime type is what
+// registers `diffusion://` with xdg, so the auth and checkout deep links reach
+// the app the same way the macOS bundle's protocol handler does.
+const linuxPackage = {
+  name: LINUX_EXECUTABLE,
+  productName: 'Diffusion Studio',
+  genericName: 'Video Editor',
+  description: 'Edit videos with coding agents, and refine any output in a full editing environment',
+  homepage: 'https://diffusion.studio',
+  icon: './assets/icon.png',
+  categories: ['AudioVideo', 'Video'],
+  mimeType: ['x-scheme-handler/diffusion'],
+} satisfies NonNullable<MakerDebConfig['options']> & NonNullable<MakerRpmConfig['options']>;
+
 const config: ForgeConfig = {
   packagerConfig: {
     name: 'Diffusion Studio',
+    // Only Linux renames the binary; on macOS it stays inside the bundle as
+    // `Contents/MacOS/Diffusion Studio`, which the staged CLI wrapper and the
+    // signing pass both address by that name. Read from the build host, since
+    // that is what packages a platform here — cross-packaging Linux from macOS
+    // would have to set it.
+    executableName: process.platform === 'linux' ? LINUX_EXECUTABLE : undefined,
     appBundleId: 'studio.diffusion.editor',
     appCategoryType: 'public.app-category.video',
     appVersion: version,
@@ -28,7 +56,7 @@ const config: ForgeConfig = {
       path !== '/web' &&
       !path.startsWith('/web/'),
     // Staged by scripts/stage-{cli,docs,skills}.mjs; end up at
-    // Contents/Resources/{cli,docs,skills}.
+    // Contents/Resources/{cli,docs,skills} on macOS and resources/{...} on Linux.
     extraResource: ['./cli', './docs', './skills'],
     osxSign: process.env.SKIP_SIGN ? undefined : {},
     osxNotarize:
@@ -41,22 +69,27 @@ const config: ForgeConfig = {
         : undefined,
   },
   makers: [
-    new MakerZIP({}, ['darwin']),
-    new MakerDMG({
-      name: `Diffusion-Studio-${process.arch}`,
-      icon: './assets/icon.icns',
-      // Dark, on-brand window; @2x sibling is picked up automatically for retina.
-      background: './assets/dmg-background.png',
-      iconSize: 120,
-      additionalDMGOptions: {
-        'background-color': '#1c1c1c',
-        window: { size: { width: 658, height: 498 } },
+    new MakerZIP({}, ['darwin', 'linux']),
+    new MakerDMG(
+      {
+        name: `Diffusion-Studio-${process.arch}`,
+        icon: './assets/icon.icns',
+        // Dark, on-brand window; @2x sibling is picked up automatically for retina.
+        background: './assets/dmg-background.png',
+        iconSize: 120,
+        additionalDMGOptions: {
+          'background-color': '#1c1c1c',
+          window: { size: { width: 658, height: 498 } },
+        },
+        contents: (opts) => [
+          { x: 188, y: 217, type: 'file', path: opts.appPath },
+          { x: 470, y: 217, type: 'link', path: '/Applications' },
+        ],
       },
-      contents: (opts) => [
-        { x: 188, y: 217, type: 'file', path: opts.appPath },
-        { x: 470, y: 217, type: 'link', path: '/Applications' },
-      ],
-    }),
+      ['darwin'],
+    ),
+    new MakerDeb({ options: linuxPackage }, ['linux']),
+    new MakerRpm({ options: linuxPackage }, ['linux']),
   ],
   publishers: [
     new PublisherGithub({
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 20c0d2ba..9687e1a7 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -26,7 +26,9 @@
   },
   "devDependencies": {
     "@electron-forge/cli": "^7.11.1",
+    "@electron-forge/maker-deb": "^7.11.1",
     "@electron-forge/maker-dmg": "^7.11.1",
+    "@electron-forge/maker-rpm": "^7.11.1",
     "@electron-forge/maker-zip": "^7.11.1",
     "@electron-forge/publisher-github": "^7.11.1",
     "@types/babel__core": "^7.20.5",
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index b965b054..0af50f9d 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -57,6 +57,15 @@ app.commandLine.appendSwitch("disable-renderer-backgrounding");
 app.commandLine.appendSwitch("disable-backgrounding-occluded-windows");
 app.commandLine.appendSwitch("disable-features", "CalculateNativeWinOcclusion");
 
+// No ozone hint is set here on purpose. Native Wayland would buy fractional
+// scaling, but on a KDE 6.7 Wayland session with the proprietary NVIDIA driver
+// it presents a broken surface — Chromium logs that Wayland and Vulkan are
+// incompatible, the renderer paints correctly (a DevTools capture is right)
+// and the window still comes up blank or without glyphs. XWayland, which is
+// what Chromium picks by default, is correct there. Electron reads
+// `ELECTRON_OZONE_PLATFORM_HINT=auto` from the environment, so anyone whose
+// session handles native Wayland can opt in without a build of their own.
+
 let setNativeCornerRadius: ((handle: Buffer, radius: number) => void) | null = null;
 let setNativeBackdrop:
   | ((handle: Buffer, blur: number, r: number, g: number, b: number, a: number) => void)
diff --git a/apps/desktop/src/menu.ts b/apps/desktop/src/menu.ts
index 31bef6aa..4e5b2b70 100644
--- a/apps/desktop/src/menu.ts
+++ b/apps/desktop/src/menu.ts
@@ -25,20 +25,24 @@ async function installCliFromMenu() {
   }
 }
 
-export function setupAppMenu() {
-  if (process.platform !== "darwin") return;
+/** The one app-specific item both menus carry; only the packaged app can link it. */
+function installCliItem(): MenuItemConstructorOptions {
+  return {
+    label: "Install dapi Command Line Tool…",
+    enabled: app.isPackaged,
+    click: installCliFromMenu,
+  };
+}
 
-  const template: MenuItemConstructorOptions[] = [
+/** The macOS menu: the app menu holds the item, in its usual place. */
+function macTemplate(): MenuItemConstructorOptions[] {
+  return [
     {
       label: app.name,
       submenu: [
         { role: "about" },
         { type: "separator" },
-        {
-          label: "Install dapi Command Line Tool…",
-          enabled: app.isPackaged,
-          click: installCliFromMenu,
-        },
+        installCliItem(),
         { type: "separator" },
         { role: "services" },
         { type: "separator" },
@@ -54,6 +58,27 @@ export function setupAppMenu() {
     { role: "viewMenu" },
     { role: "windowMenu" },
   ];
+}
+
+/**
+ * Everywhere else there is no app menu, so the item goes under File. Without
+ * a template of our own Electron shows its stock menu, which has no way to
+ * reach the installer at all — and the roles the macOS template uses
+ * (`about`, `services`, `hide`) are AppKit's, so they have no place here.
+ */
+function defaultTemplate(): MenuItemConstructorOptions[] {
+  return [
+    {
+      label: "File",
+      submenu: [installCliItem(), { type: "separator" }, { role: "quit" }],
+    },
+    { role: "editMenu" },
+    { role: "viewMenu" },
+    { role: "windowMenu" },
+  ];
+}
 
+export function setupAppMenu() {
+  const template = process.platform === "darwin" ? macTemplate() : defaultTemplate();
   Menu.setApplicationMenu(Menu.buildFromTemplate(template));
 }
diff --git a/apps/web/src/lib/desktop-app.ts b/apps/web/src/lib/desktop-app.ts
index ba502898..d3c27375 100644
--- a/apps/web/src/lib/desktop-app.ts
+++ b/apps/web/src/lib/desktop-app.ts
@@ -7,10 +7,10 @@ import { toast } from "somoto";
 import { track } from "@/lib/analytics";
 
 /**
- * Electron Forge only makes darwin artifacts, so releases are macOS-only, and
- * the DMG name is version-independent (see `MakerDMG` in `forge.config.ts`) —
- * which is what lets GitHub's `/releases/latest/download/` alias resolve to the
- * newest build.
+ * The download promos point at the macOS DMG, which is the release asset the
+ * Homebrew cask consumes too. Its name is version-independent (see `MakerDMG` in
+ * `forge.config.ts`) — which is what lets GitHub's `/releases/latest/download/`
+ * alias resolve to the newest build.
  */
 const DOWNLOAD_URL =
   "https://github.com/diffusionstudio/editor/releases/latest/download/Diffusion-Studio-arm64.dmg";
diff --git a/package-lock.json b/package-lock.json
index d48abb1a..7d79cd52 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -59,7 +59,9 @@
       },
       "devDependencies": {
         "@electron-forge/cli": "^7.11.1",
+        "@electron-forge/maker-deb": "^7.11.1",
         "@electron-forge/maker-dmg": "^7.11.1",
+        "@electron-forge/maker-rpm": "^7.11.1",
         "@electron-forge/maker-zip": "^7.11.1",
         "@electron-forge/publisher-github": "^7.11.1",
         "@types/babel__core": "^7.20.5",
@@ -786,6 +788,23 @@
         "node": ">= 16.4.0"
       }
     },
+    "node_modules/@electron-forge/maker-deb": {
+      "version": "7.11.2",
+      "resolved": "https://registry.npmjs.org/@electron-forge/maker-deb/-/maker-deb-7.11.2.tgz",
+      "integrity": "sha512-MYSdCTsqzKNmsmaq7CIFh2kJdBWUZ4njxnVGrIRClzueVITk5Kots3+eQo+e5QQLvXTVn2XTNDc2nYjvtBh+Mw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@electron-forge/maker-base": "7.11.2",
+        "@electron-forge/shared-types": "7.11.2"
+      },
+      "engines": {
+        "node": ">= 16.4.0"
+      },
+      "optionalDependencies": {
+        "electron-installer-debian": "^3.2.0"
+      }
+    },
     "node_modules/@electron-forge/maker-dmg": {
       "version": "7.11.2",
       "resolved": "https://registry.npmjs.org/@electron-forge/maker-dmg/-/maker-dmg-7.11.2.tgz",
@@ -804,6 +823,23 @@
         "electron-installer-dmg": "^5.0.1"
       }
     },
+    "node_modules/@electron-forge/maker-rpm": {
+      "version": "7.11.2",
+      "resolved": "https://registry.npmjs.org/@electron-forge/maker-rpm/-/maker-rpm-7.11.2.tgz",
+      "integrity": "sha512-BEj/DcW6bSpmOyKUa3UsOgT7Hm3ZuP0Wa6OuQEunjxeCWn7yoDTDtjuYA0xRvzk+T4NCyDO3RBGjy6nYNSPU2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@electron-forge/maker-base": "7.11.2",
+        "@electron-forge/shared-types": "7.11.2"
+      },
+      "engines": {
+        "node": ">= 16.4.0"
+      },
+      "optionalDependencies": {
+        "electron-installer-redhat": "^3.2.0"
+      }
+    },
     "node_modules/@electron-forge/maker-zip": {
       "version": "7.11.2",
       "resolved": "https://registry.npmjs.org/@electron-forge/maker-zip/-/maker-zip-7.11.2.tgz",
@@ -4127,6 +4163,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/fs-extra": {
+      "version": "9.0.13",
+      "resolved": "https://registry.npmjs.org/@types/fs-extra/-/fs-extra-9.0.13.tgz",
+      "integrity": "sha512-nEnwB++1u5lVDM2UI4c1+5R+FYaKfaAzS4OococimjVm3nQw3TuzH5UNsocrcTBbhnerblyHj4A49qXbIiZdpA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/har-format": {
       "version": "1.2.16",
       "resolved": "https://registry.npmjs.org/@types/har-format/-/har-format-1.2.16.tgz",
@@ -6210,6 +6257,242 @@
         "node": ">= 22.12.0"
       }
     },
+    "node_modules/electron-installer-common": {
+      "version": "0.10.4",
+      "resolved": "https://registry.npmjs.org/electron-installer-common/-/electron-installer-common-0.10.4.tgz",
+      "integrity": "sha512-8gMNPXfAqUE5CfXg8RL0vXpLE9HAaPkgLXVoHE3BMUzogMWenf4LmwQ27BdCUrEhkjrKl+igs2IHJibclR3z3Q==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "@electron/asar": "^3.2.5",
+        "@malept/cross-spawn-promise": "^1.0.0",
+        "debug": "^4.1.1",
+        "fs-extra": "^9.0.0",
+        "glob": "^7.1.4",
+        "lodash": "^4.17.15",
+        "parse-author": "^2.0.0",
+        "semver": "^7.1.1",
+        "tmp-promise": "^3.0.2"
+      },
+      "engines": {
+        "node": ">= 10.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/electron-userland/electron-installer-common?sponsor=1"
+      },
+      "optionalDependencies": {
+        "@types/fs-extra": "^9.0.1"
+      }
+    },
+    "node_modules/electron-installer-common/node_modules/@malept/cross-spawn-promise": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@malept/cross-spawn-promise/-/cross-spawn-promise-1.1.1.tgz",
+      "integrity": "sha512-RTBGWL5FWQcg9orDOCcp4LvItNzUPcyEU9bwaeJX0rJ1IQxzucC48Y0/sQLp/g6t99IQgAlGIaesJS+gTn7tVQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/malept"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/subscription/pkg/npm-.malept-cross-spawn-promise?utm_medium=referral&utm_source=npm_fund"
+        }
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "cross-spawn": "^7.0.1"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/electron-installer-common/node_modules/fs-extra": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz",
+      "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "at-least-node": "^1.0.0",
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/electron-installer-debian": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/electron-installer-debian/-/electron-installer-debian-3.2.0.tgz",
+      "integrity": "sha512-58ZrlJ1HQY80VucsEIG9tQ//HrTlG6sfofA3nRGr6TmkX661uJyu4cMPPh6kXW+aHdq/7+q25KyQhDrXvRL7jw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin",
+        "linux"
+      ],
+      "dependencies": {
+        "@malept/cross-spawn-promise": "^1.0.0",
+        "debug": "^4.1.1",
+        "electron-installer-common": "^0.10.2",
+        "fs-extra": "^9.0.0",
+        "get-folder-size": "^2.0.1",
+        "lodash": "^4.17.4",
+        "word-wrap": "^1.2.3",
+        "yargs": "^16.0.2"
+      },
+      "bin": {
+        "electron-installer-debian": "src/cli.js"
+      },
+      "engines": {
+        "node": ">= 10.0.0"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/@malept/cross-spawn-promise": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@malept/cross-spawn-promise/-/cross-spawn-promise-1.1.1.tgz",
+      "integrity": "sha512-RTBGWL5FWQcg9orDOCcp4LvItNzUPcyEU9bwaeJX0rJ1IQxzucC48Y0/sQLp/g6t99IQgAlGIaesJS+gTn7tVQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/malept"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/subscription/pkg/npm-.malept-cross-spawn-promise?utm_medium=referral&utm_source=npm_fund"
+        }
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "cross-spawn": "^7.0.1"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/cliui": {
+      "version": "7.0.4",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz",
+      "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==",
+      "dev": true,
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.0",
+        "wrap-ansi": "^7.0.0"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/electron-installer-debian/node_modules/fs-extra": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz",
+      "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "at-least-node": "^1.0.0",
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/yargs": {
+      "version": "16.2.2",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.2.tgz",
+      "integrity": "sha512-Nt9ZJjXTv5R8MHbqby/wXQ6Gi0Bb3TcYZkR1bzuL4yB2OxWPkXknz513gEF0GoA6tn00UpbPvERW8rzCuWCA6w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "cliui": "^7.0.2",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.0",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^20.2.2"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/electron-installer-debian/node_modules/yargs-parser": {
+      "version": "20.2.9",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz",
+      "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==",
+      "dev": true,
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/electron-installer-dmg": {
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/electron-installer-dmg/-/electron-installer-dmg-5.0.1.tgz",
@@ -6232,6 +6515,172 @@
         "appdmg": "^0.6.4"
       }
     },
+    "node_modules/electron-installer-redhat": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/electron-installer-redhat/-/electron-installer-redhat-3.4.0.tgz",
+      "integrity": "sha512-gEISr3U32Sgtj+fjxUAlSDo3wyGGq6OBx7rF5UdpIgbnpUvMN4W5uYb0ThpnAZ42VEJh/3aODQXHbFS4f5J3Iw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin",
+        "linux"
+      ],
+      "dependencies": {
+        "@malept/cross-spawn-promise": "^1.0.0",
+        "debug": "^4.1.1",
+        "electron-installer-common": "^0.10.2",
+        "fs-extra": "^9.0.0",
+        "lodash": "^4.17.15",
+        "word-wrap": "^1.2.3",
+        "yargs": "^16.0.2"
+      },
+      "bin": {
+        "electron-installer-redhat": "src/cli.js"
+      },
+      "engines": {
+        "node": ">= 10.0.0"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/@malept/cross-spawn-promise": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@malept/cross-spawn-promise/-/cross-spawn-promise-1.1.1.tgz",
+      "integrity": "sha512-RTBGWL5FWQcg9orDOCcp4LvItNzUPcyEU9bwaeJX0rJ1IQxzucC48Y0/sQLp/g6t99IQgAlGIaesJS+gTn7tVQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/malept"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/subscription/pkg/npm-.malept-cross-spawn-promise?utm_medium=referral&utm_source=npm_fund"
+        }
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "cross-spawn": "^7.0.1"
+      },
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/cliui": {
+      "version": "7.0.4",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-7.0.4.tgz",
+      "integrity": "sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==",
+      "dev": true,
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.0",
+        "wrap-ansi": "^7.0.0"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/electron-installer-redhat/node_modules/fs-extra": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz",
+      "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "at-least-node": "^1.0.0",
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/yargs": {
+      "version": "16.2.2",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-16.2.2.tgz",
+      "integrity": "sha512-Nt9ZJjXTv5R8MHbqby/wXQ6Gi0Bb3TcYZkR1bzuL4yB2OxWPkXknz513gEF0GoA6tn00UpbPvERW8rzCuWCA6w==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "cliui": "^7.0.2",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.0",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^20.2.2"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/electron-installer-redhat/node_modules/yargs-parser": {
+      "version": "20.2.9",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz",
+      "integrity": "sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==",
+      "dev": true,
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/electron-to-chromium": {
       "version": "1.5.387",
       "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.387.tgz",
@@ -7215,6 +7664,15 @@
         "node": ">= 12"
       }
     },
+    "node_modules/gar": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/gar/-/gar-1.0.4.tgz",
+      "integrity": "sha512-w4n9cPWyP7aHxKxYHFQMegj7WIAsL/YX/C4Bs5Rr8s1H9M1rNtRWRsw+ovYMkXDQ5S4ZbYHsHAPmevPjPgw44w==",
+      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/generate-function": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/generate-function/-/generate-function-2.3.1.tgz",
@@ -7256,6 +7714,21 @@
         "node": "6.* || 8.* || >= 10.*"
       }
     },
+    "node_modules/get-folder-size": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/get-folder-size/-/get-folder-size-2.0.1.tgz",
+      "integrity": "sha512-+CEb+GDCM7tkOS2wdMKTn9vU7DgnKUTuDlehkNJKNSovdCOVxs14OfKCk4cvSaR3za4gj+OBdl9opPN9xrJ0zA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "gar": "^1.0.4",
+        "tiny-each-async": "2.0.3"
+      },
+      "bin": {
+        "get-folder-size": "bin/get-folder-size"
+      }
+    },
     "node_modules/get-intrinsic": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
@@ -8682,6 +9155,14 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/lodash.get": {
       "version": "4.4.2",
       "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz",
@@ -11317,6 +11798,14 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/tiny-each-async": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/tiny-each-async/-/tiny-each-async-2.0.3.tgz",
+      "integrity": "sha512-5ROII7nElnAirvFn8g7H7MtpfV1daMcyfTGQwsn/x2VtyV+VPiO5CjReCJtWLvoKTDEDmZocf3cNPraiMnBXLA==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/tinyest": {
       "version": "0.3.2",
       "resolved": "https://registry.npmjs.org/tinyest/-/tinyest-0.3.2.tgz",
@@ -11397,6 +11886,28 @@
         "node": ">=0.6.0"
       }
     },
+    "node_modules/tmp-promise": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/tmp-promise/-/tmp-promise-3.0.3.tgz",
+      "integrity": "sha512-RwM7MoPojPxsOBYnyd2hy0bxtIlVrihNs9pj5SUvY8Zz1sQcQG2tG1hSr8PDxfgEB8RNKDhqbIlroIarSNDNsQ==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tmp": "^0.2.0"
+      }
+    },
+    "node_modules/tmp-promise/node_modules/tmp": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",
+      "integrity": "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
     "node_modules/tn1150": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/tn1150/-/tn1150-0.1.0.tgz",

From 7d1ff9bc91abafee8548e65e072ef7ca3bfa6f31 Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 17:37:02 -0500
Subject: [PATCH 3/6] feat(cli): make dapi work on Linux
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four macOS assumptions kept the CLI from working off darwin:

- `dapi open` launched the app with `open -a`, gated to darwin, so
  elsewhere it could only talk to an instance that was already up. Linux
  now starts the executable the packaged wrapper points at, then one on
  PATH, then hands `diffusion://` to xdg-open — the scheme the deb and
  rpm packages register. A failure still falls through to the socket and
  its existing error.
- `dapi fonts` hard-failed off darwin. It now enumerates through
  fontconfig, mapping fc-list's weight axis onto CSS weights and
  collapsing the one-line-per-file listing into families; the `local()`
  sources it emits are the same shape the macOS path builds, so <text>
  and the browser resolve them unchanged.
- The staged `cli/bin/dapi` wrapper hardcoded the .app bundle's Electron
  binary, so the shipped CLI could not run at all on Linux. It now picks
  the layout it sits in — the bundle path on macOS, byte for byte as
  before, or the flat packager tree beside `resources/`.
- The in-app installer linked into /usr/local/bin behind an osascript
  admin prompt. On Linux it links into ~/.local/bin, which the user owns,
  so nothing has to be elevated.
---
 apps/cli/src/fonts.ts              | 129 ++++++++++++++++++++++++++---
 apps/cli/src/index.ts              |  61 ++++++++++++--
 apps/desktop/scripts/stage-cli.mjs |  22 ++++-
 apps/desktop/src/cli-install.ts    |  33 ++++++--
 reference/fonts.md                 |   2 +-
 reference/jsx/fonts.md             |   2 +-
 reference/open.md                  |   5 +-
 7 files changed, 220 insertions(+), 34 deletions(-)

diff --git a/apps/cli/src/fonts.ts b/apps/cli/src/fonts.ts
index d2de7964..9d4cc5c1 100644
--- a/apps/cli/src/fonts.ts
+++ b/apps/cli/src/fonts.ts
@@ -63,17 +63,7 @@ function run() {
 }
 `;
 
-export type ListLocalFontsOptions = {
-  familyPattern?: string;
-  weights?: string[];
-  style?: "normal" | "italic";
-  limit?: number;
-};
-
-export function listLocalFonts(options: ListLocalFontsOptions = {}): FontFamily[] {
-  if (platform() !== "darwin") {
-    throw new Error("fonts is only supported on macOS.");
-  }
+function listDarwinFonts(): FontFamily[] {
   const result = spawnSync("osascript", ["-l", "JavaScript", "-e", LIST_FONTS_JXA], {
     encoding: "utf8",
     maxBuffer: 16 * 1024 * 1024,
@@ -81,8 +71,123 @@ export function listLocalFonts(options: ListLocalFontsOptions = {}): FontFamily[
   if (result.status !== 0) {
     throw new Error(result.stderr.trim() || "Failed to enumerate fonts.");
   }
+  return JSON.parse(result.stdout.trim()) as FontFamily[];
+}
+
+// One line per font file, so a family arrives spread over many lines and the
+// same variant repeats whenever it ships in several formats.
+const FC_LIST_FORMAT = "%{family}\\t%{style[0]}\\t%{weight}\\t%{slant}\\t%{postscriptname}\\n";
+
+// fontconfig's weight axis is its own scale, not CSS's: these are its named
+// steps paired with the CSS weight each stands for. Anything between two
+// steps is interpolated, so an unnamed intermediate weight still lands on a
+// sensible value instead of being dropped.
+const FC_WEIGHTS: readonly (readonly [fc: number, css: number])[] = [
+  [0, 100], // thin
+  [40, 200], // extralight
+  [50, 300], // light
+  [75, 400], // book
+  [80, 400], // regular
+  [100, 500], // medium
+  [180, 600], // demibold
+  [200, 700], // bold
+  [205, 800], // extrabold
+  [210, 900], // black
+];
+
+function fcWeightToCss(weight: number): string {
+  let css = 900;
+  let previous: readonly [number, number] | undefined;
+  for (const step of FC_WEIGHTS) {
+    const [fc, value] = step;
+    if (weight <= fc) {
+      css = previous ? previous[1] + ((weight - previous[0]) / (fc - previous[0])) * (value - previous[1]) : value;
+      break;
+    }
+    previous = step;
+  }
+  return String(Math.round(css / 100) * 100);
+}
 
-  const all = JSON.parse(result.stdout.trim()) as FontFamily[];
+function listFontconfigFonts(): FontFamily[] {
+  const result = spawnSync("fc-list", ["--format", FC_LIST_FORMAT], {
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error) {
+    throw new Error("Listing fonts needs fontconfig: `fc-list` could not be run. Install the fontconfig package.");
+  }
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "fontconfig (`fc-list`) failed to enumerate fonts.");
+  }
+
+  // Keyed by family, then by weight+style, which collapses the repeats. A face
+  // that also carries a narrower family name ("DejaVu Sans,DejaVu Sans
+  // Condensed") is the less canonical member of the family it is filed under,
+  // so that count breaks ties for a weight and style two faces both claim.
+  const families = new Map<string, Map<string, { variant: FontVariant; names: number }>>();
+  for (const line of result.stdout.split("\n")) {
+    const [familyList, styleName, weight, slant, postscriptName] = line.split("\t");
+    if (!familyList || !weight || !slant) continue;
+
+    const familyNames = familyList.split(",");
+    const family = familyNames[0];
+    if (family.startsWith(".")) continue;
+
+    // A variable font also lists its axis ranges (`[0 210]`); those describe
+    // no single variant, and its named instances come as their own lines.
+    const fcWeight = Number(weight);
+    const fcSlant = Number(slant);
+    if (!Number.isFinite(fcWeight) || !Number.isFinite(fcSlant)) continue;
+
+    const css = fcWeightToCss(fcWeight);
+    const style = fcSlant === 0 ? "normal" : "italic";
+    let variants = families.get(family);
+    if (!variants) {
+      variants = new Map();
+      families.set(family, variants);
+    }
+    const key = `${css} ${style}`;
+    const names = familyNames.length;
+    const claimed = variants.get(key);
+    if (claimed && claimed.names <= names) continue;
+
+    const fullName = !styleName || styleName === "Regular" ? family : `${family} ${styleName}`;
+    const locals = postscriptName ? [fullName, postscriptName] : [fullName];
+    const source = locals.map((name) => `local('${name}')`).join(", ");
+    variants.set(key, { variant: { weight: css, style, source }, names });
+  }
+
+  // fc-list emits in cache order; sort so the listing reads like the macOS one.
+  return [...families]
+    .map(([family, variants]) => {
+      const sorted = [...variants.values()].map((entry) => entry.variant);
+      sorted.sort((a, b) => a.weight.localeCompare(b.weight) || a.style.localeCompare(b.style));
+      return { family, variants: sorted };
+    })
+    .sort((a, b) => a.family.localeCompare(b.family));
+}
+
+function enumerateFonts(): FontFamily[] {
+  switch (platform()) {
+    case "darwin":
+      return listDarwinFonts();
+    case "linux":
+      return listFontconfigFonts();
+    default:
+      throw new Error("fonts is only supported on macOS and Linux.");
+  }
+}
+
+export type ListLocalFontsOptions = {
+  familyPattern?: string;
+  weights?: string[];
+  style?: "normal" | "italic";
+  limit?: number;
+};
+
+export function listLocalFonts(options: ListLocalFontsOptions = {}): FontFamily[] {
+  const all = enumerateFonts();
   const pattern = options.familyPattern?.toLowerCase();
   const weights = options.weights && options.weights.length > 0 ? new Set(options.weights) : null;
   const { style, limit } = options;
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 184dac9b..54e68de3 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -3,7 +3,7 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -333,16 +333,63 @@ async function checkNode(id: string): Promise<void> {
 type OpenOptions = { background?: boolean };
 
 /** `open -a` on a running app only activates it, so this is safe to always run. */
-function launchApp(background: boolean): Promise<boolean> {
+function launchDarwin(background: boolean): Promise<boolean> {
   const args = background ? ["-g", "-a", APP_NAME, "--args", "--hidden"] : ["-a", APP_NAME];
   return new Promise((res) => execFile("open", args, (err) => res(!err)));
 }
 
+// The app has to outlive this process, so the child is detached and its handle
+// released. A missing binary is reported asynchronously, which is why the two
+// events are raced instead of the call being wrapped in a try.
+function spawnDetached(command: string, args: string[]): Promise<boolean> {
+  const { promise, resolve: res } = Promise.withResolvers<boolean>();
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.once("error", () => res(false));
+  child.once("spawn", () => {
+    child.unref();
+    res(true);
+  });
+  return promise;
+}
+
+// The executable electron-packager emits for the Linux build, which the deb
+// and rpm packages also expose on PATH.
+const LINUX_EXECUTABLE = "diffusion-studio";
+
+// A second instance hands its argv to the running one, so relaunching the
+// executable activates the app the same way `open -a` does on macOS.
+async function launchLinux(background: boolean): Promise<boolean> {
+  const args = background ? ["--hidden"] : [];
+
+  // The packaged wrapper exports the root of the app it was shipped in, so an
+  // installed CLI starts its own app rather than whichever one is on PATH.
+  const root = process.env.DIFFUSION_APP_PATH;
+  const installed = root ? join(root, LINUX_EXECUTABLE) : undefined;
+  if (installed && existsSync(installed) && (await spawnDetached(installed, args))) return true;
+
+  if (await spawnDetached(LINUX_EXECUTABLE, args)) return true;
+
+  // The deb and rpm packages register the `diffusion` scheme, so the desktop
+  // handler still finds the app when the executable is not on PATH. xdg-open
+  // hands the URL over and exits, reporting whether anything took it, and it
+  // forwards no arguments, so this last resort always surfaces a window.
+  const { promise, resolve: res } = Promise.withResolvers<boolean>();
+  execFile("xdg-open", ["diffusion://"], (err) => res(!err));
+  return promise;
+}
+
+function launchApp(background: boolean): Promise<boolean> {
+  if (process.platform === "darwin") return launchDarwin(background);
+  if (process.platform === "linux") return launchLinux(background);
+  return Promise.resolve(false);
+}
+
 async function openProject(path: string | undefined, opts: OpenOptions): Promise<void> {
-  // Launching is macOS's job; elsewhere (and when the app is not installed,
-  // e.g. a dev checkout run from the terminal) fall through to the socket,
-  // which answers if the app is running and errors usefully if not.
-  const launched = process.platform === "darwin" && (await launchApp(opts.background ?? false));
+  // Launching needs a way to find the app; where there is none (and when the
+  // app is not installed, e.g. a dev checkout run from the terminal) fall
+  // through to the socket, which answers if the app is running and errors
+  // usefully if not.
+  const launched = await launchApp(opts.background ?? false);
 
   try {
     // A cold launch needs the renderer up before the app can answer; when
@@ -791,7 +838,7 @@ program
 program
   .command("fonts")
   .description(
-    `List the local fonts available on this machine (macOS only; does not require the app). These family names are valid \`fontFamily\` values on <text>; each family lists its variants.`,
+    `List the local fonts available on this machine (macOS and Linux; does not require the app). These family names are valid \`fontFamily\` values on <text>; each family lists its variants.`,
   )
   .option("-f, --family <pattern>", "filter to families whose name contains <pattern> (case-insensitive)")
   .option("-w, --weight <weights...>", "filter to variants with the given CSS weight(s), e.g. -w 400 700")
diff --git a/apps/desktop/scripts/stage-cli.mjs b/apps/desktop/scripts/stage-cli.mjs
index 90590cda..947dbb05 100644
--- a/apps/desktop/scripts/stage-cli.mjs
+++ b/apps/desktop/scripts/stage-cli.mjs
@@ -50,7 +50,12 @@ execFileSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund", "--no-p
 
 // The wrapper runs the CLI bundle on the app's own Electron binary in Node
 // mode, so users need no separate Node install. It resolves symlinks first
-// because both Homebrew and the in-app installer link it into PATH.
+// because both Homebrew and the in-app installer link it into PATH, then
+// works out which packaged layout it sits in: on macOS the wrapper is at
+// Contents/Resources/cli/bin, beside Contents/MacOS, while electron-packager
+// emits a flat Linux tree with resources/ next to the executable — one level
+// closer to the app root. The Linux name is packagerConfig.executableName
+// (see forge.config.ts), which only that build renames.
 const wrapper = `#!/bin/sh
 SELF="$0"
 while [ -L "$SELF" ]; do
@@ -61,8 +66,19 @@ while [ -L "$SELF" ]; do
   esac
 done
 DIR="$(cd "$(dirname "$SELF")" && pwd)"
-export DIFFUSION_APP_PATH="$(cd "$DIR/../../../.." && pwd)"
-ELECTRON_RUN_AS_NODE=1 exec "$DIR/../../../MacOS/Diffusion Studio" "$DIR/../dapi.js" "$@"
+if [ -x "$DIR/../../../MacOS/Diffusion Studio" ]; then
+  ELECTRON="$DIR/../../../MacOS/Diffusion Studio"
+  APP_ROOT="$DIR/../../../.."
+else
+  APP_ROOT="$DIR/../../.."
+  ELECTRON="$APP_ROOT/diffusion-studio"
+  if [ ! -x "$ELECTRON" ]; then
+    echo "dapi: no application executable at $ELECTRON" >&2
+    exit 1
+  fi
+fi
+export DIFFUSION_APP_PATH="$(cd "$APP_ROOT" && pwd)"
+ELECTRON_RUN_AS_NODE=1 exec "$ELECTRON" "$DIR/../dapi.js" "$@"
 `;
 writeFileSync(join(stageDir, "bin", "dapi"), wrapper);
 chmodSync(join(stageDir, "bin", "dapi"), 0o755);
diff --git a/apps/desktop/src/cli-install.ts b/apps/desktop/src/cli-install.ts
index 8e7d800d..c58c85fc 100644
--- a/apps/desktop/src/cli-install.ts
+++ b/apps/desktop/src/cli-install.ts
@@ -4,31 +4,47 @@
 
 import { app } from "electron";
 import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import type { CliInstallResult } from "./main-channels";
 
-export const CLI_LINK_PATH = "/usr/local/bin/dapi";
+// Where each platform keeps user-installed commands: /usr/local/bin needs
+// elevation, ~/.local/bin is on PATH on modern distributions and belongs to
+// the user, so linking there asks for nothing.
+export const CLI_LINK_PATH =
+  process.platform === "linux" ? join(homedir(), ".local", "bin", "dapi") : "/usr/local/bin/dapi";
 
 // The dev workflow links the workspace build into Homebrew's bin instead
 // (`symlink:create` in apps/cli), so both locations count as installed.
 const DEV_LINK_PATH = "/opt/homebrew/bin/dapi";
 
 export function isCliInstalled(): boolean {
-  return existsSync(CLI_LINK_PATH) || existsSync(DEV_LINK_PATH);
+  if (existsSync(CLI_LINK_PATH)) return true;
+  return process.platform === "darwin" && existsSync(DEV_LINK_PATH);
 }
 
+// The staged wrapper inside the app's resources, the file both platforms link.
+const CLI_WRAPPER_PATH = join(process.resourcesPath, "cli", "bin", "dapi");
+
 // Linking into /usr/local/bin needs elevation; osascript shows the standard
 // macOS admin prompt so the app itself never asks for credentials.
-function linkCli(): Promise<void> {
-  const wrapper = join(process.resourcesPath, "cli", "bin", "dapi");
-  const shell = `mkdir -p /usr/local/bin && ln -sf '${wrapper}' '${CLI_LINK_PATH}'`;
+function linkCliWithPrompt(): Promise<void> {
+  const shell = `mkdir -p /usr/local/bin && ln -sf '${CLI_WRAPPER_PATH}' '${CLI_LINK_PATH}'`;
   const script = `do shell script "${shell.replaceAll('"', '\\"')}" with administrator privileges`;
   return new Promise((resolve, reject) => {
     execFile("osascript", ["-e", script], (err) => (err ? reject(err) : resolve()));
   });
 }
 
+// The user owns ~/.local/bin, so the link is a plain filesystem operation.
+// Replacing an existing link mirrors `ln -sf`.
+function linkCliDirectly(): void {
+  mkdirSync(dirname(CLI_LINK_PATH), { recursive: true });
+  rmSync(CLI_LINK_PATH, { force: true });
+  symlinkSync(CLI_WRAPPER_PATH, CLI_LINK_PATH);
+}
+
 export async function installCli(): Promise<CliInstallResult> {
   if (!app.isPackaged) {
     return {
@@ -37,7 +53,8 @@ export async function installCli(): Promise<CliInstallResult> {
     };
   }
   try {
-    await linkCli();
+    if (process.platform === "linux") linkCliDirectly();
+    else await linkCliWithPrompt();
     return { status: "installed" };
   } catch (e) {
     const message = (e as Error).message ?? "";
diff --git a/reference/fonts.md b/reference/fonts.md
index 34b96b4e..433c8e6b 100644
--- a/reference/fonts.md
+++ b/reference/fonts.md
@@ -1,6 +1,6 @@
 # `dapi fonts`
 
-Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).
+Lists local fonts available on this machine. macOS and Linux (through fontconfig — `fc-list`). Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).
 
 ## Options
 
diff --git a/reference/jsx/fonts.md b/reference/jsx/fonts.md
index dce05467..6a34d908 100644
--- a/reference/jsx/fonts.md
+++ b/reference/jsx/fonts.md
@@ -1,6 +1,6 @@
 # Fonts
 
-Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
+Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../context.md) as `fontFamilies`. The system resolves these families for both the native renderer and the browser — CoreText on macOS, fontconfig on Linux — so there is nothing to bundle or load.
 
 ## Native `<text>`
 
diff --git a/reference/open.md b/reference/open.md
index 934ee176..149bb16f 100644
--- a/reference/open.md
+++ b/reference/open.md
@@ -44,5 +44,6 @@ With no path, nothing: exit code `0` says the app is up.
 ## Errors
 
 - The path exists but is not a folder.
-- Off macOS, the app cannot be launched; the command then requires it to
-  already be running.
+- The app could not be launched — on Linux, when neither its executable nor a
+  handler for the `diffusion://` scheme is installed, and on every other
+  platform than macOS; the command then requires the app to already be running.

From 145b4b97bfcc4788bd47d1702dbb0c2a336b51ee Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 18:14:11 -0500
Subject: [PATCH 4/6] feat(desktop): build an AppImage as well
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A deb and an rpm cover Debian/Ubuntu and Fedora; everywhere else there
was nothing to hand a user. An AppImage is one executable file that runs
without root or a package manager, so it is the artifact for the rest.
The maker needs `mksquashfs` on the build host, which the release
workflow now installs.

Both Linux packages and the AppImage share the FreeDesktop metadata, and
both now name the executable explicitly: `bin` defaults to the sanitized
package name (`diffusionstudio-desktop`), which is not what
electron-packager emits.

The in-app CLI installer refuses inside an AppImage rather than linking
into it: an AppImage runs from a mount under /tmp that disappears with
the process, so the link would dangle. The bundled dapi still works from
a running AppImage, and the message names the two options that persist —
the deb/rpm, or an unpacked AppImage.
---
 .github/workflows/release.yml   |  2 +-
 README.md                       |  4 ++++
 apps/desktop/forge.config.ts    | 27 ++++++++++++++++++-----
 apps/desktop/package.json       |  1 +
 apps/desktop/src/cli-install.ts | 14 ++++++++++++
 package-lock.json               | 39 +++++++++++++++++++++++++++++++++
 6 files changed, 81 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0ea703a5..98e36187 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -84,7 +84,7 @@ jobs:
         run: cp apps/web/.env.example apps/web/.env
 
       - name: Install packaging tools
-        run: sudo apt-get update && sudo apt-get install -y dpkg-dev fakeroot rpm
+        run: sudo apt-get update && sudo apt-get install -y dpkg-dev fakeroot rpm squashfs-tools
 
       - name: Build and publish draft release
         env:
diff --git a/README.md b/README.md
index ae64b883..5bdcc184 100644
--- a/README.md
+++ b/README.md
@@ -251,6 +251,10 @@ npm run symlink:create --workspace=@diffusionstudio/cli
 
 The link points at the CLI build, which `npm run dev:desktop` refreshes on every start, so the linked `dapi` always runs the latest code.
 
+`npm run make` builds the artifacts for the host platform: a ZIP and a DMG on macOS, and a ZIP, a `.deb`, an `.rpm` and an AppImage on Linux. The Linux makers need their own tools on the build host — `dpkg-dev` and `fakeroot` for the deb, `rpm` for the rpm, `squashfs-tools` for the AppImage — and each maker only runs when its tool is there.
+
+On a Wayland session the app runs through XWayland, which is what Chromium picks by default; native Wayland (fractional scaling, no XWayland blur) is available with `ELECTRON_OZONE_PLATFORM_HINT=auto`, though it renders incorrectly on some drivers.
+
 Before sending a PR:
 
 ```sh
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index f788b423..9955fa61 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -4,6 +4,7 @@
 
 import type { ForgeConfig } from '@electron-forge/shared-types';
 import { MakerDeb, type MakerDebConfig } from '@electron-forge/maker-deb';
+import MakerAppImage, { type MakerAppImageConfig } from '@reforged/maker-appimage';
 import { MakerDMG } from '@electron-forge/maker-dmg';
 import { MakerRpm, type MakerRpmConfig } from '@electron-forge/maker-rpm';
 import { MakerZIP } from '@electron-forge/maker-zip';
@@ -19,18 +20,30 @@ const { version } = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package
 // execs it, so both sides agree on the lowercase form.
 const LINUX_EXECUTABLE = 'diffusion-studio';
 
-// FreeDesktop metadata shared by both Linux packages. The mime type is what
+// FreeDesktop metadata shared by every Linux artifact. The mime type is what
 // registers `diffusion://` with xdg, so the auth and checkout deep links reach
-// the app the same way the macOS bundle's protocol handler does.
-const linuxPackage = {
+// the app the same way the macOS bundle's protocol handler does — for the
+// AppImage only once its desktop file is integrated (by the desktop
+// environment's prompt, or AppImageLauncher).
+const linuxDesktop = {
   name: LINUX_EXECUTABLE,
+  // What lands in the desktop entry's `Exec`, and the file the AppImage maker
+  // looks for inside the packaged tree. Both default to the sanitized
+  // package name (`diffusionstudio-desktop`), which is not what is packaged.
+  bin: LINUX_EXECUTABLE,
   productName: 'Diffusion Studio',
   genericName: 'Video Editor',
-  description: 'Edit videos with coding agents, and refine any output in a full editing environment',
-  homepage: 'https://diffusion.studio',
+  keywords: ['video', 'editor', 'agent'],
   icon: './assets/icon.png',
   categories: ['AudioVideo', 'Video'],
   mimeType: ['x-scheme-handler/diffusion'],
+} satisfies NonNullable<MakerAppImageConfig['options']>;
+
+// deb and rpm carry package metadata the desktop entry has no field for.
+const linuxPackage = {
+  ...linuxDesktop,
+  description: 'Edit videos with coding agents, and refine any output in a full editing environment',
+  homepage: 'https://diffusion.studio',
 } satisfies NonNullable<MakerDebConfig['options']> & NonNullable<MakerRpmConfig['options']>;
 
 const config: ForgeConfig = {
@@ -90,6 +103,10 @@ const config: ForgeConfig = {
     ),
     new MakerDeb({ options: linuxPackage }, ['linux']),
     new MakerRpm({ options: linuxPackage }, ['linux']),
+    // The format that runs on a distribution the deb and rpm do not cover:
+    // one file, no root, no package manager. Needs `mksquashfs` on the build
+    // host (squashfs-tools).
+    new MakerAppImage({ options: linuxDesktop }, ['linux']),
   ],
   publishers: [
     new PublisherGithub({
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 9687e1a7..bc590a96 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -31,6 +31,7 @@
     "@electron-forge/maker-rpm": "^7.11.1",
     "@electron-forge/maker-zip": "^7.11.1",
     "@electron-forge/publisher-github": "^7.11.1",
+    "@reforged/maker-appimage": "^5.3.1",
     "@types/babel__core": "^7.20.5",
     "@types/node": "^24.10.1",
     "electron": "^43.1.1",
diff --git a/apps/desktop/src/cli-install.ts b/apps/desktop/src/cli-install.ts
index c58c85fc..2b94f7ec 100644
--- a/apps/desktop/src/cli-install.ts
+++ b/apps/desktop/src/cli-install.ts
@@ -52,6 +52,20 @@ export async function installCli(): Promise<CliInstallResult> {
       error: "Installing the CLI is only available in the packaged app. Use `npm run symlink:create` in development.",
     };
   }
+
+  // An AppImage runs from a mount that only exists while it does
+  // (`/tmp/.mount_*`), so a link into its resources would dangle the moment
+  // the app quits. The bundled `dapi` works fine from inside a running one —
+  // it just has no path worth linking.
+  if (process.env.APPIMAGE) {
+    return {
+      status: "error",
+      error:
+        "An AppImage has no stable path to link from. Install the deb or rpm package to get dapi on PATH, " +
+        "or unpack this file once (`--appimage-extract`) and link the dapi wrapper under " +
+        "usr/lib/diffusion-studio/resources/cli/bin from the unpacked tree.",
+    };
+  }
   try {
     if (process.platform === "linux") linkCliDirectly();
     else await linkCliWithPrompt();
diff --git a/package-lock.json b/package-lock.json
index 7d79cd52..9b4723f2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -64,6 +64,7 @@
         "@electron-forge/maker-rpm": "^7.11.1",
         "@electron-forge/maker-zip": "^7.11.1",
         "@electron-forge/publisher-github": "^7.11.1",
+        "@reforged/maker-appimage": "^5.3.1",
         "@types/babel__core": "^7.20.5",
         "@types/node": "^24.10.1",
         "electron": "^43.1.1",
@@ -2892,6 +2893,37 @@
         "@octokit/openapi-types": "^12.11.0"
       }
     },
+    "node_modules/@reforged/maker-appimage": {
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/@reforged/maker-appimage/-/maker-appimage-5.3.1.tgz",
+      "integrity": "sha512-lJqSZO+/qZmkarZ9pKZgE5DnZxuEvRe7JXupLo6YSTEOL+bkETthWP3XCLgAxLDsLCwPuPmF1tooYCt2dcIRCQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@electron-forge/maker-base": "^6.0.0 || ^7.0.0",
+        "@reforged/maker-types": "^2.2.0",
+        "@spacingbat3/lss": "^1.0.0",
+        "semver": "^7.3.8"
+      },
+      "engines": {
+        "node": ">=19.0.0 || ^18.11.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/SpacingBat3/ReForged?sponsor=1"
+      }
+    },
+    "node_modules/@reforged/maker-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@reforged/maker-types/-/maker-types-2.2.0.tgz",
+      "integrity": "sha512-14B5Tu6fG2AWgH+bdsfJaQkAi8Bc7YC8GmMuNEWCJupU9IhvKHrdte3GAncBYO10yqSbsQx7Pi9xpyveJ5vL+Q==",
+      "dev": true,
+      "license": "ISC",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/SpacingBat3/ReForged?sponsor=1"
+      }
+    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.62.2",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.2.tgz",
@@ -3571,6 +3603,13 @@
         "solid-js": "^1.8.6"
       }
     },
+    "node_modules/@spacingbat3/lss": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@spacingbat3/lss/-/lss-1.2.0.tgz",
+      "integrity": "sha512-aywhxHNb6l7COooF3m439eT/6QN8E/RSl5IVboSKthMHcp0GlZYMSoS7546rqDLmFRxTD8f1tu/NIS9vtDwYAg==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/@supabase/auth-js": {
       "version": "2.109.0",
       "resolved": "https://registry.npmjs.org/@supabase/auth-js/-/auth-js-2.109.0.tgz",

From 1ae071ff512d845562c8e12640d95a95793dd318 Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 19:09:37 -0500
Subject: [PATCH 5/6] feat(desktop): package for Arch, and fix what a real
 package build hits

Dry-running the deb and rpm makers against the packaged tree, rather than
trusting their config, turned up two builds that could never have
succeeded, and comparing notes with #42 turned up a third:

- The deb had no `Maintainer`, one of the five fields dpkg-deb requires.
  It defaults to `package.json`'s `author`, which this workspace does not
  set, and the control template silently omits the field when it is
  undefined - so the release job would have failed on its first run.
- `@electron-forge/maker-rpm` (electron-installer-redhat 3.4.0) writes a
  spec whose `%install` runs `cp -r usr/*` relative to the build
  directory. rpm 4.20 moved that directory, so the copy fails on Fedora
  41+ and on recent Debian and Ubuntu
  (electron-userland/electron-installer-redhat#343, electron/forge#3701).
  Diagnosed in #42, which worked around it with a hand-written spec; this
  patches the template through the patch-package setup the repo already
  runs, so the maker keeps generating dependencies and metadata.
- MakerZIP shells out to `zip`, which is not installed everywhere. Named
  in the README with the other per-maker tools, and installed in CI.

Arch Linux support comes from #42: it has no Electron Forge maker, so a
script stages the forge output and runs makepkg. The PKGBUILD drops the
launcher shim that PR needed, because the Linux executable is renamed to
`diffusion-studio` and /usr/bin can link straight to it, and it puts
`dapi` on PATH directly, which a package can do and the AppImage cannot.

All four formats now install one desktop entry, kept in packaging/linux
so the makers and the PKGBUILD cannot drift: two of the three formats in
#42 registered `x-scheme-handler/diffusion` and the deb did not, which
is the difference between the auth and checkout deep links working and
silently doing nothing.

The CLI install dialog now only claims `dapi` is ready to run when the
link target is on the session PATH, and otherwise says which directory
to add - Debian and Fedora put ~/.local/bin there, Arch does not.

Co-authored-by: Tsurg <info@tsurg.com>
---
 .github/workflows/release.yml                 | 41 +++++++++++-
 README.md                                     |  4 +-
 apps/desktop/forge.config.ts                  | 41 +++++++-----
 apps/desktop/package.json                     |  1 +
 apps/desktop/scripts/make-arch.mjs            | 59 +++++++++++++++++
 apps/desktop/src/cli-install.ts               |  5 +-
 apps/desktop/src/menu.ts                      | 10 ++-
 packaging/arch/PKGBUILD                       | 63 +++++++++++++++++++
 packaging/linux/diffusion-studio.desktop      | 17 +++++
 patches/electron-installer-redhat+3.4.0.patch | 13 ++++
 10 files changed, 234 insertions(+), 20 deletions(-)
 create mode 100644 apps/desktop/scripts/make-arch.mjs
 create mode 100644 packaging/arch/PKGBUILD
 create mode 100644 packaging/linux/diffusion-studio.desktop
 create mode 100644 patches/electron-installer-redhat+3.4.0.patch

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 98e36187..020cc823 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -84,9 +84,48 @@ jobs:
         run: cp apps/web/.env.example apps/web/.env
 
       - name: Install packaging tools
-        run: sudo apt-get update && sudo apt-get install -y dpkg-dev fakeroot rpm squashfs-tools
+        run: sudo apt-get update && sudo apt-get install -y zip dpkg-dev fakeroot rpm squashfs-tools
 
       - name: Build and publish draft release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npm run publish --workspace=@diffusionstudio/desktop
+
+  # Arch has no Electron Forge maker, so this job runs the makepkg script in an
+  # Arch container. It attaches its artifact to the same draft release the
+  # other two jobs publish to, and carries no Apple secrets either.
+  publish-arch:
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    permissions:
+      contents: write
+    steps:
+      # The image is minimal: actions/checkout needs git, and makepkg needs
+      # base-devel. `sudo` is here because makepkg refuses to run as root,
+      # which is what a container job starts as.
+      - name: Install build tools
+        run: |
+          pacman -Sy --noconfirm archlinux-keyring
+          pacman -Syu --noconfirm base-devel git sudo nodejs npm
+
+      - uses: actions/checkout@v4
+
+      - run: npm ci
+
+      - name: Provide client env for web build
+        run: cp apps/web/.env.example apps/web/.env
+
+      - name: Build the Arch package as an unprivileged user
+        run: |
+          useradd -m builder
+          chown -R builder .
+          sudo -u builder npm run make:arch --workspace=@diffusionstudio/desktop
+
+      - name: Attach the package to the draft release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          pacman -S --noconfirm github-cli
+          gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 \
+            || gh release create "$GITHUB_REF_NAME" --draft --title "$GITHUB_REF_NAME" --generate-notes
+          gh release upload "$GITHUB_REF_NAME" apps/desktop/out/arch/*.pkg.tar.zst --clobber
diff --git a/README.md b/README.md
index 5bdcc184..05034bff 100644
--- a/README.md
+++ b/README.md
@@ -251,7 +251,9 @@ npm run symlink:create --workspace=@diffusionstudio/cli
 
 The link points at the CLI build, which `npm run dev:desktop` refreshes on every start, so the linked `dapi` always runs the latest code.
 
-`npm run make` builds the artifacts for the host platform: a ZIP and a DMG on macOS, and a ZIP, a `.deb`, an `.rpm` and an AppImage on Linux. The Linux makers need their own tools on the build host — `dpkg-dev` and `fakeroot` for the deb, `rpm` for the rpm, `squashfs-tools` for the AppImage — and each maker only runs when its tool is there.
+`npm run make` builds the artifacts for the host platform: a ZIP and a DMG on macOS, and a ZIP, a `.deb`, an `.rpm` and an AppImage on Linux. Each Linux maker needs its own tool on the build host — `zip` for the ZIP, `dpkg-dev` and `fakeroot` for the deb, `rpm` for the rpm, `squashfs-tools` for the AppImage — and fails if it is missing, so install the ones you want to build.
+
+Arch Linux has no Electron Forge maker, so its package is a script: `npm run make:arch --workspace=@diffusionstudio/desktop` writes `apps/desktop/out/arch/*.pkg.tar.zst` and needs `base-devel` (makepkg, which refuses to run as root). Every format installs the one desktop entry in [packaging/linux](packaging/linux).
 
 On a Wayland session the app runs through XWayland, which is what Chromium picks by default; native Wayland (fractional scaling, no XWayland blur) is available with `ELECTRON_OZONE_PLATFORM_HINT=auto`, though it renders incorrectly on some drivers.
 
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index 9955fa61..28a2b48f 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -20,32 +20,43 @@ const { version } = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package
 // execs it, so both sides agree on the lowercase form.
 const LINUX_EXECUTABLE = 'diffusion-studio';
 
-// FreeDesktop metadata shared by every Linux artifact. The mime type is what
-// registers `diffusion://` with xdg, so the auth and checkout deep links reach
-// the app the same way the macOS bundle's protocol handler does — for the
-// AppImage only once its desktop file is integrated (by the desktop
-// environment's prompt, or AppImageLauncher).
+// The desktop entry every Linux artifact installs, kept as one file so the deb,
+// the rpm, the AppImage and the Arch package cannot drift apart - and so the
+// PKGBUILD, which no maker touches, reads the same text.
+const DESKTOP_ENTRY = join(__dirname, '..', '..', 'packaging', 'linux', `${LINUX_EXECUTABLE}.desktop`);
+
+// What the makers themselves need: the entry above carries the FreeDesktop
+// fields, these name the files.
 const linuxDesktop = {
   name: LINUX_EXECUTABLE,
-  // What lands in the desktop entry's `Exec`, and the file the AppImage maker
-  // looks for inside the packaged tree. Both default to the sanitized
-  // package name (`diffusionstudio-desktop`), which is not what is packaged.
+  // What the AppImage maker looks for inside the packaged tree, and what the
+  // deb and rpm symlink into /usr/bin. Both default to the sanitized package
+  // name (`diffusionstudio-desktop`), which is not what is packaged.
   bin: LINUX_EXECUTABLE,
   productName: 'Diffusion Studio',
-  genericName: 'Video Editor',
-  keywords: ['video', 'editor', 'agent'],
   icon: './assets/icon.png',
-  categories: ['AudioVideo', 'Video'],
-  mimeType: ['x-scheme-handler/diffusion'],
+  desktopFile: DESKTOP_ENTRY,
 } satisfies NonNullable<MakerAppImageConfig['options']>;
 
-// deb and rpm carry package metadata the desktop entry has no field for.
+// deb and rpm carry package metadata the desktop entry has no field for, and
+// they take the entry under a different option name than the AppImage maker.
+// `Maintainer` is one of the five fields dpkg-deb requires and is derived from
+// `package.json`'s `author`, which this workspace does not set - without it the
+// deb build fails outright. rpm's mandatory `License` does come from
+// `package.json` (MPL-2.0), so it needs no packager.
+const { desktopFile, ...linuxCommon } = linuxDesktop;
 const linuxPackage = {
-  ...linuxDesktop,
+  ...linuxCommon,
+  desktopTemplate: desktopFile,
   description: 'Edit videos with coding agents, and refine any output in a full editing environment',
   homepage: 'https://diffusion.studio',
 } satisfies NonNullable<MakerDebConfig['options']> & NonNullable<MakerRpmConfig['options']>;
 
+const debPackage = {
+  ...linuxPackage,
+  maintainer: 'Diffusion Studio Inc. <support@diffusion.studio>',
+} satisfies NonNullable<MakerDebConfig['options']>;
+
 const config: ForgeConfig = {
   packagerConfig: {
     name: 'Diffusion Studio',
@@ -101,7 +112,7 @@ const config: ForgeConfig = {
       },
       ['darwin'],
     ),
-    new MakerDeb({ options: linuxPackage }, ['linux']),
+    new MakerDeb({ options: debPackage }, ['linux']),
     new MakerRpm({ options: linuxPackage }, ['linux']),
     // The format that runs on a distribution the deb and rpm do not cover:
     // one file, no root, no package manager. Needs `mksquashfs` on the build
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index bc590a96..e7464f13 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -22,6 +22,7 @@
     "package": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge package",
     "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge make",
     "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge publish",
+    "make:arch": "npm run package && node scripts/make-arch.mjs",
     "make:icns": "sh scripts/make-icns.sh"
   },
   "devDependencies": {
diff --git a/apps/desktop/scripts/make-arch.mjs b/apps/desktop/scripts/make-arch.mjs
new file mode 100644
index 00000000..fbe079d7
--- /dev/null
+++ b/apps/desktop/scripts/make-arch.mjs
@@ -0,0 +1,59 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+// Builds an Arch Linux package (.pkg.tar.zst) from the `electron-forge package`
+// output. Electron Forge has no Arch maker, so this is a script rather than a
+// maker; run it after `npm run package` (or `npm run make`).
+//
+// Adapted from https://github.com/diffusionstudio/editor/pull/42 by @Tsurgcom.
+// The staged tree lives in out/arch and the package lands beside it.
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = join(desktopDir, "..", "..");
+const require = createRequire(import.meta.url);
+const { version } = require(join(repoRoot, "package.json"));
+
+const PKG_NAME = "diffusion-studio";
+const outDir = join(desktopDir, "out");
+
+// electron-packager names the directory after the product, not the executable.
+const packaged = readdirSync(outDir).find((entry) => entry.startsWith("Diffusion Studio-linux-"));
+if (!packaged) {
+  console.error("make-arch: nothing packaged in out/. Run `npm run package` first.");
+  process.exit(1);
+}
+
+const archDir = join(outDir, "arch");
+rmSync(archDir, { recursive: true, force: true });
+mkdirSync(archDir, { recursive: true });
+
+// What makepkg unpacks: the app plus the two files the PKGBUILD installs.
+const srcName = `${PKG_NAME}-${version}-linux-x64`;
+const srcDir = join(archDir, srcName);
+cpSync(join(outDir, packaged), srcDir, { recursive: true });
+cpSync(join(repoRoot, "packaging", "linux", `${PKG_NAME}.desktop`), join(srcDir, `${PKG_NAME}.desktop`));
+cpSync(join(desktopDir, "assets", "icon.png"), join(srcDir, `${PKG_NAME}.png`));
+
+const tarball = `${srcName}.tar.gz`;
+execFileSync("tar", ["-czf", join(archDir, tarball), "-C", archDir, srcName], { stdio: "inherit" });
+
+writeFileSync(
+  join(archDir, "PKGBUILD"),
+  readFileSync(join(repoRoot, "packaging", "arch", "PKGBUILD"), "utf8").replaceAll("__VERSION__", version),
+);
+
+// makepkg refuses to run as root, which is what a container CI job starts as -
+// the workflow builds this step as an unprivileged user for that reason.
+execFileSync("makepkg", ["-f", "--noconfirm"], {
+  cwd: archDir,
+  stdio: "inherit",
+  env: { ...process.env, PACKAGER: "Diffusion Studio Inc. <support@diffusion.studio>" },
+});
+
+const built = readdirSync(archDir).find((entry) => entry.endsWith(".pkg.tar.zst"));
+console.log(`make-arch: wrote ${join(archDir, built)}`);
diff --git a/apps/desktop/src/cli-install.ts b/apps/desktop/src/cli-install.ts
index 2b94f7ec..469e671a 100644
--- a/apps/desktop/src/cli-install.ts
+++ b/apps/desktop/src/cli-install.ts
@@ -10,8 +10,9 @@ import { dirname, join } from "node:path";
 import type { CliInstallResult } from "./main-channels";
 
 // Where each platform keeps user-installed commands: /usr/local/bin needs
-// elevation, ~/.local/bin is on PATH on modern distributions and belongs to
-// the user, so linking there asks for nothing.
+// elevation, ~/.local/bin belongs to the user, so linking there asks for
+// nothing. Debian and Fedora put it on PATH for you, but not every
+// distribution does, so the menu checks before claiming the command is ready.
 export const CLI_LINK_PATH =
   process.platform === "linux" ? join(homedir(), ".local", "bin", "dapi") : "/usr/local/bin/dapi";
 
diff --git a/apps/desktop/src/menu.ts b/apps/desktop/src/menu.ts
index 4e5b2b70..ff63e505 100644
--- a/apps/desktop/src/menu.ts
+++ b/apps/desktop/src/menu.ts
@@ -4,6 +4,7 @@
 
 import { app, dialog, Menu } from "electron";
 import type { MenuItemConstructorOptions } from "electron";
+import { dirname } from "node:path";
 
 import { CLI_LINK_PATH, installCli } from "./cli-install";
 
@@ -11,10 +12,17 @@ async function installCliFromMenu() {
   const result = await installCli();
   if (result.status === "cancelled") return;
   if (result.status === "installed") {
+    // The session PATH is what a launcher-started app inherits; a directory
+    // only a shell rc file adds reads as missing, so this is worded as a
+    // condition rather than a claim about the user's shell.
+    const linkDir = dirname(CLI_LINK_PATH);
+    const onPath = (process.env.PATH ?? "").split(":").includes(linkDir);
     await dialog.showMessageBox({
       type: "info",
       message: "The dapi command line tool was installed.",
-      detail: `Linked at ${CLI_LINK_PATH}. Run "dapi --help" in a terminal to get started.`,
+      detail: onPath
+        ? `Linked at ${CLI_LINK_PATH}. Run "dapi --help" in a terminal to get started.`
+        : `Linked at ${CLI_LINK_PATH}. If "dapi" is not found, add ${linkDir} to your PATH.`,
     });
   } else {
     await dialog.showMessageBox({
diff --git a/packaging/arch/PKGBUILD b/packaging/arch/PKGBUILD
new file mode 100644
index 00000000..e6f078ba
--- /dev/null
+++ b/packaging/arch/PKGBUILD
@@ -0,0 +1,63 @@
+# Maintainer: Diffusion Studio Inc. <support@diffusion.studio>
+#
+# Packages the prebuilt app that `electron-forge package` leaves in
+# apps/desktop/out into an Arch Linux package. Adapted from the PKGBUILD in
+# https://github.com/diffusionstudio/editor/pull/42 by @Tsurgcom; the launcher
+# shim it carried is gone because the Linux executable is now renamed to
+# `diffusion-studio`, so /usr/bin can link straight to it.
+#
+# apps/desktop/scripts/make-arch.mjs stages this file and the source tarball,
+# substituting __VERSION__.
+pkgname=diffusion-studio
+pkgver=__VERSION__
+pkgrel=1
+pkgdesc="Edit videos with coding agents, and refine any output in a full editing environment"
+arch=('x86_64')
+url="https://diffusion.studio"
+license=('MPL-2.0')
+# Electron ships pre-stripped release binaries; stripping them again only
+# produces gdb-add-index noise and an empty -debug package.
+options=(!strip !debug)
+depends=(
+  'gtk3'
+  'nss'
+  'alsa-lib'
+  'at-spi2-core'
+  'libxss'
+  'libxtst'
+  'libxcursor'
+  'libxrandr'
+  'libxcomposite'
+  'libxdamage'
+  'libxfixes'
+  'mesa'
+  'ca-certificates'
+)
+optdepends=(
+  'xdg-utils: open exported files and diffusion:// links'
+  'fontconfig: font discovery for `dapi fonts` and the editor'
+)
+# Built from the local forge output, staged next to this file rather than
+# fetched from a URL.
+source=("diffusion-studio-$pkgver-linux-x64.tar.gz")
+sha256sums=('SKIP')
+
+package() {
+  cd "$srcdir/diffusion-studio-$pkgver-linux-x64"
+
+  install -d "$pkgdir/usr/lib/$pkgname"
+  cp -a . "$pkgdir/usr/lib/$pkgname/"
+
+  # Chromium's setuid sandbox helper, matching what the deb and rpm ship. It is
+  # only used where unprivileged user namespaces are unavailable.
+  chmod 4755 "$pkgdir/usr/lib/$pkgname/chrome-sandbox"
+
+  install -d "$pkgdir/usr/bin"
+  ln -s "/usr/lib/$pkgname/$pkgname" "$pkgdir/usr/bin/$pkgname"
+  # The dapi CLI ships inside the app's resources; a package can put it on PATH
+  # directly, so the in-app installer is only needed for the AppImage and ZIP.
+  ln -s "/usr/lib/$pkgname/resources/cli/bin/dapi" "$pkgdir/usr/bin/dapi"
+
+  install -Dm644 "$pkgname.desktop" "$pkgdir/usr/share/applications/$pkgname.desktop"
+  install -Dm644 "$pkgname.png" "$pkgdir/usr/share/pixmaps/$pkgname.png"
+}
diff --git a/packaging/linux/diffusion-studio.desktop b/packaging/linux/diffusion-studio.desktop
new file mode 100644
index 00000000..47850e5f
--- /dev/null
+++ b/packaging/linux/diffusion-studio.desktop
@@ -0,0 +1,17 @@
+[Desktop Entry]
+Version=1.5
+Type=Application
+Name=Diffusion Studio
+GenericName=Video Editor
+Comment=Edit videos with coding agents, and refine any output in a full editing environment
+Exec=diffusion-studio %U
+Icon=diffusion-studio
+Terminal=false
+StartupNotify=true
+# Groups the window with its launcher: Chromium reports the app name, not the
+# renamed executable.
+StartupWMClass=Diffusion Studio
+Categories=AudioVideo;Video;
+# Registers `diffusion://`, which is how the auth and checkout deep links come
+# back to the app - the same job `packagerConfig.protocols` does on macOS.
+MimeType=x-scheme-handler/diffusion;
diff --git a/patches/electron-installer-redhat+3.4.0.patch b/patches/electron-installer-redhat+3.4.0.patch
new file mode 100644
index 00000000..8300c110
--- /dev/null
+++ b/patches/electron-installer-redhat+3.4.0.patch
@@ -0,0 +1,13 @@
+diff --git a/node_modules/electron-installer-redhat/resources/spec.ejs b/node_modules/electron-installer-redhat/resources/spec.ejs
+index e07a8a3..3f9c2a9 100644
+--- a/node_modules/electron-installer-redhat/resources/spec.ejs
++++ b/node_modules/electron-installer-redhat/resources/spec.ejs
+@@ -24,7 +24,7 @@ print('\n\n\n') }
+ 
+ %>%install
+ mkdir -p %{buildroot}/usr/
+-cp <%= process.platform === 'darwin' ? '-R' : '-r' %> usr/* %{buildroot}/usr/
++cp <%= process.platform === 'darwin' ? '-R' : '-r' %> %{_topdir}/BUILD/usr/. %{buildroot}/usr/
+ 
+ 
+ %files

From bd368a208a3c4c4e458a7b3471bfa6fc41b9bb3c Mon Sep 17 00:00:00 2001
From: zbcoding <zbcoding@outlook.com>
Date: Thu, 3 Sep 2026 19:29:57 -0500
Subject: [PATCH 6/6] fix(cli): install a working dapi from an AppImage, and
 stop the app inheriting node mode

Two bugs, both found by installing the CLI from a real AppImage and then
quitting it - which is what a user does.

The install wrote a symlink into `resources` under the image's mount.
That mount lives under /tmp only while the app runs and its name changes
every launch, so the link dangled the moment the app quit. The image
file is stable and can run the CLI on its own Electron in node mode, so
the install now writes a wrapper that does that: the image mounts itself
for the duration of each call. The path inside the mount is read from
the running process rather than assumed, since the maker decides the
layout.

The wrapper runs the CLI with `ELECTRON_RUN_AS_NODE=1`, and a spawned
app inherited it - starting with no main script and exiting without a
window, so `dapi open` could never launch the app from any packaged
install, deb and rpm included. Earlier tests missed it because the
launch target was a shell stub, which ignores the variable.
`spawnDetached` now drops it, along with the AppImage variables, so a
launched image mounts itself afresh instead of reading this process's
mount.
---
 apps/cli/src/index.ts           | 26 ++++++++++++----
 apps/desktop/src/cli-install.ts | 55 +++++++++++++++++++++++----------
 apps/desktop/src/menu.ts        |  4 +--
 3 files changed, 60 insertions(+), 25 deletions(-)

diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 54e68de3..bfb03574 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -5,7 +5,7 @@
 
 import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { Command } from "commander";
@@ -341,9 +341,19 @@ function launchDarwin(background: boolean): Promise<boolean> {
 // The app has to outlive this process, so the child is detached and its handle
 // released. A missing binary is reported asynchronously, which is why the two
 // events are raced instead of the call being wrapped in a try.
+//
+// `ELECTRON_RUN_AS_NODE` is how the packaged wrapper runs this CLI on the app's
+// own Electron, and a child would inherit it - starting the app in node mode,
+// where it runs no main script and exits without a window. The AppImage
+// variables go too, so an image launched from here mounts itself afresh
+// instead of reading the mount this process is running from.
 function spawnDetached(command: string, args: string[]): Promise<boolean> {
+  const env = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  delete env.APPDIR;
+  delete env.APPIMAGE;
   const { promise, resolve: res } = Promise.withResolvers<boolean>();
-  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  const child = spawn(command, args, { detached: true, stdio: "ignore", env });
   child.once("error", () => res(false));
   child.once("spawn", () => {
     child.unref();
@@ -361,10 +371,14 @@ const LINUX_EXECUTABLE = "diffusion-studio";
 async function launchLinux(background: boolean): Promise<boolean> {
   const args = background ? ["--hidden"] : [];
 
-  // The packaged wrapper exports the root of the app it was shipped in, so an
-  // installed CLI starts its own app rather than whichever one is on PATH.
-  const root = process.env.DIFFUSION_APP_PATH;
-  const installed = root ? join(root, LINUX_EXECUTABLE) : undefined;
+  // The packaged wrapper exports what it was shipped in, so an installed CLI
+  // starts its own app rather than whichever one is on PATH: the app root for
+  // a normal install, and for an AppImage the image file, which is itself the
+  // executable.
+  const shipped = process.env.DIFFUSION_APP_PATH;
+  const installed = statSync(shipped ?? "", { throwIfNoEntry: false })?.isDirectory()
+    ? join(shipped!, LINUX_EXECUTABLE)
+    : shipped;
   if (installed && existsSync(installed) && (await spawnDetached(installed, args))) return true;
 
   if (await spawnDetached(LINUX_EXECUTABLE, args)) return true;
diff --git a/apps/desktop/src/cli-install.ts b/apps/desktop/src/cli-install.ts
index 469e671a..c88a3970 100644
--- a/apps/desktop/src/cli-install.ts
+++ b/apps/desktop/src/cli-install.ts
@@ -4,9 +4,9 @@
 
 import { app } from "electron";
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import type { CliInstallResult } from "./main-channels";
 
 // Where each platform keeps user-installed commands: /usr/local/bin needs
@@ -46,6 +46,39 @@ function linkCliDirectly(): void {
   symlinkSync(CLI_WRAPPER_PATH, CLI_LINK_PATH);
 }
 
+// An AppImage has nothing worth linking to: it runs from a mount under /tmp
+// that exists only while the process does, and whose name changes every
+// launch, so a symlink into `resources` dangles the moment the app quits. The
+// image file itself is stable and can run the CLI through Electron's node
+// mode, mounting itself for the duration of the call - so the install writes a
+// wrapper that does that. The path inside the mount is read from this process
+// rather than assumed, since it is the maker that decides the layout.
+function writeAppImageWrapper(appImage: string, appDir: string): void {
+  const insideMount = relative(appDir, dirname(process.resourcesPath));
+  // Runs in the child: the runtime exports APPDIR for the mount it made and
+  // APPIMAGE for the file, which is what `dapi open` needs to launch the app.
+  const bootstrap =
+    `const r=process.env.APPDIR+"/${insideMount}";` +
+    `process.env.DIFFUSION_APP_PATH=process.env.APPIMAGE;` +
+    `const j=r+"/resources/cli/dapi.js";` +
+    `process.argv=[process.argv[0],j,...process.argv.slice(1)];` +
+    `require(j);`;
+  const quoted = `'${appImage.replaceAll("'", `'\\''`)}'`;
+  const wrapper = [
+    "#!/bin/sh",
+    "# Written by Diffusion Studio's \"Install dapi Command Line Tool\" from an",
+    "# AppImage. Move or delete that file and this stops working; run the",
+    "# installer again to point it at the new location.",
+    `APPIMAGE=${quoted}`,
+    `[ -x "$APPIMAGE" ] || { echo "dapi: no Diffusion Studio AppImage at $APPIMAGE" >&2; exit 1; }`,
+    `ELECTRON_RUN_AS_NODE=1 exec "$APPIMAGE" -e '${bootstrap}' -- "$@"`,
+    "",
+  ].join("\n");
+  mkdirSync(dirname(CLI_LINK_PATH), { recursive: true });
+  rmSync(CLI_LINK_PATH, { force: true });
+  writeFileSync(CLI_LINK_PATH, wrapper, { mode: 0o755 });
+}
+
 export async function installCli(): Promise<CliInstallResult> {
   if (!app.isPackaged) {
     return {
@@ -53,22 +86,10 @@ export async function installCli(): Promise<CliInstallResult> {
       error: "Installing the CLI is only available in the packaged app. Use `npm run symlink:create` in development.",
     };
   }
-
-  // An AppImage runs from a mount that only exists while it does
-  // (`/tmp/.mount_*`), so a link into its resources would dangle the moment
-  // the app quits. The bundled `dapi` works fine from inside a running one —
-  // it just has no path worth linking.
-  if (process.env.APPIMAGE) {
-    return {
-      status: "error",
-      error:
-        "An AppImage has no stable path to link from. Install the deb or rpm package to get dapi on PATH, " +
-        "or unpack this file once (`--appimage-extract`) and link the dapi wrapper under " +
-        "usr/lib/diffusion-studio/resources/cli/bin from the unpacked tree.",
-    };
-  }
+  const { APPIMAGE, APPDIR } = process.env;
   try {
-    if (process.platform === "linux") linkCliDirectly();
+    if (APPIMAGE && APPDIR) writeAppImageWrapper(APPIMAGE, APPDIR);
+    else if (process.platform === "linux") linkCliDirectly();
     else await linkCliWithPrompt();
     return { status: "installed" };
   } catch (e) {
diff --git a/apps/desktop/src/menu.ts b/apps/desktop/src/menu.ts
index ff63e505..175a1632 100644
--- a/apps/desktop/src/menu.ts
+++ b/apps/desktop/src/menu.ts
@@ -21,8 +21,8 @@ async function installCliFromMenu() {
       type: "info",
       message: "The dapi command line tool was installed.",
       detail: onPath
-        ? `Linked at ${CLI_LINK_PATH}. Run "dapi --help" in a terminal to get started.`
-        : `Linked at ${CLI_LINK_PATH}. If "dapi" is not found, add ${linkDir} to your PATH.`,
+        ? `Installed at ${CLI_LINK_PATH}. Run "dapi --help" in a terminal to get started.`
+        : `Installed at ${CLI_LINK_PATH}. If "dapi" is not found, add ${linkDir} to your PATH.`,
     });
   } else {
     await dialog.showMessageBox({