From 1e4427f6afee461356eb0afb6d6187741e9f8781 Mon Sep 17 00:00:00 2001
From: Bernardo Magri <bernardo@bernardomagri.eu>
Date: Sat, 4 Jul 2026 10:13:50 +0100
Subject: [PATCH] docs(webcam): tuning tools in the app-suite template +
 libcamera gap filed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- templates/downstream/home.nix: commented "Webcam tuning" entries
  (cameractrls, v4l-utils) — bare packages, so template not toggle,
  per the option-surface rule; rarely needed since the IR-hide covers
  the common dual-sensor case.
- agent/BACKLOG.md PROPOSED: the portal/Flatpak camera picker still
  lists the internal IR sensor (libcamera path, untouched by the v4l2
  rule) — three options laid out, recommending document-only until a
  T14s-style machine is available to test a libcamera-side rule.

Closes BACKLOG NOW#7. Verified: V0 (flake check green; template still
evaluates through mkFlake).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 agent/BACKLOG.md              | 23 +++++++++++++++--------
 agent/JOURNAL.md              | 13 +++++++++++++
 templates/downstream/home.nix |  5 +++++
 3 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md
index 0374a7c..da6edf5 100644
--- a/agent/BACKLOG.md
+++ b/agent/BACKLOG.md
@@ -42,13 +42,6 @@ exist, the story isn't written). Site-vs-markdown is a Decision (below).
 **Verify:** V0 + a mechanical option-surface diff (eval the options,
 compare to the tables — consider making that a permanent check).
 
-### 7. Webcam follow-ups (small)
-ROADMAP § Webcam: ship `v4l-utils` + `cameractrls` (commented app-suite
-entries or alongside the camera toggle — respect the option-surface
-rule) for genuine-tuning cases; write up the portal/Flatpak
-libcamera-path gap (internal IR still listed there) as a PROPOSED item
-with options. **Verify:** V1.
-
 ## NEXT
 
 ### 8. Complete-workstation viewers + default applications
@@ -187,7 +180,21 @@ earns ≥3 entries — keep the root at six.
 *Agents: append here with a one-paragraph pitch (what/why/cost). Do not
 implement. Bernardo moves accepted items into a tier.*
 
-- *(empty)*
+- **Portal/Flatpak camera picker still lists the internal IR sensor**
+  (ROADMAP § Webcam follow-up). The shipped IR-hide is a *WirePlumber
+  v4l2* rule, but Flatpak/portal apps consume cameras via the
+  **libcamera** path, where both sensors remain visible — a Flatpak
+  Zoom user can still pick the black IR "camera". Options, roughly
+  ascending cost: (a) do nothing — document it (portal camera support
+  is still rare in practice); (b) a WirePlumber *libcamera* monitor
+  rule disabling GREY-only nodes — needs verifying that libcamera
+  monitor rules can match early enough (the v4l2 investigation found
+  only `device.api` binds pre-rule, which is why surgical scoping
+  failed before — same wall likely applies); (c) a libcamera
+  configuration/udev quirk hiding the IR sensor at the libcamera layer
+  itself. Cost: (b)/(c) need a T14s-style RGB+IR machine to verify →
+  pairs with a hardware-queue session. Recommend (a) now, (b)
+  investigated when the T14s is next available.
 
 ## Decisions `[human]`
 
diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md
index b789c08..3606010 100644
--- a/agent/JOURNAL.md
+++ b/agent/JOURNAL.md
@@ -17,6 +17,19 @@ Template:
 
 ---
 
+## 2026-07-04 — Webcam follow-ups (loop iteration #5, quick item)
+- **Task:** BACKLOG NOW#7 (Bernardo asked for "a quick item").
+- **Did:** template `home.packages` gains a commented "Webcam tuning"
+  pair (cameractrls GUI, v4l-utils CLI — bare packages, so template not
+  toggle, per the option-surface rule); the portal/Flatpak libcamera IR
+  gap is written up as a PROPOSED item with three options (recommend:
+  document-only now, libcamera-rule investigation when the T14s is
+  available). CI runs #60/#61 confirmed green (earlyoom + snapshot fix).
+- **Verified:** V0 (flake check — template evals through mkFlake;
+  changes are comments + agent docs).
+- **Next suggestion:** NOW#5 (keyboard cycle bind + summer parity) —
+  the last code item in NOW besides the docs pass.
+
 ## 2026-07-04 — Snapshot GUI un-broken + polkit agent (loop iteration #4)
 - **Task:** BACKLOG NOW#4 — btrfs-assistant segfault.
 - **Did:** re-diagnosed instead of overriding. gdb: crash is in
diff --git a/templates/downstream/home.nix b/templates/downstream/home.nix
index e8fc03c..2035935 100644
--- a/templates/downstream/home.nix
+++ b/templates/downstream/home.nix
@@ -113,6 +113,11 @@
     # kdePackages.kdenlive        # video editor (pulls in KDE libs)
     # handbrake                   # transcoder
 
+    # Webcam tuning (rarely needed — the distro's IR-hide covers the
+    # common dual-sensor problem; these are for genuine tuning cases)
+    # cameractrls                 # GUI for exposure/focus/zoom, saves per-camera presets
+    # v4l-utils                   # v4l2-ctl CLI: list formats, poke controls directly
+
     # Media
     # vlc
     # spotify                     # (unfree)