docs: add session handoff (mac-app-launcher)

docs: update CLAUDE.md + DECISIONS.md for macOS .app launcher addition
CLAUDE.md: removed stale "(to be implemented per spec §5.5)" wording for check-no-upstream-edits.sh (script is implemented and battle-tested), added tests-impl/ to the dirs-list, expanded the guardrail description. DECISIONS.md: appended the .app launcher decision (stub bundle synthesized in brew formula def install — sethLabels-side fix, no upstream patch).
2026-04-29 12:19:24 -04:00 · 2026-04-29 12:19:20 -04:00 · 2026-04-29 12:03:57 -04:00 · 2026-04-29 12:03:49 -04:00 · 2026-04-29 11:56:47 -04:00 · 2026-04-29 11:54:35 -04:00
24 changed files with 3634 additions and 12 deletions
@@ -0,0 +1,184 @@
+# Handoff: Packaging design spec approved — implementation plan pending
+
+## Session Metadata
+- Created: 2026-04-29 09:55:34 UTC
+- Project: /home/claude/bin/sethLabels
+- Branch: main
+- Session duration: ~1 hour
+- Live URL: https://git.sethpc.xyz/Seth/sethLabels
+
+### Recent Commits (for context)
+  - d3e14c6 docs: refresh CLAUDE.md + IDEA.md for design-approved phase
+  - 8e272c0 docs: add packaging design spec + decision log
+  - 9dc6776 chore: add sethLabels deployment-fork scaffold
+  - d1ee78e Fix incorrect font sizes (#321)              ← upstream HEAD
+  - 06675f8 Create template style guide and minor updates… ← upstream
+
+The first three commits are sethLabels'; everything from `d1ee78e` back is upstream's history (preserved untouched per strict-zero policy — see Important Context below).
+
+## Handoff Chain
+
+- **Continues from**: [2026-04-29-125823-scaffold-only.md](./2026-04-29-125823-scaffold-only.md)
+  - Previous title: sethLabels scaffolded — no code yet
+- **Supersedes**: None. The scaffold-only handoff documented an empty-dir state; this one documents the post-design-approval state.
+
+> Review the previous handoff for full context before filling this one. The "scaffold-only" predecessor's "Suggested Next Steps" #1 (decide upstream-tracking strategy) and #5 (initialize git + push to Gitea) are now complete; #2 (verify upstream alive) and #3 (confirm Qt version) are also resolved during this session.
+
+## Current State Summary
+
+This session moved sethLabels from "scaffold-only, no upstream pulled" to "design-approved, ready for implementation plan." Three things happened in order: (1) upstream `j-evins/glabels-qt` was cloned in-place and pushed to Gitea as `main`, with all 24 upstream contributors' commit authorship preserved end-to-end; (2) the brainstorming skill ran a 6-question multiple-choice round to lock all packaging-strategy decisions; (3) the resulting design was written into a 398-line spec at `sethlabels-docs/specs/2026-04-29-packaging-design.md` and committed. No `scripts/` or `packaging/` code was written — that's the next session's job. The spec is the load-bearing artifact; everything else (CLAUDE.md, IDEA.md, DECISIONS.md) was updated to point at it.
+
+The user explicitly chose option **(3) pause here** at session close, declining to invoke writing-plans this session. The spec is sufficient to resume cleanly; there are no in-progress edits or half-implemented states.
+
+## Architecture Overview
+
+**sethLabels is a deployment fork, not a real fork.** The discipline (locked as Invariant I1 in the spec) is **strict zero source patches** — no upstream-tracked file is ever edited. The only exception is `.gitignore` (allowlisted as a one-time scaffold-time touch). Every sethLabels addition lives in NEW files in NEW top-level directories:
+
+- Already created: `CLAUDE.md`, `IDEA.md`, `DECISIONS.md`, `GITEA_API.md` (gitignored symlink), `.claude/handoffs/`, `sethlabels-docs/specs/`
+- Planned per spec: `scripts/` (build-deb, build-appimages, compute-version, check-no-upstream-edits, lib/), `packaging/` (deb-metadata.env, appimage-recipe.env, changelog.md), `README.sethlabels.md`
+
+The "fork" is therefore best thought of as a **packaging repo with upstream's history embedded** — anyone can audit it instantly and confirm we changed nothing in the application itself.
+
+**Upstream details discovered during the session:**
+- Qt version: **Qt6 6.2** (find_package at `CMakeLists.txt:119`)
+- CPack metadata: pre-wired at `CMakeLists.txt:84-104`; generators NOT pinned → `cpack -G DEB` and `cpack -G DragNDrop` selectable at command line with zero source change
+- Install rules: clean and FHS-compliant across all subdirs (`bin`, `share/icons/hicolor`, `share/applications`, `share/mime`, `share/metainfo`, `share/man/man1`, `share/glabels-qt/{templates,translations}`)
+- Desktop integration: `.desktop` file, AppStream metainfo, MIME XML, hicolor icon set already provided by upstream
+- Two binaries shipped: `glabels-qt` (GUI) + `glabels-batch-qt` (CLI for scripted/mail-merge use)
+- CI matrix exists for ubuntu-latest, ubuntu-22.04, windows-latest, macos-latest — but upstream doesn't publish binary releases ("Currently there are no self-hosted binary snapshot releases available" — upstream README). sethLabels exists to fill this gap.
+
+## Critical Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| `sethlabels-docs/specs/2026-04-29-packaging-design.md` | THE design spec — 13 sections covering invariants, decisions, repo layout, build pipeline, release flow, brew tap, failure modes, smoke tests, glossary | **Must read before any implementation.** All design questions are answered here; do not re-derive. |
+| `DECISIONS.md` | Short-form decision log (6 settled choices + 13 rejected/deferred items) | Quick scan to check what's already been decided/rejected |
+| `CLAUDE.md` | Durable project instructions (refreshed this session) | Loaded on every session start; points at this handoff + the spec |
+| `IDEA.md` | Plain-language project brief (refreshed this session) | Read if scope feels unclear |
+| `CMakeLists.txt` (upstream root) | Defines Qt6 dep, CPack metadata, install rules | Read-only — strict-zero forbids edits. Reference for understanding what `cpack` and `linuxdeploy` will see. |
+| `.github/workflows/build-tests.yml` (upstream) | Upstream CI multi-platform build matrix | Reference for valid `apt install` deps + cmake invocation patterns when writing `scripts/lib/deps-debian.sh` |
+| `docs/BUILD-INSTRUCTIONS-LINUX.md` (upstream) | Upstream's manual build instructions | Reference for the `apt install` list + cmake flags; our `scripts/build-deb.sh` automates this |
+
+## Key Patterns Discovered
+
+- **Authorship preservation:** the gitea repo holds all 24 upstream contributors' commit authorship intact; the only Seth-authored commits are the sethLabels-specific additions (scaffold + spec + context-refresh). Verifiable via `git log --format='%an' origin/main | sort -u | wc -l` → 25 (24 upstream + Seth).
+- **Convention from sibling Seth projects** (`blind_chess`, `sethmux`, `kitty-web`, `mcp-gemma4`, `seth-orchestrator`): `GITEA_API.md` is gitignored (it's a local symlink to `~/bin/GITEA_API.md`); `.backup/` is gitignored; project-tracked files are `CLAUDE.md`, `IDEA.md`, `DECISIONS.md`, `.claude/handoffs/*.md`. sethLabels follows this convention but adds the strict-zero-policy gitignore section.
+- **Versioning convention:** `<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). Tag is `git describe --tags --abbrev=0 upstream/master`; `<N>` increments on re-package of the same upstream commit. See spec §D4 + §5.4.
+
+## Tasks Finished
+
+- [x] Cloned upstream `j-evins/glabels-qt` in-place; preserved all upstream commit authorship
+- [x] Created Gitea repo `git.sethpc.xyz/Seth/sethLabels` (default branch: `main`); pushed full history + scaffold commit
+- [x] Configured `upstream` remote → `github.com/j-evins/glabels-qt` for periodic rebases
+- [x] Added scaffold commit (`9dc6776`) with author `Seth Freiberg <seth@sethfreiberg.com>` containing CLAUDE.md, IDEA.md, DECISIONS.md, .claude/handoffs/, .gitignore additions
+- [x] Brainstormed all 6 packaging-strategy decisions: Linux format, macOS format, build infra, versioning, upstream-touch policy, package name
+- [x] Wrote design spec at `sethlabels-docs/specs/2026-04-29-packaging-design.md` (398 lines, 13 sections); self-reviewed and fixed 5 inline issues (FF/rebase wording, --peek removal, tag-fetch caller responsibility, T3 brittleness, working-tree drift in check-no-upstream-edits)
+- [x] Updated `DECISIONS.md` with 6 settled + 13 rejected/deferred decisions (all dated 2026-04-29)
+- [x] Refreshed `CLAUDE.md` "Current State" + "Conventions" sections; refreshed `IDEA.md` "Constraints / preferences"
+- [x] All 3 sethLabels commits pushed to Gitea immediately per the gitea-workflow convention
+
+## Files Modified
+
+| File | Changes | Rationale |
+|------|---------|-----------|
+| `.gitignore` | Appended sethLabels section (`.backup/`, `GITEA_API.md`, `.env*`, `.claude/handoffs/*.draft.md`) | Allowlisted exception to strict-zero (one-time scaffold touch) |
+| `CLAUDE.md` | NEW — project instructions | Created at scaffold time; refreshed this session for design-approved phase |
+| `IDEA.md` | NEW — project brief | Created at scaffold time; refreshed this session |
+| `DECISIONS.md` | NEW — populated with 6 settled + 13 rejected/deferred decisions | Tracks what was decided vs. explicitly rejected (per Seth's global persistence convention) |
+| `sethlabels-docs/specs/2026-04-29-packaging-design.md` | NEW — design spec | The design artifact this session produced |
+| `.claude/handoffs/2026-04-29-095534-spec-approved-pre-implementation.md` | NEW — this handoff | Session close artifact |
+
+No upstream files were modified (verified by `git diff --name-only upstream/master..HEAD` — only allowlist entries appear).
+
+## Decisions Made
+
+| Decision | Options Considered | Rationale |
+|----------|-------------------|-----------|
+| Linux: `.deb` + AppImage | AppImage-only, .deb-only, both, Flatpak | `.deb` for Debian-family install ergonomics + AppImage for any-Linux portability. Flatpak too heavyweight for use case. See spec §D1. |
+| macOS: Homebrew tap, build-from-source | Unsigned .dmg, signed+notarized .dmg ($99/yr), brew tap, brew tap with cask | Brew tap eliminates macOS CI/signing/Apple Dev ID entirely. User's Mac builds from source on `brew install`. See spec §D2. |
+| Build infrastructure: manual local builds | Manual, Gitea Actions runner, GitHub Actions public, GitHub Actions private | Local feedback loop beats CI loop during iteration. Scripts in `scripts/` are canonical recipe; CI YAML at the public-flip will call them unmodified. See spec §D3. |
+| Versioning: `<upstream-tag>-seth<N>` | This vs. plain upstream tag, independent semver, date-based | Lineage-preserving + rebuild counter survives packaging-only fixes + sorts correctly under `dpkg --compare-versions`. See spec §D4. |
+| Upstream-touch policy: strict zero | Strict zero, permissive small patches, strict-zero-with-CMakeLists-carveout | CPack `-D` flags cover all needed metadata at build time → no edit required to package. See spec §D5. |
+| Package name: `glabels-qt` | This vs. `sethlabels` | Strict-zero forbids renaming the binary, so package name should match command name. sethLabels identity lives in repo name + version-string `-seth<N>` marker. See spec §D6. |
+| Spec/docs location: `sethlabels-docs/` (top-level new dir) | This vs. `docs/superpowers/specs/` (inside upstream's docs/) | Strict-zero spirit forbids polluting upstream namespaces, even with new files. Top-level new dir = cleanest fork boundary. |
+
+## Immediate Next Steps
+
+1. **Invoke `writing-plans` skill** with the spec at `sethlabels-docs/specs/2026-04-29-packaging-design.md` as input. The plan should produce an ordered, dependency-aware implementation sequence — likely something like: (a) scripts/lib/deps-debian.sh, (b) scripts/check-no-upstream-edits.sh, (c) scripts/compute-version.sh, (d) scripts/build-deb.sh + smoke test on a clean Debian 13 box, (e) scripts/build-appimages.sh + smoke tests, (f) packaging/ env files, (g) README.sethlabels.md, (h) homebrew tap repo + initial formula, (i) first end-to-end release dry run.
+2. **Address the 4 user-flagged review items** before or during plan execution:
+   - §5.1 build dependency list — Seth may know Debian 13 quirks (e.g., `qt6-tools-dev-tools` vs `qt6-tools-dev` package naming)
+   - §5.5 allowlist pattern — anything Seth wants to add that doesn't fit `scripts/`/`packaging/`/`sethlabels-docs/`?
+   - §7.2 brew formula `:recommended` deps — `qrencode` and `zint` as recommended (default-on) vs required vs optional
+   - §10 smoke test T5 — gate every release on a fresh-Debian-13-VM install test, or only on upstream-tag bumps?
+3. **Consider whether to spike Path A (Qt for WebAssembly)** later — Seth raised this as a hypothetical and we concluded it's "possible but not easy" because Qt's `QPrintSupport` doesn't work in WASM (would need to render-to-PDF and let user download). Not blocking, just flagged for future.
+
+## Blockers / Open Questions
+
+- None blocking. The 4 review items in step 2 above are open but optional — they can be addressed during plan execution as small fixups, not gating questions.
+
+## Deferred Items
+
+- **Windows packaging** — deferred per project brief. Upstream's NSIS support is intact and works for anyone who wants to build their own.
+- **Custom default templates baked into the package** — strict-zero forbids; user-specific templates can live in `~/.config/glabels-qt/templates/` or a future separate repo.
+- **Branding, icon, splash, or string changes** — strict-zero forbids. sethLabels is a packaging fork, not a rebrand.
+- **CI infrastructure (Gitea Actions / GitHub Actions runner)** — battle-test phase is manual local builds; CI is added at the eventual public-flip on GitHub.
+- **Distribution to Debian backports / PPA / Ubuntu universe** — requires Debian Developer mentorship + ongoing policy compliance work; not justified for current scope.
+- **Headless print-server CT** — mentioned in `IDEA.md` as "optional/later"; not in current spec scope.
+
+## Important Context
+
+**The strict-zero source-patch policy is not a guideline, it is the project's defining discipline.** Violating it means the project drifts from "deployment fork" toward "real fork," which breaks the trivial-rebase property that makes the whole approach work. The spec's Invariant I1 is enforced by `scripts/check-no-upstream-edits.sh` (to be implemented per spec §5.5). Any temptation to "just edit one upstream file to fix a packaging issue" should be resisted — the right move is either (a) pass via `cpack -D` flags or `linuxdeploy` config, or (b) upstream the fix as a PR to glabels-qt.
+
+**The eventually-public-on-GitHub framing matters for build-host neutrality.** During battle-test, builds happen on steel141 (Seth's primary dev machine, Debian 13). At public-flip, builds move to GitHub Actions ubuntu-latest runners. The build scripts MUST work on a clean Debian 13 / Ubuntu LTS VM with nothing pre-installed beyond what `scripts/lib/deps-debian.sh` declares. Any steel141-specific path or tool dependency is a bug.
+
+**Steel141 is a build host, NOT an install target.** Earlier session draft framed it as the deploy target — that was wrong, corrected during Q1. The artifacts ship to anyone running Debian-family Linux or macOS-with-brew.
+
+**Authorship in git history is load-bearing.** All 24 upstream contributors' commits appear in `git log` with their original author/committer fields intact. Only sethLabels-specific commits (currently 3) carry Seth's authorship. This makes the fork's relationship to upstream provable end-to-end and is critical for the eventual public-fork narrative.
+
+**The "scaffold commit" is the only sethLabels commit on top of upstream/master.** Currently `9dc6776 chore: add sethLabels deployment-fork scaffold`. Two more commits exist (`8e272c0` spec + `d3e14c6` CLAUDE.md/IDEA.md refresh) but they only touch sethLabels-namespaced files. The number of commits on top of upstream will grow; what matters is that all of them honor strict-zero.
+
+## Assumptions Made
+
+- **The user picked `glabels-qt` as the package name** (Q6 → α) intending the binary, brew formula, and `.deb` package to all share the name. If a future Debian official `glabels-qt` package emerges, the version-string `-seth<N>` marker will dominate the sort, but a name conflict could be revisited.
+- **The user has Homebrew on the macOS machines they intend to install on.** The brew-tap approach assumes a technical user; if a non-technical macOS user enters scope, signed-DMG would have to be reconsidered.
+- **The user's scaffold commit (Author: Seth Freiberg <seth@sethfreiberg.com>) was set explicitly via `git config user.email seth@sethfreiberg.com` for this repo only.** The global git identity on steel141 is `Mortdecai` (a bot identity). Future commits in this repo from Claude Code should use the same Seth identity to maintain authorship consistency. The per-repo `.git/config` is already set; new agents inherit it automatically.
+
+## Potential Gotchas
+
+- **Don't run a non-rebase pull from upstream.** `git pull upstream master` (without `--rebase`) would create a merge commit, breaking linear history and complicating future strict-zero enforcement. The release flow's step 2 (spec §6) says `git rebase upstream/master`, which is correct.
+- **`compute-version.sh` reads local tag database.** If invoked outside the release flow without a fresh `git fetch --all --tags`, it can produce a stale `<N>` value. Spec §5.4 calls this out, but it's easy to miss when running scripts manually during development.
+- **AppImage builds need `linuxdeploy` and `linuxdeploy-plugin-qt` from GitHub releases — neither is apt-installable.** `scripts/lib/linuxdeploy.sh` (to be written) handles bootstrap to a script-local cache. The cache directory must be added to `.gitignore`.
+- **`dpkg-shlibdeps` (CPack's `SHLIBDEPS=ON`) sometimes mis-detects runtime deps** — particularly with optional Qt6 plugins. Mitigation in spec §F8: smoke-test install on a clean Debian 13 VM (T5).
+- **`brew tap` from non-GitHub URLs requires the explicit URL form.** Initial install is `brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git`, not `brew tap seth/tap`. This is documented in spec §7.3 but easy to forget when writing the brew tap README.
+- **Don't add `superpowers/` paths under `docs/`.** The brainstorming skill's default spec location is `docs/superpowers/specs/`, but `docs/` is an upstream directory, so we use `sethlabels-docs/specs/` instead. This was caught and corrected mid-session.
+
+## Environment State
+
+### Tools/Services Used
+
+- **gitea CLI** (`~/bin/gitea`) — used for `gitea create sethLabels`, `gitea remote sethLabels`. Token loaded from `~/.config/gitea/token`. Documented in `~/bin/GITEA_API.md` (symlinked into project but gitignored).
+- **git** — local tooling for clone, fetch, commit, push, tag. Per-repo identity set to `Seth Freiberg <seth@sethfreiberg.com>` to override the global `Mortdecai` bot identity.
+- **curl + python3** — used for Gitea API calls to verify `default_branch=main` post-push.
+
+### Active Processes
+
+- None. No background services were started or left running. No long-running shells.
+
+### Environment Variables
+
+- `HOMELAB_PASSWORD` — referenced by `~/bin/CLAUDE.md` for SSH access, NOT used in this session.
+- No other env vars set or required for the current state.
+
+## Related Resources
+
+- **Gitea repo:** https://git.sethpc.xyz/Seth/sethLabels (default branch `main`)
+- **Spec:** [`sethlabels-docs/specs/2026-04-29-packaging-design.md`](../../sethlabels-docs/specs/2026-04-29-packaging-design.md) — read this before any implementation
+- **Decision log:** [`DECISIONS.md`](../../DECISIONS.md) — short-form
+- **Predecessor handoff:** [`2026-04-29-125823-scaffold-only.md`](./2026-04-29-125823-scaffold-only.md) — the empty-scaffold state we resumed from
+- **Upstream:** https://github.com/j-evins/glabels-qt (j-evins is Jaye Evins of glabels.org)
+- **Upstream README packaging gap:** the line we're filling — *"Currently there are no self-hosted binary snapshot releases available… I encourage you to try building the code yourself."*
+- **Sibling Seth projects with similar conventions:** `~/bin/blind_chess/` (handoff structure reference), `~/bin/sethmux/` (gitignore convention)
+
+---
+
+**Security Reminder**: Validated via `validate_handoff.py` post-write. No secrets present.
@@ -0,0 +1,167 @@
+# Handoff: macOS Launchpad/Spotlight integration via stub .app wrapper added to brew tap
+
+## Session Metadata
+- Created: 2026-04-29 12:15:29 UTC
+- Project: /home/claude/bin/sethLabels
+- Branch: main
+- Session duration: continuation of the same session that produced the first-release handoff (2026-04-29-155439); this addition is ~1 hour of follow-up work
+
+### Recent Commits (for context)
+  - f6c30f2 test: move bats scratch dirs to repo-local .test-scratch/ (per global no-/tmp/ rule)
+  - 76a3cb7 docs: README.sethlabels.md — include upstream remote setup in build-from-source
+  - 891cc7c docs: add session handoff (first-release)
+  - 2d04943 docs: refresh CLAUDE.md to post-first-release phase
+  - 2108e2c docs: changelog for 3.99-master618-seth1
+
+Plus pending uncommitted edits this session (will be committed by the wrap-up step):
+  - CLAUDE.md (Conventions section: removed stale "to be implemented" wording for check-no-upstream-edits.sh; added tests-impl/ to dirs list)
+  - DECISIONS.md (appended .app launcher decision)
+
+Brew tap repo (`git.sethpc.xyz/Seth/homebrew-tap`) has TWO new commits this session:
+  - ef4d6c7 feat: generate stub .app bundle for Launchpad/Spotlight integration on macOS
+  - 3542762 fix: use upstream SVG (not nonexistent PNG) for .app icon conversion
+
+## Handoff Chain
+
+- **Continues from**: [2026-04-29-155439-first-release.md](./2026-04-29-155439-first-release.md)
+  - Previous title: sethLabels packaging pipeline live — first release published
+- **Supersedes**: None.
+
+> The predecessor captures the 12-task implementation + first-release publication. This handoff extends that work with a single follow-up feature: macOS Launchpad/Spotlight integration. No regressions in the predecessor's deliverables; everything from the first release is unchanged and still live.
+
+## Current State Summary
+
+This session continued from "first release published" state. Seth asked whether the brew install would put a glabels-qt launcher icon in the Mac menu/Launchpad. Answer: no, because upstream's `glabels/CMakeLists.txt:125` declares `add_executable(glabels-qt WIN32 ...)` with no `MACOSX_BUNDLE` keyword, producing a CLI-only Mach-O on macOS. Strict-zero (I1) forbids patching upstream to fix this. Seth picked option 1 (stub `.app` wrapper synthesized in the brew formula) over option 2 (upstream a PR) and option 3 (switch to a Cask). Implemented as two commits on the brew tap repo. The sethLabels repo itself was NOT modified — the entire feature lives in the tap's `def install` block.
+
+The `.app` launcher works by: (1) cmake installs binaries to `bin/` per upstream rules, (2) brew formula's `def install` then synthesizes `<prefix>/glabels-qt.app/Contents/{Info.plist, MacOS/glabels-qt, Resources/glabels-qt.icns}` where the launcher script is a 2-line shell that `exec`s the real CLI binary, (3) the icon is converted from upstream's installed SVG via macOS-built-in `sips`, (4) the formula's `caveats` block tells the user to run `cp -R "$(brew --prefix glabels-qt)/glabels-qt.app" /Applications/` once.
+
+NOT YET VALIDATED: needs first install on a real Mac. Two unknowns: whether macOS 13+ `sips` actually accepts SVG input (begin/rescue catches the failure with an `opoo` if not — falls back to generic icon), and whether Gatekeeper requires a right-click→Open on first launch (likely yes since the .app isn't signed, but acceptable for the project's audience).
+
+## Codebase Understanding
+
+### Architecture Overview
+
+The brew tap pattern: a Homebrew formula's `def install` runs on the user's Mac during `brew install`. It can do anything the user's shell can do, including writing files outside the source tree (within the Cellar prefix). This is the legitimate sethLabels-side hook for filling gaps that strict-zero forbids fixing in upstream code. The .app wrapper is one such gap; others (e.g., a future macOS-specific `Info.plist` content type registration for `.glabels` files) could plug in here too.
+
+The launcher script approach (`exec "#{bin}/glabels-qt" "$@"`) is a thin wrapper, not a copy. It avoids:
+- Having to `MACOSX_BUNDLE` the cmake target (needs upstream patch — strict-zero forbids)
+- Running `macdeployqt` on the binary (needs Mac to build — defeats decision D2's no-Mac-CI goal)
+- Maintaining a separate Cask with a pre-built artifact (same problem)
+
+The wrapper has one downside: launching from Launchpad doesn't inherit a shell PATH, so the wrapper's `exec` path is hardcoded at install time using brew's `#{bin}` interpolation. That `#{bin}` resolves to `/opt/homebrew/Cellar/glabels-qt/<version>/bin/` on Apple Silicon, which has rpath set up correctly for Qt6 lookup. Should "just work" without `DYLD_LIBRARY_PATH` or `QT_PLUGIN_PATH` exports.
+
+### Critical Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| `~/bin/homebrew-tap/Formula/glabels-qt.rb` | The brew formula. Contains `def install` (cmake build + .app synthesis), `def caveats` (user-facing post-install message), and `test do` (assert `--version` works). | This is the ONLY file the user changes per release — bump `tag:` and `revision:` (and the SHA needs `# pragma: allowlist secret` to bypass the tap repo's detect-secrets pre-commit hook). |
+| `~/bin/homebrew-tap/README.md` | Tap install instructions. | Has a "Launchpad / Spotlight integration (macOS)" section documenting the one-time `cp -R` step. |
+| `glabels/CMakeLists.txt` (upstream — DO NOT EDIT) | Lines 125 (`add_executable(glabels-qt WIN32 ...)` — no MACOSX_BUNDLE) and 152-156 (icon install rules) explain why we need the wrapper and where the SVG icon comes from. | Read-only — strict-zero forbids edits. The reason we need the .app wrapper. |
+| `~/bin/sethLabels/sethlabels-docs/specs/2026-04-29-packaging-design.md` | Design spec. §D2 covers the brew tap decision; the .app wrapper is a sub-decision under it. | Reference for why brew tap was chosen over .dmg/Cask. |
+| `~/bin/sethLabels/DECISIONS.md` | Project decision log. Has a new entry for the .app launcher choice. | Quick scan to see what was already decided/rejected. |
+
+### Key Patterns Discovered
+
+- **`on_macos do ... end`** — Homebrew DSL block for macOS-only formula logic. Wraps both the .app generation (in `def install`) and the user message (in `def caveats`). On Linux brew (rare for this formula), the .app code is skipped entirely.
+- **Path interpolation in heredocs** — the launcher script uses `#{bin}/glabels-qt` interpolation. At formula evaluation time `#{bin}` becomes the absolute Cellar path. So the launcher script written to disk has a hardcoded full path, not an env-dependent reference.
+- **`sips` for SVG → icns** — macOS-built-in tool. Wrapped in `begin/rescue` so a sips failure on older macOS (which can't read SVG) just `opoo`s and the .app gets a generic icon — no error path.
+- **detect-secrets in tap repo** — the tap has a detect-secrets pre-commit hook that flags 40-char hex strings as secrets. The `revision:` field (a git SHA) gets a `# pragma: allowlist secret` inline comment. Every future tap bump must preserve that pragma. Future improvement: add the SHA pattern to `.secrets.baseline` so the pragma isn't needed.
+
+## Work Completed
+
+### Tasks Finished
+
+- [x] Diagnosed the menu-launcher question by reading upstream `glabels/CMakeLists.txt:125,150` (no `MACOSX_BUNDLE`) and `docs/BUILD-INSTRUCTIONS-MACOS.md` (CLI-only `make install`)
+- [x] Presented three implementation options to Seth; he picked option 1 (stub .app via brew formula)
+- [x] Implementer subagent generated the .app wrapper block in `def install` + `caveats` method + README.md "Launchpad / Spotlight" section. Committed as `ef4d6c7` on the tap.
+- [x] Caught a bug via context check: the initial implementation globbed for `glabels.png` but upstream installs only SVGs (`glabels/CMakeLists.txt:152-156`). The `opoo` fallback would have fired on every install, leaving every .app with a generic icon.
+- [x] Fix subagent updated the glob to `glabels.svg`, prefer the scalable variant, fall back to sized variants, wrap `sips` in `begin/rescue`. Committed as `3542762` on the tap.
+- [x] CLAUDE.md fixed: removed stale "(to be implemented per spec §5.5)" wording for the guardrail; added `tests-impl/` to the dirs-list (uncommitted at handoff time).
+- [x] DECISIONS.md appended: macOS Launchpad/Spotlight integration via stub .app wrapper, with rationale (uncommitted at handoff time).
+
+### Files Modified
+
+| File | Changes | Rationale |
+|------|---------|-----------|
+| `CLAUDE.md` (sethLabels) | Removed stale "(to be implemented per spec §5.5)" parenthetical; expanded the "Enforced by..." line to mention working-tree drift + ref-existence check; added `tests-impl/` to dirs list. | Stale wording flagged by cumulative review last session; tests-impl/ omission was a small accuracy gap. |
+| `DECISIONS.md` (sethLabels) | Appended decision entry for the .app launcher approach. | Project's Decision-Log convention: every non-obvious settled choice gets logged. |
+| `~/bin/homebrew-tap/Formula/glabels-qt.rb` | Added `on_macos do` block in `def install` to synthesize the .app; added `def caveats`; later fixed the icon glob from PNG to SVG. | Two commits — ef4d6c7 (initial) + 3542762 (icon fix). |
+| `~/bin/homebrew-tap/README.md` | New "Launchpad / Spotlight integration (macOS)" subsection under `## Install`. | User-facing docs for the one-time `cp -R` step. |
+
+### Decisions Made
+
+| Decision | Options Considered | Rationale |
+|----------|-------------------|-----------|
+| .app launcher via brew formula `def install` synthesis | (1) Brew formula synthesis, (2) Upstream PR adding MACOSX_BUNDLE, (3) Switch from Formula to Cask with pre-built .app | Option 1 lives entirely sethLabels-side, no upstream dep, no Mac CI required. Option 2 indefinite timeline (upstream review). Option 3 needs a Mac to build the .app (defeats D2's no-macOS-CI simplification). |
+| Icon source = upstream SVG, converted to icns via `sips` | (a) Skip icon (generic), (b) Convert SVG via sips, (c) Convert PNG via sips, (d) Ship pre-built .icns in tap repo, (e) Fetch .icns as a brew resource | (b) chosen. Upstream installs only SVGs — verified at `glabels/CMakeLists.txt:152-156`. (c) was the initial implementation's bug. (a) is the rescue-block fallback. (d)/(e) add tap-repo maintenance. |
+| Don't auto-link .app to /Applications/ | (i) Manual `cp -R` (user runs once), (ii) Symlink during install, (iii) Use `brew linkapps` | (i) chosen. (ii) requires writing to `/Applications/` which brew formulas can't do without sudo. (iii) is deprecated. The caveats block reminds the user. |
+
+## Immediate Next Steps
+
+1. **First Mac install validation.** When you (or Seth) get to a Mac with brew, run `brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git && brew install seth/tap/glabels-qt`. Expected: build succeeds (~5-10 min first time), `which glabels-qt` finds the binary, `cp -R "$(brew --prefix glabels-qt)/glabels-qt.app" /Applications/` succeeds, the app appears in Launchpad and is searchable in Spotlight. If `sips` failed silently (older macOS), the icon will be generic — check Launchpad first.
+2. **First-launch Gatekeeper handling.** macOS will likely block first launch with "cannot be opened because it is from an unidentified developer." Right-click → Open is the standard bypass. Document this in the tap README if it turns out to be a notable friction point.
+3. **T5 fresh-Debian-13-VM smoke test for the .deb** (still deferred from the first-release handoff — also not yet done). Spin up a clean Debian 13 VM, download the .deb from the release page, install with `apt install ./...`, run `glabels-qt --version`. If unmet deps surface, override via `CPACK_DEBIAN_PACKAGE_DEPENDS` in `scripts/build-deb.sh` and re-tag as -seth2.
+
+## Blockers / Open Questions
+
+- **Does `sips` on the user's macOS version handle SVG input?** macOS 13+ should; older versions may fail. The `rescue` block falls back gracefully — the only signal will be a generic Mac icon in Launchpad.
+- **Will Gatekeeper friction be acceptable to Seth's eventual users?** First-launch right-click→Open is standard for unsigned apps. If it becomes a nuisance, options are: (a) self-sign with a free Apple ID (no notarization, only works for personal use), (b) properly sign + notarize ($99/year — explicitly rejected in §D2), (c) document the right-click→Open step prominently.
+
+## Deferred Items
+
+- **Adding the SHA pattern to `.secrets.baseline`** in the tap repo — would eliminate the need for `# pragma: allowlist secret` on every future tap bump. Trivial change but I left it for a future session since it's not blocking.
+- **Verifying the `.app` actually contains all needed Qt6 plugins on user-side** — brew's Qt6 ships with cocoa platform plugin, image format plugins, and SVG support. The wrapper's `exec` of the real binary picks them up via the binary's rpath. Should "just work" but unconfirmed without a Mac test.
+- **Cumulative-review minor follow-ups** still deferred from previous handoff: build-appimages.sh step counter `[1/6]` reused 3x, `packaging/appimage-recipe.env` is currently unwired, `compute-version.sh` opaque error if upstream has no annotated tags, changelog.md not discoverable from README.
+
+## Important Context
+
+**The .app wrapper is the FIRST piece of sethLabels-side macOS-specific build logic.** Up to this point, sethLabels was fully cross-platform-by-virtue-of-strict-zero — every script was Linux-only because the targets were Linux-only. This session adds the first piece of mac-conditional code, but ONLY on the brew-tap side (the sethLabels repo itself remains Linux-targeted). Future macOS-specific gaps (e.g., `.glabels` UTI registration, dock badge support, etc.) should follow the same pattern: handled in the brew formula's `def install` and `def caveats`, never via patches to upstream code.
+
+**The tap's detect-secrets hook is a known papercut.** Every release-flow run will require manually preserving the `# pragma: allowlist secret` comment on the `revision:` line after `sed`-replacing the SHA. The cleanest fix is to add the SHA pattern to `.secrets.baseline` (a `pre-commit run --all-files` regenerate after a `pre-commit autoupdate`). Until then, the release flow's tap-bump step should warn about this.
+
+**Don't conflate the .app wrapper with a "real" Mac app.** It's a thin shell script in `Contents/MacOS/`. Apps that need to listen for system events, register URL schemes, or claim file types properly need a real bundle with proper Info.plist UTI declarations. The current Info.plist has only the bare-minimum keys for Launchpad/Spotlight; if Seth ever wants drag-a-`.glabels`-onto-the-icon behavior, that's a separate Info.plist change.
+
+## Assumptions Made
+
+- The user has macOS 13+ (so `sips` handles SVG). Older macOS gets the rescue path with a generic icon — works, just ugly. The project audience (technical users with brew) skews to recent macOS, so this is acceptable.
+- Brew's installed Qt6 binary correctly resolves Qt plugins via rpath when launched from a non-shell context (Launchpad). Standard for brew-installed Qt apps; unverified here.
+- The `/Applications/` copy is not a deal-breaker for the user (vs. an automatic symlink). Users running brew already accept similar manual steps for `brew linkapps`-style integrations.
+- Upstream's scalable SVG icon will continue to be installed at the spec'd path on macOS. If upstream restructures the icon install rules, the formula's glob may miss — `opoo` then falls through to generic icon (not a fail-build).
+
+## Potential Gotchas
+
+- **`brew --prefix glabels-qt`** in the caveats text resolves the formula's installed prefix. If the user runs the `cp -R` BEFORE actually installing, it'll error with "no formula found." The caveats text shows this command in the post-install message, which is where it makes sense.
+- **Re-running `cp -R` after `brew upgrade`** is required because Launchpad caches the .app. The README documents this. Future improvement could be a small post-install hint via `brew services`-style integration, but that's out of scope.
+- **Editing the formula requires care around heredoc delimiters.** The current file has three: `SH` (launcher), `PLIST` (Info.plist), `CAVEATS`. Each must open and close correctly; an unclosed heredoc would silently consume the rest of the file as content. Visual inspection on the live tap confirmed all three are balanced.
+- **The .app wrapper's launcher script is shell, not a Mach-O binary.** This may cause Gatekeeper to flag it more aggressively on first launch than a signed Mach-O would. If it becomes a problem, alternatives are: (a) hardlink/symlink the real binary into the launcher path, (b) compile a tiny C program that `exec`s the real binary.
+
+## Environment State
+
+### Tools/Services Used
+
+- **Homebrew tap** at `git.sethpc.xyz/Seth/homebrew-tap` — separate Gitea repo (NOT inside sethLabels). Has its own per-release commit history (one commit per release, bumping `tag:` and `revision:`).
+- **gitea CLI** (`~/bin/gitea`) — not directly used this session (the tap was already created in Task 11 of the previous session).
+- **detect-secrets** (pre-commit hook on the tap repo) — flagged the revision SHA; resolved with inline pragma comment.
+
+### Active Processes
+
+- None.
+
+### Environment Variables
+
+- `HOMEBREW_PREFIX` — referenced in the formula's `caveats` text, resolves on the user's Mac.
+- No new env vars set or required this session.
+
+## Related Resources
+
+- **First-release handoff (predecessor):** [`2026-04-29-155439-first-release.md`](./2026-04-29-155439-first-release.md) — predecessor capturing the 12-task implementation + first published release
+- **Spec-approved-pre-implementation handoff (grandfather):** [`2026-04-29-095534-spec-approved-pre-implementation.md`](./2026-04-29-095534-spec-approved-pre-implementation.md) — the design state we resumed from
+- **Design spec:** [`../sethlabels-docs/specs/2026-04-29-packaging-design.md`](../../sethlabels-docs/specs/2026-04-29-packaging-design.md) §D2 (brew tap decision)
+- **Implementation plan:** [`../sethlabels-docs/plans/2026-04-29-packaging-implementation.md`](../../sethlabels-docs/plans/2026-04-29-packaging-implementation.md) — the 12-task plan that built the pipeline
+- **Brew tap (live):** https://git.sethpc.xyz/Seth/homebrew-tap
+- **First sethLabels release:** https://git.sethpc.xyz/Seth/sethLabels/releases/tag/3.99-master618-seth1
+- **Upstream glabels-qt cmake target (read-only reference):** `glabels/CMakeLists.txt:125` (the `WIN32` keyword without `MACOSX_BUNDLE`) and `glabels/CMakeLists.txt:152-156` (icon install rules)
+
+---
+
+**Security Reminder**: No secrets present. Validated post-write.
@@ -0,0 +1,76 @@
+# Handoff: sethLabels packaging pipeline live — first release published
+
+## Session Metadata
+- Created: 2026-04-29 15:54:39 UTC
+- Project: /home/claude/bin/sethLabels
+- Branch: main
+- Live URL: https://git.sethpc.xyz/Seth/sethLabels
+- First release: https://git.sethpc.xyz/Seth/sethLabels/releases/tag/3.99-master618-seth1
+
+### Recent Commits (for context)
+```
+2d04943 docs: refresh CLAUDE.md to post-first-release phase
+2108e2c docs: changelog for 3.99-master618-seth1
+8290870 docs: add README.sethlabels.md (fork entry point)
+9b97080 docs: add scripts/README.md (operator run guide)
+2a789e3 fix: guard batch AppImage icon path with pre-flight check
+e619699 chore: add xvfb to deps-debian.sh (required by build-appimages smoke tests)
+f7e3565 fix: prune unused binary from each AppDir before linuxdeploy bundling
+d5fb872 feat: add build-appimages.sh with inline smoke tests T3, T4
+13d4047 fix: guard rm -rf in build-deb.sh against empty BUILD_DIR
+4f2de8a feat: add build-deb.sh with inline smoke tests T1, T2
+```
+
+## Handoff Chain
+
+- **Continues from**: [2026-04-29-095534-spec-approved-pre-implementation.md](./2026-04-29-095534-spec-approved-pre-implementation.md)
+
+## Current State Summary
+
+The sethLabels packaging pipeline is fully implemented and the first tag (3.99-master618-seth1) is published to Gitea with three artifacts (1 .deb + 2 AppImages). The Homebrew tap at `git.sethpc.xyz/Seth/homebrew-tap` is bumped to point at the new tag. CLAUDE.md is refreshed. Ready for periodic releases via the spec §6 flow.
+
+## Tasks Finished
+
+- [x] All 12 tasks of the implementation plan executed end-to-end
+- [x] First .deb built and attached: glabels-qt_3.99-master618-seth1_amd64.deb (42M / 43,640,116 bytes)
+- [x] First AppImages built and attached: sethlabels-gui-3.99-master618-seth1-x86_64.AppImage (34M / 34,781,688 bytes) and sethlabels-batch-3.99-master618-seth1-x86_64.AppImage (33M / 34,404,856 bytes)
+- [x] Gitea release published at https://git.sethpc.xyz/Seth/sethLabels/releases/tag/3.99-master618-seth1 (release ID 24)
+- [x] Homebrew tap bumped to 3.99-master618-seth1 (commit 3f0451c on git.sethpc.xyz/Seth/homebrew-tap)
+- [x] CLAUDE.md refreshed for post-first-release phase (commit 2d04943)
+- [x] Three smoke tests pass: T1 (.deb info), T2 (.deb contents), T3 (batch --version), T4 (gui --help under Xvfb)
+
+## Deferred / Skipped
+
+- T5 (fresh Debian 13 VM install test) — skipped on this dry run; required before public-flip on GitHub.
+- macOS install validation — needs a Mac with brew. Formula syntax was not pre-checked because steel141 has no ruby installed. Run `brew install seth/tap/glabels-qt` on a Mac to verify.
+
+## Suggested Next Steps
+
+1. Periodic upstream rebase + new release: when upstream tags a new master version, follow the spec §6 release flow to publish a new sethLabels-N tag.
+2. T5 fresh-VM smoke test: spin up a clean Debian 13 VM, download the .deb from the release page, install with `apt install ./...`, run `glabels-qt --version`. If anything fails, the `dpkg-shlibdeps` calculation was wrong (spec §F8) — override via `CPACK_DEBIAN_PACKAGE_DEPENDS` and rebuild as -seth2.
+3. macOS validation on a real Mac — first-install path validates the formula end-to-end.
+4. Public-flip planning: when the pipeline has been battle-tested with a few releases, mirror to GitHub and add a `.github/workflows/release.yml` that calls the same scripts unmodified.
+
+## Important Context
+
+- Strict-zero (I1) is the project's defining discipline. The guardrail at `scripts/check-no-upstream-edits.sh` (with the upstream/master ref existence check added in commit 0631c55) enforces this on every build.
+- The `<upstream-tag>-seth<N>` versioning means the next release on the same upstream commit will be `<upstream-tag>-seth2`. If upstream tags a new release first, it'll be `<new-tag>-seth1`.
+- Spec discrepancy fixes applied during implementation (documented in plan header):
+  1. Added `-D CPACK_PACKAGE_NAME=glabels-qt` to build-deb.sh (spec §5.2 omitted it)
+  2. Pinned linuxdeploy/plugin-qt to dated tags (spec §F9 mandate; specific tags discovered at impl time)
+  3. Pruned each AppImage to contain only its own binary (size optimization not in spec, found via review)
+- One unanticipated detail at release time: the homebrew-tap repo's pre-commit `detect-secrets` hook flagged the git revision SHA in `Formula/glabels-qt.rb` as a high-entropy string. Resolved with an inline `# pragma: allowlist secret` comment on that line — NOT with `--no-verify`. Future tap bumps need to keep that pragma comment when replacing the SHA.
+
+## Tags now live in sethLabels
+
+```
+3.99-master618-seth1   ← first sethLabels release
+3.99-master618         ← upstream-side checkpoints (pushed during this session as a side
+3.99-master602           effect of `git push origin main --tags`; harmless, pre-existing
+3.99-master601           local tags from upstream's history)
+3.99-master598
+```
+
+---
+
+**Security Reminder**: No secrets present. Validated post-write.
@@ -53,3 +53,15 @@ GITEA_API.md

 # Handoff drafts (operator scratch — final handoffs ARE committed)
 .claude/handoffs/*.draft.md
+
+# Build outputs (out-of-tree)
+build/
+
+# linuxdeploy + plugin caches (downloaded by scripts/lib/linuxdeploy.sh on first AppImage build)
+scripts/.cache/
+
+# Locally-produced AppImage artifacts
+*.AppImage
+
+# Bats test scratch directories (created/cleaned per test)
+.test-scratch/
@@ -15,13 +15,15 @@ sethLabels is a thin deployment fork of [glabels-qt](https://github.com/j-evins/

 ## Current State

- **Phase:** ideation (just scaffolded — no code, no upstream pull yet)
- **Repo:** not yet (will live at `git.sethpc.xyz/Seth/sethLabels` once first commit lands)
- **Deploy target:** steel141 (Debian 13) — primary; CT for headless print serving optional/later
- **Upstream:** https://github.com/j-evins/glabels-qt (GPL-3.0, Qt + CMake + C++)
+- **Phase:** post-first-release. Pipeline live. First tag: 3.99-master618-seth1. Three artifacts attached to the Gitea release. Brew tap bumped to match.
+- **Repo:** `git.sethpc.xyz/Seth/sethLabels` (default branch `main`). Tap: `git.sethpc.xyz/Seth/homebrew-tap`. Upstream: `j-evins/glabels-qt` (`upstream` remote).
+- **Deploy targets live:** Debian-family Linux (`.deb` + AppImage) and macOS via Homebrew tap.
+- **Next release:** rebase, build, tag, attach, bump tap. See `scripts/README.md` and spec §6.

 ## Conventions

- This is a **fork**, not a from-scratch rewrite. Pull upstream first; only patch what we need to change. Keep diffs surgical.
- Preserve upstream license (GPL-3.0) and copyright headers.
+- This is a **deployment fork**, not a real fork. The discipline is **strict zero source patches** — no upstream-tracked file is ever edited. All sethLabels content lives in NEW top-level dirs (`scripts/`, `packaging/`, `sethlabels-docs/`, `tests-impl/`, `.claude/`). Allowlist exception: `.gitignore` (one-time scaffold-time touch).
+- Enforced by `scripts/check-no-upstream-edits.sh` — runs as the first step of every build script, also catches working-tree drift, aborts if `upstream/master` ref is missing.
+- Preserve upstream license (GPL-3.0) and copyright headers — strict-zero handles this automatically by never touching upstream files.
+- Versioning: `<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). See spec §D4 + §5.4.
 - See `~/bin/CLAUDE.md` for global homelab conventions (gitea CLI, conventional commits, credentials handling).
@@ -6,7 +6,36 @@ Format: `YYYY-MM-DD: <decision> — <why>`

 ## Architecture

+- **2026-04-29: Strict-zero source patches.** Never edit any upstream-tracked file. All sethLabels content lives in new files in new top-level directories at the repo root. — Makes `git pull upstream master --ff-only` succeed forever; rebase friction = 0. Allowlist exception: `.gitignore` (one-time scaffold-time touch). Enforced by `scripts/check-no-upstream-edits.sh`. See spec §I1, §D5.
+- **2026-04-29: Eventual-public fork.** sethLabels stays on Gitea during battle-test, then promotes to a formally public fork on GitHub once the build/release pipeline is solid. — Drives spec invariants: build host must be a clean Debian 13 / Ubuntu LTS box (not steel141-specific); brew tap source URL must be cleanly flippable Gitea→GitHub; CI is added at the flip, not before.
+- **2026-04-29: Linux artifacts = `.deb` + AppImage; macOS via Homebrew tap (build from source).** — `.deb` for Debian-family install ergonomics, AppImage for portability to non-Debian Linux. Brew tap eliminates macOS CI/signing/$99 Apple Dev ID entirely; users' Macs build from source. See spec §D1, §D2.
+- **2026-04-29: Build infrastructure = manual local builds during battle-test.** Shell scripts under `scripts/` are the canonical build recipe; CI YAML at the public-flip will call those scripts unmodified. — Local feedback loop beats CI loop during iteration on packaging. Defers infra cost. See spec §I3, §D3.
+- **2026-04-29: Versioning = `<upstream-tag>-seth<N>`.** E.g., `3.99-master618-seth1`. — Lineage-preserving; rebuild counter survives packaging-only fixes; sorts correctly under `dpkg --compare-versions`. See spec §D4.
+- **2026-04-29: Package name = `glabels-qt`.** Same name as upstream binary, brew formula, and the command users run. — sethLabels identity lives at repo level + version-string `-seth<N>` marker, not in the package name. Avoids confusing identity-split between package name and binary name. See spec §D6.
+
 ## Implementation

+- **2026-04-29: macOS = no CI required.** Homebrew tap with build-from-source means no macOS runner, no Apple Developer ID, no notarization pipeline. Tap repo (`git.sethpc.xyz/Seth/homebrew-tap`) is one ~30-line Ruby file. — Major simplification; Mac users build locally on first install (~5–10 min), all subsequent installs are version pin bumps to the tap formula.
+- **2026-04-29: Debian-family is the install target, not steel141.** Build host happens to be steel141 (or any clean Debian/Ubuntu box); install target is generic Debian-family. — No homelab paths, hostnames, or assumptions in scripts. Reproducibility on a fresh VM is the bar.
+- **2026-04-29: Spec, scripts, and packaging metadata live in NEW top-level dirs.** `sethlabels-docs/`, `scripts/`, `packaging/`. NOT in upstream's `docs/` directory. — Clear fork boundary; preserves strict-zero spirit (don't pollute upstream namespaces with our content).
+- **2026-04-29: macOS Launchpad/Spotlight integration via stub `.app` wrapper generated in brew formula.** Formula's `def install` synthesizes `glabels-qt.app/Contents/{Info.plist, MacOS/launcher, Resources/glabels-qt.icns}` after `cmake --install`. Launcher is a 2-line shell that `exec`s the real CLI binary. Icon converted from upstream's SVG via `sips`. User runs a one-time `cp -R "$(brew --prefix glabels-qt)/glabels-qt.app" /Applications/` (caveats block reminds them). — Upstream's `add_executable(glabels-qt WIN32 ...)` has no `MACOSX_BUNDLE` keyword, so cmake produces a CLI-only Mach-O on macOS. Strict-zero forbids patching upstream to fix this. The brew-formula-side stub is the cleanest sethLabels-side workaround; no Apple Developer ID, no signing pipeline, no .dmg. Tap commits `ef4d6c7` (initial wrapper) + `3542762` (SVG glob fix).
+
 ## Deferred / Rejected
 <!-- Decisions NOT to do something are just as valuable -- prevents re-proposing rejected ideas -->
+
+- **Rejected 2026-04-29: AppImage-only Linux distribution.** — Loses native Debian package manager integration (`apt remove`, dependency tracking) on the primary target distros.
+- **Rejected 2026-04-29: `.deb`-only Linux distribution.** — Loses portability to non-Debian Linux (RHEL/Fedora/Arch users couldn't install without recompiling).
+- **Rejected 2026-04-29: Flatpak.** — Sandbox runtime requirement + manifest complexity overkill for a personal-use packaging fork.
+- **Rejected 2026-04-29: Signed + notarized macOS `.dmg` (Apple Developer ID).** — $99/year recurring + notarization CI complexity not justified for a build-from-source Homebrew alternative.
+- **Rejected 2026-04-29: Unsigned macOS `.dmg`.** — Gatekeeper friction (right-click → Open) is a poor first-run experience compared to brew install.
+- **Rejected 2026-04-29: Gitea Actions self-hosted runner during battle-test.** — Homelab CT spin-up + workflow YAML setup not justified before public-flip; manual builds are faster to iterate on.
+- **Rejected 2026-04-29: Public GitHub Actions from day one.** — Skips the "battle-test in private" intent; want to validate the pipeline before going public.
+- **Rejected 2026-04-29: Plain upstream-tag versioning (no `-seth<N>` marker).** — No way to distinguish v1 of the `.deb` from v2 after a packaging fix; would have to lie about which upstream commit the package contains.
+- **Rejected 2026-04-29: Independent semver (`0.1.0`, `0.2.0`).** — Loses upstream-lineage info from the version string; users couldn't tell which glabels-qt commit they have without checking the changelog.
+- **Rejected 2026-04-29: Date-based versioning (`2026.04.29`).** — Loses both upstream-lineage and rebuild-counter information.
+- **Rejected 2026-04-29: Permissive small-patches policy on upstream files.** — Creates rebase friction on each `git pull upstream master`; even a one-file CMakeLists carve-out turned out to be unnecessary since CPack `-D` flags cover all needed metadata at build time.
+- **Rejected 2026-04-29: Package name `sethlabels`.** — Strict-zero policy forbids renaming the executable, so `apt install sethlabels` then running `glabels-qt` would split package identity from binary identity. Confusing.
+- **Deferred: Windows packaging.** — Per project brief. Upstream's NSIS support is intact; can be revisited later. Not blocking macOS+Linux delivery.
+- **Deferred: Custom default templates baked into the package.** — Strict-zero forbids; user-specific templates can live in `~/.config/glabels-qt/templates/` or a separate repo if/when needed.
+- **Deferred: Branding, icon, splash, or string changes.** — Strict-zero forbids. sethLabels is a packaging fork, not a rebrand.
+- **Deferred: Distribution to Debian backports / PPA / Ubuntu universe.** — Requires Debian Developer mentorship + ongoing policy compliance work; not justified for current scope.
@@ -12,9 +12,10 @@ Need a reliable, scriptable label designer/printer for homelab + household use (

 ## Constraints / preferences

- **Upstream:** https://github.com/j-evins/glabels-qt (track this, don't drift)
- **Stack:** Qt (5 or 6 — TBD based on upstream's current state), CMake, C++
- **Target hosts:** steel141 primarily (Debian 13). Maybe a CT for headless print serving later.
- **Branding/customization:** minimal — this is for personal use, not a product
- **License:** glabels-qt is GPL-3.0 — preserve it; any contributions stay GPL-3.0
- **Repo:** Gitea at `git.sethpc.xyz/Seth/sethLabels` (TBD until first push)
+- **Upstream:** https://github.com/j-evins/glabels-qt (track this, don't drift). The glabels.org team are the real authors — strict-zero source-patch policy preserves their attribution end-to-end.
+- **Stack:** Qt6 6.2 + CMake + C++ (confirmed by reading upstream `CMakeLists.txt:119`).
+- **Target install hosts:** any Debian-family Linux (Debian 13 / Ubuntu LTS) for `.deb` + AppImage; any macOS for Homebrew tap. Steel141 is a *build host*, not a deploy target. CT for headless print serving optional/later. Windows deferred.
+- **Branding/customization:** zero — this is a packaging fork, not a rebrand. Strict-zero policy forbids icon/string/UI edits.
+- **License:** glabels-qt is GPL-3.0 — preserved automatically (we never touch upstream files).
+- **Repo:** live at `git.sethpc.xyz/Seth/sethLabels`. Eventually-public on GitHub once the build/release pipeline is battle-tested.
+- **Eventual public-flip:** when promoted to a formal public fork on GitHub, brew tap source URL flips Gitea→GitHub (one-line tap formula edit), and CI is added via GitHub Actions calling the same `scripts/` shell scripts unmodified.
@@ -0,0 +1,93 @@
+# sethLabels
+
+> Deployment fork of [glabels-qt](https://github.com/j-evins/glabels-qt) — Qt6
+> label designer / printer, packaged for Debian-family Linux and macOS.
+
+This is **not** a code fork. The upstream application is unchanged; sethLabels
+exists solely to publish installable binary artifacts that upstream explicitly
+does not provide ("Currently there are no self-hosted binary snapshot releases
+available… I encourage you to try building the code yourself" — upstream README).
+
+For the application itself — what it does, screenshots, full feature list — see
+the upstream [`README.md`](README.md).
+
+## Install
+
+### Debian / Ubuntu (`.deb`)
+
+Download the latest `.deb` from the [releases page](https://git.sethpc.xyz/Seth/sethLabels/releases),
+then:
+
+```
+sudo apt install ./glabels-qt_<VERSION>_amd64.deb
+glabels-qt --version
+```
+
+### Any Linux (AppImage)
+
+Download `sethlabels-gui-<VERSION>-x86_64.AppImage` from the [releases page](https://git.sethpc.xyz/Seth/sethLabels/releases),
+make it executable, and run it:
+
+```
+chmod +x sethlabels-gui-<VERSION>-x86_64.AppImage
+./sethlabels-gui-<VERSION>-x86_64.AppImage
+```
+
+A separate `sethlabels-batch-<VERSION>-x86_64.AppImage` provides the CLI for
+scripted / mail-merge use.
+
+### macOS (Homebrew)
+
+```
+brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git
+brew install seth/tap/glabels-qt
+```
+
+The explicit URL form is needed because brew defaults to GitHub for tap names.
+First install builds Qt6 + glabels-qt from source (~5–10 min one-time cost; see
+spec §D2). Subsequent updates are a fast `brew upgrade`.
+
+## Build from source
+
+If you'd rather build the artifacts yourself instead of downloading a release:
+
+```
+git clone https://git.sethpc.xyz/Seth/sethLabels.git
+cd sethLabels
+git remote add upstream https://github.com/j-evins/glabels-qt.git
+git fetch upstream
+./scripts/lib/deps-debian.sh        # check / install build deps
+./scripts/build-deb.sh              # → build/deb/glabels-qt_*.deb
+./scripts/build-appimages.sh        # → sethlabels-{gui,batch}-*.AppImage
+```
+
+See [`scripts/README.md`](scripts/README.md) for full operator docs.
+
+## How this fork works
+
+sethLabels is a **deployment fork**: every sethLabels addition lives in NEW
+files in NEW top-level directories (`scripts/`, `packaging/`,
+`sethlabels-docs/`, `tests-impl/`, plus this file). Upstream files are never
+edited. The single allowlisted exception is `.gitignore`. This discipline is
+enforced by `scripts/check-no-upstream-edits.sh`.
+
+The `<upstream-tag>-seth<N>` versioning preserves the upstream-lineage in every
+artifact. Periodic `git rebase upstream/master` is conflict-free by construction.
+
+## Spec & decisions
+
+- [Design spec](sethlabels-docs/specs/2026-04-29-packaging-design.md) — invariants, decisions, build pipeline, failure modes
+- [Decision log](DECISIONS.md) — settled choices + rejected alternatives
+- [Project brief](IDEA.md) — plain-language motivation
+
+## License
+
+The upstream code is licensed under [GPL-3.0](LICENSE). sethLabels-specific
+files (everything in the dirs listed above, plus this file) are licensed under
+the same terms.
+
+## Upstream
+
+- Upstream: https://github.com/j-evins/glabels-qt (Jaye Evins / glabels.org)
+- This fork: https://git.sethpc.xyz/Seth/sethLabels
+- Brew tap: https://git.sethpc.xyz/Seth/homebrew-tap
@@ -0,0 +1,15 @@
+# linuxdeploy / linuxdeploy-plugin-qt configuration — sourced by scripts/build-appimages.sh.
+# Documents the bundling choices for both AppImages.
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.3
+
+# Qt platform plugins to include (linuxdeploy-plugin-qt picks these up automatically;
+# documenting here for posterity).
+QT_PLATFORM_PLUGINS="xcb"
+
+# Image format plugins. The GUI app needs SVG/PNG support; batch CLI does not.
+QT_IMAGE_FORMAT_PLUGINS_GUI="svg"
+QT_IMAGE_FORMAT_PLUGINS_BATCH=""
+
+# Files in the AppDir we don't want bundled (linuxdeploy is greedy by default).
+APPDIR_EXCLUDE_GLOBS=()
@@ -0,0 +1,30 @@
+# sethLabels packaging changelog
+
+Per-release packaging notes. Each entry covers what changed in the *packaging*,
+not what changed upstream. For application-level changes, see the upstream
+`docs/CHANGELOG.md` and `git log upstream/master`.
+
+## Format
+
+```
+## <version>  —  <ISO date>
+
+- bullet describing what changed in this packaging release
+- ...
+```
+
+`<version>` is `<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`), matching
+the git tag and the artifact filename. See spec §D4.
+
+---
+
+## 3.99-master618-seth1  —  2026-04-29
+
+- First end-to-end release of sethLabels packaging pipeline.
+- `.deb` produced via CMake CPack with strict-zero `-D` overrides (no upstream edits).
+- AppImages (GUI + batch) bundled via linuxdeploy + linuxdeploy-plugin-qt, pinned per F9.
+- Brew tap initial publish at `git.sethpc.xyz/Seth/homebrew-tap`.
+
+## (unreleased)
+
+- (no changes since 3.99-master618-seth1)
@@ -0,0 +1,11 @@
+# CPack DEB metadata overrides — sourced by scripts/build-deb.sh.
+# All values are passed to cpack as -D CPACK_DEBIAN_PACKAGE_<KEY>="$VALUE".
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.2
+
+MAINTAINER="Seth Freiberg <seth@sethfreiberg.com>"
+SECTION="graphics"
+HOMEPAGE="https://glabels.org"
+# CPACK_PACKAGE_NAME override — required because upstream sets
+# CPACK_PACKAGE_NAME=glabels (CMakeLists.txt:86) and decision D6 wants glabels-qt.
+PACKAGE_NAME="glabels-qt"
@@ -0,0 +1,90 @@
+# sethLabels build scripts
+
+Canonical recipe for building sethLabels artifacts. CI YAML at the public-flip
+will call these scripts unmodified — no logic moves into YAML (spec §I3).
+
+## Quick reference
+
+```
+./scripts/lib/deps-debian.sh         # check / install build deps
+./scripts/check-no-upstream-edits.sh # enforce strict-zero (I1)
+./scripts/compute-version.sh         # emit <upstream-tag>-seth<N>
+./scripts/build-deb.sh               # → build/deb/glabels-qt_<VERSION>_amd64.deb
+./scripts/build-appimages.sh         # → sethlabels-{gui,batch}-<VERSION>-x86_64.AppImage
+```
+
+## Prerequisites
+
+Debian 13 (Trixie) or Ubuntu 24.04 LTS. Run:
+
+```
+./scripts/lib/deps-debian.sh
+```
+
+If anything is missing, the script prints the exact `sudo apt install ...`
+command to run.
+
+`bats` (bash test framework) is in the dep list — it's required for the
+implementation tests under `tests-impl/`.
+
+`linuxdeploy` and `linuxdeploy-plugin-qt` are NOT apt-installable; they're
+downloaded automatically by `scripts/lib/linuxdeploy.sh` to `scripts/.cache/`
+on first AppImage build.
+
+## Versioning
+
+`<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). The `<N>` counter is
+computed from existing git tags matching `<upstream-tag>-seth*`. See spec §D4.
+
+**Caller responsibility:** the local tag db must be fresh before running
+`compute-version.sh`. Run `git fetch origin --tags` first if you're not
+inside the release flow (which fetches tags as step 1).
+
+## Release flow
+
+See spec §6 for the canonical step-by-step. TL;DR:
+
+```
+git fetch --all --tags
+git rebase upstream/master
+./scripts/check-no-upstream-edits.sh
+./scripts/build-deb.sh                       # ~2 min
+./scripts/build-appimages.sh                 # ~5 min
+VERSION=$(./scripts/compute-version.sh)
+git tag "$VERSION"
+git push origin main --tags
+# Create Gitea release for $VERSION; attach the three artifacts.
+# Bump ../homebrew-tap/Formula/glabels-qt.rb (tag + revision); commit; push.
+# Smoke verify on a clean Debian 13 VM (T5).
+```
+
+## Layout
+
+```
+scripts/
+├── README.md                     ← this file
+├── compute-version.sh            ← pure logic; emits version string
+├── check-no-upstream-edits.sh    ← guardrail enforcing I1
+├── build-deb.sh                  ← end-to-end .deb pipeline
+├── build-appimages.sh            ← end-to-end AppImage pipeline (GUI + batch)
+├── lib/
+│   ├── deps-debian.sh            ← build-dep manifest + checker
+│   └── linuxdeploy.sh            ← linuxdeploy + plugin-qt bootstrapper
+└── .cache/                       ← gitignored; linuxdeploy AppImages cache
+```
+
+## Tests
+
+```
+./tests-impl/run-all.sh
+```
+
+Runs the bats suite for pure-logic scripts. Build-script smoke tests (T1–T4)
+are inline in `build-deb.sh` and `build-appimages.sh` — they fire automatically
+on each build.
+
+## Spec
+
+The design rationale, invariants, and failure modes live in
+[`../sethlabels-docs/specs/2026-04-29-packaging-design.md`](../sethlabels-docs/specs/2026-04-29-packaging-design.md).
+Read it before changing any script.
@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# Build sethLabels AppImages (GUI + batch).
+#
+# Pipeline (spec §5.3):
+#   1. sanity / guardrail / version-compute (same as build-deb.sh)
+#   2. out-of-tree cmake build with CMAKE_INSTALL_PREFIX=/usr
+#   3. cmake --install to staging AppDir
+#   4. linuxdeploy bundle GUI AppImage
+#   5. re-stage AppDir for batch-only, linuxdeploy bundle batch AppImage
+#   6. inline smoke tests T3, T4
+#   7. print artifact paths
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.3
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+echo "==> [1/6] Sanity check build host"
+"$REPO_ROOT/scripts/lib/deps-debian.sh"
+echo "==> [1/6] Strict-zero guardrail"
+"$REPO_ROOT/scripts/check-no-upstream-edits.sh"
+echo "==> [1/6] Compute version"
+VERSION="$("$REPO_ROOT/scripts/compute-version.sh")"
+echo "    VERSION = $VERSION"
+
+# Bootstrap linuxdeploy + plugin-qt; defines $LINUXDEPLOY_BIN and $LINUXDEPLOY_PLUGIN_QT_BIN.
+# shellcheck disable=SC1091
+source "$REPO_ROOT/scripts/lib/linuxdeploy.sh"
+# linuxdeploy looks for the plugin in PATH; symlink into the cache dir suffices.
+PLUGIN_DIR="$(dirname "$LINUXDEPLOY_PLUGIN_QT_BIN")"
+PATH="$PLUGIN_DIR:$PATH"
+# Plugin file must be named exactly `linuxdeploy-plugin-qt` (no version suffix).
+PLUGIN_LINK="$PLUGIN_DIR/linuxdeploy-plugin-qt"
+ln -sf "$LINUXDEPLOY_PLUGIN_QT_BIN" "$PLUGIN_LINK"
+chmod +x "$PLUGIN_LINK"
+# Debian 13 has Qt6 only; linuxdeploy-plugin-qt's default qmake lookup looks
+# for `qmake` (Qt5 era) or `/usr/lib/qt5/bin/qmake` (neither exists). Force it
+# to the Qt6 binary explicitly so plugin staging works.
+export QMAKE=/usr/bin/qmake6
+
+echo "==> [2/6] Out-of-tree cmake build (install prefix /usr)"
+BUILD_DIR="$REPO_ROOT/build/appimage"
+APPDIR_GUI="$BUILD_DIR/AppDir-gui"
+APPDIR_BATCH="$BUILD_DIR/AppDir-batch"
+rm -rf "${BUILD_DIR:?BUILD_DIR must not be empty}"
+mkdir -p "$BUILD_DIR"
+cmake -S "$REPO_ROOT" -B "$BUILD_DIR" -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=/usr
+cmake --build "$BUILD_DIR" --parallel
+
+echo "==> [3/6] Stage install tree to AppDirs"
+DESTDIR="$APPDIR_GUI" cmake --install "$BUILD_DIR"
+# Batch AppDir gets its own copy so we can prune Qt plugins that GUI needs but batch doesn't.
+DESTDIR="$APPDIR_BATCH" cmake --install "$BUILD_DIR"
+
+# Sanity: both AppDirs must contain both binaries (we strip later, not here).
+test -x "$APPDIR_GUI/usr/bin/glabels-qt" || { echo "ERROR: GUI binary missing in AppDir-gui" >&2; exit 1; }
+test -x "$APPDIR_BATCH/usr/bin/glabels-batch-qt" || { echo "ERROR: batch binary missing in AppDir-batch" >&2; exit 1; }
+
+# Prune the unwanted binary from each AppDir so linuxdeploy bundles only the
+# libs needed by the remaining binary (otherwise both AppImages carry both
+# binaries; spec §5.3 step 3 implies "AppDir-batch" should be batch-only).
+rm "$APPDIR_GUI/usr/bin/glabels-batch-qt"
+rm "$APPDIR_BATCH/usr/bin/glabels-qt"
+# Also prune the GUI desktop files from the batch AppDir: linuxdeploy's
+# --create-desktop-file doesn't suppress pre-existing desktop files, and
+# the upstream desktop files reference Exec=glabels-qt (now pruned).
+find "$APPDIR_BATCH/usr/share/applications" -name '*.desktop' -delete
+
+echo "==> [4/6] Bundle GUI AppImage"
+DESKTOP_FILE="$APPDIR_GUI/usr/share/applications/glabels-qt.desktop"
+ICON_FILE="$APPDIR_GUI/usr/share/icons/hicolor/scalable/apps/glabels.svg"
+# Upstream's actual desktop filename may vary — list what's there if missing.
+if [ ! -f "$DESKTOP_FILE" ]; then
+  ALT_DESKTOP=$(find "$APPDIR_GUI/usr/share/applications" -name '*.desktop' | head -1)
+  if [ -n "$ALT_DESKTOP" ]; then
+    DESKTOP_FILE="$ALT_DESKTOP"
+  else
+    echo "ERROR: no .desktop file found in $APPDIR_GUI/usr/share/applications" >&2
+    exit 1
+  fi
+fi
+
+cd "$BUILD_DIR"
+APPIMAGE_EXTRACT_AND_RUN=1 \
+"$LINUXDEPLOY_BIN" \
+  --appdir "$APPDIR_GUI" \
+  --plugin qt \
+  --executable "$APPDIR_GUI/usr/bin/glabels-qt" \
+  --desktop-file "$DESKTOP_FILE" \
+  --icon-file "$ICON_FILE" \
+  --output appimage
+
+# linuxdeploy names the AppImage from the desktop file's Name= field (spaces→underscores).
+# For this upstream desktop file (Name=gLabels Label Designer 4) that produces
+# gLabels_Label_Designer_4-x86_64.AppImage.  Use a broad glob and exclude *batch*.
+GUI_RAW=$(ls "$BUILD_DIR"/*.AppImage 2>/dev/null | grep -v batch | head -1)
+GUI_OUT="$REPO_ROOT/sethlabels-gui-${VERSION}-x86_64.AppImage"
+mv "$GUI_RAW" "$GUI_OUT"
+chmod +x "$GUI_OUT"
+cd "$REPO_ROOT"
+
+echo "==> [5/6] Bundle batch AppImage"
+# Batch is CLI-only; reuse the upstream SVG icon so --create-desktop-file has
+# an icon to reference (linuxdeploy errors if the Icon= entry has no match).
+BATCH_ICON_FILE="$APPDIR_BATCH/usr/share/icons/hicolor/scalable/apps/glabels.svg"
+
+[ -f "$BATCH_ICON_FILE" ] || { echo "ERROR: batch icon not found: $BATCH_ICON_FILE" >&2; exit 1; }
+
+cd "$BUILD_DIR"
+APPIMAGE_EXTRACT_AND_RUN=1 \
+"$LINUXDEPLOY_BIN" \
+  --appdir "$APPDIR_BATCH" \
+  --plugin qt \
+  --executable "$APPDIR_BATCH/usr/bin/glabels-batch-qt" \
+  --icon-file "$BATCH_ICON_FILE" \
+  --icon-filename glabels-batch-qt \
+  --create-desktop-file \
+  --output appimage
+
+# linuxdeploy names the batch AppImage using the first desktop file it finds (the upstream
+# GUI desktop), producing the same name as the GUI build.  Since we already moved the GUI
+# AppImage out, only one .AppImage remains in BUILD_DIR at this point — pick it directly.
+BATCH_RAW=$(ls "$BUILD_DIR"/*.AppImage 2>/dev/null | head -1)
+BATCH_OUT="$REPO_ROOT/sethlabels-batch-${VERSION}-x86_64.AppImage"
+mv "$BATCH_RAW" "$BATCH_OUT"
+chmod +x "$BATCH_OUT"
+cd "$REPO_ROOT"
+
+echo "==> [6/6] Smoke tests"
+
+# Both AppImages bundle only the xcb Qt platform plugin (linuxdeploy-plugin-qt does not
+# include offscreen/minimal).  We need a real X display.  Use Xvfb if available; if not,
+# require DISPLAY to be set by the caller.
+SMOKE_XVFB_PID=""
+if ! xdpyinfo -display "${DISPLAY:-}" >/dev/null 2>&1; then
+  if command -v Xvfb >/dev/null 2>&1; then
+    echo "    (starting Xvfb :99 for headless smoke tests)"
+    Xvfb :99 -screen 0 800x600x24 &
+    SMOKE_XVFB_PID=$!
+    export DISPLAY=:99
+    sleep 1
+  else
+    echo "WARNING: no DISPLAY and Xvfb not found — smoke tests may fail on xcb platform" >&2
+  fi
+fi
+cleanup_xvfb() { [ -n "$SMOKE_XVFB_PID" ] && kill "$SMOKE_XVFB_PID" 2>/dev/null || true; }
+trap cleanup_xvfb EXIT
+
+# T3: batch AppImage --version exits 0 with non-empty output.
+echo "    T3: batch --version"
+T3_OUT=$(APPIMAGE_EXTRACT_AND_RUN=1 "$BATCH_OUT" --version 2>&1) || {
+  echo "ERROR: T3 failed — batch AppImage --version exited non-zero" >&2
+  echo "$T3_OUT" >&2
+  exit 1
+}
+# Strip EGL/DRM warnings (libEGL warning: failed to open /dev/dri/...) which are advisory.
+T3_VERSION=$(echo "$T3_OUT" | grep -v 'libEGL warning' | head -1)
+if [ -z "$T3_VERSION" ]; then
+  echo "ERROR: T3 failed — batch AppImage --version produced no version line" >&2
+  exit 1
+fi
+echo "    T3: PASS  ($T3_VERSION)"
+
+# T4: GUI AppImage --help exits 0 under headless Xvfb display.
+echo "    T4: gui --help (DISPLAY=$DISPLAY)"
+APPIMAGE_EXTRACT_AND_RUN=1 "$GUI_OUT" --help >"$BUILD_DIR/sethlabels-gui-help.txt" 2>&1 || {
+  echo "ERROR: T4 failed — GUI AppImage --help exited non-zero" >&2
+  cat "$BUILD_DIR/sethlabels-gui-help.txt" >&2
+  exit 1
+}
+echo "    T4: PASS"
+
+echo ""
+echo "Artifacts:"
+echo "  $GUI_OUT"
+echo "  $BATCH_OUT"
@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Build the sethLabels .deb package.
+#
+# Pipeline (spec §5.2):
+#   1. sanity check build host (Debian/Ubuntu, deps present)
+#   2. strict-zero guardrail
+#   3. compute version
+#   4. out-of-tree cmake build
+#   5. CPack with overrides
+#   6. inline smoke tests T1, T2
+#   7. print artifact path for the operator
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.2
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+echo "==> [1/6] Sanity check build host"
+"$REPO_ROOT/scripts/lib/deps-debian.sh"
+
+echo "==> [2/6] Strict-zero guardrail"
+"$REPO_ROOT/scripts/check-no-upstream-edits.sh"
+
+echo "==> [3/6] Compute version"
+VERSION="$("$REPO_ROOT/scripts/compute-version.sh")"
+echo "    VERSION = $VERSION"
+
+echo "==> [4/6] Out-of-tree cmake build"
+BUILD_DIR="$REPO_ROOT/build/deb"
+rm -rf "${BUILD_DIR:?BUILD_DIR must not be empty}"
+mkdir -p "$BUILD_DIR"
+cmake -S "$REPO_ROOT" -B "$BUILD_DIR" -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build "$BUILD_DIR" --parallel
+
+echo "==> [5/6] CPack DEB generation"
+# shellcheck disable=SC1091
+source "$REPO_ROOT/packaging/deb-metadata.env"
+
+cd "$BUILD_DIR"
+cpack -G DEB \
+  -D CPACK_PACKAGE_NAME="$PACKAGE_NAME" \
+  -D CPACK_PACKAGE_VERSION="$VERSION" \
+  -D CPACK_DEBIAN_PACKAGE_NAME="$PACKAGE_NAME" \
+  -D CPACK_DEBIAN_PACKAGE_MAINTAINER="$MAINTAINER" \
+  -D CPACK_DEBIAN_PACKAGE_SECTION="$SECTION" \
+  -D CPACK_DEBIAN_PACKAGE_HOMEPAGE="$HOMEPAGE" \
+  -D CPACK_DEBIAN_PACKAGE_SHLIBDEPS=ON \
+  -D CPACK_DEBIAN_FILE_NAME=DEB-DEFAULT
+cd "$REPO_ROOT"
+
+# Resolve the actual artifact filename (CPack uses DEB-DEFAULT naming convention).
+DEB_ARTIFACT=$(ls "$BUILD_DIR"/${PACKAGE_NAME}_*.deb 2>/dev/null | head -1)
+if [ -z "$DEB_ARTIFACT" ] || [ ! -f "$DEB_ARTIFACT" ]; then
+  echo "ERROR: expected .deb artifact not found in $BUILD_DIR" >&2
+  ls -la "$BUILD_DIR" >&2
+  exit 1
+fi
+
+echo "==> [6/6] Smoke tests"
+
+# T1: dpkg-deb --info parses, version field matches.
+echo "    T1: dpkg-deb --info"
+T1_OUT=$(dpkg-deb --info "$DEB_ARTIFACT")
+if ! echo "$T1_OUT" | grep -qE "^ Version: ${VERSION}$"; then
+  echo "ERROR: T1 failed — version field in .deb does not match \$VERSION=$VERSION" >&2
+  echo "$T1_OUT" >&2
+  exit 1
+fi
+echo "    T1: PASS"
+
+# T2: dpkg-deb --contents includes both binaries.
+echo "    T2: dpkg-deb --contents"
+T2_OUT=$(dpkg-deb --contents "$DEB_ARTIFACT")
+if ! echo "$T2_OUT" | grep -q '/usr/bin/glabels-qt'; then
+  echo "ERROR: T2 failed — /usr/bin/glabels-qt missing from .deb" >&2
+  exit 1
+fi
+if ! echo "$T2_OUT" | grep -q '/usr/bin/glabels-batch-qt'; then
+  echo "ERROR: T2 failed — /usr/bin/glabels-batch-qt missing from .deb" >&2
+  exit 1
+fi
+echo "    T2: PASS"
+
+# Optional: lintian (warnings-only, non-fatal during battle-test).
+if command -v lintian >/dev/null 2>&1; then
+  echo "    lintian (advisory):"
+  lintian "$DEB_ARTIFACT" || true
+fi
+
+echo ""
+echo "Artifact: $DEB_ARTIFACT"
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Enforce Invariant I1: no upstream-tracked file is ever edited.
+# Exits 0 on clean state, 1 on violation.
+#
+# Catches BOTH committed drift (commits unique to HEAD vs upstream/master)
+# AND working-tree drift (uncommitted local edits to tracked files).
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.5 (I1, F1)
+set -euo pipefail
+
+# Refuse to run silently if upstream/master ref is missing (spec §F1 — the
+# guardrail's contract is "abort on drift," not "abort on drift IF the ref
+# happens to be present"). Without this check, a fresh clone or
+# broken-remote environment would silently pass the committed-drift check.
+if ! git rev-parse --verify upstream/master >/dev/null 2>&1; then
+  echo "ERROR: upstream/master ref not found." >&2
+  echo "  Configure the upstream remote and fetch:" >&2
+  echo "    git remote add upstream https://github.com/j-evins/glabels-qt.git" >&2
+  echo "    git fetch upstream" >&2
+  echo "  See sethlabels-docs/specs/2026-04-29-packaging-design.md §6 (release flow step 1)." >&2
+  exit 1
+fi
+
+# Allowlist: files/dirs sethLabels is permitted to add or modify.
+# `.gitignore` is the one upstream-file exception (called out in spec §2).
+allowed_pattern='^\.gitignore$|^\.claude/|^scripts/|^packaging/|^sethlabels-docs/|^tests-impl/|^README\.sethlabels\.md$|^CLAUDE\.md$|^IDEA\.md$|^DECISIONS\.md$'
+
+committed=$(git diff --name-only upstream/master..HEAD 2>/dev/null || true)
+working=$(git diff --name-only HEAD 2>/dev/null || true)
+
+all_changes=$(printf "%s\n%s\n" "$committed" "$working" | sort -u | sed '/^$/d')
+
+if [ -z "$all_changes" ]; then
+  exit 0
+fi
+
+violations=$(echo "$all_changes" | grep -vE "$allowed_pattern" || true)
+
+if [ -n "$violations" ]; then
+  echo "ERROR: strict-zero policy violated. The following upstream files have been modified:"
+  echo "$violations"
+  echo ""
+  echo "See sethlabels-docs/specs/2026-04-29-packaging-design.md §I1."
+  exit 1
+fi
+
+exit 0
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Emit "<upstream-tag>-seth<N>" version string to stdout.
+# Pure logic: no side effects.
+#
+# CALLER RESPONSIBILITY (per spec §5.4): the local tag db must be fresh.
+# If invoked outside the release flow, run `git fetch origin --tags` first
+# or risk a stale <N> value.
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.4 (D4)
+set -euo pipefail
+
+upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
+existing_count=$(git tag --list "${upstream_tag}-seth*" | wc -l | tr -d ' ')
+next_n=$((existing_count + 1))
+echo "${upstream_tag}-seth${next_n}"
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Single source of truth for sethLabels build dependencies on Debian-family Linux.
+#
+# When SOURCED:   exposes SETHLABELS_DEPS array (no side effects).
+# When EXECUTED:  verifies each dep is installed; prints actionable
+#                 `sudo apt install ...` command on missing deps; exits 1.
+#                 On clean state, prints "All build dependencies present." and exits 0.
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §5.1
+set -euo pipefail
+
+SETHLABELS_DEPS=(
+  build-essential cmake ninja-build pkg-config
+  qt6-base-dev qt6-base-dev-tools
+  qt6-svg-dev
+  qt6-tools-dev qt6-tools-dev-tools
+  qt6-l10n-tools
+  libqt6printsupport6 libqt6svg6 libqt6widgets6 libqt6xml6 libqt6gui6
+  libqt6concurrent6 libqt6core6t64 libqt6test6
+  zlib1g-dev libqrencode-dev libzint-dev
+  file dpkg-dev fakeroot
+  wget
+  bats
+  xvfb
+)
+
+# Detect sourced vs. executed.
+# When sourced: BASH_SOURCE[0] != $0
+# When executed: BASH_SOURCE[0] == $0
+if [ "${BASH_SOURCE[0]}" != "${0}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# --- Executed path ---
+
+# Sanity check the build host
+if [ ! -f /etc/os-release ]; then
+  echo "WARNING: /etc/os-release missing; not Debian-family. This script is designed for Debian 13 / Ubuntu LTS." >&2
+fi
+
+if [ -f /etc/os-release ]; then
+  . /etc/os-release
+  if [[ "${ID:-}" != "debian" && "${ID:-}" != "ubuntu" ]] && [[ "${ID_LIKE:-}" != *debian* && "${ID_LIKE:-}" != *ubuntu* ]]; then
+    echo "WARNING: not running on Debian or Ubuntu (detected ID='${ID:-unknown}'). Build deps may differ." >&2
+  fi
+fi
+
+missing=()
+for pkg in "${SETHLABELS_DEPS[@]}"; do
+  if ! dpkg-query -W -f='${Status}' "$pkg" 2>/dev/null | grep -q "install ok installed"; then
+    missing+=("$pkg")
+  fi
+done
+
+if [ "${#missing[@]}" -gt 0 ]; then
+  echo "Missing build dependencies (${#missing[@]}):"
+  for p in "${missing[@]}"; do
+    echo "  - $p"
+  done
+  echo ""
+  echo "Install with:"
+  echo "  sudo apt install -y ${missing[*]}"
+  exit 1
+fi
+
+echo "All build dependencies present (${#SETHLABELS_DEPS[@]} packages verified)."
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Bootstrap linuxdeploy + linuxdeploy-plugin-qt to a script-local cache.
+#
+# When SOURCED:   exposes $LINUXDEPLOY_BIN and $LINUXDEPLOY_PLUGIN_QT_BIN paths
+#                 (downloads on first run if missing).
+# When EXECUTED:  ensures both binaries are present and prints their paths.
+#
+# Pinned per spec §F9 — version bumps are deliberate, not transparent.
+# To bump: re-run discovery (Task 5 Step 1 of the implementation plan), update
+#          the two TAG variables below, and verify a fresh AppImage build.
+#
+# Spec: sethlabels-docs/specs/2026-04-29-packaging-design.md §F9
+set -euo pipefail
+
+# === PINNED VERSIONS (update deliberately per F9) ===
+LINUXDEPLOY_TAG="1-alpha-20251107-1"
+LINUXDEPLOY_PLUGIN_QT_TAG="1-alpha-20250213-1"
+# ====================================================
+
+CACHE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/.cache"
+LINUXDEPLOY_BIN="$CACHE_DIR/linuxdeploy-${LINUXDEPLOY_TAG}-x86_64.AppImage"
+LINUXDEPLOY_PLUGIN_QT_BIN="$CACHE_DIR/linuxdeploy-plugin-qt-${LINUXDEPLOY_PLUGIN_QT_TAG}-x86_64.AppImage"
+
+LINUXDEPLOY_URL="https://github.com/linuxdeploy/linuxdeploy/releases/download/${LINUXDEPLOY_TAG}/linuxdeploy-x86_64.AppImage"
+LINUXDEPLOY_PLUGIN_QT_URL="https://github.com/linuxdeploy/linuxdeploy-plugin-qt/releases/download/${LINUXDEPLOY_PLUGIN_QT_TAG}/linuxdeploy-plugin-qt-x86_64.AppImage"
+
+ensure_tool() {
+  local url="$1" out="$2" label="$3"
+  if [ -x "$out" ]; then
+    return 0
+  fi
+  mkdir -p "$(dirname "$out")"
+  echo "Downloading $label from $url ..." >&2
+  if ! wget -q --show-progress -O "$out" "$url"; then
+    echo "ERROR: download failed for $label ($url)" >&2
+    rm -f "$out"
+    return 1
+  fi
+  chmod +x "$out"
+}
+
+ensure_tool "$LINUXDEPLOY_URL" "$LINUXDEPLOY_BIN" "linuxdeploy"
+ensure_tool "$LINUXDEPLOY_PLUGIN_QT_URL" "$LINUXDEPLOY_PLUGIN_QT_BIN" "linuxdeploy-plugin-qt"
+
+export LINUXDEPLOY_BIN LINUXDEPLOY_PLUGIN_QT_BIN
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  echo "linuxdeploy:           $LINUXDEPLOY_BIN"
+  echo "linuxdeploy-plugin-qt: $LINUXDEPLOY_PLUGIN_QT_BIN"
+fi
@@ -0,0 +1,398 @@
+# sethLabels Packaging — Design Spec
+
+- **Status:** approved (brainstormed 2026-04-29, awaiting user review of this document before plan-writing)
+- **Author:** Seth Freiberg, with assistance from Claude Code
+- **Audience:** anyone implementing or maintaining sethLabels' packaging/release pipeline
+- **Project:** [git.sethpc.xyz/Seth/sethLabels](https://git.sethpc.xyz/Seth/sethLabels)
+- **Upstream:** [github.com/j-evins/glabels-qt](https://github.com/j-evins/glabels-qt) (the glabels.org team)
+
+## 1. Problem & purpose
+
+The upstream glabels-qt project explicitly does not publish self-hosted binary releases ("Currently there are no self-hosted binary snapshot releases available… I encourage you to try building the code yourself" — upstream README). sethLabels exists to fill exactly that gap: produce installable binary artifacts for Debian-family Linux and macOS without changing the upstream application itself.
+
+The eventual goal is to publish sethLabels as a formally public packaging-fork on GitHub once the build/release pipeline is battle-tested. This spec describes the pipeline and discipline that make that possible.
+
+## 2. Invariants (load-bearing)
+
+These are not guidelines — they define the project's shape. Violating any of them moves sethLabels toward "real fork" territory and out of "deployment fork."
+
+| # | Invariant | Why |
+|---|-----------|-----|
+| I1 | **Strict zero source patches.** No upstream file is ever edited. Every sethLabels addition lives in NEW files in NEW top-level directories at the repo root. | Makes `git pull --rebase upstream master` always succeed without conflicts (our scaffold commit re-applies cleanly on each new upstream base). Rebase friction = 0. |
+| I2 | **Debian-family + macOS-via-brew target only.** No homelab-specific paths, hostnames, or assumptions anywhere in scripts. | Build must be reproducible on a clean Debian 13 / Ubuntu LTS VM. Public-fork future depends on this. |
+| I3 | **Shell scripts under `scripts/` are the canonical build recipe.** CI YAML (when added later at the public-flip) calls these scripts verbatim — no logic in YAML. | Prevents recipe drift between manual builds and CI. The script is the truth. |
+| I4 | **Manual local builds during battle-test phase.** No CI infrastructure (Gitea Actions, GitHub Actions, self-hosted runner) until the public-flip on GitHub. | Defers infra cost. Iteration speed > automation during exploration. |
+| I5 | **No branding, icon, splash, or string changes.** sethLabels is a packaging fork, not a rebrand. Artifacts identify as `glabels-qt`. | Per IDEA.md ("branding/customization: minimal — this is for personal use, not a product") and strict-zero. |
+
+The one exception to I1: `.gitignore` carries an appended sethLabels section. This was a one-time touch made at scaffold time and is treated as a known allowlisted exception throughout this spec.
+
+## 3. Decisions (settled, with rationale)
+
+Each decision below was the conclusion of a multiple-choice round during brainstorming. Recorded here so future maintainers can see what alternatives were considered and why the current choice won. See `DECISIONS.md` for the same list in shorter form.
+
+### D1 — Linux distribution formats: `.deb` AND AppImage
+
+- **Why:** `.deb` for Debian-family targets (clean apt-managed install/upgrade/uninstall); AppImage as portable fallback for any-Linux-anywhere. AppImage is essentially free once `.deb` works since linuxdeploy reuses upstream's `install()` rules.
+- **Rejected:** AppImage-only (loses native package manager integration), `.deb`-only (loses portability to non-Debian Linux), Flatpak (heavyweight runtime requirement, overkill for this use case).
+- **Cost:** AppImage bundling can be finicky around Qt6 plugin discovery — see §8.2 mitigation.
+
+### D2 — macOS distribution: Homebrew tap, build-from-source
+
+- **Why:** zero macOS CI requirement (brew runs the build on the user's machine), no $99/yr Apple Developer ID, no notarization pipeline complexity, brew handles Qt6 dependency resolution automatically (`depends_on "qt@6"`).
+- **Rejected:** unsigned `.dmg` (Gatekeeper friction), signed+notarized `.dmg` (annual cost + CI complexity), tap-with-pre-built-cask (still requires building somewhere, defeats the simplification).
+- **Constraint accepted:** first-time install on a Mac takes ~5–10 min (cmake build of Qt app from source). Acceptable for a technical user, which is the audience.
+- **Tap repo:** lives separately at `git.sethpc.xyz/Seth/homebrew-tap`. Not in the sethLabels repo.
+
+### D3 — Build infrastructure: manual local builds during battle-test
+
+- **Why:** local feedback loop (~2 min) beats CI feedback loop (push + wait); during iteration on packaging recipes the local loop is essential. Scripts written for manual use translate to CI workflow YAML mechanically when needed.
+- **Rejected:** Gitea Actions self-hosted runner (homelab CT spin-up cost not justified pre-public), public GitHub Actions from day one (skips the "battle-test in private" intent).
+- **Forward path:** at public-flip on GitHub, scripts get wrapped in a `.github/workflows/release.yml` that calls them — no logic moves into YAML.
+- **Build host expectation:** scripts must run on a clean Debian 13 / Ubuntu LTS box. Steel141 is acceptable as a build host but is not the target audience for resulting binaries.
+
+### D4 — Versioning: `<upstream-tag>-seth<N>`
+
+- **Why:** lineage in the version answers "which upstream am I running?" without changelog spelunking. Rebuild counter (`seth1` → `seth2`) lets us ship a packaging-only fix without lying about which upstream code is inside. Sorts correctly under `dpkg --compare-versions`.
+- **Format:** `<upstream-tag>` = output of `git describe --tags --abbrev=0 upstream/master` (e.g., `3.99-master618`). `<N>` = count of existing `<upstream-tag>-seth*` tags + 1.
+- **Rejected:** plain upstream tag (no way to distinguish v1 of the .deb from v2 after a packaging fix), independent semver (loses upstream-lineage info), date-based (loses both lineage and rebuild-counter info).
+
+### D5 — Upstream-touch policy: strict zero
+
+- **Why:** the IDEA brief explicitly calls for "diff small enough to rebase periodically." Strict zero takes that to its limit. CPack metadata is overridable via `cpack -D KEY=VALUE` flags at build time — no source edit required to package. Any future need for a CMake gap should be upstreamed as a PR to glabels-qt rather than carried as a local patch.
+- **Rejected:** permissive small-patches (creates rebase friction), strict-zero with a CMakeLists carve-out (the carve-out is not actually needed, since CPack `-D` covers everything we want).
+- **Enforcement:** `scripts/check-no-upstream-edits.sh` runs as a guardrail; allowlist = `.gitignore` only.
+
+### D6 — Package name: `glabels-qt`
+
+- **Why:** consistent muscle memory across `.deb`, AppImage, brew formula, and the binary the user runs. The "sethLabels" identity lives at the repo level + in the version string's `-seth<N>` marker, not in the package name. Future-proofs the public-fork narrative as "yet another packaging fork of glabels-qt."
+- **Rejected:** `sethlabels` (would split identity from binary name, since strict-zero means we can't rename the executable; `apt install sethlabels` then `glabels-qt` is confusing).
+- **Risk acknowledged:** if Debian later ships an official `glabels-qt` package, our sethLabels-versioned variant would still dominate by version-sort (`3.99-master618-seth1` > `3.99`-something-debian). Re-evaluate at that time.
+
+## 4. Repo layout
+
+The post-spec layout. Existing entries reflect what's already in the repo at `2026-04-29`. NEW entries are introduced by the spec implementation.
+
+```
+sethLabels/
+├── (all upstream files — strict zero, never touched)
+│   ├── glabels/, glabels-batch/, model/, backends/, ...
+│   ├── CMakeLists.txt, README.md, LICENSE, ...
+│   ├── data/, templates/, translations/, user-docs/
+│   └── docs/                              ← upstream's docs dir, never written into
+│
+├── .gitignore                             ← I1 exception: sethLabels section appended
+│
+├── CLAUDE.md                              ← already present (project instructions)
+├── IDEA.md                                ← already present (plain-language brief)
+├── DECISIONS.md                           ← already present (decision log)
+├── GITEA_API.md                           ← already present (gitignored symlink)
+├── README.sethlabels.md                   ← NEW: fork purpose, install/build entry
+│
+├── scripts/                               ← NEW: canonical build recipe (I3)
+│   ├── README.md                          ← human-readable run instructions
+│   ├── build-deb.sh                       ← entry: builds the .deb
+│   ├── build-appimages.sh                 ← entry: builds the 2 AppImages
+│   ├── compute-version.sh                 ← emits "<upstream-tag>-seth<N>"
+│   ├── check-no-upstream-edits.sh         ← guardrail enforcing I1
+│   └── lib/
+│       ├── deps-debian.sh                 ← apt-installable build deps
+│       └── linuxdeploy.sh                 ← downloads/caches linuxdeploy + qt plugin
+│
+├── packaging/                             ← NEW: data files consumed by scripts
+│   ├── deb-metadata.env                   ← maintainer, section, depends fallback
+│   ├── appimage-recipe.env                ← linuxdeploy plugin allowlist, exclude list
+│   └── changelog.md                       ← human-readable per-release notes
+│
+├── sethlabels-docs/                       ← NEW: sethLabels' own docs (this spec lives here)
+│   └── specs/
+│       └── 2026-04-29-packaging-design.md ← THIS file
+│
+└── .claude/                               ← already present
+    └── handoffs/
+        └── 2026-04-29-125823-scaffold-only.md
+```
+
+Companion repository (separate Gitea repo, not part of sethLabels):
+
+```
+homebrew-tap/                              ← git.sethpc.xyz/Seth/homebrew-tap
+├── README.md
+└── Formula/
+    └── glabels-qt.rb                      ← brew formula
+```
+
+## 5. Build pipeline
+
+### 5.1 Build host requirements
+
+Either a clean Debian 13 (Trixie) or Ubuntu 24.04 LTS box. The build host produces both the `.deb` and the AppImage artifacts; one machine, two scripts.
+
+`scripts/lib/deps-debian.sh` is the single source of truth for build dependencies and prints an actionable `apt install …` command when something is missing. Expected dependency set:
+
+```
+build-essential cmake ninja-build pkg-config
+qt6-base-dev qt6-base-dev-tools qt6-svg-dev qt6-tools-dev qt6-tools-dev-tools
+qt6-l10n-tools libqt6printsupport6 libqt6svg6 libqt6widgets6 libqt6xml6 libqt6gui6
+libqt6concurrent6 libqt6core6 libqt6test6
+zlib1g-dev libqrencode-dev libzint-dev libgnubarcode-dev
+file dpkg-dev fakeroot
+wget                # for downloading linuxdeploy on first AppImage build
+```
+
+`linuxdeploy` and `linuxdeploy-plugin-qt` are downloaded by `scripts/lib/linuxdeploy.sh` to a script-local cache (e.g., `scripts/.cache/linuxdeploy-x86_64.AppImage`) on first run. They are not apt-installable on Debian/Ubuntu, hence the bootstrap step. Cache is gitignored.
+
+### 5.2 `scripts/build-deb.sh`
+
+Sequential steps. Any non-zero exit aborts the build with a clear error message.
+
+1. **Sanity check the build host:** confirm Debian-family (`/etc/os-release` ID is `debian` or `ubuntu`), confirm all `deps-debian.sh` packages are installed.
+2. **Strict-zero guardrail:** call `check-no-upstream-edits.sh`. If any tracked-upstream file diverges from `upstream/master` (allowlist: `.gitignore`), abort.
+3. **Compute version:** `VERSION=$(./scripts/compute-version.sh)`.
+4. **Out-of-tree build:**
+   ```
+   cmake -S . -B build/deb -G Ninja -DCMAKE_BUILD_TYPE=Release
+   cmake --build build/deb --parallel
+   ```
+5. **Run CPack with overrides:**
+   ```
+   cd build/deb && cpack -G DEB \
+     -D CPACK_PACKAGE_VERSION="$VERSION" \
+     -D CPACK_DEBIAN_PACKAGE_MAINTAINER="$(. ../../packaging/deb-metadata.env && echo "$MAINTAINER")" \
+     -D CPACK_DEBIAN_PACKAGE_SECTION="graphics" \
+     -D CPACK_DEBIAN_PACKAGE_SHLIBDEPS=ON \
+     -D CPACK_DEBIAN_PACKAGE_HOMEPAGE="https://glabels.org" \
+     -D CPACK_DEBIAN_FILE_NAME=DEB-DEFAULT
+   ```
+   `CPACK_DEBIAN_PACKAGE_SHLIBDEPS=ON` runs `dpkg-shlibdeps` against built binaries to compute exact runtime library deps automatically. This avoids hand-maintaining a Depends list.
+6. **Smoke test the artifact:**
+   - `dpkg-deb --info build/deb/glabels-qt_${VERSION}_amd64.deb` — verifies parse-ability.
+   - `dpkg-deb --contents …` checked for both `/usr/bin/glabels-qt` and `/usr/bin/glabels-batch-qt`.
+   - `lintian build/deb/glabels-qt_${VERSION}_amd64.deb` if available — warnings noted but not fatal during battle-test.
+7. **Artifact path printed for the operator** to upload: `build/deb/glabels-qt_${VERSION}_amd64.deb`.
+
+### 5.3 `scripts/build-appimages.sh`
+
+1. Same sanity / guardrail / version-compute steps as 5.2.
+2. **Out-of-tree build into `build/appimage`:**
+   ```
+   cmake -S . -B build/appimage -G Ninja -DCMAKE_BUILD_TYPE=Release \
+     -DCMAKE_INSTALL_PREFIX=/usr
+   cmake --build build/appimage --parallel
+   ```
+3. **Stage install tree to `AppDir`:**
+   ```
+   DESTDIR=$(pwd)/build/appimage/AppDir cmake --install build/appimage
+   ```
+   `AppDir/usr/bin/glabels-qt` and `AppDir/usr/bin/glabels-batch-qt` exist after this step (driven by upstream's existing `install()` rules).
+4. **Bundle GUI AppImage:**
+   ```
+   linuxdeploy --appdir build/appimage/AppDir --plugin qt \
+     --executable build/appimage/AppDir/usr/bin/glabels-qt \
+     --desktop-file build/appimage/AppDir/usr/share/applications/org.glabels.glabels-qt.desktop \
+     --icon-file build/appimage/AppDir/usr/share/icons/hicolor/scalable/apps/glabels.svg \
+     --output appimage
+   mv glabels-qt-x86_64.AppImage sethlabels-gui-${VERSION}-x86_64.AppImage
+   ```
+5. **Bundle Batch AppImage** — re-stage AppDir (or use a separate `AppDir-batch`) to avoid pulling GUI-only Qt plugins into the batch bundle:
+   ```
+   linuxdeploy --appdir build/appimage/AppDir-batch --plugin qt \
+     --executable build/appimage/AppDir-batch/usr/bin/glabels-batch-qt \
+     --output appimage
+   mv glabels-batch-qt-x86_64.AppImage sethlabels-batch-${VERSION}-x86_64.AppImage
+   ```
+   Note: the batch CLI doesn't need a desktop file or icon (no GUI launcher).
+6. **Smoke tests:**
+   - `./sethlabels-batch-${VERSION}-x86_64.AppImage --version` — must exit 0 and print a version string.
+   - `QT_QPA_PLATFORM=minimal ./sethlabels-gui-${VERSION}-x86_64.AppImage --help` — must exit 0 (validates that the Qt plugin set is complete enough to start a headless Qt event loop).
+7. **Artifact paths printed for the operator** to upload.
+
+### 5.4 `scripts/compute-version.sh`
+
+Pure logic, no side effects. Emits version string to stdout.
+
+```
+upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
+existing_count=$(git tag --list "${upstream_tag}-seth*" | wc -l)
+next_n=$((existing_count + 1))
+echo "${upstream_tag}-seth${next_n}"
+```
+
+**Caller responsibility:** the local tag db must be fresh before running this script — `git tag --list` reads local refs only. The release flow (§6 step 1) does `git fetch --all --tags` to satisfy this. If invoked outside the release flow, the caller must run `git fetch origin --tags` first or risk a stale `<N>` value.
+
+The script is idempotent: running it multiple times before a new tag is created always returns the same value. Both `build-deb.sh` and `build-appimages.sh` call this internally to embed the version into their artifacts. Step 6 of the release flow re-invokes it to obtain `$VERSION` for the `git tag` command — values agree by purity.
+
+### 5.5 `scripts/check-no-upstream-edits.sh`
+
+The script must catch BOTH committed and uncommitted edits to upstream files. Two checks:
+
+1. **Committed drift** — files changed in commits unique to `HEAD` vs. `upstream/master`:
+   ```
+   committed=$(git diff --name-only upstream/master..HEAD)
+   ```
+2. **Working-tree drift** — uncommitted local edits to tracked files:
+   ```
+   working=$(git diff --name-only HEAD)
+   ```
+
+Both lists are filtered against the same allowlist. Any path NOT matching is a violation.
+
+```
+allowed_pattern='^\.gitignore$|^\.claude/|^scripts/|^packaging/|^sethlabels-docs/|^README\.sethlabels\.md$|^CLAUDE\.md$|^IDEA\.md$|^DECISIONS\.md$'
+all_changes=$(printf "%s\n%s\n" "$committed" "$working" | sort -u | sed '/^$/d')
+violations=$(echo "$all_changes" | grep -vE "$allowed_pattern" || true)
+if [ -n "$violations" ]; then
+  echo "ERROR: strict-zero policy violated. The following upstream files have been modified:"
+  echo "$violations"
+  echo "See sethlabels-docs/specs/2026-04-29-packaging-design.md §I1."
+  exit 1
+fi
+```
+
+Exit 0 silently on clean state.
+
+Allowlist note: `GITEA_API.md` is intentionally NOT in the allowlist because it is `.gitignore`-excluded and will never appear in any git diff. Including it would be dead code.
+
+## 6. Release flow
+
+```
+1. git fetch --all --tags                        (refreshes upstream commits AND local tag db, which compute-version.sh reads)
+2. git rebase upstream/master                    (strict-zero ⇒ always succeeds without conflicts; scaffold commit re-applies on new base)
+3. ./scripts/check-no-upstream-edits.sh          (guardrail; aborts on drift)
+4. ./scripts/build-deb.sh                        (~2 min)
+5. ./scripts/build-appimages.sh                  (~5 min, two AppImages)
+6. VERSION=$(./scripts/compute-version.sh)
+7. git tag "$VERSION"
+8. git push origin main --tags
+9. Create Gitea release for tag $VERSION via gitea CLI / API; attach:
+   - build/deb/glabels-qt_${VERSION}_amd64.deb
+   - sethlabels-gui-${VERSION}-x86_64.AppImage
+   - sethlabels-batch-${VERSION}-x86_64.AppImage
+10. Edit ../homebrew-tap/Formula/glabels-qt.rb:
+    - bump tag pin to $VERSION
+    - update sha256 of the source tarball
+    - commit "bump glabels-qt to $VERSION", push
+11. Smoke verify: download .deb on a fresh Debian 13 VM, install with `apt install ./...`, run `glabels-qt --version`.
+```
+
+The release flow is human-driven during the battle-test phase. Each step's output is visible; failures are immediately diagnosable. When the public-flip happens, steps 4, 5, 9, 10 move into a GitHub Actions `.github/workflows/release.yml` that triggers on tag push and runs the same scripts unmodified.
+
+## 7. Homebrew tap
+
+### 7.1 Tap repo layout
+
+```
+homebrew-tap/                            (separate Gitea repo: git.sethpc.xyz/Seth/homebrew-tap)
+├── README.md                            (instructions: how to tap, how to install)
+└── Formula/
+    └── glabels-qt.rb                    (the formula)
+```
+
+### 7.2 Initial formula (starting point — finalized during plan execution)
+
+```ruby
+class GlabelsQt < Formula
+  desc "gLabels Label Designer (Qt/C++) — Seth's packaging fork"
+  homepage "https://glabels.org"
+  url "https://git.sethpc.xyz/Seth/sethLabels.git",
+      tag:      "3.99-master618-seth1",
+      revision: "<placeholder, filled at first release>"
+  license "GPL-3.0-only"
+  head "https://git.sethpc.xyz/Seth/sethLabels.git", branch: "main"
+
+  depends_on "cmake"   => :build
+  depends_on "ninja"   => :build
+  depends_on "pkgconf" => :build
+  depends_on "qt"
+  depends_on "zlib"
+  depends_on "qrencode" => :recommended  # optional barcode backend
+  depends_on "zint"     => :recommended  # optional barcode backend
+
+  def install
+    system "cmake", "-S", ".", "-B", "build",
+           "-G", "Ninja",
+           "-DCMAKE_BUILD_TYPE=Release",
+           *std_cmake_args
+    system "cmake", "--build", "build"
+    system "cmake", "--install", "build"
+  end
+
+  test do
+    assert_match "gLabels", shell_output("#{bin}/glabels-batch-qt --version")
+  end
+end
+```
+
+### 7.3 User install path (macOS)
+
+```
+brew tap seth/tap https://git.sethpc.xyz/Seth/homebrew-tap.git
+brew install seth/tap/glabels-qt
+```
+
+The explicit URL form is required because brew defaults to GitHub for tap names. Documented in the tap's README. When the public-flip moves sethLabels (and the tap) to GitHub, the URL becomes the implicit GitHub default and the tap command shortens to `brew tap seth/tap`.
+
+### 7.4 Tap maintenance per release
+
+Single commit per release on the tap repo: bump `tag:` and `revision:` fields in `glabels-qt.rb`. No other edits expected.
+
+## 8. Failure modes & guardrails
+
+| # | Risk | Guardrail |
+|---|------|-----------|
+| F1 | Strict-zero policy creep | `check-no-upstream-edits.sh` runs at the start of each build script; allowlist explicit (see §5.5) |
+| F2 | AppImage Qt plugin omissions (image formats, platform plugin) | linuxdeploy-plugin-qt covers most cases; smoke test (§5.3 step 6) launches each AppImage with `QT_QPA_PLATFORM=minimal` and verifies exit code |
+| F3 | Build env drift (worked on steel141, fails on clean Debian 13 VM) | `deps-debian.sh` is the single source of truth for build deps; scripts fail fast on missing pkg with actionable apt-install command. Recommend re-validating on a fresh VM before each release. |
+| F4 | Brew formula source URL changes (Gitea → GitHub on public flip) | Single-line edit in `glabels-qt.rb`; tap repo has its own commit history so the flip is one commit. Document the URL-flip in tap repo's README. |
+| F5 | Re-package counter (`seth<N>`) collisions | Computed from existing tags via `git tag --list`, not from a state file; race-free under serial single-author releases. |
+| F6 | Manual-build script rot | `scripts/README.md` documents required commands; future CI workflow YAML calls scripts directly — preventing recipe drift. Each release flow re-exercises the scripts. |
+| F7 | Upstream rebase fails with conflicts (strict-zero broken without `check-no-upstream-edits.sh` having caught it) | Recover from a clean state in worst case: `git reset --hard upstream/master` then re-apply our scaffold commit by cherry-picking from `origin/main`. The single scaffold commit is the only thing to preserve. |
+| F8 | dpkg-shlibdeps mis-detects a runtime dep, producing a `.deb` that won't install on a target system | Mitigation: smoke-test install on a clean Debian 13 VM as part of release flow (§6 step 11). If a false positive surfaces, override via `CPACK_DEBIAN_PACKAGE_DEPENDS` flag in `build-deb.sh`. |
+| F9 | linuxdeploy or linuxdeploy-plugin-qt version drift breaks AppImage builds | `lib/linuxdeploy.sh` pins specific GitHub release versions; version bumps are deliberate, not transparent. |
+
+## 9. Out of scope (explicit)
+
+- **Windows packaging** — deferred per project brief. Upstream's NSIS support remains untouched and works for anyone who wants to build their own.
+- **macOS `.dmg`, signed binaries, notarization** — replaced by Homebrew tap building from source.
+- **Flatpak, Snap** — heavier infrastructure than warranted for the audience.
+- **Arch AUR package** — already exists per upstream README (community-maintained `glabels-qt-git`).
+- **Distribution to Debian official repos / backports / PPA / Ubuntu universe** — would require Debian Developer mentorship + ongoing policy compliance work; not the current goal.
+- **Custom default templates baked into the package** — strict-zero forbids this. User-specific templates live in `~/.config/glabels-qt/templates/` outside the package, or in a future separate repo.
+- **Branding, icon, splash, or string changes** — strict-zero forbids this.
+- **Automated CI infrastructure (Gitea Actions runner, GitHub Actions, etc.) during the battle-test phase** — manual local builds. Reconsider at public-flip on GitHub.
+- **GUI source changes of any kind** — strict-zero forbids this.
+- **Repackaging upstream's existing tag-snapshot binaries** — we always build from source, never relabel upstream artifacts.
+
+## 10. Smoke test definitions
+
+The acceptance test for any release. All four must pass before a tag is pushed.
+
+| # | Test | Pass condition |
+|---|------|----------------|
+| T1 | `dpkg-deb --info <deb>` parses and shows the correct version field | exit 0; version line matches `$VERSION` |
+| T2 | `dpkg-deb --contents <deb>` includes both binaries | both `/usr/bin/glabels-qt` and `/usr/bin/glabels-batch-qt` present |
+| T3 | `<batch-appimage> --version` runs | exit 0; output is non-empty |
+| T4 | `QT_QPA_PLATFORM=minimal <gui-appimage> --help` runs | exit 0 |
+| T5 (release-flow) | Install `.deb` on a clean Debian 13 VM, run `glabels-qt --version` | exit 0; version line matches `$VERSION` |
+
+T5 is the strongest signal — it validates that `dpkg-shlibdeps` produced a correct depends list and that Qt6 from the system package manager satisfies runtime needs. Run T5 at least once per upstream-tag bump (i.e., on every `seth1` release; can be skipped on `seth2`+ if only packaging metadata changed).
+
+## 11. Glossary
+
+- **Deployment fork** — a fork whose only purpose is to ship binaries / install packages. No source-code intent. Diff against upstream is trivial; rebases are fast-forwards.
+- **Strict zero (I1)** — the discipline that no upstream-tracked file is ever edited. All sethLabels content lives in NEW files in NEW top-level directories.
+- **Battle-test phase** — the period before sethLabels is published as a formal public fork on GitHub. During this phase: manual builds, no CI, hosted at Gitea.
+- **Public-flip** — the future event when sethLabels is moved (or dual-hosted) on GitHub as a public packaging fork. Triggers: GitHub Actions added as CI, brew tap source URL flips Gitea→GitHub, README updates.
+- **Upstream-tag** — output of `git describe --tags --abbrev=0 upstream/master` against the j-evins/glabels-qt master branch. Currently of the form `3.99-master<N>` until upstream tags 4.0.
+
+## 12. Open questions
+
+None at spec time. All design questions raised during brainstorming were resolved before writing this document. Future open questions can be added here with their resolution moving to §3 once decided.
+
+## 13. References
+
+- [j-evins/glabels-qt README](https://github.com/j-evins/glabels-qt/blob/master/README.md) — the upstream "no binary releases" notice this fork addresses
+- [`docs/BUILD-INSTRUCTIONS-LINUX.md`](../../docs/BUILD-INSTRUCTIONS-LINUX.md) — upstream's manual build instructions (the manual procedure our scripts automate)
+- [CMake CPack DEB generator docs](https://cmake.org/cmake/help/latest/cpack_gen/deb.html)
+- [linuxdeploy + qt plugin](https://github.com/linuxdeploy/linuxdeploy-plugin-qt)
+- [Homebrew Formula Cookbook](https://docs.brew.sh/Formula-Cookbook)
+- [Debian version comparison rules](https://www.debian.org/doc/debian-policy/ch-controlfields.html#version)
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Run the full bats test suite for sethLabels packaging scripts.
+# Requires: bats (apt install bats).
+set -euo pipefail
+cd "$(dirname "$0")"
+exec bats *.bats
@@ -0,0 +1,122 @@
+#!/usr/bin/env bats
+
+# Tests for scripts/check-no-upstream-edits.sh
+
+setup() {
+  REPO_ROOT="$(git rev-parse --show-toplevel)"
+  SCRIPT="$REPO_ROOT/scripts/check-no-upstream-edits.sh"
+  TMP_REPO=""
+}
+
+teardown() {
+  if [ -n "$TMP_REPO" ] && [ -d "$TMP_REPO" ]; then
+    rm -rf "$TMP_REPO"
+  fi
+}
+
+# --- Helpers ---
+
+# Build a minimal disposable repo that mimics the sethLabels structure with a
+# local "upstream/master" ref. Returns its path via stdout.
+make_test_repo() {
+  mkdir -p "$REPO_ROOT/.test-scratch"
+  local tmp=$(mktemp -d -p "$REPO_ROOT/.test-scratch")
+  cd "$tmp"
+  git init -q -b master
+  git config user.email "test@test"
+  git config user.name "test"
+  # Pretend-upstream files
+  echo "upstream content" > UPSTREAM_FILE.md
+  echo "real source" > glabels-source.cpp
+  git add UPSTREAM_FILE.md glabels-source.cpp
+  git commit -m "upstream base" -q
+  # Create a local "upstream/master" ref pointing here
+  git update-ref refs/remotes/upstream/master HEAD
+  # Create a feature branch for sethLabels content
+  git checkout -q -b main
+  echo "$tmp"
+}
+
+# --- Tests ---
+
+@test "script exists and is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+@test "exits 0 on clean state with only allowlisted committed changes" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  mkdir -p scripts packaging sethlabels-docs .claude/handoffs
+  echo "test" > CLAUDE.md
+  echo "test" > scripts/something.sh
+  echo "test" > packaging/x.env
+  echo "test" > sethlabels-docs/spec.md
+  echo "" >> .gitignore
+  git add -A
+  git commit -m "sethLabels additions" -q
+
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "exits 1 when an upstream file is committed-modified" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  echo "evil edit" >> glabels-source.cpp
+  git add glabels-source.cpp
+  git commit -m "BAD: edit upstream file" -q
+
+  run "$SCRIPT"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"glabels-source.cpp"* ]]
+  [[ "$output" == *"strict-zero"* ]]
+}
+
+@test "exits 1 when an upstream file has uncommitted working-tree edits" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  echo "uncommitted evil edit" >> glabels-source.cpp
+
+  run "$SCRIPT"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"glabels-source.cpp"* ]]
+}
+
+@test "exits 0 when only .gitignore is modified (allowlisted)" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  echo "*.tmp" >> .gitignore
+  git add .gitignore
+  git commit -m "extend gitignore" -q
+
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+}
+
+@test "exits 0 when only CLAUDE.md / IDEA.md / DECISIONS.md / README.sethlabels.md are added" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  echo "x" > CLAUDE.md
+  echo "x" > IDEA.md
+  echo "x" > DECISIONS.md
+  echo "x" > README.sethlabels.md
+  git add -A
+  git commit -m "add sethLabels root docs" -q
+
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+}
+
+@test "exits 1 when upstream/master ref is missing" {
+  TMP_REPO=$(make_test_repo)
+  cd "$TMP_REPO"
+  # Delete the upstream/master ref we set in make_test_repo.
+  git update-ref -d refs/remotes/upstream/master
+  # Modify an upstream file in working tree — would normally trigger violation.
+  echo "edit" >> glabels-source.cpp
+
+  run "$SCRIPT"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"upstream/master ref not found"* || "$stderr" == *"upstream/master ref not found"* ]]
+}
@@ -0,0 +1,59 @@
+#!/usr/bin/env bats
+
+# Tests for scripts/compute-version.sh
+# Invokes the real script against the real repo state.
+
+setup() {
+  REPO_ROOT="$(git rev-parse --show-toplevel)"
+  SCRIPT="$REPO_ROOT/scripts/compute-version.sh"
+}
+
+@test "script exists and is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+@test "output matches '<upstream-tag>-seth<N>' format" {
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" =~ ^[0-9].+-seth[0-9]+$ ]]
+}
+
+@test "N=1 when no prior seth-tags exist" {
+  # This test assumes a clean tag db. If there ARE existing seth-tags, this
+  # test will report N>1 and that's the correct value. Skipped if any
+  # upstream-tag-seth* tag already exists.
+  upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
+  existing=$(git tag --list "${upstream_tag}-seth*" | wc -l)
+  if [ "$existing" -gt 0 ]; then
+    skip "seth-tags already exist (count=$existing); N=1 invariant only holds on first release"
+  fi
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == "${upstream_tag}-seth1" ]]
+}
+
+@test "N increments past existing seth-tags" {
+  upstream_tag=$(git describe --tags --abbrev=0 upstream/master)
+  # Create a fake seth-tag for this test, then clean up.
+  fake_tag="${upstream_tag}-seth99"
+  git tag "$fake_tag" 2>/dev/null || true
+  run "$SCRIPT"
+  git tag -d "$fake_tag" >/dev/null 2>&1 || true
+  [ "$status" -eq 0 ]
+  # Existing count was at least 1 (our fake), so N >= 2.
+  n="${output##*-seth}"
+  [ "$n" -ge 2 ]
+}
+
+@test "fails cleanly when upstream/master ref is missing" {
+  # Run in a temp git repo with no upstream remote.
+  mkdir -p "$REPO_ROOT/.test-scratch"
+  tmp=$(mktemp -d -p "$REPO_ROOT/.test-scratch")
+  cd "$tmp"
+  git init -q
+  git commit --allow-empty -m "init" -q
+  run "$SCRIPT"
+  cd "$REPO_ROOT"
+  rm -rf "$tmp"
+  [ "$status" -ne 0 ]
+}
@@ -0,0 +1,63 @@
+#!/usr/bin/env bats
+
+# Tests for scripts/lib/deps-debian.sh
+
+setup() {
+  REPO_ROOT="$(git rev-parse --show-toplevel)"
+  SCRIPT="$REPO_ROOT/scripts/lib/deps-debian.sh"
+}
+
+@test "script exists and is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+@test "sourceable: exposes SETHLABELS_DEPS array" {
+  source "$SCRIPT"
+  [ "${#SETHLABELS_DEPS[@]}" -gt 5 ]
+}
+
+@test "SETHLABELS_DEPS contains core build tools" {
+  source "$SCRIPT"
+  [[ " ${SETHLABELS_DEPS[*]} " == *" cmake "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" ninja-build "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" build-essential "* ]]
+}
+
+@test "SETHLABELS_DEPS contains Qt6 libraries" {
+  source "$SCRIPT"
+  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-base-dev "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-svg-dev "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" qt6-tools-dev "* ]]
+}
+
+@test "SETHLABELS_DEPS contains barcode + zlib deps" {
+  source "$SCRIPT"
+  [[ " ${SETHLABELS_DEPS[*]} " == *" zlib1g-dev "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" libqrencode-dev "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" libzint-dev "* ]]
+}
+
+@test "SETHLABELS_DEPS contains packaging tools" {
+  source "$SCRIPT"
+  [[ " ${SETHLABELS_DEPS[*]} " == *" dpkg-dev "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" fakeroot "* ]]
+  [[ " ${SETHLABELS_DEPS[*]} " == *" wget "* ]]
+}
+
+@test "executed: prints status and exits 0 (when all installed) OR 1 with apt-install hint" {
+  run "$SCRIPT"
+  if [ "$status" -eq 0 ]; then
+    [[ "$output" == *"All build dependencies present"* ]]
+  else
+    [[ "$output" == *"sudo apt install"* ]]
+  fi
+}
+
+@test "executed: warns if not on Debian/Ubuntu" {
+  # Simulate non-Debian by overriding /etc/os-release path via env var
+  if [ -f /etc/os-release ] && grep -qE '^ID=(debian|ubuntu)' /etc/os-release; then
+    skip "currently on Debian/Ubuntu — non-Debian path covered by source review"
+  fi
+  run "$SCRIPT"
+  [[ "$output" == *"Debian"* || "$output" == *"Ubuntu"* ]]
+}
Author	SHA1	Message	Date
Seth	b7281e0f04	docs: add session handoff (mac-app-launcher)	2026-04-29 12:19:24 -04:00
Seth	4172a30487	docs: update CLAUDE.md + DECISIONS.md for macOS .app launcher addition CLAUDE.md: removed stale "(to be implemented per spec §5.5)" wording for check-no-upstream-edits.sh (script is implemented and battle-tested), added tests-impl/ to the dirs-list, expanded the guardrail description. DECISIONS.md: appended the .app launcher decision (stub bundle synthesized in brew formula def install — sethLabels-side fix, no upstream patch).	2026-04-29 12:19:20 -04:00
Seth	f6c30f2fe8	test: move bats scratch dirs to repo-local .test-scratch/ (per global no-/tmp/ rule) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 12:03:57 -04:00
Seth	76a3cb798a	docs: README.sethlabels.md — include upstream remote setup in build-from-source Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 12:03:49 -04:00
Seth	891cc7c1c8	docs: add session handoff (first-release)	2026-04-29 11:56:47 -04:00
Seth	2d049437ff	docs: refresh CLAUDE.md to post-first-release phase	2026-04-29 11:54:35 -04:00
Seth	2108e2cf15	docs: changelog for 3.99-master618-seth1	2026-04-29 11:53:32 -04:00
Seth	8290870f06	docs: add README.sethlabels.md (fork entry point)	2026-04-29 11:43:28 -04:00
Seth	9b970804fc	docs: add scripts/README.md (operator run guide)	2026-04-29 11:42:34 -04:00
Seth	2a789e30f8	fix: guard batch AppImage icon path with pre-flight check	2026-04-29 11:41:33 -04:00
Seth	e619699660	chore: add xvfb to deps-debian.sh (required by build-appimages smoke tests) build-appimages.sh T3/T4 smoke tests start Xvfb automatically when no DISPLAY is set. Without xvfb in the deps array, a clean Debian/Ubuntu host would pass the dep check but fail at smoke-test time. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 11:39:10 -04:00
Seth	f7e35652a9	fix: prune unused binary from each AppDir before linuxdeploy bundling Previously cmake --install populated both AppDirs with both binaries, causing the batch AppImage (57MB) to be larger than the GUI AppImage (47MB). Add rm lines after the sanity-check block to strip the unwanted binary from each AppDir before linuxdeploy runs. Also prune the upstream GUI desktop files from the batch AppDir (they reference Exec=glabels-qt which is now absent) and supply --icon-file + --icon-filename so --create-desktop-file resolves the icon lookup. Both AppImages now contain only their respective binary (~33-34MB each). Also document the QMAKE=/usr/bin/qmake6 workaround (Debian 13 Qt6 qmake discovery failure in linuxdeploy-plugin-qt). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 11:39:02 -04:00
Seth	d5fb872518	feat: add build-appimages.sh with inline smoke tests T3, T4 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 11:14:58 -04:00
Seth	13d4047fe1	fix: guard rm -rf in build-deb.sh against empty BUILD_DIR	2026-04-29 10:50:10 -04:00
Seth	4f2de8a92c	feat: add build-deb.sh with inline smoke tests T1, T2 Also fixes deps-debian.sh for Debian 13 (trixie): libqt6core6 was renamed to libqt6core6t64; libgnubarcode-dev removed (not in Debian 13 repos, optional upstream dep). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:44:01 -04:00
Seth	34b72ca384	feat: add packaging metadata + initial changelog	2026-04-29 10:37:38 -04:00
Seth	4a0185df53	feat: add linuxdeploy.sh bootstrap (pinned per F9) Bootstraps linuxdeploy (1-alpha-20251107-1) and linuxdeploy-plugin-qt (1-alpha-20250213-1) to scripts/.cache/ on first run. Dual-mode: sourceable (exports $LINUXDEPLOY_BIN / $LINUXDEPLOY_PLUGIN_QT_BIN) or executable (prints paths). Pinned dated snapshots per spec §F9 — no rolling continuous tag. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:34:01 -04:00
Seth	cb2f687a6b	feat: add deps-debian.sh (build-dep manifest + checker) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:28:55 -04:00
Seth	0631c55c0f	fix: check-no-upstream-edits.sh aborts when upstream/master ref missing Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:26:00 -04:00
Seth	caee5291ff	feat: add check-no-upstream-edits.sh + bats tests (enforces I1) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:22:18 -04:00
Seth	9cc418c68f	feat: add compute-version.sh + bats tests Emits <upstream-tag>-seth<N> to stdout. Pure logic, no side effects. 5/5 bats tests pass; output verified as 3.99-master618-seth1. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-29 10:18:12 -04:00
Seth	52096c0d63	chore: add packaging directory skeleton + .gitignore build patterns	2026-04-29 10:14:09 -04:00
Seth	33525a8c1d	docs: add packaging implementation plan (12 tasks)	2026-04-29 10:11:29 -04:00
Seth	da74709433	docs: add session handoff (spec-approved-pre-implementation) Captures session state at the natural pause point: design spec approved, no implementation started. Supersedes the scaffold-only handoff (which described an empty-dir state). Validated 80/100 by validate_handoff.py. The 4 file-not-found warnings reference scripts/* that are intentionally unwritten — they are the next session's deliverables per the spec. Resume next session with writing-plans skill against the spec at sethlabels-docs/specs/2026-04-29-packaging-design.md.	2026-04-29 10:00:59 -04:00
Seth	d3e14c63c0	docs: refresh CLAUDE.md + IDEA.md for design-approved phase Reflects state changes from this session: - Phase moved from "ideation, no upstream pull" to "design-approved, pre-implementation" - Repo confirmed live at git.sethpc.xyz/Seth/sethLabels (was TBD) - Qt6 6.2 confirmed (was Qt5-or-Qt6 TBD) - Target framing corrected: Debian-family generic + macOS via brew tap; steel141 is a build host, NOT the install target - Strict-zero source-patch policy spelled out (replaces vague "keep diffs surgical") - Versioning scheme noted (<upstream-tag>-seth<N>) - Eventual-public flip on GitHub captured Pointer to spec at sethlabels-docs/specs/2026-04-29-packaging-design.md added to CLAUDE.md "Current State".	2026-04-29 09:55:07 -04:00
Seth	8e272c0bd8	docs: add packaging design spec + decision log Captures the brainstormed design for sethLabels' packaging pipeline: - Strict-zero source patches; all sethLabels content in NEW top-level dirs - Linux artifacts: .deb (CPack-driven) + AppImage (linuxdeploy + Qt plugin), both built from upstream's existing install() rules - macOS: Homebrew tap, build-from-source — no macOS CI, no signing, no Apple Developer ID - Build infra: manual local builds during battle-test phase; shell scripts under scripts/ are the canonical recipe (CI YAML at the eventual public-flip on GitHub will call them verbatim) - Versioning: <upstream-tag>-seth<N> for clear lineage + rebuild counter - Package name: glabels-qt (matches binary, brew formula, command) Spec at sethlabels-docs/specs/2026-04-29-packaging-design.md. Decision log at DECISIONS.md. No code introduced — design only. Plan-writing follows.	2026-04-29 09:37:56 -04:00