# 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](https://github.com/j-evins/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.