[Email Service] Document account-wide suppressions

.agents/references/style-guide.md

@@ -398,6 +398,7 @@ Guidelines:
 - Avoid including the sidebar navigation (it changes frequently).
 - Always provide descriptive alt text.
 - Use Markdown image syntax for content images. Do not use raw `<img>` tags for screenshots or diagrams.
+- Use inline image syntax only (`![alt](~/assets/images/{product}/file.png)`). Do not use reference-style image links (`![alt][1]` with a `[1]: ~/assets/images/...` definition): Astro's asset pipeline does not resolve the `~/` alias in reference-style definitions, so the image renders as a broken relative URL.
 - Store images in `src/assets/images/{product}/` and reference them with `~/assets/images/{product}/...`. This enables Astro's asset pipeline (optimization, responsive variants, cache-busting). Only use `public/` for assets that need a stable static URL (e.g. OG images, badges, files referenced from non-Astro contexts). Do not use `public/images/` for docs screenshots or diagrams.
 
 ```mdx

.flue/.agents/skills/style-guide-review/reference/conditional/images.md

@@ -11,6 +11,8 @@ description: Rules for image syntax and asset paths in MDX content.
 
 - If a Markdown image uses empty alt text `![](...)` for a non-decorative content image → **suggestion**: add descriptive alt text per the style guide.
 
+- If an added line uses a reference-style image link (`![Alt text][n]` that points to a `[n]: ~/assets/images/...` definition line) → **warning**: convert to inline image syntax `![Alt text](~/assets/images/{product}/file.png)`. Astro's asset pipeline resolves the `~/assets/images/` alias only for inline image syntax; reference-style definitions render as broken page-relative URLs. Exception: reference-style image links inside fenced code blocks or application code examples.
+
 ## Examples
 
 Correct:
@@ -28,3 +30,8 @@ Incorrect:
 ```mdx
 ![Precursor mode selector](/images/precursor/precursor-rules.png)
 ```
+
+```mdx
+![Precursor mode selector][1]
+[1]: ~/assets/images/precursor/precursor-rules.png
+```

.flue/evals/mocks/github-repo-tools.ts

@@ -82,6 +82,19 @@ const FIXTURES: Record<string, Record<string, string>> = {
 		].join("\n"),
 	},
 
+	// Style-guide eval: reference-style image link (unresolved ~/ alias).
+	"eval-style-ref-img": {
+		"src/content/docs/cloudflare-challenges/precursor.mdx": [
+			"---",
+			"title: Precursor",
+			"---",
+			"",
+			"![Precursor mode selector][1]",
+			"",
+			"[1]: ~/assets/images/cloudflare-challenges/precursor-rules.png",
+		].join("\n"),
+	},
+
 	// Review-validator eval: file with an unhandled promise rejection.
 	"eval-val-unhandled-promise": {
 		"src/handler.ts": [

.flue/evals/style-guide.eval.ts

@@ -39,6 +39,7 @@ const RAW_IMG_SHA = "eval-style-raw-img";
 const IMAGES_PATH_SHA = "eval-style-images-path";
 const CORRECT_IMG_SHA = "eval-style-correct-img";
 const FENCED_IMG_SHA = "eval-style-fenced-img";
+const REF_IMG_SHA = "eval-style-ref-img";
 
 describeEval("style-guide reviewer", { harness }, (it) => {
 	it("flags a full URL for an internal link", async ({ run }) => {
@@ -260,6 +261,89 @@ describeEval("style-guide reviewer", { harness }, (it) => {
 		);
 	});
 
+	it("flags a reference-style image link with an unresolved ~/ alias", async ({
+		run,
+	}) => {
+		const result = await run({
+			pullRequest: PR,
+			headSha: REF_IMG_SHA,
+			filename: "src/content/docs/cloudflare-challenges/precursor.mdx",
+			addedLines: [
+				{
+					line: 8,
+					content: "![Precursor mode selector][1]",
+				},
+				{
+					line: 10,
+					content:
+						"[1]: ~/assets/images/cloudflare-challenges/precursor-rules.png",
+				},
+			],
+		});
+
+		const findings = (result.output as { findings?: Finding[] })?.findings;
+		expect(findings).toBeDefined();
+
+		const refFinding = (findings ?? []).filter(
+			(f) =>
+				f.rule?.toLowerCase().includes("image") ||
+				f.rule?.toLowerCase().includes("reference") ||
+				f.rule?.toLowerCase().includes("inline") ||
+				f.evidence?.includes("[1]"),
+		);
+		expect(refFinding.length).toBeGreaterThan(0);
+		expect(refFinding[0].severity).toBe("warning");
+
+		expect(toolCalls(result).map((c) => c.name)).toContain(
+			"submit_style_guide",
+		);
+	});
+
+	it("does not flag a reference-style image link inside a fenced code block", async ({
+		run,
+	}) => {
+		const result = await run({
+			pullRequest: PR,
+			headSha: HEAD_SHA,
+			filename: "src/content/docs/workers/example.mdx",
+			addedLines: [
+				{
+					line: 7,
+					content: "```mdx",
+				},
+				{
+					line: 8,
+					content: "![Example][1]",
+				},
+				{
+					line: 9,
+					content: "[1]: ~/assets/images/example/example.png",
+				},
+				{
+					line: 10,
+					content: "```",
+				},
+			],
+		});
+
+		const findings = (result.output as { findings?: Finding[] })?.findings;
+		expect(findings).toBeDefined();
+
+		const imgFindings = (findings ?? []).filter(
+			(f) =>
+				f.severity === "warning" &&
+				(f.rule?.toLowerCase().includes("img") ||
+					f.rule?.toLowerCase().includes("image") ||
+					f.rule?.toLowerCase().includes("reference") ||
+					f.evidence?.includes("[1]")),
+		);
+		expect(imgFindings).toHaveLength(0);
+
+		expect(toolCalls(result).map((c) => c.name)).toContain(
+			"submit_style_guide",
+		);
+	});
+
 	it("passes on correct Markdown image syntax with ~/assets/images/", async ({
 		run,
 	}) => {