docs: fold the stranded device tasks, archive the handoffs, one index per tree

docs/README.md

@@ -1,98 +1,55 @@
-# Souveraine quickshell surface
+# SouveraineOS — docs
 
-The desktop shell as a Souveraine surface — the primary visual frontend for
+Two subjects live here, and the split is real:
-SouveraineOS, with the TUI remaining the dive-in instrument.
 
-## Architecture
+- **this directory** — the device. Session authority, lock, power, sensors,
+  shell, packaging, hardware.
+- **[`substrate/`](substrate/)** — the agent. Consciousness, memory, sensorium,
+  felt state, federation transport, TUI. Rescued 2026-07-26 out of a gitignored
+  directory on a full disk; read its README before trusting anything in it.
 
-- `services/Souveraine.qml` — the substrate singleton. The ONE server
+## The device — read in this order
-  connection every shell module hangs off: agent inventory, conversation
-  lifecycle, the SSE turn stream (raw events re-emitted via
-  `streamEvent(var)`), the backchannel (`cancelTurn()` / `interject(text)`),
-  and the desktop sensorium — every send carries ambient context (active
-  window, open apps, cursor position) so she perceives the room she is being
-  spoken to in. Device sensors (SouveraineOS positional data from the Pixel
-  3 kernel path) extend `collectAmbient()`.
-- `services/Ai.qml` — ii-compat adapter. Keeps the API the illogical-impulse
-  sidebar expects; owns no transport. Shapes wire events into the message
-  objects the existing chat UI renders.
-- `modules/` (coming) — presence (portrait PNGs from memfs, posture state
-  machine), cockpit (subconscious pane), agents (master–detail manager),
-  settings, schedules. Each subscribes to the Souveraine singleton.
 
-## What changes
+**Why.** [`SESSION-AUTHORITY-DOCTRINE.md`](SESSION-AUTHORITY-DOCTRINE.md) —
+§13 first (who owns the device), then §4 (never hold state the protocol owns),
+§9 (sensors are evidence), §10–11 (one authority).
 
-- "Models" in the sidebar are **Souveraine agents** (`GET /v1/agents`).
+**What is built.** [`DEVICE-STATE-MACHINE.md`](DEVICE-STATE-MACHINE.md) — the
-  Picking one starts a conversation with that agent — memory, sensors,
+unified machine: the audit that found each bug, the evidence model, the error
-  subconscious and all.
+contract, prior art, source health, and the trail.
-- Messages stream over the server's SSE endpoint
-  (`POST /v1/conversations/:id/messages`), authenticated with the agent's
-  bearer token from `~/.souveraine/server/agents/<id>/api_token`.
-- Subconscious **surfacings**, **reflection**, and **archivist** pressure
-  render in the chat as interface notes (dedicated widgets later).
-- Reasoning and sensor activity render inside collapsible `<think>` blocks.
-- Keys/providers/temperature are owned by `souveraine.toml` — the sidebar's
-  `/key` and `/temp` commands now just point there. The keyring path is dead.
-- Token pressure is fetched after each turn from
-  `GET /v1/conversations/:id/tokens`.
 
-## Portability (KDE / non-Hyprland)
+**What is true of the hardware.**
+[`LOCK-DPMS-LESSONS.md`](LOCK-DPMS-LESSONS.md) — ordering, the FTS controller,
+suspend, with receipts.
 
-`Souveraine.qml` itself is compositor-agnostic: quickshell runs on any
+**Contracts and status.** [`SESSION-TRUST-ARCHITECTURE.md`](SESSION-TRUST-ARCHITECTURE.md)
-wlroots-ish Wayland compositor and KWin; window sensing uses the
+(the contract), [`TRUST-BOUNDARY-MATRIX.md`](TRUST-BOUNDARY-MATRIX.md)
-foreign-toplevel protocol (KWin implements it); the cursor read tries
+(what is actually gated), [`SECURITY-AUDIT.md`](SECURITY-AUDIT.md) (P1–P7 and
-`hyprctl`, then `kdotool`, then degrades to nothing — ambient never blocks
+the threat register), [`souveraine-components/`](souveraine-components/) (the
-a send. Server autostart is desktop-neutral (systemd user unit, nohup
+authority binaries and their audit ladder).
-fallback), so opening any surface summons her.
 
