---
task_id: souveraine-surface-002
title: Device-specific QuickShell profiles — shared agent channel, distinct bodies
status: scoped
priority: high
phase: delivery
created: 2026-07-13
references: docs/tasks/quickshell-surface-package.md, surfaces/quickshell/
---

# Device-Specific QuickShell Profiles

## Decision

Phone and laptop are not interchangeable shells. They are separate sensorium
surfaces of the same Souveraine service.

The shared layer is small and semantic:

- `Souveraine.qml`: server connection, agent catalog, selection, conversation
  creation/resume, streaming and backchannel operations.
- `Ai.qml`: message projection and `/agent`/`/resume` semantics.
- shared agent identity, API tokens, transcript, and subconscious events.

The body is profile-owned:

| Profile | Interaction contract | Visual contract |
|---|---|---|
| Phone | thumb-first, short-lived attention, rotation/dock/handset states | compact custom bar and pill; intentionally limited visible bulk |
| Laptop | keyboard/mouse, wider attention and many concurrent controls | richer bar, more icons, sidebars and desktop-oriented dock/overview |

No profile imports or replaces the other profile's bar, dock, or layout.

## Work breakdown

1. **Inventory current overlay files.** Mark each as common, phone, laptop, or
   genuinely unresolved. The existing mixed `deploy.sh` remains a developer
   tool only until this classification is complete.
2. **Create manifests.** `manifests/common`, `manifests/phone`, and
   `manifests/laptop` list only their own target paths. Each profile installer
   consumes its manifest, never the aggregate.
3. **Extract shared QML carefully.** Shared services must not read phone-only
   geometry, rotation state, or laptop-only sidebar assumptions. Pass profile
   capabilities/config explicitly where necessary.
4. **Package separately.** Build `common`, `phone`, and `laptop` surface
   packages as architecture-independent assets. Pacman installation writes
   `/usr/share` only; an explicit per-profile adoption command changes user
   QuickShell config after preview and consent.
5. **Test against two fixtures.** A disposable phone ii tree and laptop ii
   tree must demonstrate that each profile changes only its own files, can be
   declined without side effects, and preserves every adopted conflict.

## Immediate laptop path

The laptop needs the shared channel now, not a phone bar. The minimal targeted
deployment is `AiChat.qml` plus the already linked `Ai.qml` and
`Souveraine.qml`; it exposes `/agent` and `/resume` against the local server
without changing the laptop dock or bar. This remains the only approved live
adoption until the laptop manifest exists.

## Acceptance

- A phone package cannot place a pill or compact phone bar in laptop ii.
- A laptop package cannot add desktop density to the phone shell.
- Both profiles enumerate and switch the same server-provided agent catalog.
- Profile selection is explicit in installer output, package names, and task
  documentation; no hostname guessing is used.
