Internal linking audit and fix

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Internal linking audit and fix

Search engines find and weigh pages of the production site through its internal links. Pages nothing links to (orphans) are found late or not at all, broken links waste crawls, and 'click here' anchors say nothing about the target. Audit the link structure and fix it with links generated from the site's own data, so new pages are linked from the moment they exist.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Add links to external sites.
- Change the main navigation design without showing me first.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Build the link graph

From the routes and templates (or a crawl of the local build), work out which pages link to which. Report: orphan pages (in the sitemap or routes but linked from nowhere), pages more than three clicks from the homepage, broken internal links, links that go through a redirect, and the most common anchor texts.

### 2. Fix the structure

- Every indexable page is linked from at least one hub or list page, and hubs are linked from the main navigation or footer.
- Lists with many items paginate with real `<a href>` links, not only a 'load more' button.
- Links are real `<a href>` elements with descriptive anchor text ("invoice templates", not "click here").
- Links point at the final URL, not one that redirects.

### 3. Related links from data

Add a 'related' block to content templates (posts, product pages, docs) built from data: same category or tag, shared keywords, or a hand-picked list where one exists. Keep it to three to six links, exclude the page itself, and make sure it renders in the server HTML.

### 4. Fix the broken ones and guard

Fix or remove every broken internal link. Add a test or build step that fails on internal links to routes that do not exist.

## Done means

- [ ] No indexable page is an orphan.
- [ ] Every indexable page is within three clicks of the homepage.
- [ ] No internal link is broken or goes through a redirect.
- [ ] Content templates show related links built from data, in the server HTML.
- [ ] A check fails the build on broken internal links.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.