-What is NOT portable yet is the chrome: the chat UI is illogical-impulse's
+**Designs of record.** [`STORAGE-ENCRYPTION.md`](STORAGE-ENCRYPTION.md),
-sidebar. The path for "I run KDE, can I use this?" is a standalone
+[`FEDERATION.md`](FEDERATION.md),
-quickshell config (own ShellRoot + a window hosting the chat/presence
+[`session-authority-boot-order.md`](session-authority-boot-order.md).
-modules) that ships `Souveraine.qml` unchanged — planned once the modules
-stop being ii-embedded. Same service, same mappings, different shell.
 
-## Deploy
+**The shell and its apps.** [`FIRST-CLASS-APPS.md`](FIRST-CLASS-APPS.md) (the
+nine requirements), [`SHELL-ECOSYSTEM.md`](SHELL-ECOSYSTEM.md) (layer registry,
+manifests, guarded methods — the substrate doctrine §13's chaining needs),
+[`SETTINGS-AUTHORITY.md`](SETTINGS-AUTHORITY.md),
+[`AUDIO-PRIVACY.md`](AUDIO-PRIVACY.md),
+[`INTERFACE-ARCHITECTURE.md`](INTERFACE-ARCHITECTURE.md) (intent),
+[`HOW-IT-WORKS.md`](HOW-IT-WORKS.md) (current wiring),
+[`REFERENCE-EXTRACTION.md`](REFERENCE-EXTRACTION.md) (what to steal from whom),
+[`SETTINGS-APP-PLAN.md`](SETTINGS-APP-PLAN.md).
 
-```bash
+**Work.** [`tasks/README.md`](tasks/README.md) is the index. Single-session
-./deploy.sh        # backs up upstream Ai.qml, symlinks ours in
+units, numbered. Fewer files, not more — a finding goes in the doc that owns
-./deploy.sh -u     # restore upstream
+the subject.
-```
 
-Requires the server: `souveraine server` (default http://127.0.0.1:8484,
+**[`archive/`](archive/)** is superseded material kept as evidence. It is not
-override with `ai.souveraineUrl` in the ii config).
+authoritative and it is not deleted.
 
-## Wire contract
+## The rule that governs all of it
 
-The server's SSE layer is a full mirror of `BackendEvent` (see
+Where a doc and the code disagree, the code is right — fix one or the other in
-`src/api/models.rs::StreamEvent` — exhaustive `From` impls both ways, so a
+the same change, and never leave a third story.
-new engine event is a compile error at the seam, not a silent skip). The
-surface consumes the personification channel: subconscious tokens buffer and
-flush as one bubble when the N+1 pass ends (`subconscious_pass`), halts land
-as body signals, interstitials render by register (cenno = quiet aside,
-her_voice = gutter passage), `primary_complete` releases the input while the
-stream stays open for the subconscious, and `context_pressure` drives the
-live token counter. `atmosphere`/`outfit`/`itinerary` are logged, awaiting
-their shell-chrome layer.
-
-Server-side, the backchannel and verbs exist for every surface:
-`POST /v1/conversations/:id/cancel` (interrupt, `*[raised hand]*`
-semantics), `.../interject` (mid-turn notes, queued between turns),
-`GET .../messages` (transcript backfill), `POST .../fork` (`/btw`
-side-quests). `SendMessageRequest.ambient` injects the sensorium note.
-RemoteBackend rides all of it, so TUI remote mode gained cancel/interject/
-fork/resume in the same stroke.
-
-## Not yet wired
-
-- Sidebar UI hooks for cancel (Esc) and interject (type-while-busy) — the
-  service functions exist, the ii chat input doesn't call them yet
-- Conversation resume in the sidebar (server verb exists; surface always
-  starts fresh)
-- Atmosphere/outfit/itinerary driving actual shell chrome (events arrive;
-  modules pending)
-- File/image attachments (server has an image path; surface doesn't use it yet)
-- Regenerate (Souveraine conversations are forward-only by doctrine)
-- "Blank LLM mode" — a memoryless passthrough agent for throwaway questions;
-  needs a server-side agent flavor first
-- Dedicated widgets for surfacing/subconscious bubbles instead of interface
-  notes

docs/archive/README-quickshell-surface.md

@@ -0,0 +1,98 @@
+# Souveraine quickshell surface
+
+The desktop shell as a Souveraine surface — the primary visual frontend for
+SouveraineOS, with the TUI remaining the dive-in instrument.
+
+## Architecture
+
+- `services/Souveraine.qml` — the substrate singleton. The ONE server
+  connection every shell module hangs off: agent inventory, conversation
+  lifecycle, the SSE turn stream (raw events re-emitted via
+  `streamEvent(var)`), the backchannel (`cancelTurn()` / `interject(text)`),
+  and the desktop sensorium — every send carries ambient context (active
+  window, open apps, cursor position) so she perceives the room she is being
+  spoken to in. Device sensors (SouveraineOS positional data from the Pixel
+  3 kernel path) extend `collectAmbient()`.
+- `services/Ai.qml` — ii-compat adapter. Keeps the API the illogical-impulse
+  sidebar expects; owns no transport. Shapes wire events into the message
+  objects the existing chat UI renders.
+- `modules/` (coming) — presence (portrait PNGs from memfs, posture state
+  machine), cockpit (subconscious pane), agents (master–detail manager),
+  settings, schedules. Each subscribes to the Souveraine singleton.
+
+## What changes
+
+- "Models" in the sidebar are **Souveraine agents** (`GET /v1/agents`).
+  Picking one starts a conversation with that agent — memory, sensors,
+  subconscious and all.
+- Messages stream over the server's SSE endpoint
+  (`POST /v1/conversations/:id/messages`), authenticated with the agent's
+  bearer token from `~/.souveraine/server/agents/<id>/api_token`.
+- Subconscious **surfacings**, **reflection**, and **archivist** pressure
+  render in the chat as interface notes (dedicated widgets later).
+- Reasoning and sensor activity render inside collapsible `<think>` blocks.
+- Keys/providers/temperature are owned by `souveraine.toml` — the sidebar's
+  `/key` and `/temp` commands now just point there. The keyring path is dead.
+- Token pressure is fetched after each turn from
+  `GET /v1/conversations/:id/tokens`.
+
+## Portability (KDE / non-Hyprland)
+
+`Souveraine.qml` itself is compositor-agnostic: quickshell runs on any
+wlroots-ish Wayland compositor and KWin; window sensing uses the
+foreign-toplevel protocol (KWin implements it); the cursor read tries
+`hyprctl`, then `kdotool`, then degrades to nothing — ambient never blocks
+a send. Server autostart is desktop-neutral (systemd user unit, nohup
+fallback), so opening any surface summons her.
+
+What is NOT portable yet is the chrome: the chat UI is illogical-impulse's
+sidebar. The path for "I run KDE, can I use this?" is a standalone
+quickshell config (own ShellRoot + a window hosting the chat/presence
+modules) that ships `Souveraine.qml` unchanged — planned once the modules
+stop being ii-embedded. Same service, same mappings, different shell.
+
+## Deploy
+
+```bash
+./deploy.sh        # backs up upstream Ai.qml, symlinks ours in
+./deploy.sh -u     # restore upstream
+```
+
+Requires the server: `souveraine server` (default http://127.0.0.1:8484,
+override with `ai.souveraineUrl` in the ii config).
+
+## Wire contract
+
+The server's SSE layer is a full mirror of `BackendEvent` (see
+`src/api/models.rs::StreamEvent` — exhaustive `From` impls both ways, so a
+new engine event is a compile error at the seam, not a silent skip). The
+surface consumes the personification channel: subconscious tokens buffer and
+flush as one bubble when the N+1 pass ends (`subconscious_pass`), halts land
+as body signals, interstitials render by register (cenno = quiet aside,
+her_voice = gutter passage), `primary_complete` releases the input while the
+stream stays open for the subconscious, and `context_pressure` drives the
+live token counter. `atmosphere`/`outfit`/`itinerary` are logged, awaiting
+their shell-chrome layer.
+
+Server-side, the backchannel and verbs exist for every surface:
+`POST /v1/conversations/:id/cancel` (interrupt, `*[raised hand]*`
+semantics), `.../interject` (mid-turn notes, queued between turns),
+`GET .../messages` (transcript backfill), `POST .../fork` (`/btw`
+side-quests). `SendMessageRequest.ambient` injects the sensorium note.
+RemoteBackend rides all of it, so TUI remote mode gained cancel/interject/
+fork/resume in the same stroke.
+
+## Not yet wired
+
+- Sidebar UI hooks for cancel (Esc) and interject (type-while-busy) — the
+  service functions exist, the ii chat input doesn't call them yet
+- Conversation resume in the sidebar (server verb exists; surface always
+  starts fresh)
+- Atmosphere/outfit/itinerary driving actual shell chrome (events arrive;
+  modules pending)
+- File/image attachments (server has an image path; surface doesn't use it yet)
+- Regenerate (Souveraine conversations are forward-only by doctrine)
+- "Blank LLM mode" — a memoryless passthrough agent for throwaway questions;
+  needs a server-side agent flavor first
+- Dedicated widgets for surfacing/subconscious bubbles instead of interface
+  notes

docs/archive/README.md

@@ -0,0 +1,26 @@
+# Archive
+
+Superseded material, kept because it is evidence.
+
+**Handoffs and session dumps.** `HANDOFF.md`, `handoff-2026-07-17`,
+`handoff-2026-07-20-secrets`, `session-handoff-2026-07-16`,
+`DUMP-power-idle-lock-2026-07-15`, `DUMP-session-trust-2026-07-14`,
+`DUMP-pacman-pipeline-2026-07-24`. Each fed a doc that now owns the subject —
+the DPMS dump into `LOCK-DPMS-LESSONS.md`, the session-trust dump into the
+doctrine and the trust matrix, the pacman dump into TASK-25/27. They are the
+raw archaeology, not the answer.
+
+**Abandoned application stack.** `contacts-design.md`,
+`chatty-matrix-features.md`, `qtpim-contacts-handoff.md`, `messaging-rcs.md`.
+Chatty, libcmatrix and qtpim were all dropped 2026-07-21; contacts live in
+culver now (TASK-16). Carried the DEPRECATED banner in the live directory for
+five weeks.
+
+**One-off diagnoses.** `qs-aichat-oom.md` (the LaTeX renderer OOM),
+`README-quickshell-surface.md` (a shell description superseded by
+`HOW-IT-WORKS.md` and `INTERFACE-ARCHITECTURE.md`), `session-trust-map.html`
+(a generated visualization).
+
+`tasks/archive/from-substrate/` holds the eighteen device task files that were
+stranded in the gitignored substrate tree; each names the numbered task that
+took the subject over.

docs/substrate/tasks/INDEX.md

@@ -1,5 +1,12 @@
 # Documentation & Task Index
 
+> **STALE — generated 2026-05-19, describes May.** It does not know about any
+> July work, and the device tasks it lists have moved: eighteen to
+> `../../tasks/archive/from-substrate/`, four to `../../` as `FIRST-CLASS-APPS.md`,
+> `SHELL-ECOSYSTEM.md`, `SETTINGS-AUTHORITY.md`, `AUDIO-PRIVACY.md`. What
+> remains here is agent-substrate work. Statuses below were true in May and have
+> not been re-checked.
+>
 > Master index of all active documentation, tasks, and reference files.
 > Generated: 2026-05-19
 >

docs/tasks/README.md

@@ -58,6 +58,15 @@ work unit; 22 settings polish — folded into TASK-19 2026-07-26, its own text
 sourced its candidates from 19's "still required" list and its status was a
 placeholder ("items to enumerate with Casey at session start").
 
+**Docs consolidated 2026-07-26.** The agent-substrate tree was rescued out of
+`souveraine/docs` (gitignored, one disk, no snapshots) into `docs/substrate/`.
+Eighteen device task files that had been stranded there moved to
+`archive/from-substrate/`, each pointing at the numbered task that owns its
+subject; four live ones were promoted to `docs/` as `FIRST-CLASS-APPS.md`,
+`SHELL-ECOSYSTEM.md`, `SETTINGS-AUTHORITY.md` and `AUDIO-PRIVACY.md`. Seven
+handoffs/DUMPs and four docs for the abandoned Chatty/qtpim stack moved to
+`docs/archive/`. Top-level device docs: 31 → 19.
+
 **TASK-26 was never written and no longer needs to be.** It had two subjects
 and both are now closed. `blueline-proximity-lock` running as a second authority
 over proximity: resolved 2026-07-25, it reports to sessiond and decides nothing

docs/tasks/archive/from-substrate/README.md

@@ -0,0 +1,25 @@
+# Device tasks stranded in the substrate tree
+
+Eighteen files that tracked device work from inside `souveraine/docs`, which
+was gitignored. Every subject below is now owned by a numbered task or a doc in
+`docs/`. They are kept because several carry diagnosis that was never written
+down anywhere else.
+
+| File | Owner now | Note |
+|---|---|---|
+| `sensor-driven-lockscreen.md` | `DEVICE-STATE-MACHINE.md` §4, §10 | Peek/login lock mode is still wanted; its `SensorService` design is the one doctrine §9 flags as wiring an unverified input into a trust gate, and its proximity-blanks-locked-screen claim stopped being true 07-25 |
+| `power-indication.md` | TASK-08(b) | The upower fork, `charge_type`, and the percentage trap. Charge-aware idle policy is TASK-15's |
+| `souveraine-lock-primitives.md` + `-session-prompt.md` | TASK-02 | The AGPL primitive tiers and the cord-cut from ii. Still live work, no numbered home yet |
+| `qs-souveraine-composer.md` | `unify-shell-trees-laptop-phone.md` | How `deploy.sh` composes, and the lessons that landed hard |
+| `quickshell-surface-package.md` | TASK-25 | Adoption tool superseded by the composer; its packaging half stands |
+| `device-specific-quickshell-profiles.md` | TASK-25 | Phone/laptop manifests |
+| `souveraine-cicd-pipeline.md` | TASK-25, TASK-27 | The original pipeline design; both successors are further along |
+| `app-inventory-manifest.md` | `SHELL-ECOSYSTEM.md` | `apps.*` — a chaining verb surface (doctrine §13) |
+| `souveraine-cockpit-qml.md` | — | Cockpit feed for QML surfaces; unbuilt, no owner |
+| `every-boot-auth-prompt.md` | TASK-02 | Unprompted PAM auth every boot. Never root-caused; sessiond was the leading suspect and was never checked |
+| `greeter-phoc-swapchain-crashloop.md` | TASK-03 | phrog/phoc crash-loop on DSI-1. Predates the greetd path in use now |
+| `boot-splash-verify-fix.md` | TASK-03 | The premature `splash-signal` poke |
+| `lockscreen-wallpaper-setting.md` | TASK-02 | Never clarified with Casey; do not build from assumption |
+| `blueline-dock-tier1-drag.md`, `blueline-dock-provenance-and-deploy.md` | resolved | Landed 2026-07-12 |
+| `blueline-souveraine-kernel-os-provenance.md` | TASK-25 | Superseded by the packaging work |
+| `blueline-puremaps-gps-backup.md` | — | No owner |