Skip to content

Build your personal knowledge base with Trilium Notes

docs(flatpak): describe the vendored packaging in CLAUDE.md and the skills

Elian Doran7c1082a96400
diff --git a/.claude/skills/cutting-a-release/SKILL.md b/.claude/skills/cutting-a-release/SKILL.md
index 1904a1f32a..a339a0ad8a 100644
--- a/.claude/skills/cutting-a-release/SKILL.md
+++ b/.claude/skills/cutting-a-release/SKILL.md
@@ -84,6 +84,7 @@ This isn't theoretical — real release-prep commits touched *different* file su
- **Lockfile is NOT touched by a version-only bump.** Internal deps are `workspace:*` (resolve to `link:`, no version recorded — `grep 0.103.0 pnpm-lock.yaml` = 0 hits), and the release-prep commits above never touched `pnpm-lock.yaml`. CI installs `--frozen-lockfile` *before* any bump (`nightly.yml:71` then bump at `:75`; `release.yml:28`). `--frozen-lockfile` only fails if the release *also* changes a real dependency. The upstream doc's "run `pnpm i`" step is precautionary and misnames the file.
- **Tag must be `v`-prefixed** — `release.yml:3-5` triggers only on `v*`. A bare `0.103.0` tag does nothing.
- **`RELEASE_PAT`, not `GITHUB_TOKEN`** — `release.yml:161`. Confirmed the only PAT in the release flow; winget (downstream) uses a separate `WINGET_PAT` (`release-winget.yml:19`).
+- **Flathub does NOT publish itself.** `release.yml` has no Flathub job; `release-flathub.yml` is `workflow_dispatch`-only, so a release ships to Flathub only once someone runs `gh workflow run "Release to Flathub" -f ref=v<X.Y.Z>` and merges the pull request it opens against `flathub/org.triliumnotes.Trilium`. Needs the `FLATHUB_PAT` secret. See the `packaging-for-flathub` skill.
- **Don't hand-edit child package.jsons** — let `update-version` propagate from root, or they desync silently past the 5-file gate.
- **`update-version` is idempotent but partial in the diff** — it rewrites all 8 unconditionally; only the previously-stale ones show up in `git status`. "Only 6 files changed" is normal and not a sign you missed one.
diff --git a/.claude/skills/developing-electron-desktop/SKILL.md b/.claude/skills/developing-electron-desktop/SKILL.md
index 75c788498e..70331bdf01 100644
--- a/.claude/skills/developing-electron-desktop/SKILL.md
+++ b/.claude/skills/developing-electron-desktop/SKILL.md
@@ -26,6 +26,8 @@ apps/desktop/
e2e/ # Playwright against the built app (`pnpm --filter desktop e2e`)
scripts/build.ts # esbuild bundle + asset copy into dist/
electron-forge/ # packaging (forge.config.ts, icons, dmg, portable/safe-mode launchers)
+ # flip-fuses.ts + trim-locales.ts are ALSO run as scripts by the
+ # Flathub manifest — see the packaging-for-flathub skill before editing
```
## Process and security model
diff --git a/.claude/skills/packaging-for-flathub/SKILL.md b/.claude/skills/packaging-for-flathub/SKILL.md
index 5386201501..c7729ada2a 100644
--- a/.claude/skills/packaging-for-flathub/SKILL.md
+++ b/.claude/skills/packaging-for-flathub/SKILL.md
@@ -1,210 +1,199 @@
---
name: packaging-for-flathub
-description: Use when working on Trilium's Flathub packaging — the from-source flatpak manifest (org.triliumnotes.Trilium), scripts/generate-flatpak-sources.mts, the Flathub submission, the future release-flathub update workflow, or anything touching the packaging repo at ../com.github.zadam.trilium. Covers the settled architecture decisions (no electron-forge, no asar, new app ID, pnpm store v11, manual Electron unzip, metadata module last), the offline-build machinery (flatpak-node-generator, requiresBuild:false, lifecycle-script semantics), the org.flatpak.Builder-only toolchain rule, the expected lint findings, the verified runtime behaviors (zypak, GNOME window matching, fuses), and the submission state (PR flathub/flathub#10014 in review; /review-based pr-check mechanics; EOL-rebase of com.github.zadam.trilium last). Do NOT use for the electron-forge .flatpak release asset (see forge.config.ts) or for cutting releases (see cutting-a-release).
+description: Use when working on Trilium's Flathub packaging — the from-source flatpak recipe vendored in apps/desktop/flatpak/ (manifest, trilium.sh, flathub.json, .desktop, metainfo), the scripts/flatpak/ generators (update-repo.mts, generate-sources.mts), .github/workflows/release-flathub.yml, or the published packaging repo at ../org.triliumnotes.Trilium. Covers the settled architecture decisions (no electron-forge, no asar, sandboxed data dir, per-arch pnpm sources, build-time scripts shared with the forge build), the offline-build machinery (flatpak-node-generator, requiresBuild:false, the Electron ≥43 unzip, the armv7l crash), the org.flatpak.Builder-only toolchain rule, how Flathub test-builds pull requests (drafts included, one misleading status), and what remains (FLATHUB_PAT, release trigger, EOL-rebase of the old app ID). Do NOT use for the electron-forge .flatpak release asset (see forge.config.ts) or for cutting releases (see cutting-a-release).
---
# Packaging Trilium for Flathub
A from-source flatpak of Trilium Desktop, built offline inside the flatpak-builder
-sandbox with no Electron Forge involvement, targeted at a Flathub submission under a
-new app ID. Everything below was built and verified against **v0.105.0** on 2026-08-31
-/ 2026-09-01; the manifest builds, installs, launches, and lints clean modulo two
-expected findings.
+sandbox with no Electron Forge involvement. **The app is published**: the submission
+(flathub/flathub#10014) merged and `flathub/org.triliumnotes.Trilium` exists. The recipe
+now lives in this repo and the packaging repo is generated from it.
+
+**Flathub bans AI-generated submissions** (policy May 2026). Everything addressed to
+Flathub — pull request descriptions, review replies, linter-exception requests — is
+Elian's to author personally. Draft packaging code and manifests freely; do not write
+the words that go to Flathub reviewers.
## The two working locations
-- **This repo**: `scripts/generate-flatpak-sources.mts` (+ `.spec.ts`) — generates and
- filters `generated-sources.json` from `pnpm-lock.yaml`. Lives on branch
- `flatpak/generated_sources` (PR #11283) together with
- `apps/website/public/.well-known/org.flathub.VerifiedApps.txt` (empty, deployed and
- serving 200 at triliumnotes.org; the dev-portal token fills it after publication).
-- **The packaging repo**: `/home/elian/Projects/TriliumNext/com.github.zadam.trilium` —
- a clone of the OLD Flathub repo (Elian has write access, granted via
- flathub/flathub#6715), emptied and reused as the working directory for the NEW app.
- Contains `org.triliumnotes.Trilium.yml`, `.desktop`, `.metainfo.xml`,
- `generated-sources.json` (2 610 entries, generated from the v0.105.0 lockfile),
- `stamp-build-info.mts`, `trim-locales.mts`, `flip-fuses.mts`, README. Its contents get
- copied into the flathub/flathub `new-pr` submission; the repo itself is never pushed.
+- **This repo owns the recipe.** `apps/desktop/flatpak/` holds the manifest
+ (`org.triliumnotes.Trilium.yml`), `trilium.sh`, `flathub.json`, the `.desktop` file and
+ the metainfo. `scripts/flatpak/` holds `update-repo.mts` (writes the manifest with the
+ ref and pnpm pins, copies `trilium.sh` + `flathub.json`) and `generate-sources.mts`
+ (regenerates `generated-sources.json`). `.github/workflows/release-flathub.yml` runs
+ both against a dispatched ref and opens the pull request. Also here:
+ `apps/website/public/.well-known/org.flathub.VerifiedApps.txt` (empty, serving 200; the
+ dev-portal token fills it — post-publication flow, keep the file forever).
+- **The packaging repo**: `/home/elian/Projects/TriliumNext/org.triliumnotes.Trilium`,
+ a clone of the real Flathub repo (default branch `master`, Elian has `push`). It holds
+ only the manifest, `trilium.sh`, `flathub.json`, `generated-sources.json` and a README.
+ **Never hand-edit it** — `update-repo.mts` overwrites everything but the sources file,
+ which `generate-sources.mts` overwrites.
+
+Local flow, from this repo, in this order:
+
+```sh
+pnpm exec tsx scripts/flatpak/update-repo.mts ../org.triliumnotes.Trilium [ref]
+pnpm exec tsx scripts/flatpak/generate-sources.mts ../org.triliumnotes.Trilium
+```
+
+`ref` defaults to `HEAD`; a **tag** pins `tag:` + `commit:`, anything else pins a bare
+commit. The pinned commit must be **pushed** — Flathub clones `TriliumNext/Trilium` at
+that SHA.
## Settled decisions and why (do not relitigate without new facts)
-- **From source, not repackaged.** Flathub prefers it; the AppImage-extract fallback
- (Zettlr-style) exists if reviewers ever balk at build cost.
-- **New app ID `org.triliumnotes.Trilium`**, CamelCase last element (ecosystem norm:
- md.obsidian.Obsidian). The old `com.github.zadam.trilium` cannot be verified (ID maps
- to zadam's GitHub) and gets an `end-of-life-rebase` to the new ID **after** the new
- app publishes — EOL-ing first would leave a window where searching "trilium" finds
- nothing. `<provides>`/`<replaces>` with the old ID are already in the metainfo; user
- data survives either way because the notes DB lives in `~/.local/share/trilium-data`,
- not in `~/.var/app`.
-- **No asar, no Forge.** Payload proven byte-identical to the Forge flatpak (2 850
- files, 3 trivial diffs); the +11 MB bundle delta is compression granularity (ostree
- compresses per file, asar is one stream). Tamper-sealing comes from content-addressed
- ostree, so asar integrity fuses buy nothing.
-- **Fuses are flipped anyway** (`flip-fuses.mts`): Forge's hardening set minus the two
- asar fuses (`OnlyLoadAppFromAsar`, `EnableEmbeddedAsarIntegrityValidation`), which
- would brick a directory-loaded app. `RunAsNode` is OFF — `ELECTRON_RUN_AS_NODE`
- smoke tests no longer work, by design.
-- **Build info is stamped from the commit date** (`stamp-build-info.mts`), not wall
- clock: reproducible-builds consensus, Cemu precedent on Flathub, and rebuilds of the
- same source must not claim new dates. The tag's committed `build.ts` is a stale
- placeholder (wrong date AND revision) — the stamp is mandatory.
-- **Locale trim** (`trim-locales.mts`): 55 → 21 Chromium `.pak`s, keep-list derived at
- build time from `LOCALES` in `packages/commons/src/lib/i18n.ts` (drift-proof), with
- the `en-US.pak`-is-"en" special case. Mirrors Forge's postPackage hook.
-- **Generation is NOT wired into CI** (deliberate reversal — commit `f16771c918`):
- release-asset coupling would block every release channel on an unpinned generator.
- Future model is winget-style push (see below). Only the script + spec live upstream.
-- **`metadata` module holds `.desktop` + metainfo and MUST STAY LAST** in the manifest:
- flatpak-builder's stage cache is sequential, so this keeps metadata edits from
- invalidating the ~20-minute app build. No peer does this; it is our optimization.
-- **`--filesystem=home` stays**, justified by drag-&-drop import from anywhere in home
- (core UX) plus the data dir; needs a per-app linter exception granted at submission.
-- **No `flathub.json`** yet: defaults build x86_64 + aarch64 (the old app's
- `only-arches x86_64` reflected constraints that no longer exist; arm64 prebuilds
- ship in better-sqlite3 13). `disable-external-data-checker: true` gets added only
- when the push workflow lands.
+- **From source, not repackaged.** The AppImage-extract fallback (Zettlr-style) exists
+ if reviewers ever balk at build cost.
+- **App ID `org.triliumnotes.Trilium`**, CamelCase last element. The old
+ `com.github.zadam.trilium` gets an `end-of-life-rebase` to the new ID — still pending,
+ Elian can merge it himself; `<provides>`/`<replaces>` are already in the metainfo. User
+ data survives either way (notes live in `trilium-data`, not `~/.var/app`).
+- **No asar, no Forge.** Payload proven byte-identical to the Forge flatpak; the +11 MB
+ is compression granularity (ostree per file vs. one asar stream). Tamper-sealing comes
+ from content-addressed ostree, so asar integrity fuses buy nothing.
+- **The build-time scripts are shared with the forge build, not copies.** The manifest
+ runs the checkout's own code:
+ - `pnpm chore:update-build-info --from-commit` — commit date, not wall clock, so a
+ rebuild of the same source stamps the same bytes. The default (no flag) is what the
+ seven CI callers use; do not change it.
+ - `apps/desktop/electron-forge/flip-fuses.ts` — `FUSES` is the shared baseline; the
+ forge config spreads it and adds `OnlyLoadAppFromAsar` +
+ `EnableEmbeddedAsarIntegrityValidation` at the use site, because only Forge packages
+ an asar. `RunAsNode` is OFF, so `ELECTRON_RUN_AS_NODE` smoke tests do not work.
+ - `apps/desktop/electron-forge/trim-locales.ts` — one keep-list derived from `LOCALES`,
+ one walk, one completeness check (a keep-list locale missing from the package fails
+ the build). 55 → 21 `.pak`s on Linux.
+
+ Each has a run-as-script guard (`process.argv[1] === import.meta.filename`) and takes
+ its target as an argument. Editing them touches **both** the Flathub build and the
+ `.deb`/`.rpm`/Forge artifacts.
+- **The desktop file and metainfo install from the pinned checkout**, not from
+ packaging-repo copies and not from `raw.githubusercontent` pins. The review wanted them
+ in this repo; the URL-pin variant is also how the published build missed the
+ `StartupWMClass` fix for weeks. There is **no separate metadata module** any more —
+ nothing is left for it to cache-isolate. `trilium.sh` is the one exception, copied into
+ the packaging repo so a reviewer reads the sandbox behavior without opening the
+ checkout.
+- **Sandboxed data dir, narrow filesystem access.** `trilium.sh` sets
+ `TRILIUM_DATA_DIR` to `$XDG_DATA_HOME/trilium-data` (i.e. inside `~/.var/app`), falling
+ back to host `~/.local/share/trilium-data` when that exists; a `flatpak override` wins.
+ `--filesystem=home` is **gone** — four read-only XDG dirs cover drag-&-drop import
+ (electron#30650), so the linter exception that was pending at submission is moot.
+- **pnpm 12 ships as a native binary per platform.** The manifest stages
+ `@pnpm/exe.linux-x64` / `-arm64` tarballs with `only-arches`, because the `pnpm`
+ wrapper package's `postinstall` (which picks one) cannot run offline. `append-path`
+ points at `flatpak-node/pnpm`; the archive root holds an executable `pnpm`, so no
+ `chmod`/symlink step. Refs older than pnpm 12 are rejected by `checkPnpmSupported` —
+ pnpm 11 had a single wrapper tarball and the per-arch URL would 404.
+- **`flathub.json`** carries `disable-external-data-checker: true` (the checker probes
+ broken URLs *without* `x-checker-data`, so it would poll ~2400 generated npm sources)
+ and `automerge-flathubbot-prs: false` — the linter errors on `true`
+ (`flathub-json-automerge-enabled`). It only takes effect on the **default branch**.
+- **No `only-arches`** at app level: x86_64 + aarch64 both build (better-sqlite3 13 ships
+ arm64 prebuilds).
## The offline-build machinery (how it works, where it bites)
-- `flatpak-node-generator pnpm --pnpm-store-version v11` — the flag is **mandatory**:
- the generator defaults to store v10 (per-package JSON index), pnpm 11 reads only v11
- (SQLite `index.db`). Wrong store ⇒ generation succeeds, sandbox install fails
- minutes later. `checkPnpm` in the script guards the major.
+- `flatpak-node-generator pnpm <lockfile> --pnpm-store-version v11` — the flag is
+ **mandatory**. pnpm 12 still reads the **v11** store layout (SQLite `index.db`); the
+ generator defaults to v10 (per-package JSON index). Verify with `pnpm store path`
+ before assuming a bump changed it. `checkPnpm` in `generate-sources.mts` guards the
+ major (currently 12).
+- **The generator crashes on Electron ≥44 unless it is recent**: `KeyError:
+ electron-v44.4.1-linux-armv7l.zip`, because Electron stopped publishing armv7l and only
+ newer generator revisions skip that arch. CI pins a master commit
+ (`41c20aa10819cdb2a4f3ca171758a96d1955c018` or later) via pipx. **The copy bundled in
+ `org.flatpak.Builder` is too old** — locally, extract it and patch the guard in
+ `flatpak_node_generator/electron.py`, keeping the copy under `$HOME` (the sandbox cannot
+ see `/tmp`) and pointing `PYTHONPATH` at it through a `flatpak-node-generator` shim on
+ `PATH`. Drop that crutch once the Builder flatpak updates.
- The generated store marks every package `requiresBuild: false` ⇒ **no dependency
- lifecycle script ever runs**. The workspace's OWN `postinstall` (pdfjs-viewer,
- share-theme, wxt prepare) DOES run. Nothing in the graph needs a native build
- (better-sqlite3 13 ships N-API prebuilds; esbuild resolves `@esbuild/linux-x64`).
-- **Electron ≥43 has NO install script at all** — it lazy-downloads on first
- `require`, which offline cannot allow and the build never triggers. Hence the
- manifest unzips `flatpak-node/cache/electron/electron-v*-linux-*.zip` itself, renames
- the binary to `trilium`, deletes `chrome-sandbox` (zypak replaces the setuid
- sandbox), and the wrapper runs `zypak-wrapper`.
-- The pnpm tarball ships `bin/pnpm.cjs` **without the exec bit** ⇒ `chmod +x` before
- the `ln -s pnpm.cjs … pnpm`. The pnpm archive version must track the tag's
- `packageManager` pin (v0.105.0 = 11.22.0; minor drift is harmless, major is not).
-- Playwright's 5 browser archives (~511 MB, x64-only, no arch guards) are dead weight
- the script filters out; `--no-devel` is unsupported for pnpm lockfile v9 and would
- break the build anyway (Vite/esbuild/tsx are devDependencies).
-- Generator output is **deterministic** (byte-identical across runs, machines, cache
- states) but the tool is installed from unpinned master — the script's count/electron
- guards exist to catch drift, and any future CI use must pin a commit (Greptile P1).
+ lifecycle script runs**. The workspace's OWN `postinstall` DOES run. Nothing in the
+ graph needs a native build.
+- **Electron ≥43 has no install script** — it lazy-downloads on first `require`, which
+ offline forbids. The manifest unzips `flatpak-node/cache/electron/electron-v*-linux-*.zip`
+ itself, renames the binary to `trilium`, deletes `chrome-sandbox` (zypak replaces the
+ setuid sandbox), and the wrapper runs `zypak-wrapper`.
+- Playwright's ~511 MB of browser archives are filtered out by `filterSources`, which also
+ fails loudly if the count collapses or the Electron zip disappears. `--no-devel` is
+ unsupported for lockfile v9 and would break the build (Vite/esbuild/tsx are devDeps).
+- Generator output is **deterministic** across runs and machines.
## Toolchain rule: org.flatpak.Builder ONLY
-Build and lint exclusively through the `org.flatpak.Builder` flatpak (Flathub's CI
-toolchain; bundles flatpak-builder 1.4.9, flatpak-builder-lint, appstreamcli, ostree,
-jq, and flatpak-node-generator — the last kills any pipx/venv need locally). Using the
-host's flatpak-builder caused two wasted investigations: NixOS ships it without
-`appstreamcli` (compose step dies), and version skew produced phantom lint errors.
+Build and lint exclusively through the `org.flatpak.Builder` flatpak (bundles
+flatpak-builder, flatpak-builder-lint, appstreamcli, ostree, jq). The host's
+flatpak-builder cost two wasted investigations: NixOS ships it without `appstreamcli`,
+and version skew produced phantom lint errors.
```sh
flatpak run org.flatpak.Builder --user --install --force-clean builddir org.triliumnotes.Trilium.yml
flatpak run --command=flatpak-builder-lint org.flatpak.Builder manifest org.triliumnotes.Trilium.yml
-# Repo lint as Flathub's test pipeline judges it (test branch + REPO env):
+# Repo lint as Flathub's test pipeline judges it:
flatpak run org.flatpak.Builder --user --force-clean --default-branch=test --repo=repo builddir org.triliumnotes.Trilium.yml
flatpak run --env=REPO=https://github.com/flathub/org.triliumnotes.Trilium --command=flatpak-builder-lint org.flatpak.Builder repo repo
+# Metainfo alone, no build needed (what CI does):
+flatpak run --command=appstreamcli org.flatpak.Builder validate --explain apps/desktop/flatpak/org.triliumnotes.Trilium.metainfo.xml
```
-**Expected lint findings — do not re-investigate**: `finish-args-home-filesystem-access`
-(until the exception is granted) and `appstream-remote-icon-not-mirrored` (local-run
-artifact: the mirroring checks string-match absolute `dl.flathub.org/media` URLs that
-appstreamcli 1.x compose never emits locally; adjudicated only by Flathub's own test
-build — Cockpit's external CI hit the identical pair).
+**Expected findings — do not re-investigate**: `runtime-update-available-…` (a runtime
+bump is a deliberate decision) and, on local repo lint,
+`appstream-remote-icon-not-mirrored` (the mirroring checks string-match
+`dl.flathub.org/media` URLs that appstreamcli never emits locally; only Flathub's own
+build adjudicates it).
+
+## How Flathub builds pull requests (verified 2026-09-21)
+
+- **Draft PRs are test-built** — `flathub/org.kde.kolourpaint#128` (`draft: true`)
+ produced a vorarbeiter run. Drafting costs no coverage.
+- **Only one status is ever posted: `builds/x86_64`** — an aggregate, on every app,
+ whether or not aarch64 built. The aarch64 result is a `build-aarch64` job inside the
+ run the status links to (alongside `validate-manifest`). **Never read a green check as
+ proof aarch64 built**; open the run.
+- **The arch matrix is fail-fast, both directions** — one arch failing cancels the other.
+ Failures do post (`builds/x86_64=failure`); `bot, build` re-triggers and the newer run
+ overwrites the status.
+- **What triggers a build**: `refs/pull/*/head` (test, publishes nothing), `master`
+ (stable publish), `beta` (beta channel). A push to any other branch builds nothing — so
+ a pull request is the only way to get a build without publishing.
+- Therefore **untagged commits go out as draft PRs to `master`** (shared `update/beta`
+ branch, superseded per run) purely for the two-arch verdict. A real `beta` branch is
+ for `-rc` tags with actual testers, and publishing there has no review gate.
## Runtime behaviors (verified — trust these)
- `flatpak-builder --run` CANNOT test zypak apps (portal Spawn needs a registered
- instance: `run-environ` missing). Always `--install` + `flatpak run`.
+ instance). Always `--install` + `flatpak run`.
- GNOME matches the window to the desktop file **without any desktopName /
- CHROME_DESKTOP fix** — but only in a session started after flatpak enablement.
- If integration looks broken (generic icon, app absent from grid), check
- `XDG_DATA_DIRS` of the running gnome-shell before touching code: a re-login fixes
- it. Two "fixes" were nearly shipped for this non-bug.
-- The app runs Wayland-native (Electron auto-picks the wayland socket). The system-bus
- dbus error at startup is benign Chromium probing.
-- Data dir is shared with non-flatpak Trilium; quarantine tests with
- `--env=TRILIUM_DATA_DIR=/tmp/...`.
-- **`--talk-name=org.freedesktop.Notifications` is NOT needed** (verified empirically
- + docs.flatpak.org/en/latest/electron.html: libnotify ≥0.8 auto-uses the
- notification portal in sandboxes; modern peers — Signal/Discord/Element — omit it).
- The tray's `org.kde.StatusNotifierWatcher` HAS no portal equivalent and stays.
- Audit any finish-arg one-off with `flatpak run --no-talk-name=… <id>`; watch the
- wire with `dbus-monitor` on both the portal and classic interfaces.
-
-## Update model (designed, not yet built)
-
-Winget-style push from this repo (mirror `release-winget.yml`): a `release-flathub.yml`
-on `release: published` + `workflow_dispatch`, needing a `FLATHUB_PAT` secret — so it
-can only exist after the Flathub repo does. Duties beyond the obvious bump: metainfo
-`<release>` entry; `git rev-parse 'vX.Y.Z^{commit}'` (annotated-tag footgun); run the
-TAG'S OWN generation script against the tag's lockfile; conditional pnpm-pin update
-(fetch + sha256); node-major drift check against the manifest's node24 extension;
-skip prereleases; idempotent re-runs; supersede stale bump PRs. flathubbot test-builds
-every PR automatically; `gh pr merge --auto` is the auto-merge path if ever wanted
-(`automerge-flathubbot-prs` only covers checker PRs and never applied to us). Do the
-first cycles manually before automating.
-
-## Submission state (submitted 2026-09-01)
-
-**The submission is live: flathub/flathub#10014** ("Add org.triliumnotes.Trilium"),
-labeled `migrate-app-id` by a human triager within minutes. The AI disclosure went
-into the PR body itself (an "Additional information" bullet, proactive, with the
-app-side LLM use shown) rather than a separate up-front issue. The body also carries
-the rename/EOL-rebase rationale and the `--filesystem=home` justification. All review
-replies remain Elian's to write.
-
-What remains, in order:
-
-1. Review (expect Fluxer-style: per-finish-arg "why?", possibly "desktop/metainfo
- should live upstream" — Fluxer got that comment and still merged with the files in
- the packaging repo). `bot, build` restarts test builds; the test build is also the
- first aarch64 verdict.
-2. On merge: accept the invite (2FA, one week). Verification is a **post-publication
- dev-portal flow** — the portal issues a token that fills the currently-empty (and
- already live, HTTP 200) well-known file; keep that file forever (periodic
- re-checks). Nothing in the submission pipeline fetches it.
-3. Only after the new app is live: PR `flathub.json` with
- `end-of-life-rebase: org.triliumnotes.Trilium` to the old repo (Elian can merge it
- himself). Old app currently ships 0.63.7/2024 on EOL 23.08 to ~71k installs.
-
-## Submission-pipeline mechanics (learned from source + #10014)
-
-- **`pr-check.yml` triggers ONLY on**: a comment containing `/review`, a 2-hourly
- cron, and admin dispatch. Close/reopen and title/body edits do NOT re-run it —
- comment `/review` to clear `pr-check-blocked` after fixing something.
-- The checker (flathub-infra/flathub-submission-checker) automates only proxies;
- "requirements followed" in its posted comment is the human reviewer's line. The
- gates: title `Add <appid>` (3+ dot components, `^[A-Za-z_][\w\-]*$` each); a
- top-level manifest file (all-files-nested ⇒ auto spam-flag); the 4 template
- checklist sentences as substrings PLUS a role line whose regex allows only
- whitespace between "I am a/an" and "developer/author/…" (leftover template italics
- break it); tolerance is exactly ONE missing item. The video item needs a ticked box
- + URL within 2 lines — **waived entirely under the `migrate-app-id` label**.
-- The domain comment is informational; the checker never fetches the well-known URL
- and there is no "verified" state pre-publication.
-- **Submission branch history is preserved unsquashed** as the new app repo's master
- (verified on Fluxer's repo: its review fixups sit on the 2017 scaffold root
- forever). Tidy before opening; write commits as permanent. Decided: do NOT graft
- the old zadam repo history into the submission — provenance lives in
- `provides`/`replaces` + a link to flathub/flathub#6715 (link the issue, never
- @-mention admins for review; queue etiquette).
-- Closest precedent PR: flathub/flathub#7843 (Fluxer, 2026, month-long) — the review
- that spawned pnpm support in flatpak-builder-tools (#511). Older peers (Obsidian
- #1883, Joplin #2061, Logseq #2729, Notesnook #3543) merged in 2–5 days under the
- laxer pre-2023 climate; don't calibrate expectations on them.
-
-Post-publication niceties parked: carousel-spec screenshots (window ≤1000×700 or 2× at
-≤2000×1400, with shadow + rounded corners — current 1302×826 pinned-sha shots pass
-review but fail the featured checklist), `<branding>` colors (proposal: leaf-green
-pastel `#cfe8c0` light / `#254d18` dark, derived from the website palette
-`#4fa52b`/`#e47b19`/`#e33f3b`; compare peers via
-`flathub.org/api/v2/appstream/<id>` → `.branding`; Logseq/Loupe/Warp/Bazaar have
-blocks, Obsidian/Zed render the default gray), metainfo description refresh (bullets
-drafted for canvas/mind maps/geo maps/collections/dark theme/customizable UI/languages
-+ the relation-map→note-map wording fix; Elian rephrasing), release entries
-(latest-only now, append per release, never backfill; `<url type="details">` per
-entry), beta branch for rc tags, the `--no-playwright-browsers` upstream flag worth
-filing on flatpak-builder-tools. License stays `AGPL-3.0-only` in the metainfo (the
-conservative claim) until the repo reconciles package.json (`-only`, since 2018) with
-the README's v3+ grant (zadam 2021, commit f8c310eb8f).
+ CHROME_DESKTOP fix** — but only in a session started after flatpak enablement. If
+ integration looks broken, check `XDG_DATA_DIRS` of the running gnome-shell before
+ touching code: a re-login fixes it. Two "fixes" were nearly shipped for this non-bug.
+- The app runs Wayland-native. The system-bus dbus error at startup is benign Chromium
+ probing.
+- Quarantine tests with `--env=TRILIUM_DATA_DIR=/tmp/...`.
+- **`--talk-name=org.freedesktop.Notifications` is NOT needed** (libnotify ≥0.8 uses the
+ portal). The tray's `org.kde.StatusNotifierWatcher` has no portal equivalent and stays.
+ Audit a finish-arg with `flatpak run --no-talk-name=… <id>` and `dbus-monitor`.
+
+## What remains
+
+1. **`FLATHUB_PAT` secret** — classic token, scope `public_repo` (the repo is public;
+ `repo` is needlessly broad, `workflow` is not needed). Fine-grained equivalent: owner
+ `flathub`, Contents + Pull requests read/write — but org policy may require approval.
+ Without it the workflow's clone step fails.
+2. **The `release: published` trigger** on `release-flathub.yml`, which also wants
+ prerelease skipping. Dispatch-only today.
+3. **The packaging repo's README**, which still describes staged scripts and the old
+ pnpm/ASAR reasoning.
+4. **EOL-rebase the old app**: PR `flathub.json` with
+ `end-of-life-rebase: org.triliumnotes.Trilium` to `flathub/com.github.zadam.trilium`
+ (needs `end-of-life` too, or the linter errors). Old app ships 0.63.7/2024 on EOL
+ 23.08 to ~71k installs.
+5. Parked polish: carousel-spec screenshots (window ≤1000×700 or 2× at ≤2000×1400, shadow
+ + rounded corners), `<branding>` colors (leaf-green `#cfe8c0` light / `#254d18` dark;
+ compare peers via `flathub.org/api/v2/appstream/<id>` → `.branding`), metainfo
+ description refresh, per-release `<release>` entries (latest-only, never backfill),
+ and the `--no-playwright-browsers` flag worth filing upstream. License stays
+ `AGPL-3.0-only` until the repo reconciles package.json with the README's v3+ grant.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6cf046ab8c..e4c5bf887d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,6 +138,9 @@ Shared components live in `apps/client/src/widgets/react/` — **always** reuse
### Electron Desktop App
`apps/desktop` runs server + client in one Electron process; the renderer loads over the `trilium-app://` custom protocol and talks to main only through the preload bridge (`window.electronApi`, typed by `packages/commons/src/lib/electron_api_interface.ts`). The main process bundles to **ESM with code splitting** (`dist/main.mjs` + lazy `chunks/`, via `buildBackend(..., { format: "esm" })`); the preload and `image_worker.cjs` stay CJS. `nodeIntegration` is off, `contextIsolation` is on, `@electron/remote` is gone — never `require("electron")` in client code. Adding an API means interface + `preload.ts` + an `ipcMain` handler in the owning service + a spec. Load the **`developing-electron-desktop` skill** for the recipe, the security model, running/launch errors and testing.
+### Flathub packaging
+`apps/desktop/flatpak/` holds the whole recipe — manifest, `trilium.sh`, `flathub.json`, `.desktop`, metainfo — and `scripts/flatpak/` writes it into the Flathub repo (`update-repo.mts` pins the ref and the pnpm sources, `generate-sources.mts` rebuilds the offline `generated-sources.json`); `.github/workflows/release-flathub.yml` runs both and opens the PR. **Never hand-edit the packaging repo** — the next run overwrites it. The manifest runs the checkout's own `apps/desktop/electron-forge/{flip-fuses,trim-locales}.ts` and `chore:update-build-info --from-commit`, each shared with the forge build, so **a change there lands in both the `.deb`/`.rpm`/Forge flatpak and Flathub** — keep the run-as-script guard and the argument the manifest passes. Load the **`packaging-for-flathub` skill** before touching any of it.
+
### Standalone (in-browser) app
`apps/standalone` runs the client on the page and `@triliumnext/core` — plain JS — in a dedicated Web Worker over `@sqlite.org/sqlite-wasm` persisted in OPFS; a Web Lock elects the one tab that owns the database, which answers its own API calls straight from the worker (`standaloneApi.localFetch`); the service worker forwards other tabs' calls to it and covers what the page still requests. Every core provider has a browser twin in `apps/standalone/src/lightweight/` — **a new provider or Node import in core breaks this build first.** Load the **`developing-standalone` skill** before touching `sw.ts`, `main.ts`, `local-server-worker.ts`, `lightweight/*` or `vite.config.mts`.