feat(linux): add the GTK app for Linux

.claude/rules/changelog.md

@@ -1,19 +1,19 @@
 ---
 paths:
-  - "CHANGELOG.md"
-  - "changelog.d/**/*"
-  - "towncrier.toml"
+  - "**/CHANGELOG.md"
+  - "**/changelog.d/**/*"
+  - "**/towncrier.toml"
 ---
 
 # Changelog
 
-Unreleased changes are towncrier fragments in `changelog.d/`. A release turns them into a `CHANGELOG.md` section with `scripts/release/notes.py assemble` (`RELEASING.md`, Notes).
+Unreleased changes are towncrier fragments in `changelog.d/`. A release turns them into a `CHANGELOG.md` section with `scripts/release/notes.py assemble` (`RELEASING.md`, Notes). The Linux app is a second towncrier project under the same rules, in `linux/changelog.d/` and `linux/CHANGELOG.md`; its release runs `towncrier build --dir linux` (`linux/docs/releasing.md`).
 
 - **One file per user-visible change**, named `changelog.d/<PR>.<type>.md`: `<PR>` is the pull request that adds it, `<type>` is `added`, `changed`, `deprecated`, `removed`, `fixed` or `security`. A second entry of the same type in one PR adds a counter, as `towncrier create` does: `3452.fixed.1.md`, then `.2`. The counter does not order entries.
 - **One line, at most 120 characters, ending with a period.** Added and Changed name the new thing (`Open in Window for row inspector text fields.`); Fixed names the bug, not the fix (`Empty context menu when right-clicking a read-only inspector field.`). No file paths or type names.
 - **No refs, no credit, no `- ` prefix.** towncrier links the PR named by the file and adds the bullet; `notes.py` adds ` by @login` when the PR's author is not a maintainer.
 - **One entry per thing a user would notice.** Defects with the same visible symptom share an entry.
 - **No fragment** for a fix to something still unreleased (edit that fragment instead) or for a docs-only change.
-- **Only a `chore(release): vX.Y.Z` PR edits `CHANGELOG.md`.**
+- **Only a `chore(release): vX.Y.Z` PR edits `CHANGELOG.md`**, and only a `chore(release): linux-vX.Y.Z` PR edits `linux/CHANGELOG.md`.
 - **The lead block and `[CRITICAL]`**: `RELEASING.md`, Notes and Channels.
-- `scripts/ci/check-changelog.py` checks the fragments' text, the headings and the lead blocks in Repo Hygiene, then `towncrier build --draft --version 0.0.0` renders the fragments. towncrier refuses an unknown type and a non-numeric PR number (`ignore`, `issue_pattern`). In PR title, `--pr` checks that a PR into main names each new fragment after itself, that only a release PR edits `CHANGELOG.md`, and that a release PR changes nothing else.
+- `scripts/ci/check-changelog.py` checks both projects' fragment text, headings and lead blocks in Repo Hygiene, then `towncrier build --draft --version 0.0.0` renders the root fragments; `--dir linux` renders the Linux ones. towncrier refuses an unknown type and a non-numeric PR number (`ignore`, `issue_pattern`). In PR title, `--pr` checks that a PR into main names each new fragment after itself, that only a release PR edits a `CHANGELOG.md`, and that a release PR changes nothing else; a Linux one also sets the version.

.claude/rules/ci.md

@@ -100,7 +100,7 @@ The required check names are in `AGENTS.md` (CI). Reading a red check: `.claude/
   - `shellcheck --severity=warning` on every `*.sh` under `scripts` and `.claude/skills`;
   - the tooling tests: `scripts/ci/test_*.py`, `scripts/lib/test_*.py`, `scripts/test_localization.py` and `scripts/ci/test_libs_release.sh`;
   - `scripts/release/test_*.py` on Python 3.9 from `actions/setup-python`, in a venv that installs `scripts/release/requirements.txt` with `pip --require-hashes`;
-  - in the same venv, `check-changelog.py` and `towncrier build --draft --version 0.0.0`, which fails on a fragment name it cannot parse;
+  - in the same venv, `check-changelog.py` and `towncrier build --draft --version 0.0.0` for the root and `--dir linux`, which fails on a fragment name it cannot parse;
   - `check-lib-sourcing.py`, `check-plugin-manifest.py`, `check-plugin-provides.py`, `check-deployment-target.sh`, `check-ios-shared-isolation.py`;
   - `localization.py plugins` and `plugins --target ios`;
   - `check-string-catalogs.py`, `check-license-inventory.py`, `check-entitlements.py`, `check-test-plans.py`;
@@ -119,23 +119,24 @@ The required check names are in `AGENTS.md` (CI). Reading a red check: `.claude/
 - `ios` watches `TableProMobile/`, `Libs/`, `Plugins/TableProPluginKit/` (the package target is a symlink to it), and every `../` path it reads out of `TableProMobile/project.yml`.
 - `oracle` watches `Packages/TableProOracle/`; `hana` watches `Native/HanaBridge/`. Each suite also watches its own workflow.
 - `release` watches what the Release build reads: the app, plugin, package, native, config and libs folders, `project.yml`, the app's `Package.resolved`, `.github/plugin-registry.json`, the release scripts it runs (`build.sh`, `package.sh`, `registry.py`, `version.py`, `notes.py`), the build and CI scripts it runs and the setup actions. It skips `Plugins/*Tests/` and `Packages/*/Tests/`.
