docs: prepare PeerSpeak 0.6.7 release

docs/release-0.6.7-prep.md

@@ -0,0 +1,295 @@
+# PeerSpeak 0.6.7 release prep
+
+Prepared: 2026-08-22
+
+Planned work day: 2026-08-23 (confirm the actual date before updating the changelog)
+
+Release target: GitButter release page with a verified Linux x86_64 AppImage
+
+This is a checklist, not release authorization. Pushing `main`, creating or
+pushing a tag, creating the GitButter release, and uploading assets remain
+explicit approval gates.
+
+## Starting checkpoint
+
+Recheck every value live tomorrow; these are the known-good handoff values from
+2026-08-22.
+
+- PeerSpeak: `main` at `0823f617`, 17 commits ahead of `origin/main`.
+- PixelPass: `main` at `ce909afc`, 14 commits ahead of `origin/main`.
+- Latest published PeerSpeak tag: `v0.6.6`.
+- Current Cargo/Windows version: `0.6.6`.
+- Current field-test build:
+  `packaging/appimage/peerspeak-0.6.6-unofficial-20260822-ps0823f617-ppce909afc-fieldtest-x86_64.AppImage`
+- Current field-test SHA-256:
+  `f094a665dbd719929d6def32c8fd3d4943e4b88b6290e371e57b127c4e91ec45`.
+- The same build was staged for Lindsay at
+  `/home/lindsay/Downloads/peerspeak-0.6.6-unofficial-20260822-ps0823f617-ppce909afc-fieldtest-x86_64.AppImage`.
+- Preserve the existing user-owned `docs/FEATURES.md` modification and
+  untracked `.codex/` directory. Do not include either in release-prep commits
+  unless the user explicitly puts them in scope.
+
+The current one-row audio-picker build passed local AppImage artifact checks,
+but it still needs the final two-machine field pass. Earlier two-machine passes
+proved that desktop audio was heard, call voices were not echoed, and no warning
+was visible. They also exposed the now-fixed stale viewer/warning behavior. Do
+not substitute those earlier passes for testing the current build.
+
+## Version decision
+
+The expected release is **0.6.7**.
+
+`VERSIONING.md` defines pre-1.0 MINOR bumps as breaking wire-protocol changes,
+not as a measure of feature size. The diff from `v0.6.6` through `0823f617` is a
+large screen-share implementation and local UI/lifecycle change, but it does
+not change `src/protocol.rs` or bump an audio, friends, files, or gossip protocol
+version. Under the repository's policy, that makes this a PATCH release.
+
+Use `0.7.0` only if tomorrow's final source review finds or adds an actual
+incompatible wire change. If that happens, identify and bump the affected
+Layer-2 protocol constant/domain in the same change and plan a coordinated
+upgrade for every peer.
+
+## Critical build-label rule
+
+The first/home screen visibly identifies the binary as:
+
+```text
+PeerSpeak v<package version> (<8-character commit hash>)
+```
+
+The same label also appears in Settings. The two pieces come from different
+places:
+
+- `Cargo.toml` supplies the version through `CARGO_PKG_VERSION` and must be
+  bumped from `0.6.6` to `0.6.7`.
+- `build.rs` runs `git rev-parse --short=8 HEAD` and embeds the result as
+  `PEERSPEAK_GIT_SHORT`. **Do not edit or bump the hash by hand.**
+
+Consequences for the release order:
+
+1. Make and commit all source, version, changelog, and field-evidence changes.
+2. Build the final AppImage from that clean final commit.
+3. On first launch, verify the title screen says exactly
+   `PeerSpeak v0.6.7 (<final HEAD short hash>)`.
+4. Verify the displayed hash equals `git rev-parse --short=8 HEAD`.
+5. Tag that exact commit as `v0.6.7`.
+
+If any commit is added after an AppImage is built—even a field-evidence or
+release-note commit—the embedded hash is now old. Rebuild and revalidate the
+AppImage. Never publish an artifact whose visible hash differs from the tag
+target.
+
+## Tomorrow's runbook
+
+### 1. Re-establish live state
+
+From `/home/mollusk/git/butter/peerspeak`:
+
+```sh
+git status --short --branch
+git log -1 --oneline --decorate
+git -C ../pixelpass status --short --branch
+git -C ../pixelpass log -1 --oneline --decorate
+git fetch --prune --tags origin
+git ls-remote --heads --tags origin
+df -h / /mnt/superjar
+pgrep -af 'peerspeak|pixelpass|mpv|gst-launch' || true
+```
+
+Confirm that:
+
+- the checkpoint commits above are still the intended source;
+- neither repository has unexpected changes;
+- the existing `docs/FEATURES.md` and `.codex/` state is preserved;
+- no stale call/share processes are running;
+- `v0.6.7` does not already exist locally, remotely, or on GitButter;
+- there is enough space for one-job release builds and extracted AppImages.
+
+### 2. Complete the current-build two-machine field test
+
+Use the stamped `0823f617` AppImage on this machine and Lindsay's staged copy.
+Start with PeerSpeak and any old screen-share helper/player processes closed.
+
+Run both directions, with Lindsay keeping software encode enabled where needed:
+
+1. Mollusk hosts; Lindsay views.
+2. Lindsay hosts; Mollusk views.
+3. In each direction select the sole visible **All system audio** row.
+4. Play desktop audio after the share begins, including starting a new audio
+   stream/application during the share.
+5. Talk from both machines while the desktop audio plays.
+6. Stop sharing while the voice call remains active.
+7. Start one more share, then have both peers leave the call.
+
+Record all of these results explicitly:
+
+- the picker has one desktop-audio row, not duplicate legacy/safe choices;
+- desktop audio is heard by the viewer;
+- neither person's call voice loops back through the shared audio;
+- no transient or persistent missing-output-port warning appears;
+- stopping a share clears the viewer and warning promptly;
+- the viewer PixelPass child is reaped within roughly 500 ms after the remote
+  stream ends;
+- leaving the call clears the share and leaves no PeerSpeak-owned PixelPass,
+  player, GStreamer, capture, or echo-cancellation residue.
+
+If any row fails, stop release preparation. Save the exact visible text and
+relevant logs, fix the defect, run the focused regression gates, commit the
+fix, rebuild, and repeat the matrix.
+
+### 3. Prepare the 0.6.7 source
+
+After the current build passes:
+
+- Change `[package].version` in `Cargo.toml` to `0.6.7`.
+- Refresh the root PeerSpeak package entry in `Cargo.lock`; inspect the diff and
+  make sure it changes only as intended.
+- Change `MyAppVersion` in `packaging/windows/peerspeak.iss` to `0.6.7`, even
+  though tomorrow's planned public asset is AppImage-only. This prevents the
+  next Windows installer from silently retaining `0.6.6`.
+- Move the relevant `[Unreleased]` material into a dated `0.6.7` section in
+  `CHANGELOG.md` and add the `v0.6.7` comparison/release link.
+- State that the release is wire-compatible with `0.6.6`; do not claim a
+  protocol bump.
+- Summarize user-visible behavior, especially:
+  - **All system audio** now shares desktop sound without feeding PeerSpeak's
+    own call audio back to listeners;
+  - the safe path is the single normal desktop-audio choice;
+  - unsafe or incomplete audio-routing states fail closed and surface a useful
+    warning;
+  - viewer/share cleanup is prompt when a stream stops or a peer leaves;
+  - the Linux AppImage bundles the matching PixelPass helper.
+- Record the completed two-machine evidence in
+  `docs/screenshare-audio-exclusion-impl-plan.md`.
+
+Commit the scoped version/changelog/evidence work. Keep unrelated user changes
+out of the commit.
+
+### 4. Run source gates on the final commit
+
+Use the pinned Rust toolchain and one build job if disk or linker pressure is
+tight:
+
+```sh
+cargo fmt --all -- --check
+CARGO_BUILD_JOBS=1 cargo clippy --locked --all-targets -- -D warnings
+CARGO_BUILD_JOBS=1 cargo test --locked --all-targets
+CARGO_BUILD_JOBS=1 cargo test --locked --doc
+cargo deny --locked check
+cargo audit
+git diff --check
+git status --short --branch
+```
+
+The commands mirror the repository CI, with `--locked` added to compilation
+and test gates after the intentional lockfile refresh. A gate that cannot run
+must be recorded as unverified; do not silently treat it as passed.
+
+Also verify the bundled PixelPass source is still exactly the intended clean
+commit and run its release diagnostics before packaging:
+
+```sh
+git -C ../pixelpass status --short --branch
+git -C ../pixelpass rev-parse --short=8 HEAD
+cargo run --manifest-path ../pixelpass/Cargo.toml --locked -- --doctor
+```
+
+### 5. Build the final AppImage
+
+Build from the clean, committed PeerSpeak release source and clean PixelPass
+source in the Ubuntu 24.04 distrobox described in `packaging/appimage/README.md`.
+Keep build caches on `/mnt/superjar` and use one build job if space remains
+tight. A representative invocation is:
+
+```sh
+distrobox enter peerspeak-appimage -- env \
+  PATH="$HOME/.rustup/toolchains/1.97.1-x86_64-unknown-linux-gnu/bin:$PATH" \
+  SYSTEM_DEPS_LIBSPA_INCLUDE=/run/host/usr/include/spa-0.2 \
+  SYSTEM_DEPS_LIBPIPEWIRE_INCLUDE=/run/host/usr/include/pipewire-0.3:/run/host/usr/include/spa-0.2 \
+  CARGO_BUILD_JOBS=1 \
+  PEERSPEAK_APPIMAGE_CACHE=/mnt/superjar/peerspeak-appimage-cache \
+  ./packaging/appimage/build-appimage.sh
+```
+
+The official output should be
+`packaging/appimage/peerspeak-0.6.7-x86_64.AppImage`. Do not overwrite the
+stamped 0.6.6 field-test artifact until the release is complete and verified.
+
+### 6. Validate the exact final artifact
+
+At minimum:
+
+- record `sha256sum` and create a matching `.sha256` sidecar;
+- run `--appimage-extract` into an isolated scratch directory;
+- inspect `ldd` for both bundled `usr/bin/peerspeak` and `usr/bin/pixelpass` and
+  require no `not found` entries;
+- inspect RUNPATH/RPATH and confirm the bundle has not captured the host's
+  graphics, PulseAudio, or GStreamer stack contrary to the thin-AppImage policy;
+- run the bundled `pixelpass --capabilities` and confirm desktop-audio exclusion
+  support is advertised;
+- run the bundled `pixelpass --doctor` with a fresh temporary GStreamer registry;
+- launch the AppImage with an isolated config/data directory for a GUI smoke;
+- verify the first/home screen reads
+  `PeerSpeak v0.6.7 (<final PeerSpeak HEAD short hash>)`;
+- verify the same version/hash appears in Settings;
+- confirm the bundled PixelPass binary corresponds to `ce909afc` (or the exact
+  newer commit deliberately selected tomorrow).
+
+Because the final version/evidence commit changes the embedded hash relative to
+the current field-test artifact, do one short two-machine confirmation using
+the final AppImage: connect, share **All system audio**, confirm desktop sound
+and no voice echo/warning, stop the share, and leave cleanly.
+
+### 7. Publication gate
+
+Before any external write, present the final facts to the user:
+
+- final PeerSpeak full and short commit;
+- bundled PixelPass full and short commit;
+- `v0.6.7` proposed tag target;
+- AppImage filename, size, and SHA-256;
+- title-screen version/hash observed;
+- source, artifact, and two-machine gate results;
+- exact release notes/assets to publish.
+
+Then wait for explicit approval to publish.
+
+After approval only:
+
+1. Push `main` without force.
+2. Confirm remote `main` resolves to the tested final commit.
+3. Create an annotated `v0.6.7` tag on that exact commit and push it.
+4. Create the `v0.6.7` GitButter release page from the finalized changelog text.
+5. Upload `peerspeak-0.6.7-x86_64.AppImage` and its `.sha256` sidecar.
+6. Do not paste or store a GitButter token in the repository, documentation,
+   shell history, or release artifacts.
+
+The planned release scope is the Linux x86_64 AppImage only. Do not imply that
+a Windows installer, Debian package, or separate PixelPass release exists
+unless those artifacts are deliberately added and independently verified.
+
+### 8. Verify the public release
+
+Publication is not complete until it is independently read back:
+
+- confirm GitButter shows the correct release title, tag, notes, and both assets;
+- confirm the remote tag and remote `main` point to the expected commit;
+- download the public AppImage to a fresh temporary path;
+- verify its SHA-256 against the published sidecar and the local final hash;
+- extract or run the downloaded copy and repeat the version/hash and bundled
+  PixelPass diagnostic checks;
+- save the final release URL and verification result in the implementation plan
+  or handoff.
+
+## Failure and recovery rules
+
+- A failed gate means no tag and no release—not a waiver.
+- Never force-push or move a published tag as an automatic recovery step.
+- If the tag is pushed but release creation/upload fails, stop and report the
+  exact remote state before changing anything.
+- Keep failed or candidate artifacts clearly stamped so they cannot be mistaken
+  for the final asset.
+- Remove only exact, rebuildable scratch/extraction directories when reclaiming
+  disk space; preserve source, user changes, final artifacts, hashes, and field
+  evidence.