From 2eb7d09865a2a89c6b7690e33cb049e973e0592d Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Thu, 30 Jul 2026 11:23:10 -0400
Subject: [PATCH] docs: note that visual baselines are CI-canonical now

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LHH3wPBsoruwCaJo8Rpf6a
---
 KNOWN_ISSUES.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md
index aff714d2..793dbeee 100644
--- a/KNOWN_ISSUES.md
+++ b/KNOWN_ISSUES.md
@@ -43,3 +43,10 @@
 - **Status:** Not reproducible (2026-07-30)
 - **Description:** Intermittent `cancelledByParent` / "Promise resolution is still pending" hang, order/timing dependent.
 - **Current state:** Passes cleanly (`pass=3 fail=0 cancelled=0`) in isolation and across repeated full-suite sweeps on 2026-07-28–30. Left on file because the original failure was ordering-dependent; if it recurs, capture the full-suite ordering that produced it.
+
+## Run Notes (2026-07-30)
+
+### Visual baselines are CI-canonical — local `test:visual` may fail the kitchen-sink diff
+- **Status:** By design (since `ab120a03`)
+- **Description:** `tests/visual/baselines.json` is regenerated on ubuntu-latest by the `update-visual-baselines` workflow (trigger: `workflow_dispatch` once promoted, or a commit containing `[update-visual-baselines]`). Baselines can only match one environment, and the CI gate is the one that matters — so a dev machine with different Chromium/font rendering may now fail `npm run test:visual` locally (typically the kitchen-sink default theme) even though CI is green.
+- **Workaround:** Run visual tests in the pinned container via `scripts/run-playwright-docker.sh`, or rely on CI. Never regenerate baselines from a dev machine.