seo-internal-linking (M10)

Internal links distribute crawl priority and topical authority and tell search engines (and AI crawlers) how your pages relate. Reference: references/schema-tier1.md for the entity/@id linkage this topology should mirror; M6/seo-entity-linking owns external sameAs.

Audits

Working from the PageSnapshot (rendered_dom if present, else raw_html):

Pillar/cluster topology: classify each URL (pillar hub vs. cluster page) and confirm clusters link up to their pillar and the pillar links down to its cluster — gaps break the hub-and-spoke model.
Contextual in-body links: count links inside <main>/<article> prose (target ~3-5 descriptive in-content links per page); flag pages with zero in-body internal links.
Anchor-text descriptiveness: flag generic anchors ("click here", "read more", "learn more", bare URLs) and over-optimized exact-match repetition; anchors should describe the destination.
Orphan pages: list URLs in the sitemap/crawl with no incoming internal links from other crawled pages.
Nav-vs-in-content ratio: flag templates where boilerplate nav/footer links overwhelm contextual links, diluting per-page link signal.
Semantic HTML: check for <main>, <article>, <nav>, <header>, <footer>, one <h1>, and a logical heading order — semantic structure helps both parsers and accessibility.

Fixes

PROPOSED (fixable: proposed): concrete internal-link insertions — a specific source page, the target URL, the suggested anchor text, and the sentence/selector to attach it to — emitted as a unified diff for fix. These require per-item accept because auto-injecting body links can alter meaning, tone, or reading flow.
ADVISORY (fixable: advisory): wrapping content in semantic tags (<main>/<article>/<nav>) and heading-order corrections — described, never written by the tool, since they touch template structure.
Never invent target URLs, anchor wording, or topology you cannot observe in the snapshot/crawl — ask the user or leave a clearly-marked TODO placeholder. (Severity for this module's findings: 3.)