---
task_id: souveraine-surface-001
title: QuickShell surface package — explicit, reversible desktop adoption
status: in_progress
priority: high
phase: delivery
created: 2026-07-13
references: 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`. The QuickShell body
splits by device profile: laptop and phone share Souveraine's channel protocol,
not a top bar, dock, layout, or interaction density. 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 shared channel code and a
  currently mixed development overlay. It is **not** a universal surface
  manifest: `pill/shell.qml` and the compact rotating phone bar do not belong
  on a laptop, whose bar intentionally has more visible controls.
- `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 package name and manifest are profile-specific: at minimum
   `souveraine-surface-laptop` and `souveraine-surface-phone`; shared QML lives
   in a common asset layer. A laptop installer never considers phone files,
   and vice versa.
3. The adoption tool defaults to a dry run: it names every managed, new, and
   replacement target.
4. A normal `--apply` succeeds only when targets are new or already managed by
   Souveraine.
5. Replacements require `--adopt`; each conflicting file or symlink is copied
   to a timestamped `*.pre-souveraine-*` backup before the overlay changes it.
6. `--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.
7. Package upgrades do not run adoption automatically. They update the assets;
   the user reviews and applies their desktop changes explicitly.

## First cut — in progress

- [x] Expose `deploy.sh --manifest` so package tooling and the developer path
  share a single authoritative list of managed files.
- [x] Add `scripts/install-quickshell-surface.sh` as a safe inventory tool.
  Its apply/adopt mode is deliberately disabled until profiles exist; it cannot
  make the mixed overlay look universally safe.
- [ ] Split the current development manifest into `common`, `laptop`, and
  `phone` manifests. Classify every file by actual layout and interaction
  contract; do not infer a laptop layout from phone work or vice versa.
- [ ] Re-enable safe apply/adopt only against a selected profile. Exercise its
  dry-run, clean apply, conflict refusal, adoption backup, and uninstall
  behaviour in disposable configs for both devices.
- [ ] Add a targeted `--only <target>` mode within the chosen profile so a
  small repair such as `AiChat` can be adopted without touching a bar or dock.

## Package design — next cut

1. Add `packaging/arch/PKGBUILD.surface-common`, `.surface-laptop`, and
   `.surface-phone` (`arch=('any')`). The common package supplies the channel
   code; each profile supplies only its own QML/assets and adoption manifest.
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 appropriate profile package with pacman,
   run the profile 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-laptop` and
  `pacman -S souveraine-surface-phone` never change a QuickShell file.
- The adoption command clearly reports its plan and refuses unapproved
  replacements.
- A deliberate profile adoption makes `/agent`, `/resume`, agent selection,
  and the Souveraine panel available against the locally running package
  service without importing another device's bar or dock.
- An upgrade and uninstall preserve user settings and agent state.
