souveraine/docs/tasks/quickshell-surface-package.md

task_id	title	status	priority	phase	created	references
souveraine-surface-001	QuickShell surface package — explicit, reversible desktop adoption	in_progress	high	delivery	2026-07-13	docs/tasks/souveraine-cicd-pipeline.md, surfaces/quickshell/deploy.sh

QuickShell Surface Package

Outcome

souveraine remains the non-visual substrate package: server binary, user unit, and no ownership of ~/.souveraine or ~/.config. A separate architecture-independent souveraine-surface-quickshell package ships the QuickShell assets and an explicit adoption command. Installing/upgrading a package never silently replaces a person's ii shell, top bar, dock, or local QuickShell changes.

What exists now

• The running laptop package ships only /usr/bin/souveraine, its user unit, and license files. It correctly updates with pacman, but contains no QML.
• surfaces/quickshell/ is the canonical source for Souveraine's ii overlay.
• deploy.sh is the development deployment path; it manages symlinks and retains one .upstream copy for ordinary upstream files.
• The laptop had an older AiChat.qml; its /agent and /resume commands were absent even though the server and Ai.qml were current. The live panel is now linked to the canonical file, with the prior copy backed up.

Safety contract

1. Pacman places only package-owned assets under /usr/share/souveraine/ and an adoption tool under /usr/bin/ or /usr/libexec/.
2. The adoption tool defaults to a dry run: it names every managed, new, and replacement target.
3. A normal --apply succeeds only when targets are new or already managed by Souveraine.
4. Replacements require --adopt; each conflicting file or symlink is copied to a timestamped *.pre-souveraine-* backup before the overlay changes it.
5. --uninstall restores the original .upstream files where available and otherwise removes only Souveraine-managed symlinks. It never removes user data, agent memory, or unrelated ii files.
6. Package upgrades do not run adoption automatically. They update the assets; the user reviews and applies their desktop changes explicitly.

First cut — in progress

• Expose deploy.sh --manifest so package tooling and the developer path share a single authoritative list of managed files.
• Add scripts/install-quickshell-surface.sh, an explicit dry-run/apply/ adopt wrapper around that manifest.
• Exercise its dry-run, clean apply, conflict refusal, adoption backup, and uninstall behaviour in a disposable QuickShell config.
• Add a targeted --only <target> mode so a small repair such as AiChat can be adopted without touching the dock or bar.

Package design — next cut

1. Add packaging/arch/PKGBUILD.surface (arch=('any')) that installs the canonical QML tree under /usr/share/souveraine/quickshell/ and the safe adoption command.
2. Make the command resolve packaged assets first, with a checked-out repo retained as an explicit developer override.
3. Extend the CI release job to build/sign/publish the surface package once per edge release alongside both binary packages.
4. Add a narrow integration test using a temporary $XDG_CONFIG_HOME; verify no automatic overwrite and that --adopt preserves every conflict.
5. On phone and laptop, install the surface package with pacman, run the preview, then choose adoption deliberately. The phone's existing live symlink development loop remains valid until this proves itself.

Later: desktop profile

souveraine-desktop is a meta-package that depends on the substrate and surface packages. It does not adopt the surface itself; its post-install message directs the user to the preview command. This gives a future fresh machine one clear install target without sacrificing ownership of its shell.

Acceptance

• pacman -S souveraine never changes a QuickShell file.
• pacman -S souveraine-surface-quickshell never changes a QuickShell file.
• The adoption command clearly reports its plan and refuses unapproved replacements.
• A deliberate adoption makes /agent, /resume, agent selection, and the Souveraine panel available against the locally running package service.
• An upgrade and uninstall preserve user settings and agent state.