Handoff — 2026-09-18 — ori-desktop built on Linux, MIT LICENSE added

What was asked

cd ori-desktop && wails build.
Mid-session: "ajoute un fichier de licence MIT".
Then: how to build the macOS version (answered in chat), and "cree un document expliquant ca
dans ./ori-desktop/how-to-build.md".

State at the end

All three done. New tracked files: LICENSE (root) and ori-desktop/how-to-build.md. The
pre-existing modifications to docs/.assets/ori-architecture.drawio.svg,
ori-desktop/README.md, ori-desktop/README.fr.md and template/build.sh are the user's and
were deliberately not touched. Nothing committed, nothing pushed.

The build recipe that works in this sandbox

go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
export PATH="$PATH:$(go env GOPATH)/bin"
cd ori-desktop && wails build -tags webkit2_41    # → build/bin/ori-desktop (ELF aarch64, 9.4 MB)

Traps found

wails build without -tags webkit2_41 fails here. Wails' cgo pkg-config line asks for
webkit2gtk-4.0; Ubuntu 26.04 only packages webkit2gtk-4.1. Error:
Package 'webkit2gtk-4.0' not found ×3.
wails doctor lies about it: it reports libwebkit | Unknown | Not Found and
Fatal: Required dependencies missing: libwebkit after 4.1 is installed, because it probes
only 4.0. Trust pkg-config --modversion webkit2gtk-4.1 (→ 2.52.6) instead.
make desktop is still broken on Linux — it runs bare wails build. Left as-is
deliberately (outside the ask). If you fix it, the tag must stay Linux-only: macOS and the
Windows cross-build must not receive -tags webkit2_41.
No macOS build is possible from here. Wails needs macOS/Xcode for a .app. The
build/bin/ori-desktop.app that scripts/launch-ori.applescript opens is the user's own Mac
build; this session did not touch it. build/bin/ now holds all three targets side by side.
The apt packages live on the container disk, so a sandbox recreation loses them and the
install step has to be repeated.

The document

ori-desktop/how-to-build.md — prerequisites, a from-where/to-what cross-build matrix, one
section per platform (macOS / Linux / Windows), the wails build flags that matter, wails dev,
the tests, troubleshooting. Written in the repository's Diátaxis how-to style, in English
(the .md / .fr.md pair convention means the unsuffixed name is the English one).

Everything in it about Linux was verified in this session. The macOS section reflects the user's
own earlier build plus Wails v2.16 CLI behaviour (wails build -help was read, not guessed); the
darwin/universal variant has never been exercised in this project.

Next steps / still open

The window has never been run — neither here (no display) nor confirmed on the Mac after
the CSS specificity fix. The summary's "Not yet established" item about the iframe actually
showing ori inside WKWebView is unchanged by this session.
The Linux binary was not executed either; only compiled. xvfb + a running ori server would
be the way to smoke-test it in the sandbox.
LICENSE is referenced from nowhere: no badge or "Licence" section in README.md /
README.fr.md / ori-desktop/README*.md, no "license": "MIT" in ui/package.json. Add
those if the user wants the licence discoverable.
how-to-build.md has no French counterpart and nothing links to it. Both were left undone on
purpose: the repository pairs every doc with a .fr.md, and ori-desktop/README.md has a
"Build a redistributable binary" section that is the obvious place for the pointer — but that
file has uncommitted user edits, so it was not touched. Offered to the user.
The overlap between how-to-build.md and the build sections of ori-desktop/README*.md is now
duplicated content. If the user wants it deduplicated, the README should shrink to a link.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


# Handoff — 2026-09-18 — ori-desktop built on Linux, MIT LICENSE added

## What was asked

1. `cd ori-desktop && wails build`.
2. Mid-session: "ajoute un fichier de licence MIT".
3. Then: how to build the macOS version (answered in chat), and "cree un document expliquant ca
   dans ./ori-desktop/how-to-build.md".

## State at the end

All three done. New tracked files: `LICENSE` (root) and `ori-desktop/how-to-build.md`. The
pre-existing modifications to `docs/.assets/ori-architecture.drawio.svg`,
`ori-desktop/README.md`, `ori-desktop/README.fr.md` and `template/build.sh` are the user's and
were deliberately not touched. Nothing committed, nothing pushed.

## The build recipe that works in this sandbox

```bash
go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
export PATH="$PATH:$(go env GOPATH)/bin"
cd ori-desktop && wails build -tags webkit2_41    # → build/bin/ori-desktop (ELF aarch64, 9.4 MB)
```

## Traps found

- **`wails build` without `-tags webkit2_41` fails here.** Wails' cgo pkg-config line asks for
  `webkit2gtk-4.0`; Ubuntu 26.04 only packages `webkit2gtk-4.1`. Error:
  `Package 'webkit2gtk-4.0' not found` ×3.
- **`wails doctor` lies about it**: it reports `libwebkit | Unknown | Not Found` and
  `Fatal: Required dependencies missing: libwebkit` *after* 4.1 is installed, because it probes
  only 4.0. Trust `pkg-config --modversion webkit2gtk-4.1` (→ 2.52.6) instead.
- **`make desktop` is still broken on Linux** — it runs bare `wails build`. Left as-is
  deliberately (outside the ask). If you fix it, the tag must stay Linux-only: macOS and the
  Windows cross-build must not receive `-tags webkit2_41`.
- **No macOS build is possible from here.** Wails needs macOS/Xcode for a `.app`. The
  `build/bin/ori-desktop.app` that `scripts/launch-ori.applescript` opens is the user's own Mac
  build; this session did not touch it. `build/bin/` now holds all three targets side by side.
- The apt packages live on the container disk, so a sandbox recreation loses them and the
  install step has to be repeated.

## The document

`ori-desktop/how-to-build.md` — prerequisites, a from-where/to-what cross-build matrix, one
section per platform (macOS / Linux / Windows), the `wails build` flags that matter, `wails dev`,
the tests, troubleshooting. Written in the repository's Diátaxis how-to style, in English
(the `.md` / `.fr.md` pair convention means the unsuffixed name is the English one).

Everything in it about Linux was verified in this session. The macOS section reflects the user's
own earlier build plus Wails v2.16 CLI behaviour (`wails build -help` was read, not guessed); the
`darwin/universal` variant has never been exercised in this project.

## Next steps / still open

- The window has **never been run** — neither here (no display) nor confirmed on the Mac after
  the CSS specificity fix. The summary's "Not yet established" item about the iframe actually
  showing ori inside WKWebView is unchanged by this session.
- The Linux binary was not executed either; only compiled. `xvfb` + a running ori server would
  be the way to smoke-test it in the sandbox.
- `LICENSE` is referenced from nowhere: no badge or "Licence" section in `README.md` /
  `README.fr.md` / `ori-desktop/README*.md`, no `"license": "MIT"` in `ui/package.json`. Add
  those if the user wants the licence discoverable.
- `how-to-build.md` has no French counterpart and nothing links to it. Both were left undone on
  purpose: the repository pairs every doc with a `.fr.md`, and `ori-desktop/README.md` has a
  "Build a redistributable binary" section that is the obvious place for the pointer — but that
  file has uncommitted user edits, so it was not touched. Offered to the user.
- The overlap between `how-to-build.md` and the build sections of `ori-desktop/README*.md` is now
  duplicated content. If the user wants it deduplicated, the README should shrink to a link.