docs: add SHELL-SURFACES.md — the migration checklist

Migrations have been silently lossy: the subconscious surface was stranded for
over a week by the ii -> souveraine shell move, and five packages went stale,
both because there was no list of what exists to tick off. SHELL-SURFACES.md is
that list — every shell surface and first-party service, the contract it is
defined against, its substrate today, and whether it reaches the glass.

States the rule that would have caught it: a feature defined as QML in a shell
tree dies with that tree; one defined against a contract survives (the
subconscious model in services/Ai.qml crossed untouched; only its views, riveted
to the ii overlay system, stranded). Marks the ii-substrate furniture rows
UNVERIFIED — that verification is the checklist's first demand. STATE.md points
at it from the resume anchor.

STATE.md

@@ -9,6 +9,12 @@ this state file. Component repos keep their own repo-local PAF/ docs; what
 crosses repo boundaries lives here. Update this file when component state
 moves; it is the resume anchor.
 
+**Shell-surface migration checklist: `SHELL-SURFACES.md`.** Walk it before any
+substrate cutover (`ii` → `souveraine`, later `souveraine` → viewtop). The
+subconscious three-tier surface was stranded for over a week by the `ii` →
+`souveraine` move for want of exactly this list; five packages went stale the
+same way. If a row's substrate is the thing being left, re-home it first.
+
 Last updated: 2026-07-24 (phone updates via pacman; flashing retired).
 
 ## DEPLOYMENT — the phone updates with pacman. Do not flash.

docs/SHELL-SURFACES.md

@@ -0,0 +1,79 @@
+# Shell surfaces — migration checklist
+
+Why this exists: migrations have been silently lossy. The subconscious three-tier
+surface was stranded for over a week when the shell moved `ii` → `souveraine` —
+the files survived, but the running shell never loaded them, and nobody noticed
+until asked. Five packages went stale the same way for the same reason: there was
+no list of what exists, so there was nothing to tick off.
+
+This is that list. **Every shell surface and first-party service, the contract
+it is defined against, the substrate it lives in today, and whether it actually
+reaches the glass.** Before any substrate cutover (`ii` → `souveraine`, later
+`souveraine` → viewtop), walk this table. If a row's substrate is the thing
+being left, it must be re-homed first or it drops.
+
+The rule that would have caught the subconscious: **a feature defined as "QML in
+a shell tree" dies with that tree; a feature defined against a contract
+survives.** The subconscious *model* (`services/Ai.qml`, substrate-neutral) made
+the crossing unscathed; only the *views* (riveted to the `ii` overlay system)
+were stranded. Define features at the contract layer — the model, the `wire`
+facts/intents under viewtop — not welded to a shell.
+
+## Souveraine-native surfaces (in `modules/souveraine/`)
+
+| Surface | Contract / definition | Renders in `souveraine` shell? |
+| --- | --- | --- |
+| Boot bloom | `modules/souveraine/boot` — boot animation overlay | yes |
+| Lock surface | `modules/souveraine/lock` + sessiond `ext-session-lock` | yes |
+| Gesture rail (pill) | `modules/souveraine/navigation` — always-on gesture bar | yes |
+| Radial dial | `modules/souveraine/dial` — quick-action ring | yes |
+| Selection menu | `modules/souveraine/selection` + `services/Selection.qml`; chip tap broken (TASK-18), viewtop-bound | partial — paints, not tappable |
+| **Subconscious surface** | `modules/souveraine/subconscious` + `services/Ai.qml`; relocated out of `ii` 2026-07-30 | **no — no host mounts the views yet (the gap)** |
+
+The subconscious row is the cautionary one: re-homed, decoupled, but inert until
+a souveraine overlay/sidebar host instantiates it. The model feeds it; the view
+has no glass.
+
+## Still on the `ii` substrate (in `modules/ii/` or `ii-base/`) — UNVERIFIED
+
+These render through the legacy `ii` tree. Whether the active `souveraine` shell
+actually composes each one has **not been verified** — that is the first work
+this checklist demands. Any that the `souveraine` shell does not load are
+already silently stranded, the subconscious all over again.
+
+| Surface | Source | Renders in `souveraine` shell? |
+| --- | --- | --- |
+| Bar / status panel | `modules/ii/bar` | unverified |
+| Dock (app switcher) | `modules/ii/dock` | unverified |
+| On-screen keyboard | `modules/ii/onScreenKeyboard` + stevia/squeekboard/osk-switch | unverified |
+| Overview / app grid | `modules/ii/overview` | unverified |
+| Sidebar left (AI chat) | `modules/ii/sidebarLeft` | unverified |
+| Sidebar right | `modules/ii/sidebarRight` | unverified |
+| Polkit agent | `modules/ii/polkit` | unverified |
+| Notifications | `modules/ii/notificationPopup` | unverified |
+| Screen corners / session screen / wallpaper selector | `modules/ii/*`, `ii-base/*` | unverified |
+
+## First-party services (substrate-neutral, in `services/`)
+
+These are the contract layer. They survived `ii` → `souveraine` untouched and
+will survive `souveraine` → viewtop the same way — they are the pattern done
+right. Views should depend on these, never on a shell tree directly.
+
+`Ai` (subconscious model + stream + event log), `Selection` (primary-selection
+watcher), `Speech` (`Speech.speak` TTS), `SessiondBridge`, `GlobalStates`,
+`DeviceEvidence`, `Haptics`, `NotifyEvents`, `CrashReporter`.
+
+## How to verify a row
+
+`qs list --all` for the instance, then read
+`/run/user/1000/quickshell/by-id/<id>/log.log`. A surface that exists in the
+tree but never instantiates leaves no log line and no error — silence is the
+failure mode. Confirm each `ii`-substrate row is actually composed before
+counting the `ii` exit done.
+
+## Connects to
+
+`STATE.md` (the resume anchor — keep this table current when a surface moves),
+`INVENTORY.md` (component/repo ownership, tiered), TASK-43 (viewtop — the
+substrate these all migrate to), the selection-menu and subconscious design
+docs. The package-side twin of this problem is in TASK-25.