From c381995d24382f31d33873cf60770b027111f21f Mon Sep 17 00:00:00 2001
From: "pulse-triage[bot]"
 <249995291+pulse-triage[bot]@users.noreply.github.com>
Date: Sat, 3 Oct 2026 19:47:00 +0100
Subject: [PATCH] Keep proxy-auth help navigation independent of emoji
 fragments

The real Docs browser check reached the guide but could not resolve the guessed emoji heading fragment. Link the existing guide directly and verify its trust-boundary heading and text without inventing an anchor.

Contract-Neutral: Documentation and browser regression checks only; rendering, proxy trust and authentication runtime contracts are unchanged.
Change-source: pulse-maintainer
---
 docs/REVERSE_PROXY.md                                 | 2 +-
 frontend-modern/browser-tests/reverse-proxy-help.cjs  | 6 ++++--
 frontend-modern/public/docs/REVERSE_PROXY.md          | 2 +-
 frontend-modern/src/utils/__tests__/docsLinks.test.ts | 3 ++-
 4 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/REVERSE_PROXY.md b/docs/REVERSE_PROXY.md
index f6b19278d1..d0fdf9bd98 100644
--- a/docs/REVERSE_PROXY.md
+++ b/docs/REVERSE_PROXY.md
@@ -8,7 +8,7 @@ Use HTTPS at the public proxy and keep Pulse's backend private. The examples
 below are configuration fragments, not complete TLS or authentication setups.
 Keep Pulse authentication enabled; TLS termination does not authenticate users.
 For identity supplied by an IdP/proxy, follow the separate
-[proxy authentication guide](PROXY_AUTH.md#-header-trust-boundary).
+[proxy authentication guide](PROXY_AUTH.md), including its Header Trust Boundary.
 
 **Forwarded HTTPS headers are trusted only from a configured immediate peer.**
 Set `PULSE_TRUSTED_PROXY_CIDRS` in Pulse's deployment configuration to the proxy
diff --git a/frontend-modern/browser-tests/reverse-proxy-help.cjs b/frontend-modern/browser-tests/reverse-proxy-help.cjs
index cfd6292286..db82926d91 100644
--- a/frontend-modern/browser-tests/reverse-proxy-help.cjs
+++ b/frontend-modern/browser-tests/reverse-proxy-help.cjs
@@ -91,8 +91,10 @@ const { chromium, webkit } = require('playwright');
       const authentication = page.getByRole('link', { name: 'proxy authentication guide', exact: true });
       await authentication.focus();
       await page.keyboard.press('Enter');
-      await page.waitForFunction(inViewport, '-header-trust-boundary');
-      assert.ok(page.url().endsWith('/docs/PROXY_AUTH#-header-trust-boundary'));
+      const boundary = page.getByRole('heading', { name: '⚠️ Header Trust Boundary', exact: true });
+      await boundary.waitFor();
+      assert.ok(page.url().endsWith('/docs/PROXY_AUTH'));
+      await boundary.scrollIntoViewIfNeeded();
       assert.ok((await page.locator('article').innerText()).includes('never append to them'));
       assert.deepEqual(errors, []);
       observations.push({
diff --git a/frontend-modern/public/docs/REVERSE_PROXY.md b/frontend-modern/public/docs/REVERSE_PROXY.md
index f6b19278d1..d0fdf9bd98 100644
--- a/frontend-modern/public/docs/REVERSE_PROXY.md
+++ b/frontend-modern/public/docs/REVERSE_PROXY.md
@@ -8,7 +8,7 @@ Use HTTPS at the public proxy and keep Pulse's backend private. The examples
 below are configuration fragments, not complete TLS or authentication setups.
 Keep Pulse authentication enabled; TLS termination does not authenticate users.
 For identity supplied by an IdP/proxy, follow the separate
-[proxy authentication guide](PROXY_AUTH.md#-header-trust-boundary).
+[proxy authentication guide](PROXY_AUTH.md), including its Header Trust Boundary.
 
 **Forwarded HTTPS headers are trusted only from a configured immediate peer.**
 Set `PULSE_TRUSTED_PROXY_CIDRS` in Pulse's deployment configuration to the proxy
diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
index 2988806241..bfe282cb05 100644
--- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts
+++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts
@@ -143,7 +143,8 @@ describe('docsLinks', () => {
     expect(setup).toContain('::1/128');
     expect(setup).toContain('Wildcard ranges `0.0.0.0/0` and `::/0` are rejected');
     expect(setup).toContain('not an authentication bypass');
-    expect(setup).toContain('PROXY_AUTH.md#-header-trust-boundary');
+    expect(setup).toContain('[proxy authentication guide](PROXY_AUTH.md)');
+    expect(setup).toContain('including its Header Trust Boundary');
     const nginx = proxy.split('### Nginx')[1].split('### Caddy')[0];
     expect(nginx).toContain('HTTPS `server` block');
     expect(nginx).toContain('proxy_set_header X-Forwarded-Proto $scheme;');