Titles, descriptions and canonicals, fixed at the source

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

# Titles, descriptions and canonicals, fixed at the source

The title, meta description and canonical URL decide how each page of the production site appears in search results and which URL gets the credit. Duplicates, missing descriptions and wrong canonicals are among the most common technical SEO problems, and they are almost always caused by one shared layout. Fix them once, at the source, for every page type.

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.
- Change URLs or slugs (that needs redirects and its own plan).

## 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. Inventory

For every page type (home, static pages, each dynamic template, paginated lists, filtered views), show what the title, description and canonical would be, and where each comes from. Flag duplicates across pages, titles over about 60 characters, descriptions missing or over about 155 characters, and canonicals that point at the homepage or at a different page.

### 2. One metadata helper

Route every page through one helper that takes the page's own title, description and canonical path and outputs the title, meta description, canonical link, and the matching Open Graph and X fields.

- **Titles:** unique, the specific thing first, the brand last ("Invoice templates for freelancers | Acme"), about 50 to 60 characters.
- **Descriptions:** written per page or built from the page's own data (a product's summary, a post's excerpt), about 120 to 155 characters, never the same sentence everywhere.
- **Canonicals:** absolute, self-referencing for normal pages, lowercase, one form for trailing slashes, and without tracking parameters.

### 3. Pagination, filters and duplicates

Page 2 and later of a list should be self-canonical (not pointing at page 1) and have "Page 2" in the title. Filtered or sorted views that only reorder the same items should canonicalise to the unfiltered page or be `noindex`. Pages reachable at two URLs (with and without `www`, with and without a trailing slash, old slugs) should redirect to one, not just carry a canonical.

### 4. Guard it

Add a test (or a build check) that fails when two indexable routes share a title, when a page has no description, or when a canonical is relative or points elsewhere unexpectedly. Use the project's existing test setup.

## Done means

- [ ] Every indexable page has a unique title with the brand last and a page-specific description.
- [ ] Every page has an absolute, self-referencing canonical unless it intentionally points elsewhere.
- [ ] Paginated pages are self-canonical with the page number in the title.
- [ ] All page metadata comes from one helper.
- [ ] A test fails on duplicate titles, missing descriptions or bad canonicals.

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