+- `linux` watches `linux/`, the docs and banned-words scripts the Linux fast job runs, the detector itself and the three Linux workflows.
 - A path a suite newly reads joins that suite's pattern in the same change, or the suite skips on it.
 - `CHANGELOG.md` and `changelog.d/` are on no suite's pattern: the What's New phase writes nothing at `0.0.0-dev`, and Repo Hygiene renders every fragment and section instead.
 
 ## What runs where
 
 - A pull request: both changes jobs; macOS Tests and iOS and Package Tests unless their detector says false (Oracle only when its detector is not false); SwiftLint; Repo Hygiene; PR title. `AllPlugins` only when the `plugins` detector is not false.
 - A push to main or `release/**`: the same minus PR title, plus Release Build; never cancelled, `AllPlugins` always, the SPM cache saved on a miss. Every code push runs both plans in full; a docs-only or changelog-only push skips the suites through the detector.
-- A `v*` tag runs only `release.yml`. The test workflows never run on a tag.
+- A `v*` tag runs only `release.yml`, and a `linux-v*` tag only `release-linux.yml`, which calls `linux-packages.yml`. The test workflows never run on a tag.
 - `workflow_dispatch` exists on every workflow except `pr-title.yml` and `release.yml`.
-- `build-linux.yml` is on `main` only for its Monday schedule, which GitHub runs from the default branch. Until the Linux app's directory lands on `main`, every build job skips and `weekly-dispatch` starts the workflow on the branch the `LINUX_BRANCH` variable names (the linux branch when unset), whose testing guide describes the jobs.
+- `build-linux.yml` builds and tests the Linux app (`linux/docs/testing.md`, CI). Its `Changes (Linux)` job skips the rest when nothing under `linux/` or the scripts and workflows it reads changed, and its `Linux` job gates on all of them.
 
 ## Caches and runner budget
 
 - Swift package checkouts live in `~/.spm-cache`, keyed `spm-<os>-<hash of the app's Package.resolved>` with prefix restore. macOS Tests saves it only on a push and only on a miss: a cache saved on a PR ref is visible to that PR alone.
 - `release.yml` restores that cache and never saves it, since a save in tag scope is unreadable from other refs.
 - `release-build.yml` restores it and leaves the save to macOS Tests.
-- There is no other cache: no libs or DerivedData cache, and none in the iOS, plugin or Ubuntu workflows.
+- There is no other Apple cache: no libs or DerivedData cache, and none in the iOS or plugin workflows. The Linux jobs cache Cargo builds through `Swatinem/rust-cache` and the Flatpak build.
 - CI fits the GitHub Free and Pro plans: no paid larger runner, no self-hosted Mac. At most 5 macOS jobs run at once, and main runs queue behind PR runs for those slots.
 
 ## Writing workflow and lint code

.claude/skills/fix-issue/references/platform-linux.md

