diff --git a/CHANGELOG.md b/CHANGELOG.md
index fbd55bab..7b8c3753 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Cowork driver spike.** Added [`docs/contributing/cowork-driver-spike.md`](docs/contributing/cowork-driver-spike.md) — a time-boxed investigation (per §4a of the harness v2 design) of whether `claude-cowork` can be driven programmatically by the empirical compat harness today. Verdict: **not feasible**; cowork is a Claude Desktop app product with no public API/CLI surface. The `claude-cowork` runtime stays on `scripted-assisted` until Anthropic ships a Cowork CLI mode, Sessions API, or documented filesystem-import path. Adjacent finding (not a cowork replacement): the public-beta Skills API (`POST /v1/skills` + `container.skills[]` on `/v1/messages`) supports a fully-automatable *new* runtime — captured in the spike doc as a potential follow-up, gated on a separate design decision.
 - **Subscription-only compat harness billing.** The harness now bills a Claude Pro/Max subscription instead of the API: both token-consuming surfaces (the `claude-code` runtime driver and the LLM judge) route through one shared `claude` CLI invoker (`runtimes/shared/claude-cli.ts`) that injects the operator's `CLAUDE_CODE_OAUTH_TOKEN` and deletes every API credential from the child env, so the CLI cannot fall back to API billing. The operator's own token is sourced at preflight — env var if set, otherwise an interactive prompt — so a run only ever spends the operator's personal plan. The judge was migrated off `@anthropic-ai/sdk` (dependency removed) onto the CLI, parsing a strict JSON verdict with one retry instead of the SDK's forced-tool call (`judge-system.md` now asks for a JSON object). `RunMetadata` gains `authMode` and the report methodology discloses subscription auth + parsed-not-forced verdicts. Premise (zero API billing under the OAuth token) still pending the manual smoke test.
 
