Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
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.mdindex 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.mdindex 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 modeldiff --git a/.claude/skills/packaging-for-flathub/SKILL.md b/.claude/skills/packaging-for-flathub/SKILL.mdindex 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 FlathubA 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.```shflatpak run org.flatpak.Builder --user --install --force-clean builddir org.triliumnotes.Trilium.ymlflatpak 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.ymlflatpak 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.mdindex 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`.