fix: update stale docs links in backend and remaining frontend

Repairs 10 broken signoz.io/docs links (5 hard 404s + 5 dead anchors)
that survived the frontend-only sweep in #11319 because they live in
the Go backend and two frontend files it did not cover.

- infra-monitoring readiness checks: drop the removed `user-guides/`
  path segment and remap to the current hostmetrics/k8s-metrics anchors
- querybuilder / telemetrylogs search-troubleshooting errors: point to
  the reworded Q&A anchors (update matching test assertion)
- alert generatorURL fallback: `alerts-management/#generator-url` ->
  `alerts/` (anchor removed in docs restructure)
- missing-spans banner: -> traces-management troubleshooting FAQ anchor
- agent-skills install link: `#installation` -> `#install-the-plugin`

Every changed URL verified live (200 + anchor present).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

frontend/__mocks__/motionMock.tsx

@@ -0,0 +1,88 @@
+// oxlint-disable-next-line no-restricted-imports
+import * as React from 'react';
+
+// In jsdom, AnimatePresence from motion/react keeps children in DOM during exit
+// animations (awaiting rAF-driven completion that never fully runs in jsdom).
+// This mock makes AnimatePresence render children immediately and makes motion.*
+// elements render as their plain HTML equivalents without animation side-effects.
+//
+// IMPORTANT: motion component references are cached so React sees a stable
+// component identity across re-renders and does not enter an infinite remount loop.
+
+const MOTION_PROPS_TO_STRIP = new Set([
+	'initial',
+	'animate',
+	'exit',
+	'variants',
+	'transition',
+	'whileHover',
+	'whileTap',
+	'whileFocus',
+	'whileInView',
+	'layout',
+	'layoutId',
+	'onAnimationStart',
+	'onAnimationComplete',
+]);
+
+const cache = new Map<string, React.ComponentType>();
+
+function getMotionComponent(tag: string): React.ComponentType {
+	if (!cache.has(tag)) {
+		const Component = React.forwardRef<HTMLElement, Record<string, unknown>>(
+			(props, ref) => {
+				const domProps: Record<string, unknown> = {};
+				for (const [k, v] of Object.entries(props)) {
+					if (!MOTION_PROPS_TO_STRIP.has(k)) {
+						domProps[k] = v;
+					}
+				}
+				return React.createElement(tag, { ...domProps, ref });
+			},
+		);
+		Component.displayName = `motion.${tag}`;
+		cache.set(tag, Component as unknown as React.ComponentType);
+	}
+	return cache.get(tag) as React.ComponentType;
+}
+
+const motionHandler: ProxyHandler<Record<string, React.ComponentType>> = {
+	get(_target, prop: string) {
+		return getMotionComponent(prop);
+	},
+};
+
+export const AnimatePresence: React.FC<{
+	children?: React.ReactNode;
+	mode?: string;
+}> = ({ children }) => React.createElement(React.Fragment, null, children);
+
+export const motion = new Proxy(
+	{} as Record<string, React.ComponentType>,
+	motionHandler,
+);
+
+export const useAnimation = (): Record<string, unknown> => ({
+	start: (): unknown => Promise.resolve(),
+	stop: (): unknown => undefined,
+	set: (): unknown => undefined,
+});
+
+export const useMotionValue = (
+	initial: unknown,
+): { get: () => unknown; set: () => void } => ({
+	get: (): unknown => initial,
+	set: (): unknown => undefined,
+});
+
+export const useTransform = (): { get: () => number } => ({
+	get: (): number => 0,
+});
+
+export const useSpring = (v: unknown): unknown => v;
+
+export const useScroll = (): { scrollY: { get: () => number } } => ({
+	scrollY: { get: (): number => 0 },
+});
+
+export default { motion, AnimatePresence };

frontend/jest.config.ts