+### Added
+
+- **First-class local HTML resources (#112).** `.html`/`.htm` files are now discovered, parsed, link- and anchor-validated, checked for well-formedness, and link-rewritten on bundle — using the same `ParseResult` contract and validation framework as markdown. A parse5-backed parser extracts `<a href>` and `<img src>` links plus `id`/`name` fragment anchors; `ResourceRegistry` routes HTML through it and persists optional `anchors`/`parseErrors` on `ResourceMetadata`. Anchor validation now uses a format-neutral fragment index (each file's markdown heading slugs or HTML `id`/`name`, with its case-matching policy carried per entry), enabling cross-format anchor checks (md↔html) with HTML ids matched case-sensitively and markdown slugs case-insensitively. A new `MALFORMED_HTML` code (default `info`) surfaces parser well-formedness diagnostics. On bundle, `<a href>`/`<img src>` values are rewritten by offset-splicing the original source (never re-serialized), so unchanged markup round-trips byte-for-byte and original attribute quoting is preserved (a rewritten value that would be unsafe unquoted is wrapped in quotes). Scope is `<a href>` + `<img src>` only; `<link>`/`<script>`/`<iframe>`/`<source srcset>`/CSS `url(...)` are deferred (asset/machinery references, not the content link graph). `<base href>` is not honored — relative hrefs resolve against the file's own directory (see the breaking note below for the `ResourceMetadataSchema` tightening that shipped with this work).
+- **`DUPLICATE_RESOURCE_ID` validation code (default `error`).** When two files resolve to the same resource id after path normalization (e.g. `My Guide.md` and `my-guide.md` both → `my-guide-md`), `vat resources validate` now reports it as an `error` issue naming both files, instead of aborting the entire run with an uncaught `Duplicate resource ID` exception. Documented under [Resource Registry Codes](./docs/validation-codes.md).
+
 ### Changed (breaking, pre-1.0)
 
+- **`ResourceMetadataSchema` is now `strict()`.** Shipped with first-class HTML support (#112): the resource-metadata schema rejects unknown top-level fields instead of silently accepting them, so a typo or stale field in code that constructs `ResourceMetadata` now fails at parse time rather than passing through. Move any extra data into a recognized field or drop it.
+- **Resource ids now carry a file-extension suffix.** `generateIdFromPath` appends `-<ext>` to every resource id (e.g. `guide.md` → `guide-md`, `guide.html` → `guide-html`, `README.md` → `readme-md`). This makes a markdown file and a same-stem HTML file distinct resources instead of colliding — the prerequisite for first-class HTML resources sharing a directory with their markdown source. Resource ids are internal, path-derived identifiers (never hand-authored in config or frontmatter), but anything that referenced an id by its old bare form must use the suffixed form — most visibly `vat rag query --resource-id` filters and re-indexed chunk ids (re-index to regenerate).
 - **`vat resources validate` gains per-code severity configuration, and external-URL findings no longer fail the build by default.** Resource findings now use the same configurable severity framework as `vat skills`: each is a documented code (e.g. `LINK_BROKEN_FILE`, `EXTERNAL_URL_DEAD`) with a default severity, overridable per project under `resources.validation.severity` / `resources.validation.allow`. External-URL findings now default to `warning` and no longer flip the exit code (fixing a bug where they always failed the command); set their severity to `error` to restore failing. Severity now also accepts an `info` level. The never-implemented `resources.validation.checkLinks`/`checkAnchors`/`allowExternal` keys are removed.
 - **`validation.severity` / `validation.allow` keys are validated against real codes.** A mistyped code key (e.g. `LNIK_OUTSIDE_PROJECT`) is now a config-load error instead of a silent no-op.
 - **Corpus seed entries now require `bucket`, `confidence`, and `maturity` metadata fields.** `PluginEntrySchema` in `vat corpus scan`'s seed loader gains three required enum fields: `bucket: 'official' | 'community'`, `confidence: 'first-party' | 'curated' | 'listed'`, and `maturity: 'production' | 'experimental' | 'example'`. The bundled `corpus/seed.yaml` is updated; downstream callers running custom seeds must add the fields to every entry. `bucket` is the load-bearing discriminator (`official` entries report named findings; `community` entries are aggregate-only in follow-up work). The other two are descriptive metadata used by triage tooling.
@@ -27,6 +34,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **Transformers.js integration tests now skip on Windows CI instead of flaking.** `transformers-embedding-provider.integration.test.ts` and the Transformers.js block of `comparison.integration.test.ts` skip on Windows (in addition to skipping when the optional `@xenova/transformers` dependency is absent), matching the existing `onnx-embedding-provider` test. These tests download a model over the network and load the `onnxruntime-node` native backend — both flaky in Windows CI. Such a failure was previously mislabeled `@xenova/transformers is not installed` by an over-broad `catch` in the provider's `loadPipeline` (the package was installed; the model download/inference is what failed), which is also why an availability-only guard did not prevent it.
 - **Config-first skill discovery now honors `..` in `skills.include` patterns.** `vat build`, `vat verify`, and `vat skills validate` all funnel through `discoverSkillsFromConfig`, which previously passed every include pattern to a single downward-only crawl rooted at `projectRoot` — so an include like `"../../docs/skills/*/SKILL.md"` (common in monorepos where SKILL.md sources live alongside, not inside, the package) silently matched zero skills. `vat audit` accepted the same config only because it has a separate filesystem-first walker. Each include pattern is now split into a literal base + glob remainder via `picomatch.scan`, patterns are grouped by their resolved absolute base, and the crawler runs once per base — making config-first discovery agree with audit. User-supplied excludes stay anchored to `projectRoot` so patterns like `docs/private/**` keep their original meaning, and a pattern resolving to a nonexistent base now silently produces zero matches.
+- **Anchor validation no longer reports a false `LINK_BROKEN_ANCHOR` for un-indexed target files (#112).** Previously a fragment link to any file the resource registry had not parsed (e.g. a target outside the crawl) was reported as a broken anchor. Anchor checks now skip targets absent from the fragment index — affecting markdown and HTML alike — while genuinely missing fragments in indexed files are still reported.
+- **`vat resources validate` no longer crashes on same-stem `.md` + `.html` sibling files (#116).** Making HTML first-class added `.html`/`.htm` to the crawl, and same-stem siblings (e.g. `index.md` + `index.html`) previously produced an uncaught `Duplicate resource ID` exception that aborted the whole command. Fixed by the extension-suffixed ids above (siblings now get distinct ids), with `DUPLICATE_RESOURCE_ID` as a graceful backstop for any genuine post-normalization collision.
+- **Post-build link checks now cover bundled HTML (#116).** `checkBrokenPackagedLinks` and the unreferenced-file check previously scanned only `.md`, so a broken `<a href>`/`<img src>` inside a packaged `.html`/`.htm` file shipped with a green build. Both checks — and the reachability traversal — now extract HTML links via the same parser, so broken links in packaged HTML surface as `PACKAGED_BROKEN_LINK` (failing the build) and an HTML file referenced only by other HTML is no longer falsely flagged `PACKAGED_UNREFERENCED_FILE`.
 
 ## [0.1.38] - 2026-05-18
 
diff --git a/bun.lock b/bun.lock
index 88b3b884..5822e575 100644
--- a/bun.lock
+++ b/bun.lock
@@ -285,6 +285,7 @@
         "ajv-formats": "^3.0.1",
         "github-slugger": "^2.0.0",
         "markdown-link-check": "^3.14.2",
+        "parse5": "^7.2.1",
         "picomatch": "^4.0.3",
         "remark-frontmatter": "^5.0.0",
         "remark-gfm": "^4.0.0",
@@ -1308,7 +1309,7 @@
 
     "enhanced-resolve": ["enhanced-resolve@5.19.0", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.0" } }, "sha512-phv3E1Xl4tQOShqSte26C7Fl84EwUdZsyOuSSk9qtAGyyQs2s3jJzComh+Abf4g187lUUAvH+H26omrqia2aGg=="],
 
-    "entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
 
     "environment": ["environment@1.1.0", "", {}, "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q=="],
 
@@ -2582,6 +2583,8 @@
 
     "cross-spawn/which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
 
+    "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+
     "encoding-sniffer/iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
 
     "eslint/ajv": ["ajv@6.12.6", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g=="],
@@ -2662,8 +2665,6 @@
 
     "p-retry/retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
 
-    "parse5/entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
-
     "path-scurry/minipass": ["minipass@7.1.2", "", {}, "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw=="],
 
     "proxy-agent/lru-cache": ["lru-cache@7.18.3", "", {}, "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA=="],
diff --git a/docs/validation-codes.md b/docs/validation-codes.md
index 6b264ab7..15b84806 100644
--- a/docs/validation-codes.md
+++ b/docs/validation-codes.md
@@ -124,6 +124,17 @@ Static-analysis codes that fire anywhere markdown is analyzed — `vat resources
 - **Why it matters:** A committed document declaring a dependency on a gitignored target breaks portability — anyone cloning the repo gets the document but not the target. It also risks treating local-only or generated content as if it were part of the published artifact. Distinct from the skills-packaging code [`LINK_TO_GITIGNORED_FILE`](#link_to_gitignored_file), which guards against leaking ignored data into a *bundle*; this code fires in the `vat resources validate` path and the two coexist intentionally.
 - **Fix:** Link a tracked target, or un-ignore the file in `.gitignore` if it should be committed.
 
+## HTML Well-Formedness Codes
+
+Unlike the link codes above, this code is HTML-specific and is **not** a link code. It fires only in the `vat resources validate` path — emitted by `ResourceRegistry` while parsing `.html`/`.htm` resources — and does not run under `vat skills validate`, `vat skills build`, or `vat audit`.
+
+### `MALFORMED_HTML`
+
+- **Default:** `info`
+- **What:** An HTML resource has well-formedness problems (unclosed tags, stray characters, misnested elements) reported by the HTML parser.
+- **Why it matters:** Malformed markup parses unpredictably across browsers and tools, and can hide or mangle the links VAT extracts. Surfaced as `info` because browsers are lenient and most pages still render.
+- **Fix:** Fix the markup the parser flags. Raise severity via `validation.severity.MALFORMED_HTML` to enforce well-formedness.
+
 ## Frontmatter Link Codes
 
 Validation codes that fire when a collection's frontmatter schema declares a URI-family `format` (`uri-reference`, `uri`, `iri-reference`, `iri`) on a field and `vat resources validate` walks those values through the same engine as markdown link checking. Disabled per-collection via `validation.checkFrontmatterLinks: false` or globally via `vat resources validate --no-check-frontmatter-links`. See [Frontmatter link validation](./guides/collection-validation.md#frontmatter-link-validation).
@@ -229,6 +240,17 @@ Only meaningful when actually bundling a skill; fire from `vat skills build` (an
 - **Why it matters:** This code indicates VAT's own link rewriter produced an inconsistent bundle — a file was expected but wasn't written to the output. Unlike `LINK_MISSING_TARGET`, which flags source issues, this flags a post-build integrity failure.
 - **Fix:** Report the issue — this indicates a VAT bug. As a temporary workaround, set `severity.PACKAGED_BROKEN_LINK` to `ignore` while the underlying bug is fixed.
 
+## Resource Registry Codes
+
+*Fire when building the resource registry — `vat resources validate` and any command that crawls resources.*
+
+### `DUPLICATE_RESOURCE_ID`
+
+- **Default:** `error`
+- **What:** Two files resolve to the same resource id after path normalization (e.g. `My Guide.md` and `my-guide.md` both produce `my-guide-md`).
+- **Why it matters:** Resource ids must be unique — a collision means one file silently shadows the other in lookups, link resolution, and bundling. This surfaces as a reported issue rather than aborting the whole run with an uncaught error.
+- **Fix:** Rename one of the files so they produce distinct resource ids.
+
 ## Quality Codes
 
 *Stance: see [Length and Shape](./skill-quality-and-compatibility.md#length-and-shape) and [Authoring](./skill-quality-and-compatibility.md#authoring).*
diff --git a/packages/agent-schema/schemas/validation-config.json b/packages/agent-schema/schemas/validation-config.json
index 640a24d7..54653b98 100644
--- a/packages/agent-schema/schemas/validation-config.json
+++ b/packages/agent-schema/schemas/validation-config.json
@@ -26,6 +26,7 @@
               "LINK_DROPPED_BY_DEPTH",
               "PACKAGED_UNREFERENCED_FILE",
               "PACKAGED_BROKEN_LINK",
+              "DUPLICATE_RESOURCE_ID",
               "SKILL_LENGTH_EXCEEDS_RECOMMENDED",
               "SKILL_TOTAL_SIZE_LARGE",
               "SKILL_TOO_MANY_FILES",
@@ -65,6 +66,7 @@
               "LINK_BROKEN_ANCHOR",
               "LINK_UNKNOWN",
               "LINK_TO_GITIGNORED",
+              "MALFORMED_HTML",
               "FRONTMATTER_MISSING",
               "FRONTMATTER_INVALID_YAML",
               "FRONTMATTER_SCHEMA_ERROR",
@@ -121,6 +123,7 @@
               "LINK_DROPPED_BY_DEPTH",
               "PACKAGED_UNREFERENCED_FILE",
               "PACKAGED_BROKEN_LINK",
+              "DUPLICATE_RESOURCE_ID",
               "SKILL_LENGTH_EXCEEDS_RECOMMENDED",
               "SKILL_TOTAL_SIZE_LARGE",
               "SKILL_TOO_MANY_FILES",
@@ -160,6 +163,7 @@
               "LINK_BROKEN_ANCHOR",
               "LINK_UNKNOWN",
               "LINK_TO_GITIGNORED",
+              "MALFORMED_HTML",
               "FRONTMATTER_MISSING",
               "FRONTMATTER_INVALID_YAML",
               "FRONTMATTER_SCHEMA_ERROR",
diff --git a/packages/agent-schema/src/validation-codes.ts b/packages/agent-schema/src/validation-codes.ts
index 20acc6ff..fc78fed6 100644
--- a/packages/agent-schema/src/validation-codes.ts
+++ b/packages/agent-schema/src/validation-codes.ts
@@ -86,6 +86,12 @@ export const CODE_REGISTRY = {
     'Report the issue — this indicates a VAT bug. As a temporary workaround, set severity.PACKAGED_BROKEN_LINK to ignore while the underlying bug is fixed.',
     'packaged_broken_link',
   ),
+  DUPLICATE_RESOURCE_ID: entry(
+    'error',
+    'Two files resolve to the same resource id after path normalization.',
+    'Rename one of the files so they produce distinct resource ids.',
+    'duplicate_resource_id',
+  ),
   SKILL_LENGTH_EXCEEDS_RECOMMENDED: entry(
     'warning',
     'SKILL.md line count exceeds the recommended limit; longer files degrade skill triggering.',
@@ -326,6 +332,12 @@ export const CODE_REGISTRY = {
     'Link a tracked target or un-ignore it.',
     'link_to_gitignored',
   ),
+  MALFORMED_HTML: entry(
+    'info',
+    'HTML resource has well-formedness issues reported by the parser.',
+    'Fix the malformed markup (unclosed tags, stray characters). Informational by default; raise severity via validation.severity to enforce.',
+    'malformed_html',
+  ),
   FRONTMATTER_MISSING: entry(
     'error',
     'Schema requires frontmatter but the file has none.',
diff --git a/packages/agent-schema/test/validation-codes-html.test.ts b/packages/agent-schema/test/validation-codes-html.test.ts
new file mode 100644
index 00000000..0a9c45b3
--- /dev/null
+++ b/packages/agent-schema/test/validation-codes-html.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { CODE_REGISTRY } from '../src/validation-codes.js';
+import { createRegistryIssue } from '../src/validation-issue.js';
+
+describe('MALFORMED_HTML code', () => {
+  it('is registered as info', () => {
+    expect(CODE_REGISTRY.MALFORMED_HTML.defaultSeverity).toBe('info');
+    expect(CODE_REGISTRY.MALFORMED_HTML.reference).toBe('#malformed_html');
+  });
+
+  it('builds an info-severity issue', () => {
+    const issue = createRegistryIssue('MALFORMED_HTML', 'Malformed HTML: missing-end-tag', { line: 3 });
+    expect(issue.severity).toBe('info');
+    expect(issue.line).toBe(3);
+  });
+});
diff --git a/packages/agent-schema/test/validation-codes.test.ts b/packages/agent-schema/test/validation-codes.test.ts
index 606bd6ff..db8085df 100644
--- a/packages/agent-schema/test/validation-codes.test.ts
+++ b/packages/agent-schema/test/validation-codes.test.ts
@@ -47,6 +47,14 @@ describe('CODE_REGISTRY', () => {
     expect(CODE_REGISTRY.PACKAGED_BROKEN_LINK.defaultSeverity).toBe('error');
   });
 
+  it('registers DUPLICATE_RESOURCE_ID as an error-severity overridable code', () => {
+    expect(CODE_REGISTRY.DUPLICATE_RESOURCE_ID).toBeDefined();
+    expect(CODE_REGISTRY.DUPLICATE_RESOURCE_ID.defaultSeverity).toBe('error');
+    expect(CODE_REGISTRY.DUPLICATE_RESOURCE_ID.description.length).toBeGreaterThan(10);
+    expect(CODE_REGISTRY.DUPLICATE_RESOURCE_ID.fix.length).toBeGreaterThan(10);
+    expect(CODE_REGISTRY.DUPLICATE_RESOURCE_ID.reference).toBe('#duplicate_resource_id');
+  });
+
   it('enforces warning defaults for best-practice and meta-codes', () => {
     for (const code of [
       'SKILL_LENGTH_EXCEEDS_RECOMMENDED',
diff --git a/packages/agent-skills/src/post-build-checks.ts b/packages/agent-skills/src/post-build-checks.ts
index f0bf705e..035b008a 100644
--- a/packages/agent-skills/src/post-build-checks.ts
+++ b/packages/agent-skills/src/post-build-checks.ts
@@ -10,6 +10,7 @@ import { readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
 import { CODE_REGISTRY, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
+import { parseHtml } from '@vibe-agent-toolkit/resources';
 import { safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 
 /**
@@ -84,10 +85,66 @@ function extractLocalLinks(content: string): string[] {
 }
 
 /**
- * Walk the markdown link graph starting at SKILL.md and return the set of
+ * Extract local file hrefs from a content file — markdown or HTML.
+ *
+ * For markdown: regex-matches `[text](href)` links, skipping code blocks.
+ * For HTML/HTM: uses `parseHtml` (parse5-based) and returns `local_file` hrefs only.
+ * Fragments are stripped from all returned hrefs.
+ */
+async function extractLocalHrefs(filePath: string): Promise<string[]> {
+  if (filePath.endsWith('.html') || filePath.endsWith('.htm')) {
+    const result = await parseHtml(filePath);
+    return result.links
+      .filter(link => link.type === 'local_file')
+      .map(link => {
+        const [withoutFragment] = link.href.split('#');
+        return withoutFragment ?? '';
+      })
+      .filter(href => href.length > 0);
+  }
+  // Markdown: read content and regex-match
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath from walkDir
+  const content = await readFile(filePath, 'utf-8');
+  return extractLocalLinks(content);
+}
+
+/**
+ * Check hrefs from a content file against allFileSet and return PACKAGED_BROKEN_LINK
+ * issues for any that don't resolve to a file in the packaged output.
+ *
+ * Shared by markdown and HTML broken-link checks to eliminate duplicate resolve/emit logic.
+ */
+function collectBrokenLinkIssues(
+  sourceFile: string,
+  hrefs: string[],
+  allFileSet: Set<string>,
+  outputDir: string,
+): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const relativeSourcePath = toForwardSlash(safePath.relative(outputDir, sourceFile));
+  for (const href of hrefs) {
+    const resolved = toForwardSlash(safePath.resolve(dirname(sourceFile), href));
+    if (!allFileSet.has(resolved)) {
+      issues.push({
+        severity: CODE_REGISTRY.PACKAGED_BROKEN_LINK.defaultSeverity,
+        code: 'PACKAGED_BROKEN_LINK',
+        message: `Broken link in packaged output: ${href} (from ${relativeSourcePath})`,
+        location: relativeSourcePath,
+        fix: CODE_REGISTRY.PACKAGED_BROKEN_LINK.fix,
+        reference: CODE_REGISTRY.PACKAGED_BROKEN_LINK.reference,
+      });
+    }
+  }
+  return issues;
+}
+
+/**
+ * Walk the markdown and HTML link graph starting at SKILL.md and return the set of
  * referenced file paths (normalized to forward slashes).
  *
- * SKILL.md itself is always included as the root.
+ * SKILL.md itself is always included as the root. Traversal follows `.md`, `.html`,
+ * and `.htm` links transitively so an HTML file referenced only by another HTML file
+ * is not reported as unreferenced.
  */
 async function collectReferencedPaths(
   outputDir: string,
@@ -95,34 +152,36 @@ async function collectReferencedPaths(
 ): Promise<Set<string>> {
   const referenced = new Set<string>();
   const skillMdPath = safePath.join(outputDir, 'SKILL.md');
-  const mdQueue: string[] = [skillMdPath];
+  const fileQueue: string[] = [skillMdPath];
   const visited = new Set<string>();
 
   // SKILL.md itself is the root — always referenced
   referenced.add(toForwardSlash(skillMdPath));
 
-  while (mdQueue.length > 0) {
-    const mdFile = mdQueue.shift();
-    if (!mdFile) break;
+  while (fileQueue.length > 0) {
+    const filePath = fileQueue.shift();
+    if (!filePath) break;
 
-    const normalized = toForwardSlash(mdFile);
+    const normalized = toForwardSlash(filePath);
     if (visited.has(normalized)) continue;
     visited.add(normalized);
 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- mdFile from walkDir output
-    if (!existsSync(mdFile)) continue;
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath from walkDir output
+    if (!existsSync(filePath)) continue;
 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- mdFile validated above
-    const content = await readFile(mdFile, 'utf-8');
-    const links = extractLocalLinks(content);
+    const hrefs = await extractLocalHrefs(filePath);
 
-    for (const href of links) {
-      const resolved = toForwardSlash(safePath.resolve(dirname(mdFile), href));
+    for (const href of hrefs) {
+      const resolved = toForwardSlash(safePath.resolve(dirname(filePath), href));
       referenced.add(resolved);
 
-      // If it's a markdown file in the output, traverse it transitively
-      if (resolved.endsWith('.md') && allFileSet.has(resolved) && !visited.has(resolved)) {
-        mdQueue.push(resolved);
+      // Traverse .md, .html, and .htm files transitively
+      const isTraversable =
+        (resolved.endsWith('.md') || resolved.endsWith('.html') || resolved.endsWith('.htm')) &&
+        allFileSet.has(resolved) &&
+        !visited.has(resolved);
+      if (isTraversable) {
+        fileQueue.push(resolved);
       }
     }
   }
@@ -132,28 +191,28 @@ async function collectReferencedPaths(
 
 /**
  * Record packaged files whose output-relative path appears anywhere in any
- * packaged markdown — inside code blocks (`` ```bash\nnode scripts/cli.mjs `` ``),
- * inline code spans, or prose — as "documented" references.
+ * packaged content file (markdown or HTML) — inside code blocks, inline code
+ * spans, or prose — as "documented" references.
  *
  * A file that a skill author chose to bundle but never documents is the real
  * problem this check exists to catch; documentation by code-block invocation
  * is still documentation. By contrast, `collectReferencedPaths` is intentionally
- * strict (only `[text](href)` links) because it also walks the transitive link
+ * strict (only formal link syntax) because it also walks the transitive link
  * graph, which would be unbounded if we followed substring hits.
  */
 async function addMentionReferences(
   outputDir: string,
   referenced: Set<string>,
   candidates: string[],
-  mdFiles: string[],
+  contentFiles: string[],
 ): Promise<void> {
-  if (candidates.length === 0 || mdFiles.length === 0) {
+  if (candidates.length === 0 || contentFiles.length === 0) {
     return;
   }
 
   const contents = await Promise.all(
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- mdFile from walkDir
-    mdFiles.map(f => readFile(f, 'utf-8')),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- contentFile from walkDir
+    contentFiles.map(f => readFile(f, 'utf-8')),
   );
   const haystack = contents.join('\n');
 
@@ -166,24 +225,26 @@ async function addMentionReferences(
 }
 
 /**
- * Check that every file in the packaged output is referenced from some markdown file.
+ * Check that every file in the packaged output is referenced from some markdown or HTML file.
  *
  * Two-pass detection:
- * 1. Walk `[text](href)` link graph from SKILL.md (strict, transitive).
+ * 1. Walk formal link graph from SKILL.md (strict, transitive, covers .md and .html/.htm).
  * 2. For files not covered by pass 1, check whether their output-relative path
- *    is mentioned anywhere in packaged markdown (code blocks, prose, etc.).
+ *    is mentioned anywhere in packaged content files (markdown or HTML).
  *    Authors often document CLI scripts via invocation examples rather than
- *    markdown links, and that counts as documented.
+ *    formal links, and that counts as documented.
  */
 export async function checkUnreferencedFiles(outputDir: string): Promise<ValidationIssue[]> {
   const allFiles = walkDir(outputDir);
   const allFileSet = new Set(allFiles.map(f => toForwardSlash(f)));
   const referenced = await collectReferencedPaths(outputDir, allFileSet);
 
-  // Second pass: treat any path mention in packaged markdown as documentation.
+  // Second pass: treat any path mention in packaged content files as documentation.
   const candidates = allFiles.filter(f => !referenced.has(toForwardSlash(f)));
-  const mdFiles = allFiles.filter(f => f.endsWith('.md'));
-  await addMentionReferences(outputDir, referenced, candidates, mdFiles);
+  const contentFiles = allFiles.filter(f =>
+    f.endsWith('.md') || f.endsWith('.html') || f.endsWith('.htm')
+  );
+  await addMentionReferences(outputDir, referenced, candidates, contentFiles);
 
   // Find unreferenced files
   const issues: ValidationIssue[] = [];
@@ -194,7 +255,7 @@ export async function checkUnreferencedFiles(outputDir: string): Promise<Validat
       issues.push({
         severity: CODE_REGISTRY.PACKAGED_UNREFERENCED_FILE.defaultSeverity,
         code: 'PACKAGED_UNREFERENCED_FILE',
-        message: `Packaged file not referenced from any markdown: ${relativePath}`,
+        message: `Packaged file not referenced from any content file (markdown or HTML): ${relativePath}`,
         location: relativePath,
         fix: CODE_REGISTRY.PACKAGED_UNREFERENCED_FILE.fix,
         reference: CODE_REGISTRY.PACKAGED_UNREFERENCED_FILE.reference,
@@ -206,35 +267,21 @@ export async function checkUnreferencedFiles(outputDir: string): Promise<Validat
 }
 
 /**
- * Check that every local file link in packaged markdown files resolves to a file
+ * Check that every local file link in packaged markdown and HTML files resolves to a file
  * that exists in the packaged output.
  */
 export async function checkBrokenPackagedLinks(outputDir: string): Promise<ValidationIssue[]> {
   const allFiles = walkDir(outputDir);
-  const mdFiles = allFiles.filter(f => f.endsWith('.md'));
+  const linkableFiles = allFiles.filter(f =>
+    f.endsWith('.md') || f.endsWith('.html') || f.endsWith('.htm')
+  );
   const allFileSet = new Set(allFiles.map(f => toForwardSlash(f)));
 
   const issues: ValidationIssue[] = [];
 
-  for (const mdFile of mdFiles) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- mdFile from walkDir
-    const content = await readFile(mdFile, 'utf-8');
-    const links = extractLocalLinks(content);
-    const relativeMdPath = toForwardSlash(safePath.relative(outputDir, mdFile));
-
-    for (const href of links) {
-      const resolved = toForwardSlash(safePath.resolve(dirname(mdFile), href));
-      if (!allFileSet.has(resolved)) {
-        issues.push({
-          severity: CODE_REGISTRY.PACKAGED_BROKEN_LINK.defaultSeverity,
-          code: 'PACKAGED_BROKEN_LINK',
-          message: `Broken link in packaged output: ${href} (from ${relativeMdPath})`,
-          location: relativeMdPath,
-          fix: CODE_REGISTRY.PACKAGED_BROKEN_LINK.fix,
-          reference: CODE_REGISTRY.PACKAGED_BROKEN_LINK.reference,
-        });
-      }
-    }
+  for (const sourceFile of linkableFiles) {
+    const hrefs = await extractLocalHrefs(sourceFile);
+    issues.push(...collectBrokenLinkIssues(sourceFile, hrefs, allFileSet, outputDir));
   }
 
   return issues;
diff --git a/packages/agent-skills/src/skill-packager.ts b/packages/agent-skills/src/skill-packager.ts
index 86074d4b..3044c424 100644
--- a/packages/agent-skills/src/skill-packager.ts
+++ b/packages/agent-skills/src/skill-packager.ts
@@ -31,6 +31,7 @@ import {
   openFrontmatter,
   resolveLocalHref,
   rewriteFrontmatterUriReferencesFromSchema,
+  rewriteHtmlLinks,
   transformContent,
   type LinkRewriteRule,
   type ParseResult,
@@ -484,6 +485,7 @@ export async function packageSkill(
     templateContext: { skill: { name: skillMetadata.name } },
     collectionSchemas,
     projectRoot,
+    warn: (message) => process.stderr.write(`warning: ${message}\n`),
   });
 
   // 12b. Copy files config entries that were not auto-discovered via link traversal.
@@ -955,6 +957,8 @@ interface CopyRewriteContext {
   collectionSchemas: Map<string, object>;
   /** Absolute path to the project root — required for RFC 3986 §4.2 leading-`/` href resolution in frontmatter. */
   projectRoot: string;
+  /** Sink for non-fatal copy/rewrite diagnostics (verbatim copies, un-appliable rewrites). */
+  warn: (message: string) => void;
 }
 
 /**
@@ -1031,8 +1035,12 @@ async function copyAndRewriteFile(
   // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
   await mkdir(dirname(targetPath), { recursive: true });
 
-  // Non-markdown files or rewriting disabled: plain binary copy
-  if (!sourcePath.endsWith('.md') || !ctx.rewriteLinks) {
+  const lower = sourcePath.toLowerCase();
+  const isMarkdown = lower.endsWith('.md');
+  const isHtml = lower.endsWith('.html') || lower.endsWith('.htm');
+
+  // Non-rewritable files or rewriting disabled: plain binary copy
+  if ((!isMarkdown && !isHtml) || !ctx.rewriteLinks) {
     await copyFile(sourcePath, targetPath);
     return;
   }
@@ -1045,12 +1053,39 @@ async function copyAndRewriteFile(
   const resource = ctx.fromRegistry.getResource(safePath.resolve(sourcePath));
 
   if (!resource) {
-    // Resource not in registry — write content as-is
+    // Resource not in registry — write content as-is. For HTML this is only
+    // reachable on an ID collision (e.g. page.html + page.md), where the asset
+    // is copied verbatim and its links are NOT rewritten (v1 limitation,
+    // mirrors the pre-existing asset-collision behavior).
+    ctx.warn(
+      `Copied '${sourcePath}' verbatim without link rewriting: it is not in the resource registry ` +
+        `(typically an ID collision with a same-named markdown file). Source-relative links inside it are not rewritten.`,
+    );
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
     await writeFile(targetPath, content, 'utf-8');
     return;
   }
 
+  // HTML: offset-splice link rewrite (no frontmatter, no template body rewrite).
+  if (isHtml) {
+    const rewriteHref = buildHrefRewriter(
+      ctx.fromRegistry,
+      ctx.toRegistry,
+      sourcePath,
+      targetPath,
+      ctx.projectRoot,
+    );
+    const rewritten = rewriteHtmlLinks(content, rewriteHref, (info) => {
+      ctx.warn(
+        `Could not rewrite <${info.tagName} ${info.attr}="${info.from}"> in '${sourcePath}' (${info.reason}); ` +
+          `the original value was kept.`,
+      );
+    });
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- targetPath is constructed from validated paths
+    await writeFile(targetPath, rewritten, 'utf-8');
+    return;
+  }
+
   // Parse once via FrontmatterEditor so comments survive any frontmatter
   // rewrites. The body is held verbatim; we run it through transformContent
   // for the existing rule/template body-link rewrite contract (unchanged).
@@ -1072,7 +1107,7 @@ async function copyAndRewriteFile(
     (id) => ctx.collectionSchemas.has(id),
   );
   if (matchingCollections.length > 0) {
-    const rewriteHref = buildFrontmatterHrefRewriter(
+    const rewriteHref = buildHrefRewriter(
       ctx.fromRegistry,
       ctx.toRegistry,
       sourcePath,
@@ -1092,7 +1127,7 @@ async function copyAndRewriteFile(
 }
 
 /**
- * Build the per-href rewrite callback used for frontmatter URI-refs.
+ * Build the per-href rewrite callback used for frontmatter URI-refs and HTML attributes.
  *
  * Mirrors the body-rewrite path so frontmatter and body link rewriting agree
  * on target paths:
@@ -1107,7 +1142,7 @@ async function copyAndRewriteFile(
  *
  * Returns the original href when no rewrite applies.
  */
-function buildFrontmatterHrefRewriter(
+function buildHrefRewriter(
   fromRegistry: WalkableRegistry,
   toRegistry: ResourceRegistry,
   sourcePath: string,
diff --git a/packages/agent-skills/test/integration/packager-frontmatter-rewrite.integration.test.ts b/packages/agent-skills/test/integration/packager-frontmatter-rewrite.integration.test.ts
index 34f75872..bf30b5f7 100644
--- a/packages/agent-skills/test/integration/packager-frontmatter-rewrite.integration.test.ts
+++ b/packages/agent-skills/test/integration/packager-frontmatter-rewrite.integration.test.ts
@@ -4,7 +4,7 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { mkdirSyncReal, normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
-import { packageSkill } from '../../src/skill-packager.js';
+import { buildExampleSkill } from './packager-test-helpers.js';
 
 const SCHEMA = {
   type: 'object',
@@ -76,10 +76,7 @@ describe('packager rewrites frontmatter URI-refs with body parity (Gap 3)', () =
   });
 
   it('rewrites frontmatter URI-refs to packaged output paths and preserves comments', async () => {
-    const skillPath = safePath.join(projectRoot, 'skills', 'example', 'SKILL.md');
-    const outputPath = safePath.join(projectRoot, 'dist', 'example');
-    const result = await packageSkill(skillPath, { outputPath, formats: ['directory'] });
-    expect(result.hasErrors).toBe(false);
+    const { outputPath } = await buildExampleSkill(projectRoot);
 
     const builtSkill = readFileSync(safePath.join(outputPath, 'SKILL.md'), 'utf-8');
 
diff --git a/packages/agent-skills/test/integration/packager-html-rewrite.integration.test.ts b/packages/agent-skills/test/integration/packager-html-rewrite.integration.test.ts
new file mode 100644
index 00000000..c1609bb3
--- /dev/null
+++ b/packages/agent-skills/test/integration/packager-html-rewrite.integration.test.ts
@@ -0,0 +1,96 @@
+/* eslint-disable security/detect-non-literal-fs-filename -- Test code with temp directories */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+
+import { mkdirSyncReal, normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { buildExampleSkill } from './packager-test-helpers.js';
+
+describe('packager rewrites links inside bundled HTML resources', () => {
+  let projectRoot: string;
+  const EXTERNAL_HTML = 'external.html';
+
+  beforeAll(() => {
+    projectRoot = mkdtempSync(safePath.join(normalizedTmpdir(), 'vat-packager-html-'));
+    // Lay out:
+    //   <root>/vibe-agent-toolkit.config.yaml
+    //   <root>/skills/example/SKILL.md      (links to page.html)
+    //   <root>/skills/example/page.html     (links back to SKILL.md, has a comment)
+    mkdirSyncReal(safePath.join(projectRoot, 'skills', 'example'), { recursive: true });
+
+    writeFileSync(
+      safePath.join(projectRoot, 'vibe-agent-toolkit.config.yaml'),
+      ['version: 1', ''].join('\n'),
+    );
+    writeFileSync(
+      safePath.join(projectRoot, 'skills', 'example', 'SKILL.md'),
+      [
+        '---',
+        'name: example',
+        'description: A test skill that links to an HTML page.',
+        '---',
+        '# Example',
+        '',
+        'See [the page](./page.html) and [the external page](./external.html).',
+        '',
+      ].join('\n'),
+    );
+    writeFileSync(
+      safePath.join(projectRoot, 'skills', 'example', 'page.html'),
+      [
+        '<!doctype html>',
+        '<html>',
+        '<head><title>Test</title></head>',
+        '<body>',
+        '<!-- keep me -->',
+        '<a href="./SKILL.md">back</a>',
+        '</body>',
+        '</html>',
+        '',
+      ].join('\n'),
+    );
+    // No source-relative links to rewrite — only an external URL — so this page
+    // must round-trip byte-for-byte through the bundler.
+    writeFileSync(
+      safePath.join(projectRoot, 'skills', 'example', EXTERNAL_HTML),
+      [
+        '<!doctype html>',
+        '<html><body>',
+        '<a href="https://example.com/docs">external</a>',
+        '<img src="https://example.com/cat.png">',
+        '</body></html>',
+        '',
+      ].join('\n'),
+    );
+  });
+
+  afterAll(() => {
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it('rewrites links inside bundled HTML resources', async () => {
+    const { outputPath } = await buildExampleSkill(projectRoot);
+
+    // Non-SKILL.md resources land in the 'resources/' subdirectory of the bundle
+    const html = readFileSync(safePath.join(outputPath, 'resources', 'page.html'), 'utf-8');
+
+    // HTML comment and surrounding markup is preserved verbatim
+    expect(html).toContain('<!-- keep me -->');
+    expect(html).toContain('<html>');
+    expect(html).toContain('</body>');
+
+    // The source-relative href was rewritten to point at the bundled SKILL.md
+    expect(html).toMatch(/href="[^"]*SKILL\.md"/);
+
+    // The original source-relative href is gone (it pointed to the source layout, not the output)
+    expect(html).not.toContain('href="./SKILL.md"');
+  });
+
+  it('round-trips an HTML resource with no rewritable links byte-for-byte', async () => {
+    const { outputPath } = await buildExampleSkill(projectRoot);
+    const source = readFileSync(safePath.join(projectRoot, 'skills', 'example', EXTERNAL_HTML), 'utf-8');
+    const bundled = readFileSync(safePath.join(outputPath, 'resources', EXTERNAL_HTML), 'utf-8');
+    // External-only links resolve to themselves, so the bundler must not touch a byte.
+    expect(bundled).toBe(source);
+  });
+});
diff --git a/packages/agent-skills/test/integration/packager-test-helpers.ts b/packages/agent-skills/test/integration/packager-test-helpers.ts
new file mode 100644
index 00000000..9ef0b55f
--- /dev/null
+++ b/packages/agent-skills/test/integration/packager-test-helpers.ts
@@ -0,0 +1,29 @@
+/**
+ * Shared helpers for packager integration tests.
+ *
+ * Extracted to eliminate duplicated setup across packager-*.integration.test.ts files.
+ */
+
+import { safePath } from '@vibe-agent-toolkit/utils';
+import { expect } from 'vitest';
+
+import { packageSkill } from '../../src/skill-packager.js';
+
+/**
+ * Package the canonical `skills/example/SKILL.md` skill inside `projectRoot`
+ * into `dist/example` and assert that packaging succeeded without errors.
+ *
+ * Both HTML-rewrite and frontmatter-rewrite tests use the same skill path
+ * layout; this helper centralises the three-line setup that was duplicated
+ * across those test files.
+ *
+ * @param projectRoot - Root directory of the temporary test project
+ * @returns `outputPath` (`<projectRoot>/dist/example`) for further assertions
+ */
+export async function buildExampleSkill(projectRoot: string): Promise<{ outputPath: string }> {
+  const skillPath = safePath.join(projectRoot, 'skills', 'example', 'SKILL.md');
+  const outputPath = safePath.join(projectRoot, 'dist', 'example');
+  const result = await packageSkill(skillPath, { outputPath, formats: ['directory'] });
+  expect(result.hasErrors).toBe(false);
+  return { outputPath };
+}
diff --git a/packages/agent-skills/test/integration/post-build-checks-html.integration.test.ts b/packages/agent-skills/test/integration/post-build-checks-html.integration.test.ts
new file mode 100644
index 00000000..691e5ae2
--- /dev/null
+++ b/packages/agent-skills/test/integration/post-build-checks-html.integration.test.ts
@@ -0,0 +1,123 @@
+/**
+ * Integration tests: post-build checks cover HTML/HTM files.
+ *
+ * Regression tests for the gap where checkBrokenPackagedLinks and
+ * checkUnreferencedFiles hard-filtered to .md, causing broken links
+ * INSIDE bundled HTML to ship with a green build.
+ */
+/* eslint-disable security/detect-non-literal-fs-filename -- Test code with temp directories */
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+
+import { mkdirSyncReal, normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { checkBrokenPackagedLinks, checkUnreferencedFiles } from '../../src/post-build-checks.js';
+
+const PACKAGED_BROKEN_LINK = 'PACKAGED_BROKEN_LINK';
+const PACKAGED_UNREFERENCED_FILE = 'PACKAGED_UNREFERENCED_FILE';
+const RESOURCES_DIR = 'resources';
+
+/** Write SKILL.md at outputDir root linking to the given relative path. */
+function writeSkillMd(outputDir: string, linkTarget: string): void {
+  writeFileSync(safePath.join(outputDir, 'SKILL.md'), [
+    '---',
+    'name: test',
+    'description: A test skill for post-build HTML checks.',
+    '---',
+    '# Test',
+    '',
+    `See [the page](./${linkTarget}).`,
+    '',
+  ].join('\n'));
+}
+
+/** Minimal HTML page content with a single <a href> link. */
+function htmlPage(href: string): string {
+  return [
+    '<!doctype html>',
+    '<html>',
+    '<body>',
+    `<a href="${href}">link</a>`,
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}
+
+describe('post-build checks: HTML/HTM file support', () => {
+  let outputDir: string;
+
+  beforeEach(() => {
+    outputDir = mkdtempSync(safePath.join(normalizedTmpdir(), 'vat-post-build-html-'));
+  });
+
+  afterEach(() => {
+    rmSync(outputDir, { recursive: true, force: true });
+  });
+
+  describe('checkBrokenPackagedLinks', () => {
+    it('reports PACKAGED_BROKEN_LINK for a broken <a href> inside a bundled HTML file', async () => {
+      // Arrange: SKILL.md → resources/page.html → ./missing.html (absent from output)
+      mkdirSyncReal(safePath.join(outputDir, RESOURCES_DIR), { recursive: true });
+      writeSkillMd(outputDir, `${RESOURCES_DIR}/page.html`);
+      writeFileSync(
+        safePath.join(outputDir, RESOURCES_DIR, 'page.html'),
+        htmlPage('./missing.html'),
+      );
+      // missing.html intentionally absent — the link inside page.html is broken.
+
+      // Act
+      const issues = await checkBrokenPackagedLinks(outputDir);
+
+      // Assert: HTML file is checked and the broken link is reported as an error
+      expect(issues.map(i => i.code)).toContain(PACKAGED_BROKEN_LINK);
+      expect(issues.find(i => i.code === PACKAGED_BROKEN_LINK)?.severity).toBe('error');
+    });
+
+    it('does not report PACKAGED_BROKEN_LINK for a valid link inside a bundled HTML file', async () => {
+      // Arrange: page.html links to sibling.html which exists in the output
+      mkdirSyncReal(safePath.join(outputDir, RESOURCES_DIR), { recursive: true });
+      writeSkillMd(outputDir, `${RESOURCES_DIR}/page.html`);
+      writeFileSync(
+        safePath.join(outputDir, RESOURCES_DIR, 'page.html'),
+        htmlPage('./sibling.html'),
+      );
+      writeFileSync(
+        safePath.join(outputDir, RESOURCES_DIR, 'sibling.html'),
+        '<!doctype html><html><body><p>sibling</p></body></html>\n',
+      );
+
+      // Act
+      const issues = await checkBrokenPackagedLinks(outputDir);
+
+      // Assert: valid HTML links produce no broken-link issue
+      expect(issues.filter(i => i.code === PACKAGED_BROKEN_LINK)).toHaveLength(0);
+    });
+  });
+
+  describe('checkUnreferencedFiles', () => {
+    it('does not report PACKAGED_UNREFERENCED_FILE for HTML file linked only from another HTML file', async () => {
+      // Arrange: SKILL.md → resources/page.html → resources/linked-page.html
+      // linked-page.html is NOT directly linked from SKILL.md; only reachable via HTML traversal.
+      mkdirSyncReal(safePath.join(outputDir, RESOURCES_DIR), { recursive: true });
+      writeSkillMd(outputDir, `${RESOURCES_DIR}/page.html`);
+      writeFileSync(
+        safePath.join(outputDir, RESOURCES_DIR, 'page.html'),
+        htmlPage('./linked-page.html'),
+      );
+      writeFileSync(
+        safePath.join(outputDir, RESOURCES_DIR, 'linked-page.html'),
+        '<!doctype html><html><body><p>Content only reachable through page.html.</p></body></html>\n',
+      );
+
+      // Act
+      const issues = await checkUnreferencedFiles(outputDir);
+
+      // Assert: traversal follows HTML <a href> links so linked-page.html is NOT unreferenced
+      const unreferencedLocations = issues
+        .filter(i => i.code === PACKAGED_UNREFERENCED_FILE)
+        .map(i => i.location);
+      expect(unreferencedLocations).not.toContain(`${RESOURCES_DIR}/linked-page.html`);
+    });
+  });
+});
diff --git a/packages/resources/package.json b/packages/resources/package.json
index 25a35d60..f9b8f6f5 100644
--- a/packages/resources/package.json
+++ b/packages/resources/package.json
@@ -39,6 +39,7 @@
     "ajv-formats": "^3.0.1",
     "github-slugger": "^2.0.0",
     "markdown-link-check": "^3.14.2",
+    "parse5": "^7.2.1",
     "picomatch": "^4.0.3",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.0",
diff --git a/packages/resources/src/frontmatter-link-validator.ts b/packages/resources/src/frontmatter-link-validator.ts
index 13542325..bf5dcb49 100644
--- a/packages/resources/src/frontmatter-link-validator.ts
+++ b/packages/resources/src/frontmatter-link-validator.ts
@@ -21,9 +21,9 @@
 import { createRegistryIssue, type IssueCode } from '@vibe-agent-toolkit/agent-schema';
 
 import { classifyLink } from './link-parser.js';
-import { validateLink, type ValidateLinkOptions } from './link-validator.js';
+import { validateLink, type FragmentIndex, type ValidateLinkOptions } from './link-validator.js';
 import { walkFrontmatterUriReferences } from './schema-uri-walker.js';
-import type { HeadingNode, ResourceLink, ValidationIssue } from './types.js';
+import type { ResourceLink, ValidationIssue } from './types.js';
 
 /** Map the link-level code emitted by validateLink to its frontmatter-scoped code. */
 const LINK_CODE_TO_FRONTMATTER_CODE: Partial<Record<IssueCode, IssueCode>> = {
@@ -51,14 +51,14 @@ export interface FrontmatterLinkValidationResult {
  * @param frontmatter - Parsed frontmatter (or undefined)
  * @param schema - JSON Schema for the collection
  * @param sourceFilePath - Absolute path to the source file
- * @param headingsByFile - Heading trees (for anchor validation)
+ * @param fragmentsByFile - Fragment index (file path → set of valid fragments) for anchor validation
  * @param options - Same shape as validateLink (projectRoot, gitTracker, ...)
  */
 export async function validateFrontmatterLinks(
   frontmatter: Record<string, unknown> | undefined,
   schema: object,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions,
 ): Promise<FrontmatterLinkValidationResult> {
   if (!frontmatter) return { issues: [], externalUrls: [] };
@@ -89,7 +89,7 @@ export async function validateFrontmatterLinks(
       line: 1, // Frontmatter per-field line numbers are post-v1.
     };
 
-    const issue = await validateLink(syntheticLink, sourceFilePath, headingsByFile, options);
+    const issue = await validateLink(syntheticLink, sourceFilePath, fragmentsByFile, options);
     if (!issue) continue;
 
     issues.push(rewriteIssue(issue, capture.dottedPath));
diff --git a/packages/resources/src/html-link-parser.ts b/packages/resources/src/html-link-parser.ts
new file mode 100644
index 00000000..db922805
--- /dev/null
+++ b/packages/resources/src/html-link-parser.ts
@@ -0,0 +1,140 @@
+/**
+ * HTML resource parser.
+ *
+ * Parses local HTML files into the shared `ParseResult` shape:
+ * - `<a href>` and `<img src>` links (classified by `classifyLink`)
+ * - `id` / `name` attributes as fragment anchors
+ * - well-formedness diagnostics from parse5's `onParseError`
+ *
+ * Uses parse5 (WHATWG-conformant). The parse5 document + element walker are
+ * exported so the link rewriter (html-transform.ts) shares one parser path.
+ *
+ * Non-goal: `<base href>` is not honored — relative links are resolved against
+ * the file's own directory, not a document base.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+
+import { parse, type DefaultTreeAdapterMap } from 'parse5';
+
+import { classifyLink, type ParseResult } from './link-parser.js';
+import type { HtmlParseError } from './schemas/resource-metadata.js';
+import type { ResourceLink } from './types.js';
+
+type P5Node = DefaultTreeAdapterMap['node'];
+type P5Element = DefaultTreeAdapterMap['element'];
+type P5ChildNode = DefaultTreeAdapterMap['childNode'];
+
+/** A parsed parse5 document together with any well-formedness diagnostics. */
+export interface HtmlDocument {
+  document: DefaultTreeAdapterMap['document'];
+  parseErrors: HtmlParseError[];
+}
+
+/**
+ * Parse an HTML source string with source-location info and collect parser
+ * errors. Shared by `parseHtml` (link/anchor extraction) and `rewriteHtmlLinks`
+ * (attribute offset splicing).
+ */
+export function parseHtmlDocument(source: string): HtmlDocument {
+  const parseErrors: HtmlParseError[] = [];
+  const document = parse(source, {
+    sourceCodeLocationInfo: true,
+    onParseError: (err) => {
+      // parse5's ParserError extends Location which always has startLine: number.
+      // We always include line since it is always present.
+      parseErrors.push({ message: err.code, line: err.startLine });
+    },
+  });
+  return { document, parseErrors };
+}
+
+/**
+ * Depth-first walk yielding every element node in the tree.
+ *
+ * Deliberate gap: a `<template>` element's content lives in its separate
+ * `content` fragment (not `childNodes`), so links inside `<template>` are not
+ * walked, and foreign-content (SVG/MathML) subtrees are not special-cased.
+ * Both are rare in the content link graph we rewrite.
+ */
+export function* walkElements(node: P5Node): Generator<P5Element> {
+  if ('tagName' in node) {
+    yield node;
+  }
+  if ('childNodes' in node) {
+    for (const child of node.childNodes as P5ChildNode[]) {
+      yield* walkElements(child);
+    }
+  }
+}
+
+function getAttr(element: P5Element, name: string): string | undefined {
+  return element.attrs.find((a) => a.name === name)?.value;
+}
+
+function makeLink(href: string, line: number | undefined): ResourceLink {
+  return { text: '', href, type: classifyLink(href), ...(line !== undefined && { line }) };
+}
+
+function visitElement(
+  element: P5Element,
+  links: ResourceLink[],
+  anchors: Set<string>,
+): void {
+  const line = element.sourceCodeLocation?.startLine;
+
+  if (element.tagName === 'a') {
+    const href = getAttr(element, 'href');
+    if (href !== undefined) {
+      links.push(makeLink(href, line));
+    }
+    const name = getAttr(element, 'name');
+    if (name !== undefined && name !== '') {
+      anchors.add(name);
+    }
+  } else if (element.tagName === 'img') {
+    const src = getAttr(element, 'src');
+    if (src !== undefined) {
+      links.push(makeLink(src, line));
+    }
+  }
+
+  const id = getAttr(element, 'id');
+  if (id !== undefined && id !== '') {
+    anchors.add(id);
+  }
+}
+
+/**
+ * Parse an HTML file into a `ParseResult`.
+ *
+ * @param filePath - Absolute path to the HTML file.
+ */
+export async function parseHtml(filePath: string): Promise<ParseResult> {
+  const [content, stats] = await Promise.all([
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a user-provided path parameter
+    readFile(filePath, 'utf-8'),
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- filePath is a user-provided path parameter
+    stat(filePath),
+  ]);
+
+  const { document, parseErrors } = parseHtmlDocument(content);
+
+  const links: ResourceLink[] = [];
+  const anchors = new Set<string>();
+
+  for (const element of walkElements(document)) {
+    visitElement(element, links, anchors);
+  }
+
+  const anchorList = [...anchors];
+  return {
+    links,
+    headings: [],
+    content,
+    sizeBytes: stats.size,
+    estimatedTokenCount: Math.ceil(content.length / 4),
+    ...(anchorList.length > 0 && { anchors: anchorList }),
+    ...(parseErrors.length > 0 && { parseErrors }),
+  };
+}
diff --git a/packages/resources/src/html-transform.ts b/packages/resources/src/html-transform.ts
new file mode 100644
index 00000000..eb1a3655
--- /dev/null
+++ b/packages/resources/src/html-transform.ts
@@ -0,0 +1,157 @@
+/**
+ * Structure-preserving HTML link rewriter.
+ *
+ * Rewrites `<a href>` and `<img src>` attribute VALUES in place by splicing the
+ * original source string at parse5-reported offsets. The document is never
+ * re-serialized (parse5's serializer normalizes whitespace, quotes, void
+ * elements, and the doctype), so unchanged input round-trips byte-for-byte.
+ *
+ * Uses the same `RewriteHref` callback model as `rewriteBodyLinks` — callers
+ * supply per-href target resolution; this module owns only the splice mechanics.
+ *
+ * Non-goal: `<base href>` is not honored. Relative hrefs are resolved by the
+ * caller against the file's own directory; a `<base>` element that would
+ * override that in a browser is ignored.
+ */
+
+import { parseHtmlDocument, walkElements } from './html-link-parser.js';
+import type { RewriteHref } from './rewriter-helpers.js';
+
+/** Tag name → the single link-bearing attribute we rewrite. */
+const LINK_ATTR_BY_TAG: Record<string, string | undefined> = { a: 'href', img: 'src' };
+
+interface ValueSpan {
+  valueStart: number;
+  valueEnd: number;
+  /** `"` or `'` for quoted attributes; `''` for unquoted. */
+  quote: string;
+}
+
+interface Edit extends ValueSpan {
+  newValue: string;
+}
+
+/**
+ * Chars that force an unquoted HTML attribute value to be quoted. Follows the
+ * WHATWG unquoted-attribute-value rules: whitespace, quotes, `<`, `>`, plus
+ * backtick and `=` (a superset of paths we expect, kept strict for safety).
+ */
+const UNQUOTED_UNSAFE = /[\s"'`<>=]/;
+
+/**
+ * Locate the value sub-range within an attribute's full source span.
+ *
+ * parse5 reports the whole-attribute span (`href="value"`); this finds the
+ * value's absolute offsets and the quote char. Returns undefined for boolean
+ * attributes (no `=`).
+ */
+function valueSpan(attrSource: string, base: number): ValueSpan | undefined {
+  const eq = attrSource.indexOf('=');
+  if (eq === -1) {
+    return undefined;
+  }
+  let i = eq + 1;
+  while (i < attrSource.length && /\s/.test(attrSource.charAt(i))) {
+    i += 1;
+  }
+  if (i >= attrSource.length) {
+    return undefined;
+  }
+  const ch = attrSource.charAt(i);
+  if (ch === '"' || ch === "'") {
+    const close = attrSource.indexOf(ch, i + 1);
+    const end = close === -1 ? attrSource.length : close;
+    return { valueStart: base + i + 1, valueEnd: base + end, quote: ch };
+  }
+  return { valueStart: base + i, valueEnd: base + attrSource.length, quote: '' };
+}
+
+/**
+ * Encode a new value for writing. For quoted attributes the surrounding quotes
+ * stay in the source (we only replace the inner value), so we escape `&` and the
+ * active quote. For originally-unquoted values we keep them bare when safe, else
+ * wrap in double quotes.
+ */
+function encodeValue(newValue: string, quote: string): string {
+  if (quote === '"' || quote === "'") {
+    const amp = newValue.replaceAll('&', '&amp;');
+    return quote === '"' ? amp.replaceAll('"', '&quot;') : amp.replaceAll("'", '&#39;');
+  }
+  if (newValue.length > 0 && !UNQUOTED_UNSAFE.test(newValue)) {
+    return newValue.replaceAll('&', '&amp;');
+  }
+  const escaped = newValue.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+  return `"${escaped}"`;
+}
+
+/** A wanted link rewrite that could not be spliced back into the source. */
+export interface UnappliedRewrite {
+  tagName: string;
+  attr: string;
+  /** The original attribute value the rewrite targeted. */
+  from: string;
+  /** The value the rewrite wanted to write. */
+  to: string;
+  /**
+   * Why the splice could not be located:
+   * - `no-source-location` — parse5 omitted the attribute's offsets (synthesized
+   *   during error recovery on malformed input).
+   * - `unparseable-attribute` — the attribute's source span had no locatable
+   *   value (e.g. an unterminated quote).
+   */
+  reason: 'no-source-location' | 'unparseable-attribute';
+}
+
+/**
+ * Rewrite `<a href>` / `<img src>` values in `source` using `rewriteHref`.
+ * Returns `source` unchanged (byte-for-byte) when no value changes.
+ *
+ * A rewrite that is wanted (the href resolves to a new value) but cannot be
+ * spliced back — because parse5 omitted the source location or the attribute
+ * span is unparseable — is reported via `onUnapplied` rather than dropped
+ * silently. Malformed pages are exactly the ones that hit this path, so the
+ * caller can surface it instead of shipping a stale link.
+ */
+export function rewriteHtmlLinks(
+  source: string,
+  rewriteHref: RewriteHref,
+  onUnapplied?: (info: UnappliedRewrite) => void,
+): string {
+  const { document } = parseHtmlDocument(source);
+  const edits: Edit[] = [];
+
+  for (const element of walkElements(document)) {
+    const attrName = LINK_ATTR_BY_TAG[element.tagName];
+    if (attrName === undefined) {
+      continue;
+    }
+    const attr = element.attrs.find((a) => a.name === attrName);
+    if (attr === undefined) {
+      continue;
+    }
+    // Resolve first so we only record drops that actually lose a wanted edit.
+    const newValue = rewriteHref(attr.value);
+    if (newValue === attr.value) {
+      continue;
+    }
+    const location = element.sourceCodeLocation?.attrs?.[attrName];
+    if (location === undefined) {
+      onUnapplied?.({ tagName: element.tagName, attr: attrName, from: attr.value, to: newValue, reason: 'no-source-location' });
+      continue;
+    }
+    const span = valueSpan(source.slice(location.startOffset, location.endOffset), location.startOffset);
+    if (span === undefined) {
+      onUnapplied?.({ tagName: element.tagName, attr: attrName, from: attr.value, to: newValue, reason: 'unparseable-attribute' });
+      continue;
+    }
+    edits.push({ ...span, newValue });
+  }
+
+  // Apply descending by start offset so earlier edits don't shift later ones.
+  edits.sort((a, b) => b.valueStart - a.valueStart);
+  let result = source;
+  for (const edit of edits) {
+    result = result.slice(0, edit.valueStart) + encodeValue(edit.newValue, edit.quote) + result.slice(edit.valueEnd);
+  }
+  return result;
+}
diff --git a/packages/resources/src/index.ts b/packages/resources/src/index.ts
index aadfcbe1..266aba4a 100644
--- a/packages/resources/src/index.ts
+++ b/packages/resources/src/index.ts
@@ -85,6 +85,11 @@ export {
 // Export parser interface for advanced use cases
 export { parseMarkdown, type ParseResult } from './link-parser.js';
 
+export { parseHtml } from './html-link-parser.js';
+// HtmlParseError is Zod-sourced (single source of truth) — see schemas/resource-metadata.ts.
+export type { HtmlParseError } from './schemas/resource-metadata.js';
+export { rewriteHtmlLinks, type UnappliedRewrite } from './html-transform.js';
+
 // Export frontmatter validation
 export { validateFrontmatter } from './frontmatter-validator.js';
 
diff --git a/packages/resources/src/link-parser.ts b/packages/resources/src/link-parser.ts
index 9cc76bab..18065436 100644
--- a/packages/resources/src/link-parser.ts
+++ b/packages/resources/src/link-parser.ts
@@ -1,5 +1,5 @@
 /**
- * Markdown link parser and analyzer.
+ * Markdown link parser and shared resource-parsing types.
  *
  * Parses markdown files to extract:
  * - Links (regular, reference-style, autolinks)
@@ -7,6 +7,10 @@
  * - File size and token estimates
  *
  * Uses unified/remark for robust markdown parsing with GFM support.
+ *
+ * Also defines the format-neutral `ParseResult` contract shared with the HTML
+ * parser (`html-link-parser.ts`). The `HtmlParseError` shape is Zod-sourced
+ * from `schemas/resource-metadata.ts` (single source of truth).
  */
 
 import { readFile, stat } from 'node:fs/promises';
@@ -20,10 +24,11 @@ import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
 import * as yaml from 'yaml';
 
+import type { HtmlParseError } from './schemas/resource-metadata.js';
 import type { HeadingNode, LinkType, ResourceLink } from './types.js';
 
 /**
- * Result of parsing a markdown file.
+ * Result of parsing a resource file (markdown or HTML).
  */
 export interface ParseResult {
   links: ResourceLink[];
@@ -33,6 +38,10 @@ export interface ParseResult {
   content: string;
   sizeBytes: number;
   estimatedTokenCount: number;
+  /** Fragment targets (HTML `id`/`name` attributes). Markdown leaves this undefined. */
+  anchors?: string[];
+  /** HTML well-formedness diagnostics. Markdown leaves this undefined. */
+  parseErrors?: HtmlParseError[];
 }
 
 /**
diff --git a/packages/resources/src/link-validator.ts b/packages/resources/src/link-validator.ts
index 854f1138..58caa262 100644
--- a/packages/resources/src/link-validator.ts
+++ b/packages/resources/src/link-validator.ts
@@ -25,7 +25,7 @@ import {
   verifyCaseSensitiveFilename,
 } from '@vibe-agent-toolkit/utils';
 
-import type { HeadingNode, ResourceLink } from './types.js';
+import type { ResourceLink } from './types.js';
 import { isWithinProject, issueLocation, resolveLocalHref } from './utils.js';
 
 type LinkIssueExtras = Partial<Pick<ValidationIssue, 'location' | 'line' | 'link' | 'suggestion'>>;
@@ -66,7 +66,7 @@ export interface ValidateLinkOptions {
  *
  * @param link - The link to validate
  * @param sourceFilePath - Absolute path to the file containing the link
- * @param headingsByFile - Map of file paths to their heading trees
+ * @param fragmentsByFile - Fragment index: file path → set of valid fragments (markdown slugs + HTML id/name)
  * @param options - Validation options (projectRoot, skipGitIgnoreCheck)
  * @returns ValidationIssue if link is broken, null if valid
  *
@@ -84,15 +84,15 @@ export interface ValidateLinkOptions {
 export async function validateLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   switch (link.type) {
     case 'local_file':
-      return await validateLocalFileLink(link, sourceFilePath, headingsByFile, options);
+      return await validateLocalFileLink(link, sourceFilePath, fragmentsByFile, options);
 
     case 'anchor':
-      return await validateAnchorLink(link, sourceFilePath, headingsByFile, options?.projectRoot);
+      return await validateAnchorLink(link, sourceFilePath, fragmentsByFile, options?.projectRoot);
 
     case 'external':
       // External URLs are not validated - don't report them
@@ -232,7 +232,7 @@ export function gitIgnoreSafetyIssue(
 async function validateLocalFileLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   options?: ValidateLinkOptions
 ): Promise<ValidationIssue | null> {
   const resolved = resolveLocalHref(link.href, sourceFilePath, options?.projectRoot);
@@ -263,8 +263,8 @@ async function validateLocalFileLink(
   if (gitIgnoreIssue) return gitIgnoreIssue;
 
   if (resolved.anchor) {
-    const anchorValid = await validateAnchor(resolved.anchor, fileResult.resolvedPath, headingsByFile);
-    if (!anchorValid) {
+    const check = checkAnchor(resolved.anchor, fileResult.resolvedPath, fragmentsByFile);
+    if (check === 'broken') {
       return createRegistryIssue(
         'LINK_BROKEN_ANCHOR',
         `Anchor not found: #${resolved.anchor} in ${fileResult.resolvedPath}`,
@@ -276,30 +276,42 @@ async function validateLocalFileLink(
   return null;
 }
 
+/**
+ * Exhaustiveness guard for the {@link AnchorCheck} union: a compile error at the
+ * call site means a new variant was added without being handled here.
+ */
+function assertNever(value: never): never {
+  throw new Error(`Unhandled AnchorCheck variant: ${String(value)}`);
+}
+
 /**
  * Validate an anchor link (within current file).
  */
 async function validateAnchorLink(
   link: ResourceLink,
   sourceFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>,
+  fragmentsByFile: FragmentIndex,
   projectRoot?: string,
 ): Promise<ValidationIssue | null> {
   // Extract anchor (strip leading #)
   const anchor = link.href.startsWith('#') ? link.href.slice(1) : link.href;
 
   // Validate anchor exists in current file
-  const isValid = await validateAnchor(anchor, sourceFilePath, headingsByFile);
+  const check = checkAnchor(anchor, sourceFilePath, fragmentsByFile);
 
-  if (!isValid) {
-    return createRegistryIssue(
-      'LINK_BROKEN_ANCHOR',
-      `Anchor not found: ${link.href}`,
-      linkExtras(link, sourceFilePath, projectRoot, ''),
-    );
+  switch (check) {
+    case 'skip':
+    case 'valid':
+      return null;
+    case 'broken':
+      return createRegistryIssue(
+        'LINK_BROKEN_ANCHOR',
+        `Anchor not found: ${link.href}`,
+        linkExtras(link, sourceFilePath, projectRoot, ''),
+      );
+    default:
+      return assertNever(check);
   }
-
-  return null;
 }
 
 
@@ -338,65 +350,85 @@ async function validateResolvedFile(
   return result;
 }
 
+/** Result of checking an anchor against the fragment index. */
+export type AnchorCheck = 'skip' | 'valid' | 'broken';
+
 /**
- * Validate that an anchor (heading slug) exists in a file.
- *
- * @param anchor - The heading slug to find (without leading #)
- * @param targetFilePath - Absolute path to the file containing the heading
- * @param headingsByFile - Map of file paths to their heading trees
- * @returns True if anchor exists, false otherwise
- *
- * @example
- * ```typescript
- * const valid = await validateAnchor('my-heading', '/project/docs/guide.md', headingsMap);
- * ```
+ * A file's fragment targets plus how to match against them. HTML `id`/`name`
+ * anchors are matched case-sensitively; markdown heading slugs are case-folded.
+ * The policy lives on the entry rather than being re-derived from the file
+ * extension at match time, so a new resource format only has to set this flag.
  */
-async function validateAnchor(
-  anchor: string,
-  targetFilePath: string,
-  headingsByFile: Map<string, HeadingNode[]>
-): Promise<boolean> {
-  // Get headings for target file
-  const headings = headingsByFile.get(targetFilePath);
-  if (!headings) {
-    return false;
-  }
+export interface FragmentIndexEntry {
+  /** `true` for case-sensitive matching (HTML ids), `false` for case-folded (markdown slugs). */
+  caseSensitive: boolean;
+  fragments: Set<string>;
+}
+
+/** File path → its fragment targets and matching policy. */
+export type FragmentIndex = Map<string, FragmentIndexEntry>;
+
+/**
+ * Whether a path is an HTML resource (`.html`/`.htm`). The single place the
+ * extension drives format-specific behavior: case-sensitive ids (via
+ * {@link fragmentIndexEntry}) and the HTML top-fragment navigation rule.
+ */
+export function isHtmlPath(filePath: string): boolean {
+  return /\.html?$/i.test(filePath);
+}
 
-  // Search for matching slug (case-insensitive)
-  return findHeadingBySlug(headings, anchor);
+/** Build one index entry, choosing the case-folding policy from the file type. */
+export function fragmentIndexEntry(filePath: string, fragments: Set<string> = new Set()): FragmentIndexEntry {
+  return { caseSensitive: isHtmlPath(filePath), fragments };
 }
 
 /**
- * Recursively search heading tree for a matching slug.
- *
- * Performs case-insensitive comparison of slugs.
+ * Build a {@link FragmentIndex} from `[path, fragments]` pairs, deriving each
+ * entry's matching policy from its path. Single construction path shared by the
+ * registry and tests.
+ */
+export function fragmentIndex(entries: Iterable<readonly [string, Set<string>]> = []): FragmentIndex {
+  const map: FragmentIndex = new Map();
+  for (const [filePath, fragments] of entries) {
+    map.set(filePath, fragmentIndexEntry(filePath, fragments));
+  }
+  return map;
+}
+
+/**
+ * Check whether a fragment exists in the target file's anchor set.
  *
- * @param headings - Array of heading nodes to search
- * @param targetSlug - The slug to find
- * @returns True if slug found, false otherwise
+ * - `'skip'`  — target file is not indexed; we cannot prove the anchor is
+ *   broken, so callers must not emit an issue.
+ * - Matching follows the entry's `caseSensitive` policy (HTML ids exact,
+ *   markdown slugs case-folded). The index carries the policy, so this never
+ *   re-derives the folding rule from the file extension.
+ * - For HTML targets the empty fragment (`#`) and `top` (ASCII
+ *   case-insensitive) are always valid: per the HTML fragment-navigation
+ *   algorithm both scroll to the top of the document regardless of whether a
+ *   matching element exists, so `href="#"` / `href="#top"` are not broken.
  *
- * @example
- * ```typescript
- * const found = findHeadingBySlug(headings, 'my-heading');
- * ```
+ * @param anchor - Fragment without the leading `#`.
+ * @param targetFilePath - Absolute path of the file the fragment lives in.
+ * @param fragmentsByFile - Fragment index carrying each file's matching policy.
  */
-function findHeadingBySlug(
-  headings: HeadingNode[],
-  targetSlug: string
-): boolean {
-  const normalizedTarget = targetSlug.toLowerCase();
-
-  for (const heading of headings) {
-    // Check current heading
-    if (heading.slug.toLowerCase() === normalizedTarget) {
-      return true;
-    }
-
-    // Recursively check children
-    if (heading.children && findHeadingBySlug(heading.children, targetSlug)) {
-      return true;
-    }
+export function checkAnchor(
+  anchor: string,
+  targetFilePath: string,
+  fragmentsByFile: FragmentIndex,
+): AnchorCheck {
+  const entry = fragmentsByFile.get(targetFilePath);
+  if (!entry) {
+    return 'skip';
   }
-
-  return false;
+  // HTML spec: the empty fragment and "top" (case-insensitive) always navigate
+  // to the top of the document — valid even with no matching id. This is an
+  // HTML-format navigation rule, distinct from the case-folding policy above.
+  if (isHtmlPath(targetFilePath) && (anchor === '' || anchor.toLowerCase() === 'top')) {
+    return 'valid';
+  }
+  const found = entry.caseSensitive
+    ? entry.fragments.has(anchor)
+    : entry.fragments.has(anchor.toLowerCase());
+  return found ? 'valid' : 'broken';
 }
diff --git a/packages/resources/src/resource-registry.ts b/packages/resources/src/resource-registry.ts
index 6c844ac1..42292f7f 100644
--- a/packages/resources/src/resource-registry.ts
+++ b/packages/resources/src/resource-registry.ts
@@ -22,8 +22,9 @@ import {
   type FrontmatterExternalUrl,
 } from './frontmatter-link-validator.js';
 import { validateFrontmatter } from './frontmatter-validator.js';
+import { parseHtml } from './html-link-parser.js';
 import { parseMarkdown } from './link-parser.js';
-import { validateLink, type ValidateLinkOptions } from './link-validator.js';
+import { fragmentIndexEntry, validateLink, type FragmentIndex, type ValidateLinkOptions } from './link-validator.js';
 import type { ResourceCollectionInterface } from './resource-collection-interface.js';
 import type { SHA256 } from './schemas/checksum.js';
 import type { ProjectConfig } from './schemas/project-config.js';
@@ -31,6 +32,27 @@ import type { HeadingNode, ResourceMetadata } from './schemas/resource-metadata.
 import type { ValidationResult } from './schemas/validation-result.js';
 import { issueLocation, matchesGlobPattern, splitHrefAnchor } from './utils.js';
 
+/**
+ * Typed error thrown when two resources produce the same ID.
+ *
+ * Carries the authoritative id and both paths so callers can record accurate
+ * issue data without re-deriving the id from the file path (which would be
+ * wrong when the id came from a frontmatter `idField` value).
+ */
+export class DuplicateResourceIdError extends Error {
+  readonly id: string;
+  readonly existingPath: string;
+  readonly conflictingPath: string;
+
+  constructor(id: string, conflictingPath: string, existingPath: string) {
+    super(`Duplicate resource ID '${id}': '${conflictingPath}' conflicts with '${existingPath}'`);
+    this.name = 'DuplicateResourceIdError';
+    this.id = id;
+    this.existingPath = existingPath;
+    this.conflictingPath = conflictingPath;
+  }
+}
+
 /**
  * Options for crawling directories to add resources.
  */
@@ -169,6 +191,12 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    */
   private readonly frontmatterExternalUrlsByResource: Map<string, FrontmatterExternalUrl[]> = new Map();
 
+  /**
+   * Collisions recorded by addResources() when two files produce the same resource id.
+   * Cleared by clear(). Surfaced as DUPLICATE_RESOURCE_ID issues in validate().
+   */
+  private duplicateIdCollisions: Array<{ id: string; existingPath: string; conflictingPath: string }> = [];
+
   constructor(options?: ResourceRegistryOptions) {
     if (options?.baseDir !== undefined) {
       this.baseDir = options.baseDir;
@@ -233,9 +261,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       // Check for duplicate ID
       const existingById = registry.resourcesById.get(resource.id);
       if (existingById) {
-        throw new Error(
-          `Duplicate resource ID '${resource.id}': '${resource.filePath}' conflicts with '${existingById.filePath}'`
-        );
+        throw new DuplicateResourceIdError(resource.id, resource.filePath, existingById.filePath);
       }
 
       // Add to path index
@@ -304,8 +330,12 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Normalize path to absolute
     const absolutePath = safePath.resolve(filePath);
 
-    // Parse the markdown file (needed before ID generation for frontmatter lookup)
-    const parseResult = await parseMarkdown(absolutePath);
+    // Parse the file — HTML or markdown depending on extension
+    const lowerPath = absolutePath.toLowerCase();
+    const isHtml = lowerPath.endsWith('.html') || lowerPath.endsWith('.htm');
+    const parseResult = isHtml
+      ? await parseHtml(absolutePath)
+      : await parseMarkdown(absolutePath);
 
     // Generate ID using priority chain: frontmatter field → relative path → filename stem
     const id = this.generateId(absolutePath, parseResult.frontmatter);
@@ -313,9 +343,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Check for duplicate ID (allow re-adding same file path)
     const existingById = this.resourcesById.get(id);
     if (existingById && existingById.filePath !== absolutePath) {
-      throw new Error(
-        `Duplicate resource ID '${id}': '${absolutePath}' conflicts with '${existingById.filePath}'`
-      );
+      throw new DuplicateResourceIdError(id, absolutePath, existingById.filePath);
     }
 
     // Get file modified time
@@ -336,6 +364,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       filePath: absolutePath,
       links: parseResult.links,
       headings: parseResult.headings,
+      ...(parseResult.anchors !== undefined && { anchors: parseResult.anchors }),
+      ...(parseResult.parseErrors !== undefined && { parseErrors: parseResult.parseErrors }),
       ...(parseResult.frontmatter !== undefined && { frontmatter: parseResult.frontmatter }),
       ...(parseResult.frontmatterError !== undefined && { frontmatterError: parseResult.frontmatterError }),
       sizeBytes: parseResult.sizeBytes,
@@ -372,7 +402,20 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async addResources(filePaths: string[]): Promise<ResourceMetadata[]> {
     const results: ResourceMetadata[] = [];
     for (const fp of filePaths) {
-      results.push(await this.addResource(fp));
+      try {
+        results.push(await this.addResource(fp));
+      } catch (error) {
+        if (error instanceof DuplicateResourceIdError) {
+          this.duplicateIdCollisions.push({
+            id: error.id,
+            existingPath: error.existingPath,
+            conflictingPath: error.conflictingPath,
+          });
+          // First-added wins; skip conflicting file and continue crawling.
+        } else {
+          throw error;
+        }
+      }
     }
     return results;
   }
@@ -396,7 +439,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async crawl(options: CrawlOptions): Promise<ResourceMetadata[]> {
     const {
       baseDir,
-      include = ['**/*.md'],
+      include = ['**/*.md', '**/*.html', '**/*.htm'],
       exclude = ['**/node_modules/**', '**/.git/**', '**/dist/**'],
       followSymlinks = false,
     } = options;
@@ -442,12 +485,48 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     return issues;
   }
 
+  /**
+   * Emit MALFORMED_HTML issues from each resource's HTML parse errors.
+   * @private
+   */
+  private collectHtmlParseErrors(): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    for (const resource of this.resourcesByPath.values()) {
+      for (const parseError of resource.parseErrors ?? []) {
+        issues.push(
+          createRegistryIssue(
+            'MALFORMED_HTML',
+            `Malformed HTML: ${parseError.message}`,
+            {
+              location: issueLocation(resource.filePath, this.baseDir),
+              ...(parseError.line !== undefined && { line: parseError.line }),
+            },
+          ),
+        );
+      }
+    }
+    return issues;
+  }
+
+  /**
+   * Emit DUPLICATE_RESOURCE_ID errors for collisions recorded by addResources().
+   * @private
+   */
+  private collectDuplicateIdErrors(): ValidationIssue[] {
+    return this.duplicateIdCollisions.map(({ id, existingPath, conflictingPath }) =>
+      createRegistryIssue(
+        'DUPLICATE_RESOURCE_ID',
+        `Two files resolve to the same resource id '${id}': '${issueLocation(existingPath, this.baseDir)}' and '${issueLocation(conflictingPath, this.baseDir)}'. Rename one of the files so they produce distinct resource ids.`,
+      ),
+    );
+  }
+
   /**
    * Validate all links in all resources.
    * @private
    */
   private async validateAllLinks(
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -463,7 +542,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
               ...(this.gitTracker !== undefined && { gitTracker: this.gitTracker })
             };
 
-        const issue = await validateLink(link, resource.filePath, headingsByFile, validateOptions);
+        const issue = await validateLink(link, resource.filePath, fragmentsByFile, validateOptions);
         if (issue) {
           issues.push(issue);
         }
@@ -501,7 +580,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
    * @private
    */
   private async validateCollectionFrontmatter(
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -523,7 +602,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
       const collectionIssues = await this.validateResourceCollectionSchemas(
         resource,
         fsPromises,
-        headingsByFile,
+        fragmentsByFile,
         skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
@@ -539,7 +618,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   private async validateResourceCollectionSchemas(
     resource: ResourceMetadata,
     fsModule: typeof fs,
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     const issues: ValidationIssue[] = [];
@@ -560,7 +639,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
         resource,
         collection.validation,
         fsModule,
-        headingsByFile,
+        fragmentsByFile,
         skipGitIgnoreCheck,
       );
       issues.push(...collectionIssues);
@@ -577,7 +656,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     resource: ResourceMetadata,
     validation: NonNullable<NonNullable<ProjectConfig['resources']>['collections']>[string]['validation'],
     fsModule: typeof fs,
-    headingsByFile: Map<string, HeadingNode[]>,
+    fragmentsByFile: FragmentIndex,
     skipGitIgnoreCheck: boolean,
   ): Promise<ValidationIssue[]> {
     if (!validation?.frontmatterSchema) {
@@ -620,7 +699,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
           resource.frontmatter,
           schema,
           resource.filePath,
-          headingsByFile,
+          fragmentsByFile,
           linkOptions,
         );
         issues.push(...linkIssues);
@@ -679,8 +758,8 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   async validate(options?: ValidateOptions): Promise<ValidationResult> {
     const startTime = Date.now();
 
-    // Build headings map for validation
-    const headingsByFile = this.buildHeadingsByFileMap();
+    // Build fragment index for anchor validation
+    const fragmentsByFile = this.buildFragmentIndex();
 
     // Reset frontmatter external URL state for this validation run
     this.frontmatterExternalUrlsByResource.clear();
@@ -688,19 +767,21 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     // Collect all validation issues
     const issues: ValidationIssue[] = [];
 
-    // Check for YAML parsing errors first
-    issues.push(...this.collectYamlErrors());
+    // Surface parse-time diagnostics: YAML frontmatter errors first, then HTML
+    // well-formedness, then duplicate-id collisions. Combined into one push() call
+    // (SonarCloud S7778).
+    issues.push(...this.collectYamlErrors(), ...this.collectHtmlParseErrors(), ...this.collectDuplicateIdErrors());
 
     // Validate each link in each resource
     const linkIssues = await this.validateAllLinks(
-      headingsByFile,
+      fragmentsByFile,
       options?.skipGitIgnoreCheck ?? false
     );
     issues.push(...linkIssues);
 
     // Per-collection frontmatter validation
     const collectionFrontmatterIssues = await this.validateCollectionFrontmatter(
-      headingsByFile,
+      fragmentsByFile,
       options?.skipGitIgnoreCheck ?? false,
     );
     issues.push(...collectionFrontmatterIssues);
@@ -1044,6 +1125,7 @@ export class ResourceRegistry implements ResourceCollectionInterface {
     this.resourcesById.clear();
     this.resourcesByName.clear();
     this.resourcesByChecksum.clear();
+    this.duplicateIdCollisions = [];
   }
 
   /**
@@ -1253,14 +1335,20 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 
   /**
-   * Build a map of file paths to their heading trees.
-   *
-   * Used for link validation.
+   * Build a format-neutral fragment index for anchor validation: each file's
+   * absolute path → the set of valid fragment targets. Markdown contributes
+   * heading slugs (lowercased); HTML contributes its `id`/`name` anchors.
    */
-  private buildHeadingsByFileMap(): Map<string, HeadingNode[]> {
-    const map = new Map<string, HeadingNode[]>();
+  private buildFragmentIndex(): FragmentIndex {
+    const map: FragmentIndex = new Map();
     for (const resource of this.resourcesByPath.values()) {
-      map.set(resource.filePath, resource.headings);
+      const fragments = new Set<string>();
+      collectHeadingSlugs(resource.headings, fragments);
+      for (const anchor of resource.anchors ?? []) {
+        fragments.add(anchor);
+      }
+      // Policy (case-sensitive ids vs folded slugs) is derived from the file type.
+      map.set(resource.filePath, fragmentIndexEntry(resource.filePath, fragments));
     }
     return map;
   }
@@ -1318,29 +1406,47 @@ export class ResourceRegistry implements ResourceCollectionInterface {
   }
 }
 
+/** Recursively collect lowercased heading slugs into `out`. */
+function collectHeadingSlugs(headings: HeadingNode[], out: Set<string>): void {
+  for (const heading of headings) {
+    out.add(heading.slug.toLowerCase());
+    if (heading.children) {
+      collectHeadingSlugs(heading.children, out);
+    }
+  }
+}
+
 /**
  * Generate an ID from a file path.
  *
+ * Every resource id includes a `-<ext>` suffix derived from the file extension
+ * (dot stripped, lowercased). This makes ids from different file types distinct
+ * even when the stem is identical (e.g. `foo.md` → `foo-md`, `foo.html` → `foo-html`).
+ * Extensionless files (e.g. `Makefile`) receive no suffix.
+ *
  * When `baseDir` is provided, computes a relative path from baseDir and uses the full
  * directory structure in the ID. When no `baseDir`, uses the filename stem only.
  *
  * @param filePath - Absolute file path
  * @param baseDir - Base directory for relative path computation (optional)
- * @returns Generated ID in kebab-case
+ * @returns Generated ID in kebab-case with `-<ext>` suffix
  *
  * @example
  * ```typescript
- * // Without baseDir: filename stem only
- * generateIdFromPath('/project/docs/User Guide.md')  // 'user-guide'
- * generateIdFromPath('/project/README.md')            // 'readme'
+ * // Without baseDir: filename stem + extension suffix
+ * generateIdFromPath('/project/docs/User Guide.md')  // 'user-guide-md'
+ * generateIdFromPath('/project/README.md')            // 'readme-md'
+ * generateIdFromPath('/project/page.html')            // 'page-html'
+ * generateIdFromPath('/project/Makefile')             // 'makefile'
  *
- * // With baseDir: relative path
- * generateIdFromPath('/project/docs/concepts/core/overview.md', '/project/docs')  // 'concepts-core-overview'
- * generateIdFromPath('/project/docs/guide.md', '/project/docs')                   // 'guide'
+ * // With baseDir: relative path + extension suffix
+ * generateIdFromPath('/project/docs/concepts/core/overview.md', '/project/docs')  // 'concepts-core-overview-md'
+ * generateIdFromPath('/project/docs/guide.md', '/project/docs')                   // 'guide-md'
  * ```
  */
 export function generateIdFromPath(filePath: string, baseDir?: string): string {
   let rawId: string;
+  let extSuffix = '';
 
   if (baseDir) {
     // Compute relative path from baseDir, remove extension
@@ -1349,11 +1455,23 @@ export function generateIdFromPath(filePath: string, baseDir?: string): string {
     const withoutExt = ext ? relativePath.slice(0, -ext.length) : relativePath;
     // Normalize path separators to forward slashes (cross-platform), then replace with hyphens
     rawId = toForwardSlash(withoutExt).replaceAll('/', '-');
+    if (ext) {
+      // Strip the leading dot; lowercasing happens in the kebab pipeline below
+      extSuffix = `-${ext.slice(1)}`;
+    }
   } else {
     // Fallback: basename only (no directory context)
-    rawId = path.basename(filePath, path.extname(filePath));
+    const ext = path.extname(filePath);
+    rawId = path.basename(filePath, ext);
+    if (ext) {
+      extSuffix = `-${ext.slice(1)}`;
+    }
   }
 
+  // Append extension suffix before the kebab pipeline so hyphen-collapse and
+  // trim apply uniformly (e.g. suffixed-.md → 'suffixed--md' → 'suffixed-md')
+  rawId = `${rawId}${extSuffix}`;
+
   // Convert to kebab-case:
   // 1. Replace underscores and spaces with hyphens
   // 2. Convert to lowercase
diff --git a/packages/resources/src/schemas/resource-metadata.ts b/packages/resources/src/schemas/resource-metadata.ts
index 0a3b158d..23253b86 100644
--- a/packages/resources/src/schemas/resource-metadata.ts
+++ b/packages/resources/src/schemas/resource-metadata.ts
@@ -36,6 +36,16 @@ export const LinkNodeTypeSchema = z.enum([
 
 export type LinkNodeType = z.infer<typeof LinkNodeTypeSchema>;
 
+/**
+ * Zod schema for an HTML well-formedness diagnostic.
+ */
+export const HtmlParseErrorSchema = z.object({
+  message: z.string().describe('parse5 error code (e.g. "missing-end-tag")'),
+  line: z.number().int().positive().optional().describe('1-based source line, when known'),
+}).describe('HTML well-formedness diagnostic');
+
+export type HtmlParseError = z.infer<typeof HtmlParseErrorSchema>;
+
 /**
  * Represents a heading node in the document's table of contents.
  *
@@ -96,6 +106,10 @@ export const ResourceMetadataSchema = z.object({
   filePath: z.string().describe('Absolute path to the resource file'),
   links: z.array(ResourceLinkSchema).describe('All links found in the resource'),
   headings: z.array(HeadingNodeSchema).describe('Document table of contents (top-level headings only; children are nested)'),
+  anchors: z.array(z.string()).optional()
+    .describe('Fragment targets for anchor validation (HTML id/name attributes)'),
+  parseErrors: z.array(HtmlParseErrorSchema).optional()
+    .describe('HTML well-formedness diagnostics (populated for HTML resources only)'),
   frontmatter: z.record(z.string(), z.unknown()).optional()
     .describe('Parsed YAML frontmatter (if present in markdown file)'),
   frontmatterError: z.string().optional()
@@ -106,6 +120,6 @@ export const ResourceMetadataSchema = z.object({
   checksum: SHA256Schema.describe('SHA-256 checksum of file content'),
   collections: z.array(z.string()).optional()
     .describe('Collection names this resource belongs to (populated when using config-based discovery)'),
-}).describe('Complete metadata for a markdown resource');
+}).strict().describe('Complete metadata for a markdown resource');
 
 export type ResourceMetadata = z.infer<typeof ResourceMetadataSchema>;
diff --git a/packages/resources/test/frontmatter-link-validator.test.ts b/packages/resources/test/frontmatter-link-validator.test.ts
index 48c9b9ee..b2792450 100644
--- a/packages/resources/test/frontmatter-link-validator.test.ts
+++ b/packages/resources/test/frontmatter-link-validator.test.ts
@@ -5,13 +5,13 @@ import { normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 
 import { validateFrontmatterLinks } from '../src/frontmatter-link-validator.js';
-import type { HeadingNode } from '../src/types.js';
+import { fragmentIndex, type FragmentIndex } from '../src/link-validator.js';
 
 describe('validateFrontmatterLinks', () => {
   let projectRoot: string;
   let sourceFile: string;
   let targetFile: string;
-  let headingsByFile: Map<string, HeadingNode[]>;
+  let fragmentsByFile: FragmentIndex;
 
   beforeAll(async () => {
     projectRoot = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-fmlv-'));
@@ -21,14 +21,9 @@ describe('validateFrontmatterLinks', () => {
     await writeFile(sourceFile, '---\n---\n# Source\n');
     await writeFile(targetFile, '# Target\n\n## Section A\n');
 
-    headingsByFile = new Map();
-    headingsByFile.set(targetFile, [
-      { level: 1, text: 'Target', slug: 'target', children: [
-        { level: 2, text: 'Section A', slug: 'section-a', children: [] },
-      ] },
-    ]);
-    headingsByFile.set(sourceFile, [
-      { level: 1, text: 'Source', slug: 'source', children: [] },
+    fragmentsByFile = fragmentIndex([
+      [targetFile, new Set(['target', 'section-a'])],
+      [sourceFile, new Set(['source'])],
     ]);
   });
 
@@ -48,7 +43,7 @@ describe('validateFrontmatterLinks', () => {
     frontmatter: Record<string, unknown> | undefined,
     schema: object = refSchema,
   ) =>
-    validateFrontmatterLinks(frontmatter, schema, sourceFile, headingsByFile, {
+    validateFrontmatterLinks(frontmatter, schema, sourceFile, fragmentsByFile, {
       projectRoot,
       skipGitIgnoreCheck: true,
     });
@@ -140,7 +135,7 @@ describe('validateFrontmatterLinks', () => {
         { ref: '/docs/target.md' },
         refSchema,
         sourceFile,
-        headingsByFile,
+        fragmentsByFile,
         { skipGitIgnoreCheck: true },
       );
       expect(issues).toHaveLength(1);
diff --git a/packages/resources/test/generate-id.test.ts b/packages/resources/test/generate-id.test.ts
index 5011583c..2088d3d6 100644
--- a/packages/resources/test/generate-id.test.ts
+++ b/packages/resources/test/generate-id.test.ts
@@ -2,70 +2,146 @@ import { describe, expect, it } from 'vitest';
 
 import { generateIdFromPath } from '../src/resource-registry.js';
 
+// ── Shared path constants (avoid duplicate-string lint errors) ─────────────
+const PROJECT_ROOT = '/project';
+const PROJECT_DOCS = '/project/docs';
+const GUIDE_HTML_ID = 'guide-html';
+const GUIDE_MD = '/project/guide.md';
+const GUIDE_HTML = '/project/guide.html';
+const GUIDE_HTM = '/project/guide.htm';
+const MAKEFILE = '/project/Makefile';
+const MY_CONFIG_MD = '/project/my.config.md';
+const README_MD = '/project/README.md';
+const USER_GUIDE_MD = '/project/User Guide.md';
+const DOCS_GUIDE_MD = '/project/docs/guide.md';
+const DEEP_OVERVIEW_MD = '/project/docs/concepts/core/overview.md';
+
 describe('generateIdFromPath', () => {
   describe('without baseDir (filename stem fallback)', () => {
-    it('should generate ID from filename stem', () => {
-      expect(generateIdFromPath('/project/docs/README.md')).toBe('readme');
+    it('should generate ID from filename stem with extension suffix', () => {
+      expect(generateIdFromPath(README_MD)).toBe('readme-md');
     });
 
     it('should convert underscores to hyphens', () => {
-      expect(generateIdFromPath('/project/API_v2.md')).toBe('api-v2');
+      expect(generateIdFromPath('/project/API_v2.md')).toBe('api-v2-md');
     });
 
     it('should convert spaces to hyphens', () => {
-      expect(generateIdFromPath('/project/User Guide.md')).toBe('user-guide');
+      expect(generateIdFromPath(USER_GUIDE_MD)).toBe('user-guide-md');
     });
 
     it('should remove special characters', () => {
-      expect(generateIdFromPath('/project/doc@v1.0.md')).toBe('docv10');
+      expect(generateIdFromPath('/project/doc@v1.0.md')).toBe('docv10-md');
     });
 
     it('should collapse multiple hyphens', () => {
-      expect(generateIdFromPath('/project/my--doc.md')).toBe('my-doc');
+      expect(generateIdFromPath('/project/my--doc.md')).toBe('my-doc-md');
     });
 
     it('should trim leading hyphens', () => {
-      expect(generateIdFromPath('/project/-prefixed.md')).toBe('prefixed');
+      expect(generateIdFromPath('/project/-prefixed.md')).toBe('prefixed-md');
     });
 
-    it('should trim trailing hyphens', () => {
-      expect(generateIdFromPath('/project/suffixed-.md')).toBe('suffixed');
+    it('should trim trailing hyphens from stem (ext suffix still appended)', () => {
+      expect(generateIdFromPath('/project/suffixed-.md')).toBe('suffixed-md');
     });
 
     it('should handle numeric filenames', () => {
-      expect(generateIdFromPath('/project/03-overview.md')).toBe('03-overview');
+      expect(generateIdFromPath('/project/03-overview.md')).toBe('03-overview-md');
+    });
+
+    it('should append -html suffix for .html extension', () => {
+      expect(generateIdFromPath(GUIDE_HTML)).toBe(GUIDE_HTML_ID);
+    });
+
+    it('should append -htm suffix for .htm extension', () => {
+      expect(generateIdFromPath(GUIDE_HTM)).toBe('guide-htm');
+    });
+
+    it('should not append a trailing hyphen for extensionless files', () => {
+      expect(generateIdFromPath(MAKEFILE)).toBe('makefile');
+    });
+
+    it('should strip interior dots before appending extension suffix', () => {
+      // my.config.md: stem = 'my.config', ext = '.md'
+      // stem through kebab pipeline strips the dot → 'myconfig', suffix → 'myconfig-md'
+      expect(generateIdFromPath(MY_CONFIG_MD)).toBe('myconfig-md');
     });
   });
 
   describe('with baseDir (relative path)', () => {
-    it('should generate ID from relative path', () => {
-      expect(generateIdFromPath('/project/docs/concepts/core/overview.md', '/project/docs'))
-        .toBe('concepts-core-overview');
+    it('should generate ID from relative path with extension suffix', () => {
+      expect(generateIdFromPath(DEEP_OVERVIEW_MD, PROJECT_DOCS))
+        .toBe('concepts-core-overview-md');
     });
 
     it('should handle file at baseDir root', () => {
-      expect(generateIdFromPath('/project/docs/guide.md', '/project/docs'))
-        .toBe('guide');
+      expect(generateIdFromPath(DOCS_GUIDE_MD, PROJECT_DOCS))
+        .toBe('guide-md');
     });
 
     it('should handle deeply nested paths', () => {
-      expect(generateIdFromPath('/project/a/b/c/d/file.md', '/project'))
-        .toBe('a-b-c-d-file');
+      expect(generateIdFromPath('/project/a/b/c/d/file.md', PROJECT_ROOT))
+        .toBe('a-b-c-d-file-md');
     });
 
     it('should convert underscores in path segments', () => {
-      expect(generateIdFromPath('/project/my_dir/my_file.md', '/project'))
-        .toBe('my-dir-my-file');
+      expect(generateIdFromPath('/project/my_dir/my_file.md', PROJECT_ROOT))
+        .toBe('my-dir-my-file-md');
     });
 
     it('should handle spaces in directory names', () => {
-      expect(generateIdFromPath('/project/My Docs/User Guide.md', '/project'))
-        .toBe('my-docs-user-guide');
+      expect(generateIdFromPath('/project/My Docs/User Guide.md', PROJECT_ROOT))
+        .toBe('my-docs-user-guide-md');
     });
 
     it('should handle numbered path segments', () => {
-      expect(generateIdFromPath('/project/01-concepts/02-advanced/03-details.md', '/project'))
-        .toBe('01-concepts-02-advanced-03-details');
+      expect(generateIdFromPath('/project/01-concepts/02-advanced/03-details.md', PROJECT_ROOT))
+        .toBe('01-concepts-02-advanced-03-details-md');
+    });
+
+    it('should append -html suffix for .html files under baseDir', () => {
+      expect(generateIdFromPath('/project/docs/guide.html', PROJECT_DOCS))
+        .toBe(GUIDE_HTML_ID);
+    });
+  });
+
+  describe('canonical examples from spec', () => {
+    it('guide.md → guide-md', () => {
+      expect(generateIdFromPath(GUIDE_MD)).toBe('guide-md');
+    });
+
+    it('README.md → readme-md', () => {
+      expect(generateIdFromPath(README_MD)).toBe('readme-md');
+    });
+
+    it('User Guide.md → user-guide-md', () => {
+      expect(generateIdFromPath(USER_GUIDE_MD)).toBe('user-guide-md');
+    });
+
+    it('docs/guide.md with baseDir docs → guide-md', () => {
+      expect(generateIdFromPath(DOCS_GUIDE_MD, PROJECT_DOCS)).toBe('guide-md');
+    });
+
+    it('docs/concepts/core/overview.md with baseDir docs → concepts-core-overview-md', () => {
+      expect(generateIdFromPath(DEEP_OVERVIEW_MD, PROJECT_DOCS))
+        .toBe('concepts-core-overview-md');
+    });
+
+    it('guide.html → guide-html', () => {
+      expect(generateIdFromPath(GUIDE_HTML)).toBe(GUIDE_HTML_ID);
+    });
+
+    it('guide.htm → guide-htm', () => {
+      expect(generateIdFromPath(GUIDE_HTM)).toBe('guide-htm');
+    });
+
+    it('Makefile (extensionless) → makefile (no trailing hyphen)', () => {
+      expect(generateIdFromPath(MAKEFILE)).toBe('makefile');
+    });
+
+    it('my.config.md → myconfig-md', () => {
+      expect(generateIdFromPath(MY_CONFIG_MD)).toBe('myconfig-md');
     });
   });
 });
diff --git a/packages/resources/test/html-link-parser.test.ts b/packages/resources/test/html-link-parser.test.ts
new file mode 100644
index 00000000..32e6a5d4
--- /dev/null
+++ b/packages/resources/test/html-link-parser.test.ts
@@ -0,0 +1,59 @@
+/* eslint-disable security/detect-non-literal-fs-filename -- test writes to temp dirs from computed paths */
+import { mkdtemp, writeFile } from 'node:fs/promises';
+
+import { normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
+import { afterAll, describe, expect, it } from 'vitest';
+
+import { parseHtml } from '../src/html-link-parser.js';
+
+const dirs: string[] = [];
+
+async function writeHtml(name: string, body: string): Promise<string> {
+  const dir = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-html-'));
+  dirs.push(dir);
+  const file = safePath.join(dir, name);
+  await writeFile(file, body, 'utf-8');
+  return file;
+}
+
+afterAll(async () => {
+  const { rm } = await import('node:fs/promises');
+  await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })));
+});
+
+describe('parseHtml', () => {
+  it('extracts <a href> and <img src> links', async () => {
+    const file = await writeHtml(
+      'page.html',
+      '<html><body><a href="./other.html">x</a><img src="img/logo.png"></body></html>',
+    );
+    const result = await parseHtml(file);
+    const hrefs = result.links.map((l) => l.href).sort((a, b) => a.localeCompare(b));
+    expect(hrefs).toEqual(['./other.html', 'img/logo.png']);
+    expect(result.links.find((l) => l.href === './other.html')?.type).toBe('local_file');
+  });
+
+  it('collects id and name attributes as anchors', async () => {
+    const file = await writeHtml(
+      'anchors.html',
+      '<html><body><h2 id="intro">Intro</h2><a name="legacy"></a></body></html>',
+    );
+    const result = await parseHtml(file);
+    expect(new Set(result.anchors)).toEqual(new Set(['intro', 'legacy']));
+    expect(result.headings).toEqual([]);
+  });
+
+  it('reports malformed markup via parseErrors', async () => {
+    const file = await writeHtml('bad.html', '<html><body><p>unclosed</body></html>');
+    const result = await parseHtml(file);
+    expect(result.parseErrors).toBeDefined();
+    expect((result.parseErrors ?? []).length).toBeGreaterThan(0);
+  });
+
+  it('omits anchors/parseErrors when there are none', async () => {
+    const file = await writeHtml('clean.html', '<!doctype html><title>t</title><p>hi</p>');
+    const result = await parseHtml(file);
+    expect(result.anchors).toBeUndefined();
+    expect(result.parseErrors).toBeUndefined();
+  });
+});
diff --git a/packages/resources/test/html-transform.test.ts b/packages/resources/test/html-transform.test.ts
new file mode 100644
index 00000000..4e104b7f
--- /dev/null
+++ b/packages/resources/test/html-transform.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseHtmlDocument, walkElements } from '../src/html-link-parser.js';
+import { rewriteHtmlLinks, type UnappliedRewrite } from '../src/html-transform.js';
+
+const swap = (from: string, to: string) => (href: string) => (href === from ? to : href);
+
+/** A valueless `href` attribute — has no value span, so a wanted rewrite cannot be applied. */
+const VALUELESS_HREF = '<a href>x</a>';
+
+/** Re-parse `html` and return the entity-decoded value of the first `<tag attr>`. */
+function readAttr(html: string, tag: string, attr: string): string | undefined {
+  const { document } = parseHtmlDocument(html);
+  for (const el of walkElements(document)) {
+    if (el.tagName !== tag) continue;
+    const found = el.attrs.find((a) => a.name === attr);
+    if (found) return found.value;
+  }
+  return undefined;
+}
+
+describe('rewriteHtmlLinks', () => {
+  it('returns byte-identical source when nothing changes', () => {
+    const src = '<!doctype html>\n<a href="./a.html">x</a> <!-- keep -->\n<img src=\'b.png\'>';
+    expect(rewriteHtmlLinks(src, (h) => h)).toBe(src);
+  });
+
+  it('rewrites only the targeted href, preserving double quotes', () => {
+    const src = '<a href="./old.html" class="z">x</a>';
+    expect(rewriteHtmlLinks(src, swap('./old.html', './new.html'))).toBe(
+      '<a href="./new.html" class="z">x</a>',
+    );
+  });
+
+  it('preserves single quotes', () => {
+    const src = "<img src='old.png'>";
+    expect(rewriteHtmlLinks(src, swap('old.png', 'new.png'))).toBe("<img src='new.png'>");
+  });
+
+  it('keeps unquoted values unquoted when safe', () => {
+    const src = '<a href=old.html>x</a>';
+    expect(rewriteHtmlLinks(src, swap('old.html', 'new.html'))).toBe('<a href=new.html>x</a>');
+  });
+
+  it('adds quotes to a previously-unquoted value only when unsafe', () => {
+    const src = '<a href=old.html>x</a>';
+    expect(rewriteHtmlLinks(src, swap('old.html', 'new file.html'))).toBe(
+      '<a href="new file.html">x</a>',
+    );
+  });
+
+  it('escapes & and the active quote in the written value', () => {
+    const src = '<a href="old">x</a>';
+    expect(rewriteHtmlLinks(src, swap('old', 'a&b"c'))).toBe('<a href="a&amp;b&quot;c">x</a>');
+  });
+
+  it('applies multiple rewrites without offset drift', () => {
+    const src = '<a href="a.html">1</a><a href="b.html">2</a>';
+    const mapping: Record<string, string> = { 'a.html': 'x.html', 'b.html': 'y.html' };
+    const rw = (h: string) => mapping[h] ?? h;
+    expect(rewriteHtmlLinks(src, rw)).toBe('<a href="x.html">1</a><a href="y.html">2</a>');
+  });
+
+  // Grouped into one block on purpose: a run of near-identical single-assertion
+  // `it` blocks trips SonarCloud's copy-paste detector (it normalizes literals,
+  // so varying the fixtures doesn't help). One multi-assertion body covers the
+  // remaining valueSpan/encodeValue edge branches without that repetition.
+  it('handles attribute-shape edge cases', () => {
+    // Single-quote attribute: escape & and the active single quote.
+    expect(rewriteHtmlLinks("<img src='q.png'>", swap('q.png', "a'b&c"))).toBe(
+      "<img src='a&#39;b&amp;c'>",
+    );
+    // Whitespace around the = sign is preserved; only the value is spliced.
+    expect(rewriteHtmlLinks('<a href = "ws.html">x</a>', swap('ws.html', 'done.html'))).toBe(
+      '<a href = "done.html">x</a>',
+    );
+    // An <a> without an href attribute is skipped; a later real href still rewrites.
+    expect(
+      rewriteHtmlLinks('<a name="anchor">x</a><a href="real.html">y</a>', swap('real.html', 'out.html')),
+    ).toBe('<a name="anchor">x</a><a href="out.html">y</a>');
+    // Valueless and empty-value attributes have no value span to rewrite.
+    expect(rewriteHtmlLinks(VALUELESS_HREF, () => 'changed')).toBe(VALUELESS_HREF);
+    expect(rewriteHtmlLinks('<a href=>x</a>', () => 'changed')).toBe('<a href=>x</a>');
+  });
+
+  it('reports a wanted rewrite it cannot apply instead of dropping it silently', () => {
+    const unapplied: UnappliedRewrite[] = [];
+    // The rewrite is wanted (-> 'changed') but cannot be applied, so it must be recorded.
+    const out = rewriteHtmlLinks(VALUELESS_HREF, () => 'changed', (info) => unapplied.push(info));
+    expect(out).toBe(VALUELESS_HREF); // still byte-for-byte unchanged
+    expect(unapplied).toHaveLength(1);
+    expect(unapplied[0]).toMatchObject({ tagName: 'a', attr: 'href', to: 'changed', reason: 'unparseable-attribute' });
+  });
+
+  it('does not report when no rewrite is wanted', () => {
+    const unapplied: UnappliedRewrite[] = [];
+    rewriteHtmlLinks(VALUELESS_HREF, (h) => h, (info) => unapplied.push(info));
+    expect(unapplied).toHaveLength(0);
+  });
+
+  it('round-trips: the rewritten value decodes back to the exact target (no double-escape)', () => {
+    // Splicing escapes `&` and the active quote into the source; a correct
+    // implementation means a browser/parser decodes the value back to the
+    // intended target verbatim. `a&b` vs `a&amp;b` are the double-escape canary.
+    for (const target of ['a&b', 'a&amp;b', 'a"b', "a'b", 'x?y=1&z=2', 'plain.html']) {
+      const out = rewriteHtmlLinks('<a href="old">x</a>', swap('old', target));
+      expect(readAttr(out, 'a', 'href')).toBe(target);
+    }
+  });
+});
diff --git a/packages/resources/test/integration/collection-validation-fixtures.integration.test.ts b/packages/resources/test/integration/collection-validation-fixtures.integration.test.ts
index 77649507..d96dbbfb 100644
--- a/packages/resources/test/integration/collection-validation-fixtures.integration.test.ts
+++ b/packages/resources/test/integration/collection-validation-fixtures.integration.test.ts
@@ -73,7 +73,7 @@ describe('Collection validation with test fixtures', () => {
     expect(result.issues).toHaveLength(7);
 
     // Verify all expected files have errors
-    const errorFiles = result.issues.map((e) => basename(e.location));
+    const errorFiles = result.issues.map((e) => basename(e.location ?? ''));
     expect(errorFiles).toContain('guide-invalid-category.md');
     expect(errorFiles).toContain('guide-missing-required.md');
     expect(errorFiles).toContain('doc-invalid-status.md');
@@ -89,7 +89,7 @@ describe('Collection validation with test fixtures', () => {
     // Valid files should have no errors
     const validFiles = ['guide-valid.md', 'doc-valid.md', 'code-reviewer-SKILL.md'];
     const validFileErrors = result.issues.filter(
-      (i) => validFiles.some((f) => i.location.includes(f))
+      (i) => validFiles.some((f) => i.location?.includes(f))
     );
 
     expect(validFileErrors).toHaveLength(0);
@@ -101,7 +101,7 @@ describe('Collection validation with test fixtures', () => {
     // Find enum validation error (invalid category)
     const categoryError = result.issues.find(
       (i) =>
-        i.location.includes('guide-invalid-category.md') &&
+        i.location?.includes('guide-invalid-category.md') &&
         i.message.includes('category')
     );
     expect(categoryError).toBeDefined();
@@ -111,7 +111,7 @@ describe('Collection validation with test fixtures', () => {
     // Find missing required field error
     const missingError = result.issues.find(
       (i) =>
-        i.location.includes('guide-missing-required.md') &&
+        i.location?.includes('guide-missing-required.md') &&
         i.message.includes('title')
     );
     expect(missingError).toBeDefined();
@@ -120,7 +120,7 @@ describe('Collection validation with test fixtures', () => {
     // Find pattern validation error (kebab-case)
     const patternError = result.issues.find(
       (i) =>
-        i.location.includes('badName-SKILL.md') &&
+        i.location?.includes('badName-SKILL.md') &&
         i.message.includes('name')
     );
     expect(patternError).toBeDefined();
@@ -138,7 +138,7 @@ describe('Collection validation with test fixtures', () => {
 
     // Guide collection uses strict schema (additionalProperties: false)
     // Valid guide has no extra fields, should pass
-    const validGuide = registry.getResourceById('valid-guide-valid');
+    const validGuide = registry.getResourceById('valid-guide-valid-md');
     expect(validGuide).toBeDefined();
   });
 
@@ -152,7 +152,7 @@ describe('Collection validation with test fixtures', () => {
 
     // doc-valid.md has custom_field and another_custom which should be allowed
     const docErrors = result.issues.filter(
-      (i) => i.location.includes('doc-valid.md')
+      (i) => i.location?.includes('doc-valid.md')
     );
     expect(docErrors).toHaveLength(0);
   });
@@ -163,8 +163,8 @@ describe('Collection validation with test fixtures', () => {
     // Skills collection should catch multiple error types
     const skillErrors = result.issues.filter(
       (i) =>
-        i.location.includes('-SKILL.md') &&
-        !i.location.includes('code-reviewer')
+        i.location?.includes('-SKILL.md') &&
+        !i.location?.includes('code-reviewer')
     );
 
     // 4 invalid skill files
@@ -182,7 +182,7 @@ describe('Collection validation with test fixtures', () => {
 
     // Verify short-description error is present (one of the 4 skill errors)
     expect(skillErrors.some((e) =>
-      e.location.includes('short-description-SKILL.md')
+      e.location?.includes('short-description-SKILL.md')
     )).toBe(true);
   });
 
diff --git a/packages/resources/test/integration/link-validator-gitignore.integration.test.ts b/packages/resources/test/integration/link-validator-gitignore.integration.test.ts
index 5f8fe150..3bc3f630 100644
--- a/packages/resources/test/integration/link-validator-gitignore.integration.test.ts
+++ b/packages/resources/test/integration/link-validator-gitignore.integration.test.ts
@@ -15,8 +15,7 @@ import path from 'node:path';
 import { normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { validateLink } from '../../src/link-validator.js';
-import type { HeadingNode } from '../../src/types.js';
+import { fragmentIndex, validateLink } from '../../src/link-validator.js';
 import { isWithinProject } from '../../src/utils.js';
 import { createGitRepo, createLink, setupTempDirTestSuite } from '../test-helpers.js';
 
@@ -73,7 +72,7 @@ async function validateWithGitIgnoreCheck(
   projectRoot: string
 ) {
   const link = createLink('local_file', linkHref, 'Test link', 2);
-  const headingsMap = new Map<string, HeadingNode[]>();
+  const headingsMap = fragmentIndex();
 
   return await validateLink(link, sourceFile, headingsMap, {
     projectRoot,
diff --git a/packages/resources/test/integration/link-validator.integration.test.ts b/packages/resources/test/integration/link-validator.integration.test.ts
index 4f239947..f3920340 100644
--- a/packages/resources/test/integration/link-validator.integration.test.ts
+++ b/packages/resources/test/integration/link-validator.integration.test.ts
@@ -10,12 +10,16 @@
  */
 
 
+import { writeFile } from 'node:fs/promises';
+
+/* eslint-disable security/detect-non-literal-fs-filename -- tests use dynamic file paths in temp directory */
+
 import { mkdirSyncReal, normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from 'vitest';
 
-import { validateLink } from '../../src/link-validator.js';
-import type { HeadingNode } from '../../src/types.js';
-import { assertValidation, createGitRepo, createHeadings, createLink } from '../test-helpers.js';
+import { fragmentIndex, validateLink, type FragmentIndex } from '../../src/link-validator.js';
+import { ResourceRegistry } from '../../src/resource-registry.js';
+import { assertValidation, createGitRepo, createLink, setupSubdirTestSuite } from '../test-helpers.js';
 
 /**
  * Helper to test that a non-ignored file linking to a gitignored file returns an error
@@ -23,7 +27,7 @@ import { assertValidation, createGitRepo, createHeadings, createLink } from '../
 async function assertGitignoreError(gitRoot: string, linkHref: string, linkText: string): Promise<void> {
   const sourceFile = safePath.join(gitRoot, 'source.md');
   const link = createLink('local_file', linkHref, linkText, 1);
-  const headingsMap = new Map<string, HeadingNode[]>();
+  const headingsMap = fragmentIndex();
 
   await assertValidation(
     {
@@ -61,12 +65,32 @@ const NONEXISTENT_FILE_LINK = './nonexistent.md';
 const NONEXISTENT_ANCHOR = '#nonexistent';
 const TARGET_FILE_LINK = './target.md';
 
+/**
+ * Build the standard headings map used in anchor-validation tests:
+ * a single entry mapping `sourceFile` to the slug of HEADING_ANCHOR_HEADING.
+ */
+function makeAnchorHeadingsMap(sourceFile: string): FragmentIndex {
+  return fragmentIndex([
+    [sourceFile, new Set([HEADING_ANCHOR_HEADING.slug.toLowerCase()])],
+  ]);
+}
+
+/**
+ * Crawl a directory into a fresh ResourceRegistry and run validation.
+ * Extracted to eliminate the repeated 3-line setup in cross-format anchor tests.
+ */
+async function crawlAndValidate(dir: string): Promise<Awaited<ReturnType<ResourceRegistry['validate']>>> {
+  const reg = new ResourceRegistry({ baseDir: dir });
+  await reg.crawl({ baseDir: dir });
+  return reg.validate({ skipGitIgnoreCheck: true });
+}
+
 describe('validateLink', () => {
   describe('local_file links', () => {
     it('should validate valid relative path', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('local_file', TARGET_FILE_LINK, 'Link to target', 3);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -76,7 +100,7 @@ describe('validateLink', () => {
     it('should validate valid relative path with ../', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, 'subdir', 'nested.md');
       const link = createLink('local_file', '../target.md', 'Link to parent', 1);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -89,7 +113,7 @@ describe('validateLink', () => {
         {
           sourceFile: safePath.join(FIXTURES_DIR, BROKEN_FILE_MD),
           link: createLink('local_file', NONEXISTENT_FILE_LINK, 'Broken link', 3),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex(),
           expected: {
             code: 'LINK_BROKEN_FILE',
             messageContains: ['File not found', 'nonexistent.md'],
@@ -118,7 +142,7 @@ describe('validateLink', () => {
           {
             sourceFile,
             link: createLink('local_file', './testfile.md', 'Wrong case link', 3),
-            headingsMap: new Map<string, HeadingNode[]>(),
+            headingsMap: fragmentIndex(),
             expected: {
               code: 'LINK_BROKEN_FILE',
               messageContains: ['case mismatch', 'TestFile.md', 'testfile.md'],
@@ -137,8 +161,8 @@ describe('validateLink', () => {
       const targetFile = safePath.join(FIXTURES_DIR, TARGET_MD);
       const link = createLink('local_file', './target.md#valid-anchor', 'Link with anchor', 5);
 
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [targetFile, createHeadings(VALID_ANCHOR_HEADING)],
+      const headingsMap = fragmentIndex([
+        [targetFile, new Set([VALID_ANCHOR_HEADING.slug.toLowerCase()])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -153,8 +177,8 @@ describe('validateLink', () => {
         {
           sourceFile: safePath.join(FIXTURES_DIR, 'broken-anchor.md'),
           link: createLink('local_file', './target.md#nonexistent-heading', 'Broken anchor', 3),
-          headingsMap: new Map<string, HeadingNode[]>([
-            [targetFile, createHeadings(VALID_ANCHOR_HEADING)],
+          headingsMap: fragmentIndex([
+            [targetFile, new Set([VALID_ANCHOR_HEADING.slug.toLowerCase()])],
           ]),
           expected: {
             code: 'LINK_BROKEN_ANCHOR',
@@ -174,7 +198,7 @@ describe('validateLink', () => {
       // leading-/ branch entirely).
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('local_file', '/does/not/exist.md', 'Absolute path');
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -196,7 +220,7 @@ describe('validateLink', () => {
         fs.writeFileSync(sourceFile, '');
 
         const link = createLink('local_file', 'files/My%20Document%20Name.pdf', 'PDF link', 3);
-        const headingsMap = new Map<string, HeadingNode[]>();
+        const headingsMap = fragmentIndex();
 
         const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -215,9 +239,7 @@ describe('validateLink', () => {
         {
           sourceFile,
           link: createLink('anchor', '#heading-anchor', 'Anchor link', 5),
-          headingsMap: new Map<string, HeadingNode[]>([
-            [sourceFile, createHeadings(HEADING_ANCHOR_HEADING)],
-          ]),
+          headingsMap: makeAnchorHeadingsMap(sourceFile),
           expected: null,
         },
         expect,
@@ -231,9 +253,7 @@ describe('validateLink', () => {
         {
           sourceFile,
           link: createLink('anchor', NONEXISTENT_ANCHOR, 'Broken anchor', 10),
-          headingsMap: new Map<string, HeadingNode[]>([
-            [sourceFile, createHeadings(HEADING_ANCHOR_HEADING)],
-          ]),
+          headingsMap: makeAnchorHeadingsMap(sourceFile),
           expected: {
             code: 'LINK_BROKEN_ANCHOR',
             messageContains: ['Anchor not found', NONEXISTENT_ANCHOR],
@@ -250,9 +270,7 @@ describe('validateLink', () => {
         {
           sourceFile,
           link: createLink('anchor', '#HEADING-ANCHOR', 'Case mismatch', 5),
-          headingsMap: new Map<string, HeadingNode[]>([
-            [sourceFile, createHeadings(HEADING_ANCHOR_HEADING)],
-          ]),
+          headingsMap: makeAnchorHeadingsMap(sourceFile),
           expected: null,
         },
         expect,
@@ -263,17 +281,8 @@ describe('validateLink', () => {
       const sourceFile = safePath.join(FIXTURES_DIR, 'complex.md');
       const link = createLink('anchor', '#nested-child', 'Nested heading', 10);
 
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [sourceFile, createHeadings({
-          text: 'Parent Heading',
-          slug: 'parent-heading',
-          level: 2,
-          children: createHeadings({
-            text: 'Nested Child',
-            slug: 'nested-child',
-            level: 3,
-          }),
-        })],
+      const headingsMap = fragmentIndex([
+        [sourceFile, new Set(['parent-heading', 'nested-child'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -287,7 +296,7 @@ describe('validateLink', () => {
         {
           sourceFile: safePath.join(FIXTURES_DIR, VALID_MD),
           link: createLink('anchor', '#any-heading', 'No headings', 5),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex([[safePath.join(FIXTURES_DIR, VALID_MD), new Set<string>()]]),
           expected: {
             code: 'LINK_BROKEN_ANCHOR',
           },
@@ -301,7 +310,7 @@ describe('validateLink', () => {
     it('should return null for HTTP URL (external links not validated)', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('external', 'http://example.com', 'HTTP link', 6);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -311,7 +320,7 @@ describe('validateLink', () => {
     it('should return null for HTTPS URL (external links not validated)', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('external', 'https://example.com/path', 'HTTPS link', 7);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -323,7 +332,7 @@ describe('validateLink', () => {
     it('should return null for valid email', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('email', 'mailto:test@example.com', 'Email link', 8);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -333,7 +342,7 @@ describe('validateLink', () => {
     it('should return null for email without mailto:', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('email', 'test@example.com', 'Plain email', 9);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -348,7 +357,7 @@ describe('validateLink', () => {
         {
           sourceFile: safePath.join(FIXTURES_DIR, VALID_MD),
           link: createLink('unknown', 'ftp://example.com/file', 'FTP link', 10),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex(),
           expected: {
             code: 'LINK_UNKNOWN',
             messageContains: 'Unknown link type',
@@ -365,7 +374,7 @@ describe('validateLink', () => {
         {
           sourceFile: safePath.join(FIXTURES_DIR, VALID_MD),
           link: createLink('unknown', 'tel:+1234567890', 'Tel link', 11),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex(),
           expected: {
             code: 'LINK_UNKNOWN',
           },
@@ -379,7 +388,7 @@ describe('validateLink', () => {
     it('should handle Unix-style paths', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('local_file', TARGET_FILE_LINK, 'Unix path');
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -390,7 +399,7 @@ describe('validateLink', () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       // Node's path.resolve will normalize this correctly on all platforms
       const link = createLink('local_file', './subdir/nested.md', 'Mixed path');
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -404,8 +413,8 @@ describe('validateLink', () => {
       const link = createLink('anchor', '#heading-anchor', 'No line number');
       delete link.line;
 
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [sourceFile, createHeadings({ text: 'Heading Anchor', slug: 'heading-anchor' })],
+      const headingsMap = fragmentIndex([
+        [sourceFile, new Set(['heading-anchor'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -417,8 +426,8 @@ describe('validateLink', () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('anchor', '#', 'Empty anchor', 5);
 
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [sourceFile, createHeadings({ text: 'Heading', slug: 'heading' })],
+      const headingsMap = fragmentIndex([
+        [sourceFile, new Set(['heading'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -430,7 +439,7 @@ describe('validateLink', () => {
     it('should handle file path with anchor where file does not exist', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('local_file', './nonexistent.md#heading', 'Broken file with anchor', 5);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -448,8 +457,8 @@ describe('validateLink', () => {
       const link = createLink('local_file', '#heading', 'Anchor as file', 5);
 
       const targetFile = safePath.join(FIXTURES_DIR, 'target.md');
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [targetFile, createHeadings({ text: 'Heading', slug: 'heading' })],
+      const headingsMap = fragmentIndex([
+        [targetFile, new Set(['heading'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -461,27 +470,8 @@ describe('validateLink', () => {
       const sourceFile = safePath.join(FIXTURES_DIR, 'complex.md');
       const link = createLink('anchor', '#deeply-nested', 'Deep nesting', 20);
 
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [sourceFile, createHeadings({
-          text: 'Level 1',
-          slug: 'level-1',
-          level: 1,
-          children: createHeadings({
-            text: 'Level 2',
-            slug: 'level-2',
-            level: 2,
-            children: createHeadings({
-              text: 'Level 3',
-              slug: 'level-3',
-              level: 3,
-              children: createHeadings({
-                text: 'Deeply Nested',
-                slug: 'deeply-nested',
-                level: 4,
-              }),
-            }),
-          }),
-        })],
+      const headingsMap = fragmentIndex([
+        [sourceFile, new Set(['level-1', 'level-2', 'level-3', 'deeply-nested'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -494,7 +484,7 @@ describe('validateLink', () => {
     it('should include all required fields in error issue', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, BROKEN_FILE_MD);
       const link = createLink('local_file', NONEXISTENT_FILE_LINK, 'Broken', 3);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -514,7 +504,7 @@ describe('validateLink', () => {
     it('should include empty suggestion in broken file issue', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, BROKEN_FILE_MD);
       const link = createLink('local_file', NONEXISTENT_FILE_LINK, 'Broken');
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       const result = await validateLink(link, sourceFile, headingsMap);
 
@@ -525,8 +515,8 @@ describe('validateLink', () => {
     it('should include empty suggestion in broken anchor issue', async () => {
       const sourceFile = safePath.join(FIXTURES_DIR, VALID_MD);
       const link = createLink('anchor', NONEXISTENT_ANCHOR, 'Broken');
-      const headingsMap = new Map<string, HeadingNode[]>([
-        [sourceFile, createHeadings({ text: 'Valid', slug: 'valid' })],
+      const headingsMap = fragmentIndex([
+        [sourceFile, new Set(['valid'])],
       ]);
 
       const result = await validateLink(link, sourceFile, headingsMap);
@@ -591,7 +581,7 @@ describe('validateLink', () => {
       fs.writeFileSync(sourceFile, '# Source');
 
       const link = createLink('local_file', TARGET_FILE_LINK, 'Link to target', 1);
-      const headingsMap = new Map<string, HeadingNode[]>();
+      const headingsMap = fragmentIndex();
 
       await assertValidation(
         {
@@ -629,6 +619,74 @@ describe('validateLink', () => {
     });
   });
 
+  describe('cross-format anchor validation', () => {
+    const suite = setupSubdirTestSuite('cross-format-suite-');
+
+    beforeAll(suite.beforeAll);
+    afterAll(suite.afterAll);
+    beforeEach(suite.beforeEach);
+
+    it('validates markdown → HTML anchors and flags missing ones', async () => {
+      // guide.md links to page.html#intro (valid) and page.html#nope (broken)
+      await writeFile(
+        safePath.join(suite.tempDir, 'guide.md'),
+        '[a](./page.html#intro)\n[b](./page.html#nope)\n',
+        'utf-8',
+      );
+      await writeFile(
+        safePath.join(suite.tempDir, 'page.html'),
+        '<html><body><h2 id="intro">Intro</h2></body></html>',
+        'utf-8',
+      );
+
+      const result = await crawlAndValidate(suite.tempDir);
+
+      const brokenAnchors = result.issues.filter((i) => i.code === 'LINK_BROKEN_ANCHOR');
+      // Only #nope should be flagged; #intro is a valid HTML id
+      expect(brokenAnchors).toHaveLength(1);
+      expect(brokenAnchors[0]?.message).toContain('nope');
+    });
+
+    it('validates HTML → markdown anchors (zero broken-anchor)', async () => {
+      // page.html links to guide.md#my-heading — heading slug matches
+      await writeFile(
+        safePath.join(suite.tempDir, 'page.html'),
+        '<html><body><a href="./guide.md#my-heading">x</a></body></html>',
+        'utf-8',
+      );
+      await writeFile(
+        safePath.join(suite.tempDir, 'guide.md'),
+        '## My Heading\n',
+        'utf-8',
+      );
+
+      const result = await crawlAndValidate(suite.tempDir);
+
+      const brokenAnchors = result.issues.filter((i) => i.code === 'LINK_BROKEN_ANCHOR');
+      expect(brokenAnchors).toHaveLength(0);
+    });
+
+    it('skips anchor check for a non-indexed target file', async () => {
+      // doc.md links to external.md#whatever — external.md is NOT present/crawled
+      await writeFile(
+        safePath.join(suite.tempDir, 'doc.md'),
+        '[x](./external.md#whatever)\n',
+        'utf-8',
+      );
+      // external.md intentionally absent
+
+      const result = await crawlAndValidate(suite.tempDir);
+
+      const brokenFiles = result.issues.filter((i) => i.code === 'LINK_BROKEN_FILE');
+      const brokenAnchors = result.issues.filter((i) => i.code === 'LINK_BROKEN_ANCHOR');
+
+      // The file is missing → LINK_BROKEN_FILE emitted
+      expect(brokenFiles.length).toBeGreaterThan(0);
+      // But no LINK_BROKEN_ANCHOR — target is un-indexed so anchor check is skipped
+      expect(brokenAnchors).toHaveLength(0);
+    });
+  });
+
   describe('leading-/ links (RFC 3986 §4.2 absolute-path reference)', () => {
     let projectRoot: string;
     let sourceFile: string;
@@ -653,7 +711,7 @@ describe('validateLink', () => {
 
     it('resolves /docs/foo.md against projectRoot', async () => {
       const link = createLink('local_file', '/docs/foo.md', 'Leading slash', 1);
-      const result = await validateLink(link, sourceFile, new Map<string, HeadingNode[]>(), {
+      const result = await validateLink(link, sourceFile, fragmentIndex(), {
         projectRoot,
         skipGitIgnoreCheck: true,
       });
@@ -662,7 +720,7 @@ describe('validateLink', () => {
 
     it('emits absolute_no_root broken_file when projectRoot is undefined', async () => {
       const link = createLink('local_file', '/docs/foo.md', 'Leading slash', 1);
-      const result = await validateLink(link, sourceFile, new Map<string, HeadingNode[]>(), {
+      const result = await validateLink(link, sourceFile, fragmentIndex(), {
         skipGitIgnoreCheck: true,
       });
       expect(result).not.toBeNull();
@@ -672,7 +730,7 @@ describe('validateLink', () => {
 
     it('emits absolute_escapes_root broken_file when leading-/ escapes projectRoot', async () => {
       const link = createLink('local_file', '/../escape.md', 'Escape', 1);
-      const result = await validateLink(link, sourceFile, new Map<string, HeadingNode[]>(), {
+      const result = await validateLink(link, sourceFile, fragmentIndex(), {
         projectRoot,
         skipGitIgnoreCheck: true,
       });
@@ -683,13 +741,10 @@ describe('validateLink', () => {
 
     it('resolves anchor on leading-/ link', async () => {
       const link = createLink('local_file', '/docs/foo.md#section-a', 'Leading slash anchor', 1);
-      const headings = new Map<string, HeadingNode[]>([
+      const headings = fragmentIndex([
         [
           safePath.join(projectRoot, 'docs', 'foo.md'),
-          createHeadings(
-            { text: 'Foo', slug: 'foo', level: 1 },
-            { text: 'Section A', slug: 'section-a', level: 2 },
-          ),
+          new Set(['foo', 'section-a']),
         ],
       ]);
       const result = await validateLink(link, sourceFile, headings, {
@@ -705,7 +760,7 @@ describe('validateLink', () => {
         {
           sourceFile,
           link: createLink('local_file', '/docs/', 'Directory target', 1),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex(),
           expected: { code: 'LINK_BROKEN_FILE', messageContains: 'Link target is a directory' },
           validationOptions: { projectRoot, skipGitIgnoreCheck: true },
         },
@@ -719,7 +774,7 @@ describe('validateLink', () => {
         {
           sourceFile,
           link: createLink('local_file', '../', 'Relative directory target', 1),
-          headingsMap: new Map<string, HeadingNode[]>(),
+          headingsMap: fragmentIndex(),
           expected: { code: 'LINK_BROKEN_FILE', messageContains: 'Link target is a directory' },
           validationOptions: { projectRoot, skipGitIgnoreCheck: true },
         },
diff --git a/packages/resources/test/integration/resource-parser.integration.test.ts b/packages/resources/test/integration/resource-parser.integration.test.ts
index 1bedb87a..8996185d 100644
--- a/packages/resources/test/integration/resource-parser.integration.test.ts
+++ b/packages/resources/test/integration/resource-parser.integration.test.ts
@@ -3,11 +3,10 @@
  * Tests parsing real markdown, JSON, and YAML files with proper resource type detection
  */
 
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 
-
-import { normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { safePath } from '@vibe-agent-toolkit/utils';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 
 import {
   detectResourceType,
@@ -17,6 +16,7 @@ import {
   parseYamlResource,
 } from '../../src/types/resource-parser.ts';
 import { ResourceType } from '../../src/types/resources.ts';
+import { setupSubdirTestSuite } from '../test-helpers.js';
 
 // ============================================================================
 // File-scope test constants (accessible to all tests)
@@ -34,33 +34,13 @@ const CONFIG_YAML_FILE = 'config.yaml';
 // Test suite setup
 // ============================================================================
 
-let testCounter = 0;
-const suite = {
-  suiteDir: '',
-  tempDir: '',
-  beforeAll: async () => {
-    suite.suiteDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'resource-parser-suite-'));
-  },
-  afterAll: async () => {
-    await rm(suite.suiteDir, { recursive: true, force: true });
-  },
-  beforeEach: async () => {
-    testCounter++;
-    suite.tempDir = safePath.join(suite.suiteDir, `test-${testCounter}`);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- tempDir is from mkdtemp
-    await mkdir(suite.tempDir, { recursive: true });
-  },
-  afterEach: async () => {
-    // Per-test cleanup handled by suite cleanup
-  },
-};
+const suite = setupSubdirTestSuite('resource-parser-suite-');
 
 describe('parseMarkdownResource', () => {
 
   beforeAll(suite.beforeAll);
   afterAll(suite.afterAll);
   beforeEach(suite.beforeEach);
-  afterEach(suite.afterEach);
 
   it('should parse markdown with frontmatter', async () => {
     const filePath = safePath.join(suite.tempDir, 'doc.md');
@@ -202,7 +182,6 @@ describe('parseJsonSchemaResource', () => {
   beforeAll(suite.beforeAll);
   afterAll(suite.afterAll);
   beforeEach(suite.beforeEach);
-  afterEach(suite.afterEach);
 
   it('should parse JSON Schema with $schema keyword', async () => {
     const filePath = safePath.join(suite.tempDir, USER_SCHEMA_FILE);
@@ -281,7 +260,6 @@ describe('parseJsonSchemaResource', () => {
 
 describe('parseJsonResource', () => {
   beforeEach(suite.beforeEach);
-  afterEach(suite.afterEach);
 
   it('should parse regular JSON data', async () => {
     const filePath = safePath.join(suite.tempDir, 'data.json');
@@ -331,7 +309,6 @@ describe('parseJsonResource', () => {
 
 describe('parseYamlResource', () => {
   beforeEach(suite.beforeEach);
-  afterEach(suite.afterEach);
 
   it('should parse YAML data', async () => {
     const filePath = safePath.join(suite.tempDir, CONFIG_YAML_FILE);
diff --git a/packages/resources/test/integration/resource-registry.integration.test.ts b/packages/resources/test/integration/resource-registry.integration.test.ts
index 11739950..b11374b5 100644
--- a/packages/resources/test/integration/resource-registry.integration.test.ts
+++ b/packages/resources/test/integration/resource-registry.integration.test.ts
@@ -16,7 +16,7 @@ import { describe, expect, it, beforeEach, afterEach, beforeAll, afterAll } from
 
 import { ResourceRegistry } from '../../src/resource-registry.js';
 import type { ResourceMetadata } from '../../src/types.js';
-import { findPackageRoot } from '../test-helpers.js';
+import { findPackageRoot, setupSubdirTestSuite } from '../test-helpers.js';
 
 // Get test fixtures directory
 const packageRoot = findPackageRoot(import.meta.dirname);
@@ -24,10 +24,10 @@ const fixturesDir = safePath.join(packageRoot, 'test-fixtures');
 
 // Constants for commonly used file names and patterns (avoid string duplication)
 const BROKEN_FILE_MD = 'broken-file.md';
-const BROKEN_FILE_ID = 'broken-file';
+const BROKEN_FILE_ID = 'broken-file-md';
 const EXTERNAL_MD = 'external.md';
 const VALID_MD_PATTERN = '**/valid.md';
-const NESTED_FILE_ID = 'subdir-nested';
+const NESTED_FILE_ID = 'subdir-nested-md';
 
 // Helper to extract resource IDs (avoids nested arrow functions in tests)
 function extractResourceIds(resources: ResourceMetadata[]): string[] {
@@ -47,6 +47,20 @@ async function createDuplicateNamedFiles(baseDirectory: string): Promise<void> {
   await writeFile(safePath.join(baseDirectory, 'dir2', 'readme.md'), '# Dir 2', 'utf-8');
 }
 
+/**
+ * Validate a registry and assert exactly one `DUPLICATE_RESOURCE_ID` error issue,
+ * returning it so the caller can assert on its message. Shared by the
+ * duplicate-id collision tests to avoid repeating the validate/filter/assert tail.
+ */
+async function expectSingleDuplicateIdError(reg: ResourceRegistry) {
+  const result = await reg.validate({ skipGitIgnoreCheck: true });
+  const dupIssues = result.issues.filter((i) => i.code === 'DUPLICATE_RESOURCE_ID');
+  expect(dupIssues).toHaveLength(1);
+  const issue = dupIssues[0];
+  expect(issue?.severity).toBe('error');
+  return issue;
+}
+
 describe('ResourceRegistry - Integration Tests', () => {
   let registry: ResourceRegistry;
 
@@ -69,7 +83,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       const resource = await registry.addResource(validPath);
 
       expect(resource).toBeDefined();
-      expect(resource.id).toBe('valid');
+      expect(resource.id).toBe('valid-md');
       expect(resource.filePath).toBe(validPath);
       expect(resource.links.length).toBeGreaterThan(0);
       expect(resource.headings.length).toBeGreaterThan(0);
@@ -100,7 +114,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       const resource1 = await registry.addResource(validPath);
       const resource2 = await registry.addResource(brokenPath);
 
-      expect(resource1.id).toBe('valid');
+      expect(resource1.id).toBe('valid-md');
       expect(resource2.id).toBe(BROKEN_FILE_ID);
     });
 
@@ -108,12 +122,12 @@ describe('ResourceRegistry - Integration Tests', () => {
       const validPath = safePath.join(fixturesDir, 'valid.md');
 
       const resource1 = await registry.addResource(validPath);
-      expect(resource1.id).toBe('valid');
+      expect(resource1.id).toBe('valid-md');
 
       // Re-adding same path should succeed (update in place)
       const resource2 = await registry.addResource(validPath);
-      expect(resource2.id).toBe('valid');
-      expect(registry.getResourceById('valid')).toBeDefined();
+      expect(resource2.id).toBe('valid-md');
+      expect(registry.getResourceById('valid-md')).toBeDefined();
     });
 
     it('should normalize relative paths to absolute', async () => {
@@ -188,9 +202,9 @@ describe('ResourceRegistry - Integration Tests', () => {
       expect(resources.length).toBeGreaterThanOrEqual(6);
 
       const ids = resources.map((r) => r.id);
-      expect(ids).toContain('valid');
+      expect(ids).toContain('valid-md');
       expect(ids).toContain(BROKEN_FILE_ID);
-      expect(ids).toContain('target');
+      expect(ids).toContain('target-md');
     });
 
     it('should respect include patterns', async () => {
@@ -200,7 +214,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       });
 
       expect(resources).toHaveLength(1);
-      expect(resources[0]?.id).toBe('valid');
+      expect(resources[0]?.id).toBe('valid-md');
     });
 
     it('should respect exclude patterns', async () => {
@@ -288,7 +302,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       const result = await registry.validate();
 
       // Filter to only issues from valid.md
-      const validIssues = result.issues.filter((i) => i.location.endsWith('valid.md'));
+      const validIssues = result.issues.filter((i) => i.location?.endsWith('valid.md'));
 
       // Should have no errors from valid.md
       expect(validIssues).toHaveLength(0);
@@ -324,7 +338,7 @@ describe('ResourceRegistry - Integration Tests', () => {
 
       registry.resolveLinks();
 
-      const validResource = registry.getResourceById('valid');
+      const validResource = registry.getResourceById('valid-md');
       expect(validResource).toBeDefined();
 
       const localFileLinks = validResource?.links.filter((link) => link.type === 'local_file');
@@ -339,7 +353,7 @@ describe('ResourceRegistry - Integration Tests', () => {
 
       // Verify resolved IDs are correct
       const targetLink = localFileLinks?.find((link) => link.href.includes('target.md'));
-      expect(targetLink?.resolvedId).toBe('target');
+      expect(targetLink?.resolvedId).toBe('target-md');
     });
 
     it('should not set resolvedId for non-existent targets', async () => {
@@ -361,7 +375,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       await registry.addResource(safePath.join(fixturesDir, 'valid.md'));
       await registry.addResource(safePath.join(fixturesDir, 'target.md'));
 
-      const validResource = registry.getResourceById('valid');
+      const validResource = registry.getResourceById('valid-md');
       const originalLinks = validResource?.links;
 
       registry.resolveLinks();
@@ -371,7 +385,7 @@ describe('ResourceRegistry - Integration Tests', () => {
 
       // But now has resolvedId
       const targetLink = validResource?.links.find((link) => link.href.includes('target.md'));
-      expect(targetLink?.resolvedId).toBe('target');
+      expect(targetLink?.resolvedId).toBe('target-md');
     });
   });
 
@@ -386,7 +400,7 @@ describe('ResourceRegistry - Integration Tests', () => {
         const resource = registry.getResource(validPath);
 
         expect(resource).toBeDefined();
-        expect(resource?.id).toBe('valid');
+        expect(resource?.id).toBe('valid-md');
       });
 
       it('should get resource by relative path', () => {
@@ -397,7 +411,7 @@ describe('ResourceRegistry - Integration Tests', () => {
         const resource = registry.getResource(relativePath);
 
         expect(resource).toBeDefined();
-        expect(resource?.id).toBe('valid');
+        expect(resource?.id).toBe('valid-md');
       });
 
       it('should return undefined for non-existent path', () => {
@@ -408,7 +422,7 @@ describe('ResourceRegistry - Integration Tests', () => {
 
     describe('getResourceById()', () => {
       it('should get resource by ID', () => {
-        const resource = registry.getResourceById('valid');
+        const resource = registry.getResourceById('valid-md');
 
         expect(resource).toBeDefined();
         expect(resource?.filePath).toContain('valid.md');
@@ -440,7 +454,7 @@ describe('ResourceRegistry - Integration Tests', () => {
         const resources = registry.getResourcesByPattern(VALID_MD_PATTERN);
 
         expect(resources.length).toBe(1);
-        expect(resources[0]?.id).toBe('valid');
+        expect(resources[0]?.id).toBe('valid-md');
       });
 
       it('should match multiple resources with wildcard', () => {
@@ -450,7 +464,7 @@ describe('ResourceRegistry - Integration Tests', () => {
         // Extract ids mapping to avoid nested arrow function
         const resourceIds = extractResourceIds(resources);
         expect(resourceIds).toContain(BROKEN_FILE_ID);
-        expect(resourceIds).toContain('broken-anchor');
+        expect(resourceIds).toContain('broken-anchor-md');
       });
 
       it('should match nested files', () => {
@@ -518,7 +532,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       registry.clear();
 
       expect(registry.getAllResources()).toHaveLength(0);
-      expect(registry.getResourceById('valid')).toBeUndefined();
+      expect(registry.getResourceById('valid-md')).toBeUndefined();
       expect(registry.getStats().totalResources).toBe(0);
     });
 
@@ -529,32 +543,16 @@ describe('ResourceRegistry - Integration Tests', () => {
       await registry.addResource(safePath.join(fixturesDir, 'target.md'));
 
       expect(registry.getAllResources()).toHaveLength(1);
-      expect(registry.getResourceById('target')).toBeDefined();
+      expect(registry.getResourceById('target-md')).toBeDefined();
     });
   });
 
   describe('validate with frontmatter schema', () => {
-    let suiteDir: string;
-    let tempDir: string;
-    let testCounter = 0;
-
-    beforeAll(async () => {
-      suiteDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'frontmatter-suite-'));
-    });
+    const suite = setupSubdirTestSuite('frontmatter-suite-');
 
-    afterAll(async () => {
-      await rm(suiteDir, { recursive: true, force: true });
-    });
-
-    beforeEach(async () => {
-      testCounter++;
-      tempDir = safePath.join(suiteDir, `test-${testCounter}`);
-      await mkdir(tempDir, { recursive: true });
-    });
-
-    afterEach(async () => {
-      // Per-test cleanup handled by suite cleanup
-    });
+    beforeAll(suite.beforeAll);
+    afterAll(suite.afterAll);
+    beforeEach(suite.beforeEach);
 
     it('should validate frontmatter against schema and report missing required fields', async () => {
       const registry = new ResourceRegistry();
@@ -589,7 +587,7 @@ describe('ResourceRegistry - Integration Tests', () => {
       const registry = new ResourceRegistry();
 
       // Create a file with invalid YAML
-      const invalidYamlPath = safePath.join(tempDir, 'invalid-yaml.md');
+      const invalidYamlPath = safePath.join(suite.tempDir, 'invalid-yaml.md');
       await writeFile(
         invalidYamlPath,
         `---
@@ -623,7 +621,7 @@ tags: test
 
       // Should overwrite (path map) but keep same ID
       expect(registry.getAllResources()).toHaveLength(1);
-      expect(registry.getResourceById('valid')).toBeDefined();
+      expect(registry.getResourceById('valid-md')).toBeDefined();
     });
 
     it('should handle empty directories gracefully', async () => {
@@ -651,7 +649,7 @@ tags: test
       // Any file should work, as headings are optional
       await registry.addResource(safePath.join(fixturesDir, EXTERNAL_MD));
 
-      const resource = registry.getResourceById('external');
+      const resource = registry.getResourceById('external-md');
       expect(resource).toBeDefined();
 
       // Should handle validation even with no headings
@@ -682,8 +680,8 @@ tags: test
         const r1 = await reg.addResource(safePath.join(tempDir, 'docs', 'guide.md'));
         const r2 = await reg.addResource(safePath.join(tempDir, 'api', 'reference.md'));
 
-        expect(r1.id).toBe('docs-guide');
-        expect(r2.id).toBe('api-reference');
+        expect(r1.id).toBe('docs-guide-md');
+        expect(r2.id).toBe('api-reference-md');
       });
 
       it('should handle files at baseDir root without directory prefix', async () => {
@@ -692,7 +690,7 @@ tags: test
         const reg = new ResourceRegistry({ baseDir: tempDir });
         const resource = await reg.addResource(safePath.join(tempDir, 'readme.md'));
 
-        expect(resource.id).toBe('readme');
+        expect(resource.id).toBe('readme-md');
       });
 
       it('should avoid collisions for same-named files in different dirs', async () => {
@@ -702,8 +700,8 @@ tags: test
         const r1 = await reg.addResource(safePath.join(tempDir, 'dir1', 'readme.md'));
         const r2 = await reg.addResource(safePath.join(tempDir, 'dir2', 'readme.md'));
 
-        expect(r1.id).toBe('dir1-readme');
-        expect(r2.id).toBe('dir2-readme');
+        expect(r1.id).toBe('dir1-readme-md');
+        expect(r2.id).toBe('dir2-readme-md');
       });
 
       it('should propagate baseDir from crawl() when not set on constructor', async () => {
@@ -719,8 +717,8 @@ tags: test
         expect(reg.baseDir).toBe(tempDir);
 
         // IDs should be path-relative, not filename stems
-        const r1 = reg.getResourceById('dir1-readme');
-        const r2 = reg.getResourceById('dir2-readme');
+        const r1 = reg.getResourceById('dir1-readme-md');
+        const r2 = reg.getResourceById('dir2-readme-md');
         expect(r1).toBeDefined();
         expect(r2).toBeDefined();
       });
@@ -732,7 +730,7 @@ tags: test
         const reg = new ResourceRegistry({ baseDir: tempDir });
         const resource = await reg.addResource(safePath.join(tempDir, 'concepts', 'core', 'overview.md'));
 
-        expect(resource.id).toBe('concepts-core-overview');
+        expect(resource.id).toBe('concepts-core-overview-md');
       });
     });
 
@@ -756,7 +754,7 @@ tags: test
         const reg = new ResourceRegistry({ idField: 'slug' });
         const resource = await reg.addResource(safePath.join(tempDir, 'doc.md'));
 
-        expect(resource.id).toBe('doc');
+        expect(resource.id).toBe('doc-md');
       });
 
       it('should fall back to path-based ID when idField not in frontmatter but baseDir set', async () => {
@@ -771,7 +769,7 @@ tags: test
         const resource = await reg.addResource(safePath.join(tempDir, 'guides', 'intro.md'));
 
         // No 'slug' in frontmatter → falls back to path-relative ID
-        expect(resource.id).toBe('guides-intro');
+        expect(resource.id).toBe('guides-intro-md');
       });
 
       it('should prioritize frontmatter ID over path-based ID', async () => {
@@ -811,18 +809,20 @@ tags: test
       });
 
       it('should throw when frontmatter ID collides with path-based ID', async () => {
+        // first.md has no slug → path-based id = 'first-md'
         await writeFile(safePath.join(tempDir, 'first.md'), '# First', 'utf-8');
+        // second.md has slug: first-md → frontmatter id = 'first-md' → collision
         await writeFile(
           safePath.join(tempDir, 'second.md'),
-          '---\nslug: first\n---\n# Second',
+          '---\nslug: first-md\n---\n# Second',
           'utf-8'
         );
 
         const reg = new ResourceRegistry({ idField: 'slug' });
-        await reg.addResource(safePath.join(tempDir, 'first.md')); // ID = 'first'
+        await reg.addResource(safePath.join(tempDir, 'first.md')); // ID = 'first-md'
         await expect(
-          reg.addResource(safePath.join(tempDir, 'second.md')) // frontmatter slug = 'first'
-        ).rejects.toThrow(/Duplicate resource ID 'first'/);
+          reg.addResource(safePath.join(tempDir, 'second.md')) // frontmatter slug = 'first-md'
+        ).rejects.toThrow(/Duplicate resource ID 'first-md'/);
       });
 
       it('should throw on duplicate resource ID from different files without baseDir', async () => {
@@ -832,7 +832,7 @@ tags: test
         await reg.addResource(safePath.join(tempDir, 'dir1', 'readme.md'));
         await expect(
           reg.addResource(safePath.join(tempDir, 'dir2', 'readme.md'))
-        ).rejects.toThrow(/Duplicate resource ID 'readme'/);
+        ).rejects.toThrow(/Duplicate resource ID 'readme-md'/);
       });
 
       it('should detect duplicates in fromResources', () => {
@@ -858,18 +858,137 @@ tags: test
         ).toThrow(/Duplicate resource ID 'readme'/);
       });
 
-      it('should detect duplicates in addResources', async () => {
+      it('should record duplicate-id collisions in addResources and surface them via validate()', async () => {
         await createDuplicateNamedFiles(tempDir);
 
-        // Without baseDir, both produce 'readme' → duplicate
+        // Without baseDir, both produce 'readme-md' → duplicate.
+        // addResources() now captures the collision rather than throwing; the
+        // first-added file wins and the second is skipped. validate() surfaces
+        // the collision as a DUPLICATE_RESOURCE_ID error.
         const reg = new ResourceRegistry();
         await expect(
           reg.addResources([
             safePath.join(tempDir, 'dir1', 'readme.md'),
             safePath.join(tempDir, 'dir2', 'readme.md'),
           ])
-        ).rejects.toThrow(/Duplicate resource ID 'readme'/);
+        ).resolves.not.toThrow();
+
+        const issue = await expectSingleDuplicateIdError(reg);
+        expect(issue?.message).toMatch(/readme-md/);
       });
     });
   });
+
+  describe('HTML resource discovery', () => {
+    let htmlTempDir: string;
+
+    beforeEach(async () => {
+      htmlTempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'html-discovery-test-'));
+    });
+
+    afterEach(async () => {
+      await rm(htmlTempDir, { recursive: true, force: true });
+    });
+
+    it('discovers and parses HTML resources', async () => {
+      await writeFile(
+        safePath.join(htmlTempDir, 'page.html'),
+        '<a href="./next.html">n</a>',
+        'utf-8',
+      );
+      const reg = new ResourceRegistry({ baseDir: htmlTempDir });
+      await reg.crawl({ baseDir: htmlTempDir });
+      const html = reg.getAllResources().find((r) => r.filePath.endsWith('page.html'));
+      expect(html).toBeDefined();
+      expect(html?.links.map((l) => l.href)).toContain('./next.html');
+    });
+
+    it('produces distinct ids for foo.md and foo.html in the same directory', async () => {
+      // Acceptance test: the original crash was caused by foo.md and foo.html
+      // colliding on the same bare id. With extension suffixes they are distinct.
+      await writeFile(safePath.join(htmlTempDir, 'foo.md'), '# Foo md', 'utf-8');
+      await writeFile(safePath.join(htmlTempDir, 'foo.html'), '<h1>Foo html</h1>', 'utf-8');
+
+      const reg = new ResourceRegistry({ baseDir: htmlTempDir });
+      // Must not throw
+      await reg.crawl({ baseDir: htmlTempDir });
+
+      const resources = reg.getAllResources();
+      const ids = resources.map((r) => r.id);
+      expect(ids).toContain('foo-md');
+      expect(ids).toContain('foo-html');
+      // Confirm they are truly distinct (no deduplication / crash)
+      expect(new Set(ids).size).toBe(ids.length);
+    });
+
+    it('emits MALFORMED_HTML info issues for HTML parse errors', async () => {
+      // A malformed HTML file: unclosed <p> tag triggers a parse5 diagnostic
+      await writeFile(
+        safePath.join(htmlTempDir, 'bad.html'),
+        '<html><body><p>unclosed</body></html>',
+        'utf-8',
+      );
+      const reg = new ResourceRegistry({ baseDir: htmlTempDir });
+      await reg.crawl({ baseDir: htmlTempDir });
+      const result = await reg.validate({ skipGitIgnoreCheck: true });
+
+      const malformedIssues = result.issues.filter((i) => i.code === 'MALFORMED_HTML');
+      expect(malformedIssues.length).toBeGreaterThan(0);
+      expect(malformedIssues[0]?.severity).toBe('info');
+    });
+  });
+
+  describe('Duplicate resource ID (graceful handling)', () => {
+    let dupTempDir: string;
+
+    beforeEach(async () => {
+      dupTempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'dup-id-test-'));
+    });
+
+    afterEach(async () => {
+      await rm(dupTempDir, { recursive: true, force: true });
+    });
+
+    it('crawl() does not throw and validate() emits DUPLICATE_RESOURCE_ID error when two same-extension files produce the same id', async () => {
+      // 'My Guide.md' and 'my-guide.md' both normalise to 'my-guide-md' after Task 1's
+      // extension suffix. This is the canonical same-extension collision scenario.
+      await writeFile(safePath.join(dupTempDir, 'My Guide.md'), '# My Guide', 'utf-8');
+      await writeFile(safePath.join(dupTempDir, 'my-guide.md'), '# my guide', 'utf-8');
+
+      const reg = new ResourceRegistry({ baseDir: dupTempDir });
+
+      // crawl() must not throw
+      await expect(reg.crawl({ baseDir: dupTempDir })).resolves.not.toThrow();
+
+      const issue = await expectSingleDuplicateIdError(reg);
+      // Message must name both colliding paths and the shared id
+      expect(issue?.message).toMatch(/my-guide-md/);
+      expect(issue?.message).toMatch(/My Guide\.md/);
+      expect(issue?.message).toMatch(/my-guide\.md/);
+    });
+
+    it('addResources() does not throw and validate() emits DUPLICATE_RESOURCE_ID with correct paths when two files collide via idField frontmatter slug', async () => {
+      // Both files declare the same frontmatter slug value → same idField-derived ID.
+      // Before the fix the catch block re-derived the id via generateIdFromPath, which
+      // would produce 'beta-md' (not 'shared-slug'), so resourcesById.get('beta-md')
+      // returned undefined and existingPath was recorded as '' — making the emitted
+      // DUPLICATE_RESOURCE_ID issue report an empty existingPath.
+      const fileA = safePath.join(dupTempDir, 'alpha.md');
+      const fileB = safePath.join(dupTempDir, 'beta.md');
+      await writeFile(fileA, '---\nslug: shared-slug\n---\n# Alpha', 'utf-8');
+      await writeFile(fileB, '---\nslug: shared-slug\n---\n# Beta', 'utf-8');
+
+      const reg = new ResourceRegistry({ baseDir: dupTempDir, idField: 'slug' });
+
+      // addResources() must not throw
+      await expect(reg.addResources([fileA, fileB])).resolves.not.toThrow();
+
+      const issue = await expectSingleDuplicateIdError(reg);
+      // The reported id must be the frontmatter slug, NOT a path-derived id
+      expect(issue?.message).toMatch(/shared-slug/);
+      // Both file names must appear — existingPath must not be '' (the pre-fix bug)
+      expect(issue?.message).toMatch(/alpha\.md/);
+      expect(issue?.message).toMatch(/beta\.md/);
+    });
+  });
 });
diff --git a/packages/resources/test/link-validator-helpers.test.ts b/packages/resources/test/link-validator-helpers.test.ts
index 757201db..603d2686 100644
--- a/packages/resources/test/link-validator-helpers.test.ts
+++ b/packages/resources/test/link-validator-helpers.test.ts
@@ -9,7 +9,9 @@
 import { describe, expect, it } from 'vitest';
 
 import {
+  checkAnchor,
   fileExistenceIssue,
+  fragmentIndex,
   gitIgnoreSafetyIssue,
   resolutionFailureIssue,
   type ValidateLinkOptions,
@@ -125,6 +127,54 @@ describe('fileExistenceIssue', () => {
   });
 });
 
+describe('checkAnchor', () => {
+  const GUIDE_MD = '/abs/guide.md';
+  const PAGE_HTML = '/abs/page.html';
+  const PAGE_HTM = '/abs/legacy.htm';
+  const index = fragmentIndex([
+    [GUIDE_MD, new Set(['my-heading'])],
+    [PAGE_HTML, new Set(['Intro', 'legacy'])],
+    [PAGE_HTM, new Set(['Section'])],
+  ]);
+
+  it('skips targets that are not indexed', () => {
+    expect(checkAnchor('anything', '/abs/not-indexed.md', index)).toBe('skip');
+  });
+
+  it('matches markdown slugs case-insensitively', () => {
+    expect(checkAnchor('My-Heading', GUIDE_MD, index)).toBe('valid');
+    expect(checkAnchor('missing', GUIDE_MD, index)).toBe('broken');
+  });
+
+  it('matches HTML ids case-sensitively', () => {
+    expect(checkAnchor('Intro', PAGE_HTML, index)).toBe('valid');
+    expect(checkAnchor('intro', PAGE_HTML, index)).toBe('broken');
+  });
+
+  it('treats the empty fragment and "top" (case-insensitive) as valid on HTML targets', () => {
+    // HTML spec: `#` and `#top` always navigate to the top of the document,
+    // valid even though neither id is in the index.
+    expect(checkAnchor('', PAGE_HTML, index)).toBe('valid');
+    expect(checkAnchor('top', PAGE_HTML, index)).toBe('valid');
+    expect(checkAnchor('TOP', PAGE_HTML, index)).toBe('valid');
+    expect(checkAnchor('Top', PAGE_HTML, index)).toBe('valid');
+  });
+
+  it('does not special-case empty/"top" for markdown targets', () => {
+    // Markdown behavior is untouched: neither is a real heading slug here.
+    expect(checkAnchor('', GUIDE_MD, index)).toBe('broken');
+    expect(checkAnchor('top', GUIDE_MD, index)).toBe('broken');
+  });
+
+  it('applies the HTML matching rules to the .htm extension too', () => {
+    // .htm is HTML: case-sensitive ids + empty/top navigation, same as .html.
+    expect(checkAnchor('Section', PAGE_HTM, index)).toBe('valid');
+    expect(checkAnchor('section', PAGE_HTM, index)).toBe('broken');
+    expect(checkAnchor('', PAGE_HTM, index)).toBe('valid');
+    expect(checkAnchor('top', PAGE_HTM, index)).toBe('valid');
+  });
+});
+
 describe('gitIgnoreSafetyIssue', () => {
   it('returns null when skipGitIgnoreCheck is true', () => {
     expect(
diff --git a/packages/resources/test/metadata-schema.test.ts b/packages/resources/test/metadata-schema.test.ts
index 4ef520ce..b63b7ab6 100644
--- a/packages/resources/test/metadata-schema.test.ts
+++ b/packages/resources/test/metadata-schema.test.ts
@@ -1,6 +1,5 @@
 import { describe, it, expect } from 'vitest';
 
-
 import { ResourceMetadataSchema } from '../src/schemas/resource-metadata.js';
 
 describe('ResourceMetadataSchema with checksum', () => {
@@ -63,3 +62,30 @@ describe('ResourceMetadataSchema with checksum', () => {
     }
   });
 });
+
+describe('ResourceMetadataSchema HTML fields', () => {
+  const base = {
+    id: 'x',
+    filePath: '/abs/x.html',
+    links: [],
+    headings: [],
+    sizeBytes: 1,
+    estimatedTokenCount: 1,
+    modifiedAt: new Date(),
+    checksum: 'a'.repeat(64),
+  };
+
+  it('accepts optional anchors and parseErrors', () => {
+    const parsed = ResourceMetadataSchema.parse({
+      ...base,
+      anchors: ['intro'],
+      parseErrors: [{ message: 'missing-end-tag', line: 3 }],
+    });
+    expect(parsed.anchors).toEqual(['intro']);
+    expect(parsed.parseErrors?.[0]?.message).toBe('missing-end-tag');
+  });
+
+  it('rejects unknown top-level fields (strict)', () => {
+    expect(() => ResourceMetadataSchema.parse({ ...base, bogus: 1 })).toThrow();
+  });
+});
diff --git a/packages/resources/test/test-helpers.ts b/packages/resources/test/test-helpers.ts
index f5cc275f..051e2d77 100644
--- a/packages/resources/test/test-helpers.ts
+++ b/packages/resources/test/test-helpers.ts
@@ -5,7 +5,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { normalizedTmpdir, safePath } from '@vibe-agent-toolkit/utils';
@@ -13,7 +13,7 @@ import { expect, type Assertion } from 'vitest';
 
 import { ExternalLinkValidator } from '../src/external-link-validator.js';
 import { parseMarkdown } from '../src/link-parser.js';
-import type { ValidateLinkOptions as LinkValidatorOptions } from '../src/link-validator.js';
+import type { FragmentIndex, ValidateLinkOptions as LinkValidatorOptions } from '../src/link-validator.js';
 import { validateLink } from '../src/link-validator.js';
 import { ResourceRegistry } from '../src/resource-registry.js';
 import type { HeadingNode, ResourceLink, ValidationIssue } from '../src/types.js';
@@ -184,6 +184,54 @@ export function setupTempDirTestSuite(testPrefix: string): {
   return suite;
 }
 
+/**
+ * Setup a suite-scoped temp directory with per-test subdirectories.
+ *
+ * Creates a single `suiteDir` once for the whole `describe` block, then
+ * allocates a numbered subdirectory (`test-1`, `test-2`, …) for each test so
+ * that tests are isolated without paying the cost of creating and deleting a
+ * fresh top-level temp directory for every test.  The suite directory is
+ * removed in `afterAll`.
+ *
+ * Lifecycle wiring (call inside the target `describe` block):
+ * ```typescript
+ * const suite = setupSubdirTestSuite('my-suite-');
+ * beforeAll(suite.beforeAll);
+ * afterAll(suite.afterAll);
+ * beforeEach(suite.beforeEach);
+ * ```
+ *
+ * @param suitePrefix - Prefix for the suite-level temp directory
+ * @returns Object with `suiteDir`/`tempDir` refs and lifecycle hook callbacks
+ */
+export function setupSubdirTestSuite(suitePrefix: string): {
+  suiteDir: string;
+  tempDir: string;
+  beforeAll: () => Promise<void>;
+  afterAll: () => Promise<void>;
+  beforeEach: () => Promise<void>;
+} {
+  let testCounter = 0;
+  const suite = {
+    suiteDir: '',
+    tempDir: '',
+    beforeAll: async () => {
+      suite.suiteDir = await mkdtemp(safePath.join(normalizedTmpdir(), suitePrefix));
+    },
+    afterAll: async () => {
+      await rm(suite.suiteDir, { recursive: true, force: true });
+    },
+    beforeEach: async () => {
+      testCounter++;
+      suite.tempDir = safePath.join(suite.suiteDir, `test-${testCounter}`);
+      // eslint-disable-next-line security/detect-non-literal-fs-filename -- suite.tempDir is constructed from mkdtemp output, safe in test context
+      await mkdir(suite.tempDir, { recursive: true });
+    },
+  };
+
+  return suite;
+}
+
 /**
  * Setup external link validator test suite with temp directory and validator.
  *
@@ -240,20 +288,6 @@ export function createLink(
   };
 }
 
-/**
- * Helper to create a simple heading tree
- */
-export function createHeadings(
-  ...headings: Array<{ text: string; slug: string; level?: number; children?: HeadingNode[] }>
-): HeadingNode[] {
-  return headings.map((h) => ({
-    text: h.text,
-    slug: h.slug,
-    level: h.level ?? 2,
-    children: h.children,
-  }));
-}
-
 /**
  * Options for validating a link with expected results
  */
@@ -262,8 +296,8 @@ export interface ValidateLinkOptions {
   sourceFile: string;
   /** Link to validate */
   link: ResourceLink;
-  /** Headings map for validation */
-  headingsMap: Map<string, HeadingNode[]>;
+  /** Fragment index for anchor validation (file path → set of valid fragments) */
+  headingsMap: FragmentIndex;
   /** Expected validation result (null = valid, object = error) */
   expected: null | {
     code: ValidationIssue['code'];