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

Inputs

Work from the PageSnapshot named in your dispatch envelope: read

parsed

from

<run_dir>/pages/<slug>.json

(

anchors[]

with

region

internal

anchor

landmarks

) and the crawl graph in

<run_dir>/crawl.json

(

graph.edges

pages[].inlinks

templates[]

); Grep

pages/<slug>.html

for verbatim evidence; site artifacts live in

<run_dir>/site/{robots.json,sitemaps.json,discovery.json}

. Deterministic findings already emitted by

audit.mjs

are listed in

<run_dir>/findings.deterministic.json

— do not re-emit those ids; add model-judged findings only. If invoked directly with a URL/path and no snapshot exists, first run

node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs"

and use the printed snapshot path.

Working from the PageSnapshot (

parsed_rendered

when

render.used

is not

none

, else

parsed

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.

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.)

Per page:

node "${CLAUDE_PLUGIN_ROOT}/scripts/link-graph.mjs" --snapshot <pages/<slug>.json>

(or

--url <u>

--file <path> --base <origin>

) returns that page's link profile (

verification.method: link_graph

total_links

internal_unique

external_unique

in_content_target

generic_anchors

empty_anchors

dropped

. It does not compute topology from one page.

Emit findings per

schema/finding.schema.json

. Examples:

A fixed "3-5 links per page" is a usability/structure heuristic, not a ranking law — treat the count as directional and never cap a score on it alone.
Exact-match anchor stuffing and "more links = more authority" are myths: relevance and editorial context matter more than raw count, and excess can look manipulative. Recommend links only where they genuinely help the reader.