@@ -0,0 +1,54 @@
+# Platform: Linux
+
+The native Linux app. Every profile has these seven sections in this order, so a value is always in the same place.
+
+## Covers
+
+A report from Linux. The code is `linux/`: a Cargo workspace of crates under `linux/crates/` (the GTK app, the UI-free core, storage, sessions, networking, SSH and one crate per driver), built by Meson. Drivers are linked in at compile time; there are no plugins. A fix lands in one or more crates; name them.
+
+## Base
+
+- Worktree base: `origin/main`.
+- Pull request base: `main`.
+
+## Done
+
+`linux/AGENTS.md`, plus the root `AGENTS.md` principles and writing style it points to. Under Claude Code, `linux/CLAUDE.md` loads it once a file under `linux/` is read; read it by path anyway in Phase 0, since the worktree path is not guaranteed to trigger that. Codex does not load it at all, so read it yourself.
+
+## Native standard
+
+GTK 4 and libadwaita, used the way the GNOME Human Interface Guidelines describe, with the widget the toolkit already provides before anything drawn by hand. The version floor is GNOME 50: GTK 4.22, libadwaita 1.9, GtkSourceView 5.18, GLib 2.88. The compiler enforces it through the binding crates' feature gates, so an API above the floor does not build.
+
+Sources, the API ground truth and how to build a probe: `references/research-linux.md`.
+
+## Verify
+
+Pass `--platform linux`, which a Linux machine picks by default. Every step runs inside `<tree>/linux` with the environment `meson devenv` gives Cargo.
+
+| Step | When |
+| --- | --- |
+| `setup` | a new tree; `linux/meson.build`, `linux/meson.options` or a file under `linux/data/` changed |
+| `build` | always |
+| `test <package> [filter]` | always, for each crate you changed |
+| `test` | before the pull request: every suite, as the CI fast job runs them |
+| `lint` | always: rustfmt, then clippy with and without default features |
+| `data` | a desktop entry, the GSettings schema, the metainfo or the icons changed |
+| `l10n` | a user-facing string or a file that holds them changed |
+| `docker <package>` | a driver, SSH or anything they connect through changed |
+| `secrets` | `tablepro-storage` secret handling changed |
+| `dist` | `meson.build` install rules changed (commit first) |
+
+- The first step after a merge from the base is `setup`.
+- Pick packages by what you changed: `grep -rl <name> linux/crates --include='*.rs'`. Package names are in each crate's `Cargo.toml`.
+- Extra review pass: none beyond the security pass.
+- Traps and remedies: `references/verification-linux.md`.
+
+## Screen
+
+Run the app from the tree with `meson devenv -C _build ./crates/app/tablepro` inside `linux/`. A development build uses its own application ID and data directories, so it never touches an installed one; point the `XDG_*_HOME` variables at a scratch directory as well when the shot must not show the user's real connections. Nothing drives the app from a script yet: only `app.*` actions reach D-Bus, and the window's actions do not. Launch it in the state the shot needs and capture with the `org.freedesktop.portal.Screenshot` portal, which GNOME allows for an unsandboxed caller; `org.gnome.Shell.Screenshot` refuses. The portal captures the whole screen, so crop to the window. Dark and light: `ADW_DEBUG_COLOR_SCHEME=force-dark` or `force-light`.
+
+## Ship
+
+- A user-visible change gets one fragment in `linux/changelog.d/` (`.claude/rules/changelog.md`), never in the root `changelog.d/`, which is the macOS release notes.
+- Commit scope `linux`, or `linux-<area>` for one area of the app.
+- A probe worth keeping becomes a test in the crate it measures; the Linux workspace keeps no separate probe directory.

.claude/skills/fix-issue/references/research-linux.md