@@ -20,6 +20,7 @@ const config: Config.InitialOptions = {
 		'\\.module\\.mjs$': '<rootDir>/__mocks__/cssMock.ts',
 		'\\.md$': '<rootDir>/__mocks__/cssMock.ts',
 		'^uplot$': '<rootDir>/__mocks__/uplotMock.ts',
+		'^motion/react$': '<rootDir>/__mocks__/motionMock.tsx',
 		'^@signozhq/resizable$': '<rootDir>/__mocks__/resizableMock.tsx',
 		'^hooks/useSafeNavigate$': USE_SAFE_NAVIGATE_MOCK_PATH,
 		'^src/hooks/useSafeNavigate$': USE_SAFE_NAVIGATE_MOCK_PATH,

frontend/src/components/CreateServiceAccountModal/CreateServiceAccountModal.tsx

@@ -92,6 +92,7 @@ function CreateServiceAccountModal(): JSX.Element {
 			width="narrow"
 			className="create-sa-modal"
 			disableOutsideClick={isErrorModalVisible}
+			testId="create-service-account-modal"
 		>
 			<div className="create-sa-modal__content">
 				<form

frontend/src/components/CreateServiceAccountModal/__tests__/CreateServiceAccountModal.test.tsx

@@ -1,13 +1,7 @@
 import { toast } from '@signozhq/ui/sonner';
 import { rest, server } from 'mocks-server/server';
 import { NuqsTestingAdapter } from 'nuqs/adapters/testing';
-import {
-	render,
-	screen,
-	userEvent,
-	waitFor,
-	waitForElementToBeRemoved,
-} from 'tests/test-utils';
+import { render, screen, userEvent, waitFor } from 'tests/test-utils';
 
 import CreateServiceAccountModal from '../CreateServiceAccountModal';
 
@@ -89,7 +83,7 @@ describe('CreateServiceAccountModal', () => {
 
 		await waitFor(() => {
 			expect(
-				screen.queryByRole('dialog', { name: /New Service Account/i }),
+				screen.queryByTestId('create-service-account-modal'),
 			).not.toBeInTheDocument();
 		});
 	});
@@ -129,7 +123,7 @@ describe('CreateServiceAccountModal', () => {
 		});
 
 		expect(
-			screen.getByRole('dialog', { name: /New Service Account/i }),
+			screen.getByTestId('create-service-account-modal'),
 		).toBeInTheDocument();
 	});
 
