docs: clarify PR scope and add PR-specific documentation

- Add LIBSODIUM_PKG_CONFIG_FIX.md specific to PR #102 changes
- Update LIBSODIUM_BUILD_FIX.md to indicate it covers both PR #101 and #102
- Label each section with which PR introduced the change

Addresses automated review feedback about documentation not matching
changed files list (reviewer only saw PR #102 files, but doc covered
both PRs).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

LIBSODIUM_BUILD_FIX.md

@@ -1,4 +1,8 @@
-# libsodium Build Failure Fix
+# libsodium Build Failure Fix (Complete Solution)
+
+> **Note:** This document describes the complete fix implemented across **two PRs**:
+> - **PR #101**: Docker package additions + initial Windows env vars + test coverage
+> - **PR #102**: pkg-config detection control (see `LIBSODIUM_PKG_CONFIG_FIX.md` for PR #102 details)
 
 ## Description
 
@@ -9,11 +13,16 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm
 1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg`
 2. **Windows cross-build**: `SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG`
 
-## Root Cause
+## Root Cause (Two-Part Issue)
 
+**Part 1 (Fixed in PR #101):**
 - **Linux builds**: Docker images lacked `libsodium-dev` package
 - **Windows cross-build**: Missing explicit `SODIUM_LIB_DIR` environment variable despite pre-built libsodium in the cross-compiler image
 
+**Part 2 (Fixed in PR #102):**
+- **Linux builds**: `libsodium-sys-stable` build script wasn't explicitly told to use pkg-config
+- **Windows cross-build**: Setting `SODIUM_LIB_DIR` without disabling pkg-config caused detection conflict
+
 ## Acceptance Criteria
 
 - [x] All three Docker build images updated with libsodium dependencies
@@ -25,7 +34,7 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm
 
 ## Work Implemented
 
-### 1. Docker Image Updates
+### 1. Docker Image Updates (PR #101)
 
 **`.docker/Dockerfile.linux-amd64`**
 - Added `libsodium-dev` to apt package installation list
@@ -38,15 +47,15 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm
 **`.gitea/workflows/auto-tag.yml`**
 
 **Linux amd64 build:**
-- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection of libsodium
+- **PR #102:** Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection of libsodium
 
 **Linux arm64 build:**
-- Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection for cross-compiled libsodium
+- **PR #102:** Added `SODIUM_USE_PKG_CONFIG: "1"` to force pkg-config detection for cross-compiled libsodium
 
 **Windows cross-compile build:**
-- Added `SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib` to point to pre-built libsodium
-- Added `SODIUM_STATIC: "1"` to ensure static linking of pre-built libsodium
-- Added `SODIUM_USE_PKG_CONFIG: "no"` to prevent conflict with explicit SODIUM_LIB_DIR
+- **PR #101:** Added `SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib` to point to pre-built libsodium
+- **PR #101:** Added `SODIUM_STATIC: "1"` to ensure static linking of pre-built libsodium
+- **PR #102:** Added `SODIUM_USE_PKG_CONFIG: "no"` to prevent conflict with explicit SODIUM_LIB_DIR
 
 **Rationale:**
 `libsodium-sys-stable`'s build.rs checks environment variables in this order:
@@ -57,7 +66,7 @@ This fix resolves build failures across all CI/CD build targets (Linux amd64/arm
 Linux builds have `libsodium-dev` + `pkg-config` installed, so we force pkg-config mode.
 Windows has pre-compiled libsodium at a known path, so we use explicit path mode and disable pkg-config.
 
-### 3. Test Coverage
+### 3. Test Coverage (PR #101)
 
 **`src-tauri/src/state.rs`**
 - Added comprehensive test module with 3 tests:

LIBSODIUM_PKG_CONFIG_FIX.md

@@ -0,0 +1,90 @@
+# libsodium pkg-config Detection Fix
+
+## Description
+
+This PR fixes libsodium build failures that persisted after adding `libsodium-dev` packages to Docker images (PR #101). The issue was that `libsodium-sys-stable`'s build script wasn't being explicitly told **how** to find libsodium.
+
+**Remaining build failures after PR #101:**
+
+1. **Linux amd64/arm64**: `libsodium not found via pkg-config or vcpkg` (despite `libsodium-dev` + `pkg-config` being installed)
+2. **Windows cross-build**: `SODIUM_LIB_DIR is incompatible with SODIUM_USE_PKG_CONFIG` (conflicting detection methods)
+
+## Root Cause
+
+The `libsodium-sys-stable` crate's `build.rs` checks environment variables in this precedence:
+
+1. If `SODIUM_LIB_DIR` is set → use explicit path (incompatible with `SODIUM_USE_PKG_CONFIG` mode)
+2. If `SODIUM_USE_PKG_CONFIG` ≠ "no" → try pkg-config detection
+3. Fall back to vcpkg or fail with error
+
+**What went wrong:**
+
+- **Linux**: Had the packages installed but wasn't explicitly told to use pkg-config → fell through to vcpkg → failed
+- **Windows**: Set `SODIUM_LIB_DIR` (from previous PR) but also had pkg-config available → conflicting modes → build script error
+
+## Changes in This PR
+
+### `.gitea/workflows/auto-tag.yml`
+
+#### Linux amd64 build (line ~347)
+```yaml
+env:
+  SODIUM_USE_PKG_CONFIG: "1"  # NEW: Force pkg-config detection
+```
+
+**Why:** Ensures `libsodium-sys-stable` uses the installed `libsodium-dev` package via pkg-config.
+
+#### Linux arm64 build (line ~633)
+```yaml
+env:
+  SODIUM_USE_PKG_CONFIG: "1"  # NEW: Force pkg-config for cross-compile
+```
+
+**Why:** Same as amd64 - force pkg-config to find the arm64 libsodium package.
+
+#### Windows cross-compile build (line ~448)
+```yaml
+env:
+  SODIUM_LIB_DIR: /usr/x86_64-w64-mingw32/lib      # Already present from PR #101
+  SODIUM_STATIC: "1"                               # Already present from PR #101
+  SODIUM_USE_PKG_CONFIG: "no"                      # NEW: Disable pkg-config
+```
+
+**Why:** Prevents conflict between explicit path mode (`SODIUM_LIB_DIR`) and pkg-config detection. Windows uses pre-built libsodium from Dockerfile, not system packages.
+
+### `LIBSODIUM_BUILD_FIX.md`
+
+Updated documentation section 2 (CI/CD Pipeline Fix) to explain:
+- Platform-specific environment variable strategy
+- Build script precedence order
+- Rationale for each approach
+
+## Strategy Summary
+
+| Platform | Method | Env Vars | Reason |
+|----------|--------|----------|--------|
+| Linux amd64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev` + `pkg-config` installed |
+| Linux arm64 | pkg-config | `SODIUM_USE_PKG_CONFIG=1` | Has `libsodium-dev:arm64` + `pkg-config` |
+| Windows | explicit path | `SODIUM_LIB_DIR=...` + `SODIUM_USE_PKG_CONFIG=no` | Pre-built lib in known location, disable pkg-config |
+
+## Testing
+
+This PR only modifies CI workflow environment variables. Testing occurs via CI pipeline:
+
+- [ ] Linux amd64 build succeeds with pkg-config detection
+- [ ] Linux arm64 build succeeds with cross-compile pkg-config
+- [ ] Windows build succeeds with explicit lib path (no pkg-config conflict)
+- [ ] All platforms produce valid `.deb`, `.rpm`, `.exe`, `.msi` artifacts
+
+## Relationship to PR #101
+
+**PR #101** (already merged):
+- Added `libsodium-dev` to Linux Docker images
+- Added `SODIUM_LIB_DIR` + `SODIUM_STATIC` to Windows workflow
+- Added smoke test in `src-tauri/src/state.rs`
+
+**This PR** (new):
+- Adds `SODIUM_USE_PKG_CONFIG` env vars to tell build script **how** to find libsodium
+- Fixes detection failures that persisted after package installation
+
+Both PRs together form the complete fix.