fix(agents): validate image-map navigation targets

docs/development/agent-workflow.md

@@ -54,7 +54,7 @@ Heading anchors decode HTML character references in text and use `github-slugger
 for GitHub-compatible character filtering and duplicate suffixes.
 Only headings present outside inert HTML containers contribute slugs or duplicate counters.
 Explicit HTML anchors use `parse5`, excluding comments, scripts, styles and template contents.
-Rendered HTML anchor hrefs and image sources use the same local-reference checks
+Rendered HTML anchor and image-map area hrefs and image sources use the same local-reference checks
 as Markdown links, including decoded attributes and fragment validation.
 Image references check file existence without interpreting image fragments as
 Markdown headings; document links keep anchor checks even when sharing a target.

tools/skills/agent-guidance-markdown.mjs

@@ -69,7 +69,8 @@ function htmlNavigation(html, inspect = () => {}) {
             )
                 anchors.push(attribute.value);
             if (
-                (node.tagName === 'a' && attribute.name === 'href') ||
+                (['a', 'area'].includes(node.tagName) &&
+                    attribute.name === 'href') ||
                 (['img', 'video', 'audio', 'source', 'track'].includes(
                     node.tagName
                 ) &&
@@ -78,7 +79,7 @@ function htmlNavigation(html, inspect = () => {}) {
             )
                 references.push({
                     target: attribute.value,
-                    image: node.tagName !== 'a',
+                    image: !['a', 'area'].includes(node.tagName),
                 });
             if (
                 ['img', 'source'].includes(node.tagName) &&

tools/skills/validate-agent-guidance.test.mjs

@@ -1060,3 +1060,24 @@ for (const filename of [
         assert.ok((await diagnostics(t, { 'AGENTS.md': guidance })).length > 0);
     });
 }
+
+for (const target of ['docs/missing.md', 'docs/example.md#missing']) {
+    test(`image-map navigation is validated: ${target}`, async (t) => {
+        assert.ok(
+            (
+                await diagnostics(t, {
+                    'AGENTS.md': `<map><area href="${target}"></map>`,
+                })
+            ).length > 0
+        );
+    });
+}
+test('valid image-map navigation and inert areas pass', async (t) => {
+    assert.deepEqual(
+        await diagnostics(t, {
+            'AGENTS.md':
+                '<map><area href="docs/example.md#repeat"></map>\n<template><map><area href="missing.md"></map></template>',
+        }),
+        []
+    );
+});