sethLabels/.claude/handoffs/2026-04-29-125823-scaffold-only.md

Handoff: sethLabels scaffolded — no code yet

Session Metadata

• Created: 2026-04-29 12:58:23 UTC
• Project: /home/claude/bin/sethLabels
• Branch: n/a (no git repo yet)
• Session duration: ~5 min
• Live URL: n/a

Handoff Chain

• Continues from: None — this is the project's first handoff.
• Supersedes: None.

Current State Summary

Project directory scaffolded per ~/bin/CREATE_PROJECT.md as a deployment fork of upstream glabels-qt. No code has been pulled, no git repo initialized, no Gitea repo created. Only the ~/bin/-convention files exist:

sethLabels/
├── CLAUDE.md           durable project instructions
├── DECISIONS.md        empty decision log (template-derived, header set)
├── GITEA_API.md        symlink → ~/bin/GITEA_API.md
├── IDEA.md             plain-language brief
└── .claude/handoffs/
    └── 2026-04-29-125823-scaffold-only.md   (this file)

Phase: ideation. Nothing is running anywhere. No upstream commit pinned. No build attempted.

Architecture Overview

This is a deployment fork — the discipline is to keep the diff against j-evins/glabels-qt master surgical so we can rebase periodically without pain. Anything we add should be additive (new files: deploy scripts, packaging recipes, Seth-specific templates) rather than invasive edits to upstream source. If we need to patch upstream code, prefer a thin patch series we can replay.

Stack is Qt + CMake + C++ (GPL-3.0). Target host is steel141 (Debian 13). A future option is a headless print-server CT, but that's not part of this scaffold's scope.

Critical Files

File	Purpose	Relevance
~/bin/sethLabels/IDEA.md	Plain-language brief — why this fork exists	Read first if upstream choice or scope feels unclear
~/bin/sethLabels/CLAUDE.md	Durable project instructions	Loaded every session
~/bin/sethLabels/DECISIONS.md	Empty — populate as architectural choices land	Write to when locking in upstream-pin strategy, Qt5-vs-Qt6, etc.
~/bin/CREATE_PROJECT.md	Recipe used to scaffold this	Reference if future projects need the same shape

Suggested Next Steps (ordered)

The user said just scaffold + handoff — none of this was attempted. Pick up here next session:

1. Decide upstream-tracking strategy. Options:
   • (a) Clone j-evins/glabels-qt into this dir, push to Gitea as sethLabels, add upstream as a remote, merge from upstream/master periodically.
   • (b) Keep upstream as a git submodule and layer deployment glue around it. Record the choice in DECISIONS.md before pulling code.
2. Verify upstream is alive. Check j-evins/glabels-qt for last commit date + open issues; this is a fork of mate-desktop's glabels lineage and forks-of-forks have a tendency to bitrot. If j-evins is stale, the real upstream might be elsewhere — re-evaluate before forking.
3. Confirm Qt version. Upstream's CMakeLists.txt will say Qt5 or Qt6. Debian 13 ships both — pick whichever upstream targets.
4. Build it once on steel141 to establish the known-good build recipe. Capture exact apt install deps and CMake invocation in a BUILD.md (or in CLAUDE.md if short).
5. Initialize git + push to Gitea. gitea create sethLabels → gitea remote sethLabels → gitea push. Use a descriptive commit message like init: scaffold + import upstream glabels-qt @ <sha>.
6. Only then start any deployment-specific work (templates, packaging, install scripts).

Open Questions

• Is j-evins/glabels-qt actually the right upstream, or should we be tracking a different fork? (See "verify upstream is alive" above.)
• Does Seth want a .deb package, an AppImage, or just a built binary in /usr/local/bin?
• Is there a printer model or label-stock library we should pre-load as default templates?

These don't block scaffolding — they block the first real coding session. Ask before implementing.

Risks / Watch-outs

• Upstream is GPL-3.0. Any code we add that links against it must also be GPL-3.0-compatible. Don't accidentally relicense.
• "Deployment fork" failure mode: scope creep into a real fork. If we find ourselves writing >100 lines of upstream-source patches, that's a signal to either upstream the change or rethink whether we actually want a fork.
• glabels-qt is one of those projects with multiple competing forks (j-evins, jimevins-original, mate-desktop's glabels-3, etc.). Pin the upstream we choose explicitly in DECISIONS.md so we don't drift.