@@ -0,0 +1,47 @@
+# Research sources: Linux
+
+Where to find the correct behavior for the Linux app, and what counts as evidence for it. The method is in the research brief (`references/lanes.md`); this file is the sources.
+
+## GNOME platform
+
+- **API ground truth: the GObject Introspection files** under `/usr/share/gir-1.0/` (`Gtk-4.0.gir`, `Adw-1.gir`, `GtkSource-5.gir`, `Gio-2.0.gir`; GLib's is under `/usr/lib/<multiarch>/gir-1.0/`). Each symbol carries the version that introduced it, so `grep -n -A3 '<class name="Sidebar"' /usr/share/gir-1.0/Adw-1.gir` answers whether it is at or below the floor. The C headers say the same with `GDK_AVAILABLE_IN_4_22`, `ADW_AVAILABLE_IN_1_9` and `GTK_SOURCE_AVAILABLE_IN_5_18`.
+- **The Rust bindings** gate each symbol behind a feature such as `v4_22` or `v1_9`. The workspace enables the GNOME 50 set in `linux/Cargo.toml`, so read the gate in the crate's source when the question is whether a binding exists: it is under `linux/_build/cargo-home/registry/src/` once the tree has been built.
+- **The web documentation is newer than the floor.** docs.gtk.org and the GtkSourceView site document later releases than GNOME 50, and even the installed GIR files carry the odd newer symbol. A web page gives the intent; the GIR version and the feature gate settle whether TablePro can use it.
+- **GNOME Human Interface Guidelines**: `https://developer.gnome.org/hig/`. For a database client the pages that matter most are header bars, sidebars, utility panes, boxed lists, list and column views, selection mode, tabs, search, menus, dialogs, toasts, banners, placeholders, keyboard and accessibility. Quote the rule; "the HIG says so" without a quote is not evidence.
+- **API references**: GTK at `https://docs.gtk.org/gtk4/`, libadwaita for the floor at `https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1.9/`, GtkSourceView at `https://gnome.pages.gitlab.gnome.org/gtksourceview/gtksourceview5/`, gtk4-rs at `https://gtk-rs.org/gtk4-rs/stable/latest/docs/gtk4/`, libadwaita-rs at `https://world.pages.gitlab.gnome.org/Rust/libadwaita-rs/stable/latest/docs/libadwaita/`. The Relm4 book trails the version in `linux/Cargo.lock`, so read the locked crate's source for Relm4.
+- **freedesktop specifications**, for anything that talks to the desktop: Secret Service (`https://specifications.freedesktop.org/secret-service/latest/`), XDG Desktop Portal (`https://flatpak.github.io/xdg-desktop-portal/docs/api-reference.html`), Desktop Entry (`https://specifications.freedesktop.org/desktop-entry/latest/`), AppStream (validate locally with `appstreamcli validate --explain`) and the Flathub MetaInfo guidelines (`https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines`).
+- **TablePro's own decisions** in `linux/docs/decisions/` and `linux/ARCHITECTURE.md`: a fix must not contradict a recorded decision without saying so.
+
+## Dependencies
+
+The source is the crate as compiled, not a web page.
+
+- Versions are in `linux/Cargo.lock`. A crate pinned to a git revision is in `linux/Cargo.toml`, and its checkout is under `linux/_build/cargo-home/git/checkouts/`.
+- Read the crate's source at that version under `linux/_build/cargo-home/registry/src/`, with the doc comments for each item in play and what a call returns when it cannot do the job.
+- System libraries the binary links (SQLite, MIT Kerberos, GTK) are the installed versions; `pkg-config --modversion <name>` gives each.
+- Where the source does not settle it, measure: a test against the real engine (marked `#[ignore = "requires docker"]` when it needs a container) or a scratch Cargo project that links what we link. The workspace has no mocks, so a probe uses the real thing.
+
+## Comparable clients
+
+A Linux user describing how something "should" work is usually describing one of these. None of them is a GTK app, so they answer what capability users expect, never how it should look.
+
+| Client | Why read it | Where |
+| --- | --- | --- |
+| DBeaver | The default database client on Linux; widest driver and dialect coverage | `github.com/dbeaver/dbeaver` |
+| DataGrip | Deepest SQL tooling; take the capability, not the interaction | `jetbrains.com/datagrip` |
+| Beekeeper Studio | Open source, ships Linux builds | `github.com/beekeeper-studio/beekeeper-studio` |
+| DbGate | Open source, cross-engine | `github.com/dbgate/dbgate` |
+| pgAdmin 4 | The PostgreSQL reference tool | `github.com/pgadmin-org/pgadmin4` |
+| DB Browser for SQLite | The SQLite reference tool | `github.com/sqlitebrowser/sqlitebrowser` |
+
+For how a surface should look and behave, read GNOME applications built on the same stack:
+
+| Application | Read it for | Where |
+| --- | --- | --- |
+| libadwaita demo | One page per pattern, in its `demo` folder | `gitlab.gnome.org/GNOME/libadwaita` |
+| GNOME Text Editor | A GtkSourceView editor with tabs, a sidebar and search | `gitlab.gnome.org/GNOME/gnome-text-editor` |
+| GNOME Builder | Panes, a source editor, search and trees at IDE scale | `gitlab.gnome.org/GNOME/gnome-builder` |
+| Loupe, Snapshot, Fractal | Rust apps with the same Meson and Cargo shape | `gitlab.gnome.org/GNOME/loupe`, `gitlab.gnome.org/GNOME/snapshot`, `gitlab.gnome.org/World/fractal` |
+| Nautilus | Sidebars, column views and selection mode | `gitlab.gnome.org/GNOME/nautilus` |
+
+None of these can be run from here, so every claim about one is confirmed from a source you read or marked inferred.