Owner: lane PKG/QA. See ../docs/07-packaging.md.

## `.deb` — local test build only

There is no PPA, no GPG signing, no Launchpad wiring here. This produces a `.deb` you
install with `dpkg -i` on the box you built it on (or an identical one), for testing —
not something to hand to a user or publish anywhere. See `docs/07-packaging.md`'s
package matrix for the eventual PPA plan.

```sh
sudo ./tools/bootstrap.sh --packaging          # debhelper, dpkg-dev, lintian, devscripts, fakeroot
dpkg-buildpackage -us -uc -b                   # from the repo root; -b = binary only, no signing
sudo dpkg -i ../velox_0.1.0-1_amd64.deb
lintian ../velox_0.1.0-1_amd64.deb
```

Uninstall: `sudo dpkg -r velox` (or `sudo dpkg -P velox` to purge — see below for what
purge does and does not do here).

### Known limitations of this build — read before relying on any of these

- **`libveloxcore` is static, not `.so.1`.** The install layout in `docs/07-packaging.md`
  originally called for a shared, versioned `libveloxcore.so.1`; the user decided against
  building one for now (no consumer needs it as a shared object yet, and it would need a
  `SOVERSION` added to CORE's own `core/CMakeLists.txt`). The doc was corrected in the
  same commit as this packaging work — it no longer describes something unshipped.

- **Placeholder app icon.** `gui/resources/icons/` (GUI's lane) is empty — no real icon
  art exists anywhere in the repo yet. `packaging/icons/hicolor/*/apps/velox.png` is a
  plain generated placeholder (flat color, a download-arrow glyph), good enough to
  install correctly and pass `desktop-file-validate`/lintian's icon checks, and nothing
  more. **Replace it before any real release** — and do the icon-set licence audit
  `docs/07-packaging.md`'s release checklist asks for once real art exists (this
  placeholder was drawn from scratch for this package, so it has no licence question of
  its own, but it is not real Velox branding either).

- **No license has been chosen for Velox's own source yet.** There is no top-level
  `LICENSE` file in the repo. `debian/copyright` says so plainly (`License:
  Unlicensed-TODO`) rather than inventing one — that is a real project decision, above
  any one lane. Expect `lintian` to flag this package over it; that is lintian doing its
  job, not a bug in this packaging, and it stays a known exception to "lintian clean"
  until the project adopts a license. The release checklist's "Licence audit" item (Qt,
  libcurl, SQLite, ffmpeg, icon set) is separate and still open regardless.

- **Pairing has no real approval UI in this build.** `libdbus-1-dev` is not in this
  build's `Build-Depends` (D1's GUI-dialog/desktop-notification approver needs it and
  isn't wired up yet — `daemon/src/main.cpp` still uses `EnvAutoApprover`
  unconditionally). That approver auto-**rejects** every pairing request unless
  `VELOX_PAIR_AUTO=1` is set in `veloxd`'s environment — there is no prompt, no
  accept/decline, it is all-or-nothing. `postinst` prints this prominently after
  install; it is repeated here so it isn't missed by anyone reading only one of the two.
  **Do not set `VELOX_PAIR_AUTO=1` on a machine or account where auto-accepting every
  pairing request is unacceptable.**

- **Socket activation is real.** `velox.service` and `velox.socket` both ship, verbatim
  from DAEMON's `packaging/systemd/README.md` — `veloxd` receives the pre-bound fd via
  `sd_listen_fds()` (`daemon/src/rpc/systemd_activation.cpp`) rather than binding its own
  socket. `debian/rules` does **not** disable `dh_installsystemduser` (only the
  system-level `dh_installsystemd`, since these are `--user` units); debhelper finds both
  units under `lib/systemd/user/` in the install tree and enables the pair together
  (`Also=velox.socket` in `velox.service`'s `[Install]`).

- **The systemd `--user` service starts enabled for your *next* login, not this one.**
  debhelper's `dh_installsystemduser` (verified in the built package's `postinst`) marks
  `velox.service` enabled automatically — that takes effect the next time each user's
  `systemd --user` instance starts. It cannot reach an *already-running* session from a
  root maintainer script, so for the session you're in right now, `postinst` prints:
  ```sh
  systemctl --user daemon-reload
  systemctl --user start velox.service
  ```

- **`dpkg -P velox` (purge) does not delete user data.** The uninstall test this package
  is built to pass is "manifests, units and sockets removed; user data untouched *unless
  purged*" — this build is deliberately conservative and leaves `$XDG_DATA_HOME/velox`
  (normally `~/.local/share/velox`, the task database) alone on **both** `remove` and
  `purge`, for every account. A root maintainer script deleting per-user data across
  every account on the system is exactly the kind of destructive, hard-to-test operation
  that deserves its own design pass, not a first cut bolted on here. `postrm` only ever
  undoes what `postinst` did: the per-user native-messaging manifest it copied in.

### The uninstall test, concretely

What `docs/07-packaging.md`'s release checklist asks for, and what this build actually
does:

| Removed on `dpkg -r`/`-P`? | |
|---|---|
| `/usr/bin/{veloxd,velox,velox-gui}`, `/usr/libexec/velox/velox-nmhost` | yes — dpkg itself, ordinary package files |
| `/usr/lib/systemd/user/{velox.service,velox.socket}` | yes — same |
| `/usr/lib/mozilla/native-messaging-hosts/com.velox.host.json` | yes — same |
| Per-user `~/.mozilla/native-messaging-hosts/com.velox.host.json` | yes — `postrm`, both `remove` and `purge` |
| `$XDG_DATA_HOME/velox` (task DB, settings) | **no, on either `remove` or `purge`** — see above |

### Native messaging

`velox-nmhost` (DAEMON's `nmhost/`) and its manifest (DAEMON's
`packaging/nativehost/com.velox.host.json`) now ship in this package — the top-level
`CMakeLists.txt`'s install rules are guarded on `if(TARGET velox-nmhost)`, the same way its
`add_subdirectory()` calls are, so this lit up automatically the day that lane merged, no
packaging change needed on this end.