From 70da1600756fc91a5e7042bc6e6de6c594f88d55 Mon Sep 17 00:00:00 2001
From: Bastien Soret <99390284+bastiensoret@users.noreply.github.com>
Date: Fri, 20 Mar 2026 10:24:44 +0100
Subject: [PATCH 1/4] Update icon paths in manifest.json

---
 manifest.json | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/manifest.json b/manifest.json
index 520cde1..8b49c52 100644
--- a/manifest.json
+++ b/manifest.json
@@ -37,9 +37,10 @@
     }
   },
   "icons": {
-    "16": "icons/icon16.png",
-    "48": "icons/icon48.png",
-    "128": "icons/icon128.png"
+    "16": "static/icons/icon16.png",
+    "48": "static/icons/icon48.png",
+    "128": "static/icons/icon128.png"
+}
   },
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'self'"

From 912ebe2487938b6e4ea871cf7e2f8af7bcdb37c0 Mon Sep 17 00:00:00 2001
From: Bastien Soret <99390284+bastiensoret@users.noreply.github.com>
Date: Fri, 20 Mar 2026 10:27:55 +0100
Subject: [PATCH 2/4] Change icon paths to static directory in manifest.json

---
 manifest.json | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/manifest.json b/manifest.json
index 8b49c52..17deb95 100644
--- a/manifest.json
+++ b/manifest.json
@@ -31,16 +31,15 @@
   "action": {
     "default_popup": "popup.html",
     "default_icon": {
-      "16": "icons/icon16.png",
-      "48": "icons/icon48.png",
-      "128": "icons/icon128.png"
+      "16": "static/icons/icon16.png",
+      "48": "static/icons/icon48.png",
+      "128": "static/icons/icon128.png"
     }
   },
   "icons": {
     "16": "static/icons/icon16.png",
     "48": "static/icons/icon48.png",
     "128": "static/icons/icon128.png"
-}
   },
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'self'"

From ce43505bf0a0e9ee19ac0bf5fc5cb5443c519339 Mon Sep 17 00:00:00 2001
From: bastiensoret <bastiensoret@gmail.com>
Date: Fri, 20 Mar 2026 13:33:28 +0100
Subject: [PATCH 3/4] =?UTF-8?q?fix(ui):=20responsive=20audit=20=E2=80=94?=
 =?UTF-8?q?=20accessibility,=20CSS=20isolation,=20and=20visual=20polish?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace inline styles with CSS classes, add ARIA attributes and focus-visible
rings, fix font sizes and contrast ratios, wire AbortController for overlay
listener cleanup, and animate dismiss instead of display:none.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                      |  18 +++
 src/content/ui/comment-prefill.js |  37 +++--
 src/content/ui/overlay-manager.js | 219 +++++++++++++++++++-----------
 src/popup/popup.css               |  71 +++++++---
 src/popup/popup.html              |  38 +++---
 src/popup/popup.js                |  38 ++++--
 static/overlay.css                | 200 +++++++++++++++++++++++----
 7 files changed, 451 insertions(+), 170 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 13f92a4..2725a3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,8 @@ All notable changes to César are documented here.
 - Bundle size reporting in build output (metafile)
 
 ### Fixed
+- Comment prefill polls for editor (up to 2s) instead of fixed 500ms delay — fixes race on slow connections
+- Comment prefill scopes broader search to same post ancestor — prevents injecting into wrong post
 - `escapeHTML` rewritten as pure string replacement — works in service workers (no `document` dependency)
 - `chrome.storage` wrappers now properly reject on `runtime.lastError`
 - LLM error handlers use `await` instead of `return` (errors were silently swallowed)
@@ -22,6 +24,22 @@ All notable changes to César are documented here.
 - Removed stale `reason_fr` fallbacks from overlay manager and feed scanner
 
 ### Changed
+- Overlay dismiss animates out (scale + fade) instead of `display: none` — smoother UX
+- Inline styles replaced with CSS classes across overlay manager and popup (no more `style.color` in JS)
+- All `!important` rules removed from overlay CSS — specificity fixed via selector weight
+- Text arrows (`▼`) replaced with inline SVGs for cross-platform consistency
+- AbortController wired to all overlay event listeners for proper cleanup on re-inject
+- Overlay CSS resets font properties on `*` to prevent LinkedIn style bleed
+- Popup: `html lang` changed from `fr` to `en`; scrollbar styled; `max-height` on reveal panel reduced
+- Minimum font sizes raised to 11px across badges, labels, and footer for readability
+- Low-contrast text colors bumped (`#606078` → `#9a9ab0`, `#3a3a4e` → `#9a9ab0`)
+- Added `aria-label`, `aria-expanded`, `aria-controls`, and proper `<label>` associations across popup and overlay
+- Added `focus-visible` ring on all interactive elements (popup toggles, buttons, inputs, selects)
+- Added `prefers-reduced-motion` media query — disables slide-in, pulse, and spin animations
+- Added severity label badges (HIGH / MED / LOW) in overlay header
+- Added spinner animation on loader icon during comment prefill
+- Added LinkedIn dark-mode border contrast override for badges
+- Feedback buttons: clicking one now dims the others (`sourceit-btn-acted`)
 - Data attributes renamed from `data-sourceit-*` to `data-cesar-*`
 - Debug mode off by default in production (`CONFIG.DEBUG = false`)
 - Third-party regex patterns use Unicode-aware `\p{L}` for accented characters