@@ -137,15 +131,14 @@ describe('CreateServiceAccountModal', () => {
 		const user = userEvent.setup({ pointerEventsCheck: 0 });
 		renderModal();
 
-		const dialog = await screen.findByRole('dialog', {
-			name: /New Service Account/i,
-		});
+		await screen.findByTestId('create-service-account-modal');
 		await user.click(screen.getByRole('button', { name: /Cancel/i }));
 
-		await waitForElementToBeRemoved(dialog);
-		expect(
-			screen.queryByRole('dialog', { name: /New Service Account/i }),
-		).not.toBeInTheDocument();
+		await waitFor(() => {
+			expect(
+				screen.queryByTestId('create-service-account-modal'),
+			).not.toBeInTheDocument();
+		});
 	});
 
 	it('shows "Name is required" after clearing the name field', async () => {

frontend/src/components/ServiceAccountDrawer/AddKeyModal/index.tsx

@@ -151,6 +151,7 @@ function AddKeyModal(): JSX.Element {
 			className="add-key-modal"
 			showCloseButton
 			disableOutsideClick={isErrorModalVisible}
+			testId="add-key-modal"
 		>
 			{phase === Phase.FORM && (
 				<KeyFormPhase

frontend/src/components/ServiceAccountDrawer/DeleteAccountModal.tsx

@@ -91,6 +91,7 @@ function DeleteAccountModal(): JSX.Element {
 				color="destructive"
 				loading={isDeleting}
 				onClick={handleConfirm}
+				data-testid="confirm-delete-btn"
 			>
 				<Trash2 size={12} />
 				Delete
@@ -111,6 +112,7 @@ function DeleteAccountModal(): JSX.Element {
 			className="alert-dialog sa-delete-dialog"
 			showCloseButton={false}
 			disableOutsideClick={isErrorModalVisible}
+			testId="delete-service-account-modal"
 			footer={footer}
 		>
 			{content}

frontend/src/components/ServiceAccountDrawer/EditKeyModal/index.tsx

@@ -175,6 +175,7 @@ function EditKeyModal({ keyItem }: EditKeyModalProps): JSX.Element {
 			}
 			showCloseButton={!isRevokeConfirmOpen}
 			disableOutsideClick={isErrorModalVisible}
+			testId="edit-key-modal"
 			footer={
 				isRevokeConfirmOpen ? (
 					<RevokeKeyFooter

frontend/src/components/ServiceAccountDrawer/__tests__/AddKeyModal.test.tsx

@@ -2,13 +2,7 @@ import { toast } from '@signozhq/ui/sonner';
 import { setupAuthzAdmin } from 'lib/authz/utils/authz-test-utils';
 import { rest, server } from 'mocks-server/server';
 import { NuqsTestingAdapter } from 'nuqs/adapters/testing';
-import {
-	render,
-	screen,
-	userEvent,
-	waitFor,
-	waitForElementToBeRemoved,
-} from 'tests/test-utils';
+import { render, screen, userEvent, waitFor } from 'tests/test-utils';
 
 import AddKeyModal from '../AddKeyModal';
 
@@ -97,7 +91,7 @@ describe('AddKeyModal', () => {
 
 		await screen.findByText('snz_abc123xyz456secret');
 		expect(screen.getByText(/Store the key securely/i)).toBeInTheDocument();
-		await screen.findByRole('dialog', { name: /Key Created Successfully/i });
+		expect(screen.getByTestId('add-key-modal')).toBeInTheDocument();
 	});
 
 	it('copy button writes key to clipboard and shows toast.success', async () => {
@@ -133,9 +127,11 @@ describe('AddKeyModal', () => {
 		const user = userEvent.setup({ pointerEventsCheck: 0 });
 		renderModal();
 
-		const dialog = await screen.findByRole('dialog', { name: /Add a New Key/i });
+		await screen.findByTestId('add-key-modal');
 		await user.click(screen.getByRole('button', { name: /Cancel/i }));
 
-		await waitForElementToBeRemoved(dialog);
+		await waitFor(() => {
+			expect(screen.queryByTestId('add-key-modal')).not.toBeInTheDocument();
+		});
 	});
 });

frontend/src/components/ServiceAccountDrawer/__tests__/EditKeyModal.test.tsx

@@ -73,9 +73,7 @@ describe('EditKeyModal (URL-controlled)', () => {
 	it('renders nothing when edit-key param is absent', () => {
 		renderModal(null, { account: 'sa-1' });
 
-		expect(
-			screen.queryByRole('dialog', { name: /Edit Key Details/i }),
-		).not.toBeInTheDocument();
+		expect(screen.queryByTestId('edit-key-modal')).not.toBeInTheDocument();
 	});
 
 	it('renders key data from prop when edit-key param is set', async () => {
@@ -102,9 +100,7 @@ describe('EditKeyModal (URL-controlled)', () => {
 		});
 
 		await waitFor(() => {
-			expect(
-				screen.queryByRole('dialog', { name: /Edit Key Details/i }),
-			).not.toBeInTheDocument();
+			expect(screen.queryByTestId('edit-key-modal')).not.toBeInTheDocument();
 		});
 	});
 
@@ -131,9 +127,7 @@ describe('EditKeyModal (URL-controlled)', () => {
 		expect(latestUrlUpdate.queryString).not.toContain('edit-key=');
 
 		await waitFor(() => {
-			expect(
-				screen.queryByRole('dialog', { name: /Edit Key Details/i }),
-			).not.toBeInTheDocument();
+			expect(screen.queryByTestId('edit-key-modal')).not.toBeInTheDocument();
 		});
 	});
 
@@ -145,9 +139,7 @@ describe('EditKeyModal (URL-controlled)', () => {
 		await user.click(screen.getByRole('button', { name: /Revoke Key/i }));
 
 		// Same dialog, now showing revoke confirmation
-		await expect(
-			screen.findByRole('dialog', { name: /Revoke Original Key Name/i }),
-		).resolves.toBeInTheDocument();
+		expect(screen.getByTestId('edit-key-modal')).toBeInTheDocument();
 		expect(
 			screen.getByText(/Revoking this key will permanently invalidate it/i),
 		).toBeInTheDocument();
@@ -170,9 +162,7 @@ describe('EditKeyModal (URL-controlled)', () => {
 		});
 
 		await waitFor(() => {
-			expect(
-				screen.queryByRole('dialog', { name: /Edit Key Details/i }),
-			).not.toBeInTheDocument();
+			expect(screen.queryByTestId('edit-key-modal')).not.toBeInTheDocument();
 		});
 	});
 });

frontend/src/components/ServiceAccountDrawer/__tests__/ServiceAccountDrawer.test.tsx

@@ -222,21 +222,20 @@ describe('ServiceAccountDrawer', () => {
 			screen.getByRole('button', { name: /Delete Service Account/i }),
 		);
 
-		const dialog = await screen.findByRole('dialog', {
-			name: /Delete service account CI Bot/i,
-		});
-		expect(dialog).toBeInTheDocument();
+		await screen.findByTestId('delete-service-account-modal');
+		expect(
+			screen.getByTestId('delete-service-account-modal'),
+		).toBeInTheDocument();
 
-		const confirmBtns = screen.getAllByRole('button', { name: /^Delete$/i });
-		await user.click(confirmBtns[confirmBtns.length - 1]);
+		await user.click(screen.getByTestId('confirm-delete-btn'));
 
-		await waitFor(() => {
-			expect(deleteSpy).toHaveBeenCalled();
-		});
-
-		await waitFor(() => {
-			expect(screen.queryByDisplayValue('CI Bot')).not.toBeInTheDocument();
-		});
+		await waitFor(
+			() => {
+				expect(deleteSpy).toHaveBeenCalled();
+				expect(screen.queryByDisplayValue('CI Bot')).not.toBeInTheDocument();
+			},
+			{ timeout: 3000 },
+		);
 	});
 
 	it('deleted account shows read-only name, no Save button, no Delete button', async () => {

frontend/src/container/ServiceAccountsSettings/__tests__/ServiceAccountsSettings.authz.integration.test.tsx

@@ -208,7 +208,7 @@ describe('ServiceAccountsSettings (integration)', () => {
 
 		fireEvent.click(screen.getByRole('button', { name: /New Service Account/i }));
 
-		await screen.findByRole('dialog', { name: /New Service Account/i });
+		await screen.findByTestId('create-service-account-modal');
 		expect(screen.getByPlaceholderText('Enter a name')).toBeInTheDocument();
 	});
 

frontend/src/pages/TraceDetailsV3/TraceDetailsHeader/MissingSpansBanner.tsx

@@ -5,7 +5,7 @@ import { ArrowUpRight } from '@signozhq/icons';
 import styles from './MissingSpansBanner.module.scss';
 
 const MISSING_SPANS_DOCS_URL =
-	'https://signoz.io/docs/userguide/traces/#missing-spans';
+	'https://signoz.io/docs/traces-management/troubleshooting/faqs/#q-why-are-some-spans-missing-from-a-trace';
 
 function MissingSpansBanner(): JSX.Element | null {
 	// Session-only dismissal — not persisted, so the banner returns on reload.

frontend/src/utils/docLinks.ts

@@ -14,7 +14,8 @@ const DOCLINKS = {
 		'https://signoz.io/docs/userguide/logs_clickhouse_queries/',
 	QUERY_CLICKHOUSE_METRICS:
 		'https://signoz.io/docs/userguide/write-a-metrics-clickhouse-query/',
-	AGENT_SKILL_INSTALL: 'https://signoz.io/docs/ai/agent-skills/#installation',
+	AGENT_SKILL_INSTALL:
+		'https://signoz.io/docs/ai/agent-skills/#install-the-plugin',
 };
 
 export default DOCLINKS;

pkg/modules/inframonitoring/implinframonitoring/checks_constants.go

@@ -16,11 +16,11 @@ const (
 
 // Documentation links — one per component. User-facing; emitted on missing-entries.
 const (
-	docLinkHostMetricsReceiver        = "https://signoz.io/docs/infrastructure-monitoring/user-guides/hostmetrics/#configure-the-hostmetrics-receiver"
-	docLinkKubeletStatsReceiver       = "https://signoz.io/docs/infrastructure-monitoring/user-guides/k8s-metrics/#setup-kubelet-stats-receiver"
-	docLinkK8sClusterReceiver         = "https://signoz.io/docs/infrastructure-monitoring/user-guides/k8s-metrics/#setup-k8s-cluster-receiver"
-	docLinkResourceDetectionProcessor = "https://signoz.io/docs/infrastructure-monitoring/user-guides/hostmetrics/#configure-the-resourcedetection-processor"
-	docLinkK8sAttributesProcessor     = "https://signoz.io/docs/infrastructure-monitoring/user-guides/k8s-metrics/#3-setup-k8sattributesprocessor-to-enable-kubernetes-metadata"
+	docLinkHostMetricsReceiver        = "https://signoz.io/docs/infrastructure-monitoring/hostmetrics/#configure-the-hostmetrics-receiver"
+	docLinkKubeletStatsReceiver       = "https://signoz.io/docs/infrastructure-monitoring/k8s-metrics/#2-configure-the-kubelet-stats-receiver"
+	docLinkK8sClusterReceiver         = "https://signoz.io/docs/infrastructure-monitoring/k8s-metrics/#1-configure-the-k8s-cluster-receiver"
+	docLinkResourceDetectionProcessor = "https://signoz.io/docs/infrastructure-monitoring/hostmetrics/#configure-the-processors"
+	docLinkK8sAttributesProcessor     = "https://signoz.io/docs/infrastructure-monitoring/k8s-metrics/#3-enable-kubernetes-metadata"
 )
 
 var (

pkg/query-service/constants/constants.go

@@ -124,7 +124,7 @@ const (
 // alert related constants
 const (
 	// AlertHelpPage is used in case default alert repo url is not set
-	AlertHelpPage   = "https://signoz.io/docs/userguide/alerts-management/#generator-url"
+	AlertHelpPage   = "https://signoz.io/docs/alerts/"
 	AlertTimeFormat = "2006-01-02 15:04:05"
 )
 

pkg/querybuilder/key_resolution.go

@@ -13,10 +13,10 @@ const (
 	// to multiple field context / data type combinations.
 	FieldContextDataTypesDocURL = "https://signoz.io/docs/userguide/field-context-data-types/"
 	// KeyNotFoundDocURL documents the "key not found" error.
-	KeyNotFoundDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#key-fieldname-not-found"
+	KeyNotFoundDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#q-im-getting-key-fieldname-not-found--why-cant-it-find-my-field"
 
 	// Doc URLs for the has/hasAny/hasAll and hasToken "unsupported" errors.
-	functionBodyJSONSearchDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#function-supports-only-body-json-search"
+	functionBodyJSONSearchDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#q-im-getting-function-supports-only-body-json-search--can-i-use-functions-on-other-fields"
 	hasTokenFunctionDocURL       = "https://signoz.io/docs/userguide/functions-reference/#hastoken-function"
 )
 

pkg/querybuilder/where_clause_visitor_test.go

@@ -169,7 +169,7 @@ func TestVisitKey(t *testing.T) {
 			},
 			expectedKeys:       []telemetrytypes.TelemetryFieldKey{},
 			expectedErrors:     []string{"key `unknown_key` not found"},
-			expectedMainErrURL: "https://signoz.io/docs/userguide/search-troubleshooting/#key-fieldname-not-found",
+			expectedMainErrURL: "https://signoz.io/docs/userguide/search-troubleshooting/#q-im-getting-key-fieldname-not-found--why-cant-it-find-my-field",
 			expectedWarnings:   nil,
 			expectedMainWrnURL: "",
 		},
@@ -351,7 +351,7 @@ func TestVisitKey(t *testing.T) {
 			ignoreNotFoundKeys: false,
 			expectedKeys:       []telemetrytypes.TelemetryFieldKey{},
 			expectedErrors:     []string{"key `unknown_key` not found"},
-			expectedMainErrURL: "https://signoz.io/docs/userguide/search-troubleshooting/#key-fieldname-not-found",
+			expectedMainErrURL: "https://signoz.io/docs/userguide/search-troubleshooting/#q-im-getting-key-fieldname-not-found--why-cant-it-find-my-field",
 			expectedWarnings:   nil,
 			expectedMainWrnURL: "",
 		},

pkg/telemetrylogs/const.go

@@ -53,7 +53,7 @@ const (
 	// Documentation URLs attached to function-call errors so the visitor can
 	// surface them to the user without knowing function-specific details.
 	hasTokenFunctionDocURL       = "https://signoz.io/docs/userguide/functions-reference/#hastoken-function"
-	functionBodyJSONSearchDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#function-supports-only-body-json-search"
+	functionBodyJSONSearchDocURL = "https://signoz.io/docs/userguide/search-troubleshooting/#q-im-getting-function-supports-only-body-json-search--can-i-use-functions-on-other-fields"
 )
 
 var (