diff --git a/src/content/ui/comment-prefill.js b/src/content/ui/comment-prefill.js
index c10fca2..eda45d7 100644
--- a/src/content/ui/comment-prefill.js
+++ b/src/content/ui/comment-prefill.js
@@ -8,7 +8,7 @@ import { escapeHTML } from '../../shared/sanitize.js';
  */
 export async function prefillComment(postElement, text, btn) {
   const originalHTML = btn.innerHTML;
-  btn.innerHTML = `${ICONS.loader} Opening...`;
+  btn.innerHTML = `<span class="sourceit-icon-spin">${ICONS.loader}</span> Opening...`;
 
   try {
     // Step 1: Find and click LinkedIn's "Comment" button to open the comment box
@@ -34,10 +34,7 @@ export async function prefillComment(postElement, text, btn) {
       linkedinCommentBtn.click();
     }
 
-    // Step 2: Wait for the comment editor to appear
-    await new Promise((resolve) => setTimeout(resolve, 500));
-
-    // Step 3: Find the comment input (contenteditable div)
+    // Step 2: Poll for the comment editor to appear (up to 2s)
     const editorSelectors = [
       '.ql-editor[data-placeholder]',
       '.ql-editor',
@@ -47,17 +44,18 @@ export async function prefillComment(postElement, text, btn) {
     ];
 
     let editor = null;
-    for (const sel of editorSelectors) {
-      editor = postElement.querySelector(sel);
-      if (editor) break;
-    }
-
-    // Broader search if not found within post
-    if (!editor) {
+    for (let attempt = 0; attempt < 10 && !editor; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 200));
       for (const sel of editorSelectors) {
-        const candidates = document.querySelectorAll(sel);
-        for (const c of candidates) {
-          if (c.offsetParent !== null) editor = c;
+        editor = postElement.querySelector(sel);
+        if (editor) break;
+      }
+      // Broader search — scoped to the same post ancestor to avoid injecting into wrong post
+      if (!editor) {
+        const postAncestor = postElement.closest('.feed-shared-update-v2') || postElement;
+        for (const sel of editorSelectors) {
+          editor = postAncestor.querySelector(sel);
+          if (editor) break;
         }
       }
     }
@@ -72,14 +70,12 @@ export async function prefillComment(postElement, text, btn) {
       editor.dispatchEvent(new Event('change', { bubbles: true }));
 
       btn.innerHTML = `${ICONS.check} Ready — review and post`;
-      btn.style.color = '#2e7d32';
-      btn.style.borderColor = '#c8e6c9';
+      btn.classList.add('sourceit-btn-post-success');
     } else {
       // Fallback: copy to clipboard
       await navigator.clipboard.writeText(text);
       btn.innerHTML = `${ICONS.copy} Copied — paste in comment`;
-      btn.style.color = '#e65100';
-      btn.style.borderColor = '#ffe0b2';
+      btn.classList.add('sourceit-btn-post-fallback');
     }
   } catch (_err) {
     // Ultimate fallback
@@ -94,7 +90,6 @@ export async function prefillComment(postElement, text, btn) {
   // Reset button after 5s
   setTimeout(() => {
     btn.innerHTML = originalHTML;
-    btn.style.color = '';
-    btn.style.borderColor = '';
+    btn.classList.remove('sourceit-btn-post-success', 'sourceit-btn-post-fallback');
   }, 5000);
 }
diff --git a/src/content/ui/overlay-manager.js b/src/content/ui/overlay-manager.js
index 521e75b..23a1910 100644
--- a/src/content/ui/overlay-manager.js
+++ b/src/content/ui/overlay-manager.js
@@ -3,35 +3,54 @@ import { ICONS } from './icons.js';
 import { prefillComment } from './comment-prefill.js';
 import { escapeHTML } from '../../shared/sanitize.js';
 
+const POST_CONTENT_SEL = '.feed-shared-update-v2__content';
+
+const SEVERITY_LABELS = { high: 'HIGH', medium: 'MED', low: 'LOW' };
+
 export class OverlayManager {
+  /** Remove existing overlays and their event listeners */
+  _removeExisting(postElement) {
+    postElement.querySelectorAll('.sourceit-overlay').forEach((o) => {
+      const ac = o._abortController;
+      if (ac) ac.abort();
+      o.remove();
+    });
+  }
+
   injectPendingOverlay(postElement) {
-    postElement.querySelectorAll('.sourceit-overlay').forEach((o) => o.remove());
+    this._removeExisting(postElement);
 
     const overlay = document.createElement('div');
     overlay.className = 'sourceit-overlay sourceit-severity-medium';
+    const ac = new AbortController();
+    overlay._abortController = ac;
 
     overlay.innerHTML = `
       <div class="sourceit-badge">
         <div class="sourceit-badge-header">
           <span class="sourceit-icon">${ICONS.shield}</span>
           <span class="sourceit-title">César</span>
-          <span style="font-size:11px;color:#a4b0be;flex:1;">Analyzing...</span>
+          <span class="sourceit-analyzing-text">Analyzing...</span>
           <span class="sourceit-score sourceit-pending-score">...</span>
-          <button class="sourceit-dismiss" title="Close">${ICONS.x}</button>
+          <button class="sourceit-dismiss" title="Close" aria-label="Close">${ICONS.x}</button>
         </div>
         <div class="sourceit-badge-body">
-          <p class="sourceit-explanation" style="font-size:11px;color:#a4b0be;margin:0;">AI verification in progress</p>
+          <p class="sourceit-pending-explanation">AI verification in progress</p>
         </div>
       </div>
     `;
 
-    overlay.querySelector('.sourceit-dismiss').addEventListener('click', (e) => {
-      e.stopPropagation();
-      overlay.classList.add('sourceit-hidden');
-    });
+    overlay.querySelector('.sourceit-dismiss').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        overlay.classList.add('sourceit-hidden');
+      },
+      { signal: ac.signal }
+    );
 
     const target =
-      postElement.querySelector('.feed-shared-update-v2__content') || postElement;
+      postElement.querySelector(POST_CONTENT_SEL) || postElement;
     target.insertBefore(overlay, target.firstChild);
   }
 
@@ -39,45 +58,53 @@ export class OverlayManager {
    * Show a "cleared" badge when LLM determined the post is legitimate.
    */
   injectClearedOverlay(postElement, llmResult) {
-    postElement.querySelectorAll('.sourceit-overlay').forEach((o) => o.remove());
+    this._removeExisting(postElement);
 
     const overlay = document.createElement('div');
     overlay.className = 'sourceit-overlay sourceit-cleared';
+    const ac = new AbortController();
+    overlay._abortController = ac;
 
     const reason = escapeHTML(llmResult.reason || 'Original content');
 
     overlay.innerHTML = `
       <div class="sourceit-badge sourceit-badge-cleared">
-        <div class="sourceit-badge-header" style="border-bottom:none;">
+        <div class="sourceit-badge-header">
           <span class="sourceit-icon sourceit-icon-cleared">${ICONS.check}</span>
           <span class="sourceit-title">César</span>
           <span class="sourceit-llm-badge">AI</span>
-          <button class="sourceit-dismiss" title="Close">${ICONS.x}</button>
+          <button class="sourceit-dismiss" title="Close" aria-label="Close">${ICONS.x}</button>
         </div>
-        <div style="display:block;font-size:12px;color:#c8d0da;padding:4px 12px 8px;line-height:1.4;word-wrap:break-word;">${reason}</div>
+        <div class="sourceit-cleared-reason">${reason}</div>
       </div>
     `;
 
-    overlay.querySelector('.sourceit-dismiss').addEventListener('click', (e) => {
-      e.stopPropagation();
-      overlay.classList.add('sourceit-hidden');
-    });
+    overlay.querySelector('.sourceit-dismiss').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        overlay.classList.add('sourceit-hidden');
+      },
+      { signal: ac.signal }
+    );
 
-    // Auto-fade after 8 seconds
+    // Auto-fade after 8 seconds — disable interaction on faded overlay
     setTimeout(() => {
-      overlay.style.opacity = '0.4';
+      if (overlay.isConnected) overlay.classList.add('sourceit-cleared-faded');
     }, CONFIG.CLEARED_FADE_DELAY);
 
     const target =
-      postElement.querySelector('.feed-shared-update-v2__content') || postElement;
+      postElement.querySelector(POST_CONTENT_SEL) || postElement;
     target.insertBefore(overlay, target.firstChild);
   }
 
   injectOverlay(postElement, regexResult, authorInfo, llmResult) {
-    postElement.querySelectorAll('.sourceit-overlay').forEach((o) => o.remove());
+    this._removeExisting(postElement);
 
     const overlay = document.createElement('div');
     overlay.className = 'sourceit-overlay';
+    const ac = new AbortController();
+    overlay._abortController = ac;
 
     const isLLM = llmResult !== null && llmResult !== undefined;
     const confidence = isLLM ? llmResult.confidence : regexResult.score;
@@ -113,7 +140,7 @@ export class OverlayManager {
         <div class="sourceit-comment-draft sourceit-collapsed">
           <button class="sourceit-comment-toggle">
             <span>${ICONS.comment} Comment with source</span>
-            <span class="sourceit-toggle-arrow">▼</span>
+            <span class="sourceit-toggle-arrow"><svg viewBox="0 0 10 6" width="10" height="6" fill="none"><path d="M1 1l4 4 4-4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
           </button>
           <div class="sourceit-comment-body">
             <div class="sourceit-comment-text-row">
@@ -143,92 +170,132 @@ export class OverlayManager {
         <div class="sourceit-badge-header">
           <span class="sourceit-icon">${severity === 'high' ? ICONS.alert : ICONS.shield}</span>
           <span class="sourceit-title">César</span>
+          <span class="sourceit-severity-label">${SEVERITY_LABELS[severity]}</span>
           <span class="sourceit-score">${confidence}%</span>
           ${isLLM ? '<span class="sourceit-llm-badge">AI</span>' : '<span class="sourceit-no-ai-badge">no AI</span>'}
-          <button class="sourceit-dismiss" title="Close">${ICONS.x}</button>
+          <button class="sourceit-dismiss" title="Close" aria-label="Close">${ICONS.x}</button>
         </div>
         ${rawReason ? `<div class="sourceit-reason-line">${rawReason}</div>` : ''}
         <div class="sourceit-badge-body">
           ${explanationHTML}
           <div class="sourceit-actions">
-            <button class="sourceit-btn sourceit-btn-confirm">${ICONS.check} Confirm</button>
-            <button class="sourceit-btn sourceit-btn-partial">${ICONS.minus} Partial</button>
-            <button class="sourceit-btn sourceit-btn-false">${ICONS.x} False positive</button>
+            <button class="sourceit-btn sourceit-btn-confirm" aria-label="Confirm detection">${ICONS.check} Confirm</button>
+            <button class="sourceit-btn sourceit-btn-partial" aria-label="Mark as partial">${ICONS.minus} Partial</button>
+            <button class="sourceit-btn sourceit-btn-false" aria-label="Mark as false positive">${ICONS.x} False positive</button>
           </div>
         </div>
       </div>
     `;
 
-    // Event listeners
-    overlay.querySelector('.sourceit-dismiss').addEventListener('click', (e) => {
-      e.stopPropagation();
-      overlay.classList.add('sourceit-hidden');
-    });
+    // Event listeners — all wired through AbortController for cleanup
+    const opts = { signal: ac.signal };
 
-    overlay.querySelector('.sourceit-btn-confirm').addEventListener('click', (e) => {
-      e.stopPropagation();
-      const btn = e.currentTarget;
-      btn.innerHTML = `${ICONS.check} Confirmed`;
-      btn.disabled = true;
-      btn.classList.add('sourceit-btn-confirmed');
-    });
+    overlay.querySelector('.sourceit-dismiss').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        overlay.classList.add('sourceit-hidden');
+      },
+      opts
+    );
 
-    overlay.querySelector('.sourceit-btn-partial').addEventListener('click', (e) => {
-      e.stopPropagation();
-      const btn = e.currentTarget;
-      btn.innerHTML = `${ICONS.minus} Noted`;
-      btn.disabled = true;
-      btn.style.opacity = '0.6';
-    });
+    const disableOtherActions = (activeBtn) => {
+      overlay.querySelectorAll('.sourceit-actions .sourceit-btn').forEach((b) => {
+        if (b !== activeBtn) b.classList.add('sourceit-btn-acted');
+        b.disabled = true;
+      });
+    };
 
-    overlay.querySelector('.sourceit-btn-false').addEventListener('click', (e) => {
-      e.stopPropagation();
-      overlay.classList.add('sourceit-hidden');
-      postElement.removeAttribute(CONFIG.FLAGGED_ATTR);
-    });
+    overlay.querySelector('.sourceit-btn-confirm').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        const btn = e.currentTarget;
+        btn.innerHTML = `${ICONS.check} Confirmed`;
+        btn.classList.add('sourceit-btn-confirmed');
+        disableOtherActions(btn);
+      },
+      opts
+    );
+
+    overlay.querySelector('.sourceit-btn-partial').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        const btn = e.currentTarget;
+        btn.innerHTML = `${ICONS.minus} Noted`;
+        disableOtherActions(btn);
+      },
+      opts
+    );
+
+    overlay.querySelector('.sourceit-btn-false').addEventListener(
+      'click',
+      (e) => {
+        e.stopPropagation();
+        overlay.classList.add('sourceit-hidden');
+        postElement.removeAttribute(CONFIG.FLAGGED_ATTR);
+      },
+      opts
+    );
 
     // Comment section toggle (collapsible)
     const commentToggle = overlay.querySelector('.sourceit-comment-toggle');
     if (commentToggle) {
-      commentToggle.addEventListener('click', (e) => {
-        e.stopPropagation();
-        const draft = overlay.querySelector('.sourceit-comment-draft');
-        draft.classList.toggle('sourceit-collapsed');
-      });
+      commentToggle.addEventListener(
+        'click',
+        (e) => {
+          e.stopPropagation();
+          const draft = overlay.querySelector('.sourceit-comment-draft');
+          draft.classList.toggle('sourceit-collapsed');
+        },
+        opts
+      );
     }
 
     // Copy comment button
     const copyBtn = overlay.querySelector('.sourceit-btn-copy');
     if (copyBtn) {
-      copyBtn.addEventListener('click', (e) => {
-        e.stopPropagation();
-        const commentText = overlay.querySelector('.sourceit-comment-text')?.textContent;
-        if (commentText) {
-          navigator.clipboard.writeText(commentText).then(() => {
-            copyBtn.innerHTML = `${ICONS.check}`;
-            copyBtn.style.color = '#2e7d32';
-            setTimeout(() => {
-              copyBtn.innerHTML = `${ICONS.copy}`;
-              copyBtn.style.color = '';
-            }, 2000);
-          });
-        }
-      });
+      copyBtn.addEventListener(
+        'click',
+        (e) => {
+          e.stopPropagation();
+          const commentText = overlay.querySelector('.sourceit-comment-text')?.textContent;
+          if (commentText) {
+            navigator.clipboard.writeText(commentText).then(() => {
+              copyBtn.innerHTML = `${ICONS.check}`;
+              copyBtn.classList.add('sourceit-btn-copy-success');
+              setTimeout(() => {
+                copyBtn.innerHTML = `${ICONS.copy}`;
+                copyBtn.classList.remove('sourceit-btn-copy-success');
+              }, 2000);
+            }).catch(() => {
+              copyBtn.innerHTML = `${ICONS.x}`;
+              setTimeout(() => { copyBtn.innerHTML = `${ICONS.copy}`; }, 2000);
+            });
+          }
+        },
+        opts
+      );
     }
 
     // "Post comment" — pre-fill LinkedIn comment box
     const postCommentBtn = overlay.querySelector('.sourceit-btn-post-comment');
     if (postCommentBtn) {
-      postCommentBtn.addEventListener('click', (e) => {
-        e.stopPropagation();
-        const commentText = overlay.querySelector('.sourceit-comment-text')?.textContent;
-        if (!commentText) return;
-        prefillComment(postElement, commentText, postCommentBtn);
-      });
+      postCommentBtn.addEventListener(
+        'click',
+        (e) => {
+          e.stopPropagation();
+          const commentText = overlay.querySelector('.sourceit-comment-text')?.textContent;
+          if (!commentText) return;
+          prefillComment(postElement, commentText, postCommentBtn);
+        },
+        opts
+      );
     }
 
     const target =
-      postElement.querySelector('.feed-shared-update-v2__content') || postElement;
+      postElement.querySelector(POST_CONTENT_SEL) || postElement;
     target.insertBefore(overlay, target.firstChild);
   }
 }
diff --git a/src/popup/popup.css b/src/popup/popup.css
index d44b7ec..a9e64ce 100644
--- a/src/popup/popup.css
+++ b/src/popup/popup.css
@@ -6,9 +6,17 @@ body {
   color: #e8e8ee;
   font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
   overflow-x: hidden;
+  overflow-y: auto;
   font-size: 13px;
+  scrollbar-width: thin;
+  scrollbar-color: #2a2a40 transparent;
 }
 
+body::-webkit-scrollbar { width: 6px; }
+body::-webkit-scrollbar-track { background: transparent; }
+body::-webkit-scrollbar-thumb { background: #2a2a40; border-radius: 3px; }
+body::-webkit-scrollbar-thumb:hover { background: #3a3a55; }
+
 .header {
   background: #13132a;
   padding: 14px 20px;
@@ -73,7 +81,11 @@ body {
 
 .header-toggle input:checked + .header-toggle-slider::before {
   transform: translateX(16px);
-  background: #7bc47b;
+  background: #7bed9f;
+}
+
+.header-toggle input:focus-visible + .header-toggle-slider {
+  box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5);
 }
 
 .main { padding: 16px 20px; }
@@ -91,7 +103,7 @@ body {
 
 .parasite-label {
   font-size: 12px;
-  color: #808098;
+  color: #9a9ab0;
 }
 
 .parasite-value {
@@ -119,8 +131,8 @@ body {
 .toggle-label { font-size: 13px; color: #c0c0d0; }
 
 .web-search-desc {
-  font-size: 10px;
-  color: #606078;
+  font-size: 11px;
+  color: #9a9ab0;
   margin-top: 6px;
   line-height: 1.5;
 }
@@ -161,7 +173,11 @@ body {
 
 .toggle input:checked + .toggle-slider::before {
   transform: translateX(16px);
-  background: #7bc47b;
+  background: #7bed9f;
+}
+
+.toggle input:focus-visible + .toggle-slider {
+  box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5);
 }
 
 .reveal-btn {
@@ -170,7 +186,7 @@ body {
   border: 1px solid rgba(255,255,255,0.05);
   border-radius: 10px;
   padding: 10px 14px;
-  color: #606078;
+  color: #9a9ab0;
   font-size: 11px;
   cursor: pointer;
   display: flex;
@@ -182,14 +198,19 @@ body {
 
 .reveal-btn:hover {
   background: rgba(255,255,255,0.025);
-  color: #808098;
+  color: #a0a0b8;
 }
 
+.reveal-btn:focus-visible { box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5); outline: none; }
+
 .reveal-arrow {
   transition: transform 0.25s;
-  font-size: 9px;
+  display: flex;
+  align-items: center;
 }
 
+.reveal-arrow svg { width: 10px; height: 6px; }
+
 .reveal-btn.open .reveal-arrow { transform: rotate(180deg); }
 
 .reveal-content {
@@ -198,7 +219,7 @@ body {
   transition: max-height 0.3s ease;
 }
 
-.reveal-content.open { max-height: 500px; }
+.reveal-content.open { max-height: 350px; }
 
 .reveal-inner {
   padding: 14px 0 0;
@@ -208,8 +229,8 @@ body {
 }
 
 .group-label {
-  font-size: 9px;
-  color: #4a4a60;
+  font-size: 11px;
+  color: #9a9ab0;
   text-transform: uppercase;
   letter-spacing: 0.08em;
   margin-bottom: -2px;
@@ -217,10 +238,10 @@ body {
 
 .provider-select {
   width: 100%;
-  background: rgba(255,255,255,0.04);
+  background: rgba(255,255,255,0.04) url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6'%3E%3Cpath d='M0 0l5 6 5-6z' fill='%239a9ab0'/%3E%3C/svg%3E") no-repeat right 10px center;
   border: 1px solid rgba(255,255,255,0.07);
   border-radius: 8px;
-  padding: 7px 10px;
+  padding: 7px 28px 7px 10px;
   color: #c0c0d0;
   font-size: 11px;
   outline: none;
@@ -228,12 +249,17 @@ body {
   font-family: inherit;
 }
 
+.provider-select:focus-visible {
+  box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5);
+}
+
 .provider-select option { background: #13132a; }
 
 .api-key-row { display: flex; gap: 6px; }
 
 .api-key-input {
   flex: 1;
+  min-width: 0;
   background: rgba(255,255,255,0.04);
   border: 1px solid rgba(255,255,255,0.07);
   border-radius: 8px;
@@ -244,12 +270,16 @@ body {
   outline: none;
 }
 
+.api-key-input:focus-visible {
+  box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5);
+}
+
 .api-key-btn {
   background: rgba(255,255,255,0.06);
   border: 1px solid rgba(255,255,255,0.1);
   border-radius: 8px;
   padding: 7px 12px;
-  color: #808098;
+  color: #9a9ab0;
   font-size: 11px;
   font-weight: 600;
   cursor: pointer;
@@ -258,8 +288,9 @@ body {
 }
 
 .api-key-btn:hover { background: rgba(255,255,255,0.1); color: #c0c0d0; }
+.api-key-btn:focus-visible { box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5); outline: none; }
 
-.api-status { font-size: 10px; color: #606078; }
+.api-status { font-size: 11px; color: #808098; }
 
 .setting-row {
   display: flex;
@@ -268,7 +299,7 @@ body {
   padding: 4px 0;
 }
 
-.setting-text { font-size: 12px; color: #808098; }
+.setting-text { font-size: 12px; color: #808098; cursor: pointer; }
 
 .footer {
   padding: 10px 20px;
@@ -277,8 +308,12 @@ body {
 }
 
 .footer-text {
-  font-size: 10px;
+  font-size: 11px;
   font-weight: 400;
-  color: #3a3a4e;
+  color: #9a9ab0;
   letter-spacing: 0.03em;
 }
+
+.api-status-success { color: #7bed9f; }
+.api-status-error { color: #ff8a9c; }
+.web-search-desc-error { color: #ff8a9c; }
diff --git a/src/popup/popup.html b/src/popup/popup.html
index 621626d..e1d0636 100644
--- a/src/popup/popup.html
+++ b/src/popup/popup.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="fr">
+<html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -16,7 +16,7 @@
       <span class="logo-text">César</span>
     </div>
     <label class="header-toggle" title="Toggle detection">
-      <input type="checkbox" id="toggle-active" checked>
+      <input type="checkbox" id="toggle-active" checked aria-label="Toggle César detection">
       <span class="header-toggle-slider"></span>
     </label>
   </div>
@@ -32,7 +32,7 @@
       <div class="toggle-row">
         <span class="toggle-label">Web search</span>
         <label class="toggle">
-          <input type="checkbox" id="toggle-websearch">
+          <input type="checkbox" id="toggle-websearch" aria-label="Enable web search">
           <span class="toggle-slider"></span>
         </label>
       </div>
@@ -41,16 +41,16 @@
       </div>
     </div>
 
-    <button class="reveal-btn" id="reveal-btn">
+    <button class="reveal-btn" id="reveal-btn" aria-expanded="false" aria-controls="reveal-content">
       <span>Settings</span>
-      <span class="reveal-arrow">▼</span>
+      <span class="reveal-arrow"><svg viewBox="0 0 10 6" width="10" height="6" fill="none"><path d="M1 1l4 4 4-4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
     </button>
 
     <div class="reveal-content" id="reveal-content">
       <div class="reveal-inner">
 
-        <div class="group-label">Provider</div>
-        <select class="provider-select" id="provider-select">
+        <label class="group-label" for="provider-select">Provider</label>
+        <select class="provider-select" id="provider-select" aria-label="LLM provider">
           <option value="auto">Auto-detect</option>
           <option value="anthropic">Anthropic — Haiku 4.5</option>
           <option value="openai">OpenAI — GPT-5 mini</option>
@@ -58,29 +58,29 @@
           <option value="grok">xAI — Grok 4.1 Fast</option>
         </select>
 
-        <div class="group-label">API key</div>
+        <label class="group-label" for="api-key-input">API key</label>
         <div class="api-key-row">
-          <input type="password" class="api-key-input" id="api-key-input" placeholder="sk-ant-... / sk-... / AIza...">
-          <button class="api-key-btn" id="api-key-save">OK</button>
+          <input type="password" class="api-key-input" id="api-key-input" placeholder="Paste your API key" aria-label="API key">
+          <button class="api-key-btn" id="api-key-save" aria-label="Save API key">OK</button>
         </div>
         <div class="api-status" id="api-status">No API key — regex only</div>
 
-        <div class="group-label">Options</div>
+        <span class="group-label" role="heading" aria-level="3">Options</span>
 
         <div class="setting-row">
-          <span class="setting-text">Auto-expand posts</span>
-          <label class="toggle">
-            <input type="checkbox" id="toggle-expand">
+          <label class="setting-text" for="toggle-expand">Auto-expand posts</label>
+          <span class="toggle">
+            <input type="checkbox" id="toggle-expand" aria-label="Auto-expand flagged posts">
             <span class="toggle-slider"></span>
-          </label>
+          </span>
         </div>
 
         <div class="setting-row">
-          <span class="setting-text">Mode debug</span>
-          <label class="toggle">
-            <input type="checkbox" id="toggle-debug">
+          <label class="setting-text" for="toggle-debug">Mode debug</label>
+          <span class="toggle">
+            <input type="checkbox" id="toggle-debug" aria-label="Debug mode">
             <span class="toggle-slider"></span>
-          </label>
+          </span>
         </div>
 
       </div>
diff --git a/src/popup/popup.js b/src/popup/popup.js
index 05930a5..4744287 100644
--- a/src/popup/popup.js
+++ b/src/popup/popup.js
@@ -22,12 +22,13 @@ function updateApiStatus(key, providerSetting) {
   chrome.runtime.sendMessage({ type: 'cesar-get-providers' }, (resp) => {
     if (chrome.runtime.lastError || !resp) return;
     const match = resp.providers.find((p) => p.id === provider);
+    status.classList.remove('api-status-success', 'api-status-error');
     if (match) {
-      status.innerHTML = `<span style="color:#7bed9f">●</span> ${match.name} — ${match.model}`;
-      status.style.color = '#7bed9f';
+      status.textContent = `● ${match.name} — ${match.model}`;
+      status.classList.add('api-status-success');
     } else {
       status.textContent = 'Unknown provider';
-      status.style.color = '#ff6b81';
+      status.classList.add('api-status-error');
     }
   });
 }
@@ -49,8 +50,10 @@ async function saveApiKey() {
   const effective = providerSelect !== 'auto' ? providerSelect : detected;
 
   if (!effective) {
-    document.getElementById('api-status').textContent = 'Unknown key — select a provider manually';
-    document.getElementById('api-status').style.color = '#ff6b81';
+    const statusEl = document.getElementById('api-status');
+    statusEl.textContent = 'Unknown key — select a provider manually';
+    statusEl.classList.remove('api-status-success');
+    statusEl.classList.add('api-status-error');
     return;
   }
 
@@ -58,6 +61,16 @@ async function saveApiKey() {
   input.value = key.substring(0, 10) + '...' + key.substring(key.length - 4);
   document.getElementById('provider-select').value = effective;
   updateApiStatus(key, effective);
+
+  // Brief save confirmation on the button
+  const saveBtn = document.getElementById('api-key-save');
+  const origText = saveBtn.textContent;
+  saveBtn.textContent = 'Saved';
+  saveBtn.style.color = '#7bed9f';
+  setTimeout(() => {
+    saveBtn.textContent = origText;
+    saveBtn.style.color = '';
+  }, 1500);
 }
 
 document.addEventListener('DOMContentLoaded', async () => {
@@ -98,11 +111,13 @@ document.addEventListener('DOMContentLoaded', async () => {
   document.getElementById('reveal-btn').addEventListener('click', () => {
     const btn = document.getElementById('reveal-btn');
     const content = document.getElementById('reveal-content');
-    btn.classList.toggle('open');
-    content.classList.toggle('open');
+    const isOpen = content.classList.toggle('open');
+    btn.classList.toggle('open', isOpen);
+    btn.setAttribute('aria-expanded', String(isOpen));
   });
 
   // Web search toggle — requires API key
+  let webSearchErrorTimer = null;
   document.getElementById('toggle-websearch').addEventListener('change', async (e) => {
     if (e.target.checked) {
       const keyData = await getStorage(['cesar_api_key']);
@@ -110,17 +125,20 @@ document.addEventListener('DOMContentLoaded', async () => {
         e.target.checked = false;
         const desc = document.querySelector('.web-search-desc');
         const originalText = desc.textContent;
+        if (webSearchErrorTimer) clearTimeout(webSearchErrorTimer);
         desc.textContent = 'An API key is required for web search. Add one in Settings below.';
-        desc.style.color = '#ff6b81';
-        setTimeout(() => {
+        desc.classList.add('web-search-desc-error');
+        webSearchErrorTimer = setTimeout(() => {
           desc.textContent = originalText;
-          desc.style.color = '';
+          desc.classList.remove('web-search-desc-error');
+          webSearchErrorTimer = null;
         }, 3000);
         // Open settings panel
         const revealBtn = document.getElementById('reveal-btn');
         const revealContent = document.getElementById('reveal-content');
         if (!revealContent.classList.contains('open')) {
           revealBtn.classList.add('open');
+          revealBtn.setAttribute('aria-expanded', 'true');
           revealContent.classList.add('open');
         }
       } else {
diff --git a/static/overlay.css b/static/overlay.css
index 2d03399..0328b9b 100644
--- a/static/overlay.css
+++ b/static/overlay.css
@@ -4,7 +4,12 @@
 .sourceit-overlay * {
   box-sizing: border-box;
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  font-size: 12px;
+  color: #f1f2f6;
+  font-weight: 400;
   line-height: 1.5;
+  text-decoration: none;
+  font-style: normal;
 }
 
 .sourceit-overlay {
@@ -12,11 +17,29 @@
   z-index: 100;
   margin: 0 0 8px 0;
   padding: 0 16px;
-  animation: sourceit-slideIn 0.3s ease-out;
+  animation: sourceit-slideIn 0.3s ease-out backwards;
+  will-change: transform, opacity;
+  color: #f1f2f6;
+  font-size: 12px;
+  text-align: left;
+  letter-spacing: normal;
+  text-transform: none;
+  word-spacing: normal;
+  direction: ltr;
+}
+
+.sourceit-overlay.sourceit-hidden {
+  opacity: 0;
+  transform: scaleY(0);
+  transform-origin: top;
+  max-height: 0;
+  overflow: hidden;
+  margin: 0;
+  padding: 0;
+  pointer-events: none;
+  transition: opacity 0.2s ease, transform 0.25s ease, max-height 0.3s ease 0.15s, margin 0.3s ease 0.15s, padding 0.3s ease 0.15s;
 }
 
-.sourceit-overlay.sourceit-hidden { display: none; }
-
 .sourceit-badge {
   background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
   border-radius: 8px;
@@ -60,6 +83,27 @@
   flex-grow: 1;
 }
 
+.sourceit-analyzing-text {
+  font-size: 11px;
+  color: #a4b0be;
+  flex: 1;
+}
+
+.sourceit-pending-explanation {
+  font-size: 11px;
+  color: #a4b0be;
+  margin: 0;
+}
+
+.sourceit-cleared-reason {
+  display: block;
+  font-size: 12px;
+  color: #c8d0da;
+  padding: 4px 12px 8px;
+  line-height: 1.4;
+  word-wrap: break-word;
+}
+
 .sourceit-reason-line {
   display: block;
   font-size: 12px;
@@ -100,7 +144,7 @@
 }
 
 .sourceit-llm-badge {
-  font-size: 9px;
+  font-size: 11px;
   font-weight: 700;
   padding: 2px 6px;
   border-radius: 3px;
@@ -111,7 +155,7 @@
 }
 
 .sourceit-no-ai-badge {
-  font-size: 8px;
+  font-size: 11px;
   font-weight: 600;
   padding: 2px 6px;
   border-radius: 3px;
@@ -122,7 +166,7 @@
 }
 
 .sourceit-no-ai-notice {
-  font-size: 10px;
+  font-size: 11px;
   color: #606878;
   margin-bottom: 8px;
   padding: 6px 8px;
@@ -167,7 +211,7 @@
 
 .sourceit-detail-row {
   display: flex;
-  align-items: baseline;
+  align-items: center;
   gap: 6px;
   font-size: 11px;
   padding: 4px 8px;
@@ -189,7 +233,7 @@
   color: #747d8c;
   min-width: 50px;
   flex-shrink: 0;
-  font-size: 10px;
+  font-size: 11px;
   text-transform: uppercase;
   letter-spacing: 0.03em;
 }
@@ -234,10 +278,13 @@
 .sourceit-comment-toggle svg { width: 12px; height: 12px; stroke: #AFA9EC; }
 
 .sourceit-toggle-arrow {
-  font-size: 9px;
+  display: flex;
+  align-items: center;
   transition: transform 0.25s;
 }
 
+.sourceit-toggle-arrow svg { width: 10px; height: 6px; }
+
 .sourceit-collapsed .sourceit-toggle-arrow { transform: rotate(0deg); }
 .sourceit-comment-draft:not(.sourceit-collapsed) .sourceit-toggle-arrow { transform: rotate(180deg); }
 
@@ -260,7 +307,7 @@
   line-height: 1.5;
   margin: 0;
   flex: 1;
-  user-select: all;
+  user-select: text;
 }
 
 .sourceit-btn-copy {
@@ -281,18 +328,18 @@
 
 .sourceit-comment-actions { margin-top: 8px; }
 
-.sourceit-btn-post-comment {
-  background: rgba(127,119,221,0.15) !important;
-  border-color: rgba(127,119,221,0.35) !important;
-  color: #AFA9EC !important;
+.sourceit-badge-body .sourceit-btn.sourceit-btn-post-comment {
+  background: rgba(127,119,221,0.15);
+  border-color: rgba(127,119,221,0.35);
+  color: #AFA9EC;
   width: 100%;
   justify-content: center;
-  padding: 6px 14px !important;
-  font-weight: 600 !important;
-  font-size: 11px !important;
+  padding: 6px 14px;
+  font-weight: 600;
+  font-size: 11px;
 }
 
-.sourceit-btn-post-comment:hover { background: rgba(127,119,221,0.25) !important; }
+.sourceit-badge-body .sourceit-btn.sourceit-btn-post-comment:hover { background: rgba(127,119,221,0.25); }
 .sourceit-btn-post-comment svg { stroke: #AFA9EC; }
 
 /* ---- Action buttons ---- */
@@ -303,7 +350,7 @@
 }
 
 .sourceit-btn {
-  font-size: 10px;
+  font-size: 11px;
   font-weight: 500;
   padding: 4px 10px;
   border-radius: 5px;
@@ -318,7 +365,7 @@
   gap: 4px;
 }
 
-.sourceit-btn svg { width: 10px; height: 10px; }
+.sourceit-btn svg { width: 12px; height: 12px; }
 .sourceit-btn:hover { background: rgba(255,255,255,0.08); color: #dfe4ea; }
 
 .sourceit-btn-confirm {
@@ -342,17 +389,69 @@
   color: #747d8c;
 }
 
-.sourceit-btn-confirmed {
-  background: rgba(46,213,115,0.15) !important;
-  border-color: rgba(46,213,115,0.3) !important;
-  color: #7bed9f !important;
+.sourceit-actions .sourceit-btn.sourceit-btn-confirmed {
+  background: rgba(46,213,115,0.15);
+  border-color: rgba(46,213,115,0.3);
+  color: #7bed9f;
   cursor: default;
 }
 
+.sourceit-actions .sourceit-btn.sourceit-btn-acted {
+  opacity: 0.4;
+  pointer-events: none;
+}
+
+/* ---- Severity labels (colorblind-safe) ---- */
+.sourceit-severity-label {
+  font-size: 9px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  padding: 1px 5px;
+  border-radius: 3px;
+}
+
+.sourceit-severity-high .sourceit-severity-label {
+  background: rgba(255,71,87,0.15);
+  color: #ff6b81;
+}
+
+.sourceit-severity-medium .sourceit-severity-label {
+  background: rgba(255,165,2,0.15);
+  color: #ffbe76;
+}
+
+.sourceit-severity-low .sourceit-severity-label {
+  background: rgba(255,255,255,0.06);
+  color: #dfe4ea;
+}
+
+/* ---- Loader spin ---- */
+.sourceit-icon-spin svg {
+  animation: sourceit-spin 1s linear infinite;
+}
+
+@keyframes sourceit-spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
 /* ---- Animations ---- */
 @keyframes sourceit-slideIn {
-  from { opacity: 0; transform: translateY(-6px); }
-  to { opacity: 1; transform: translateY(0); }
+  from {
+    opacity: 0;
+    transform: translateY(-6px);
+    max-height: 0;
+    margin-bottom: 0;
+    overflow: hidden;
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+    max-height: 500px;
+    margin-bottom: 8px;
+    overflow: hidden;
+  }
 }
 
 /* ---- Cleared state (AI confirmed legitimate) ---- */
@@ -381,3 +480,52 @@
   0%, 100% { opacity: 1; }
   50% { opacity: 0.3; }
 }
+
+/* Respect reduced-motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  .sourceit-overlay { animation: none; }
+  .sourceit-pending-score { animation: none; }
+  .sourceit-icon-spin svg { animation: none; }
+  .sourceit-cleared { transition: none; }
+}
+
+/* Faded cleared overlays should not be interactive */
+.sourceit-cleared-faded { opacity: 0.4; pointer-events: none; }
+
+/* Copy button success feedback */
+.sourceit-btn-copy-success { color: #7bed9f; }
+
+/* Post comment button state feedback */
+.sourceit-btn-post-success {
+  color: #7bed9f;
+  border-color: rgba(46,213,115,0.3);
+}
+
+.sourceit-btn-post-fallback {
+  color: #ffbe76;
+  border-color: rgba(255,165,2,0.3);
+}
+
+/* LinkedIn dark mode — increase badge border contrast */
+@media (prefers-color-scheme: dark) {
+  .sourceit-badge {
+    border-color: rgba(255,255,255,0.14);
+  }
+}
+:root.theme--dark .sourceit-badge,
+body.theme--dark .sourceit-badge,
+.theme--dark .sourceit-badge,
+[class*="theme--dark"] .sourceit-badge,
+.artdeco-theme--dark .sourceit-badge {
+  border-color: rgba(255,255,255,0.14);
+}
+
+/* Focus-visible for overlay interactive elements */
+.sourceit-dismiss:focus-visible,
+.sourceit-btn:focus-visible,
+.sourceit-btn-copy:focus-visible,
+.sourceit-comment-toggle:focus-visible,
+.sourceit-btn-post-comment:focus-visible {
+  box-shadow: 0 0 0 2px rgba(123, 237, 159, 0.5);
+  outline: none;
+}

From e24fc6df6e54362fa57032d5a1e4e808656e1ac9 Mon Sep 17 00:00:00 2001
From: bastiensoret <bastiensoret@gmail.com>
Date: Fri, 20 Mar 2026 13:38:03 +0100
Subject: [PATCH 4/4] docs(commit): add doc sync step and clarify --fast
 behavior

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/commit/skill.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/commit/skill.md b/.claude/skills/commit/skill.md
index 7dac70c..5ae1963 100644
--- a/.claude/skills/commit/skill.md
+++ b/.claude/skills/commit/skill.md
@@ -1,6 +1,6 @@
 ---
 name: "commit"
-description: "Safe commit with pre-audit. Use /commit instead of git commit directly. Scans staged changes for César-specific violations, runs the verification loop (test → lint), then creates a properly formatted commit."
+description: "Safe commit with pre-audit. Use /commit instead of git commit directly. Scans staged changes for César-specific violations, runs the verification loop (test → lint), updates docs (CHANGELOG, ROADMAP, README, CLAUDE.md), then creates a properly formatted commit."
 user_invocable: true
 ---
 
@@ -115,6 +115,8 @@ If permissions were added, ask the user to confirm they are necessary — Chrome
 
 **If `--fast` was passed**: skip this step entirely and go to Step 5.
 
+> Note: `--fast` skips tests/lint only — Step 5 (doc sync) is never skipped.
+
 Run these in order. Stop immediately if any fails.
 
 ```sh
@@ -129,7 +131,20 @@ If any command fails, show the error output and stop. Fix the issue before commi
 
 ---
 
-## Step 5 — Create the commit
+## Step 5 — Update documentation and roadmap
+
+Before committing, check whether the staged changes affect anything documented in the project's markdown files. Review and update as needed:
+
+1. **CHANGELOG.md** — Add an entry under the current version section (or create a new `[Unreleased]` section) describing what changed. Follow the existing Keep a Changelog format (Added / Fixed / Changed / Removed).
+2. **ROADMAP.md** — If the commit ships, progresses, or completes a roadmap item, update its status (e.g., 📋 → 🔨 or 🔨 → ✅). If the commit introduces a new planned feature not yet on the roadmap, add it.
+3. **README.md** — If the commit changes user-facing behavior, UI, supported LLMs, or anything mentioned in the README, update the relevant section.
+4. **CLAUDE.md** — If the commit changes architecture, build setup, key constraints, or commands, update the dev guide.
+
+Only touch files that actually need updating — don't add noise. Stage the updated docs together with the code changes.
+
+---
+
+## Step 6 — Create the commit
 
 Stage specific files (never `git add -A` or `git add .`):