# Discovery

What each page type tells search engines, language models and social platforms, and the one inventory every surface reads.

Discovery is the set of tags, files and images that let something outside the site find a page and describe it: search-engine metadata, structured data, a sitemap and feeds, language-model indexes and Markdown, and social preview images. All of it is built from `src/seo`, from one list of public pages, so the sitemap, `llms.txt`, the feeds and the tests cannot disagree about what exists.

## Route inventory

`routes()` in `src/seo/inventory.ts` lists every public page with its path, title, description, last-modified date, kind, social-image design, breadcrumb trail and whether it may be indexed. Docs and pieces are read from `content/`, and the résumé from its data. A new page appears in every surface by being in the inventory; no route keeps a list of its own.

## Metadata

Each route's `generateMetadata` calls `pageMetadata(path)` in `src/seo/metadata.ts`, and no route writes a tag itself. The builder emits the title, description, canonical URL, authors, keywords, Open Graph, a Twitter `summary_large_image` card, robots, and the alternate links to the page's Markdown and to both feeds. The root layout sets `metadataBase` and the title template `%s — d/rksci`.

Titles are at most 60 characters and descriptions 50 to 160, the limits of the writing guide; `bun test` fails a page outside them.

## Page types

| Page type      | Path           | Open Graph type | JSON-LD                          | Markdown          | Image design |
| -------------- | -------------- | --------------- | -------------------------------- | ----------------- | ------------ |
| Landing        | `/`            | website         | WebSite                          | `/index.md`       | landing      |
| Docs page      | `/docs/<slug>` | website         | BreadcrumbList                   | `/docs/<slug>.md` | docs         |
| Piece index    | `/research`    | website         | BreadcrumbList                   | `/research.md`    | index        |
| Feature piece  | `/<slug>`      | article         | ScholarlyArticle, BreadcrumbList | `/<slug>.md`      | feature      |
| Write-up piece | `/<slug>`      | article         | Article, BreadcrumbList          | `/<slug>.md`      | writeup      |
| Résumé         | `/blake`       | profile         | ProfilePage, BreadcrumbList      | `/blake/cv.md`    | resume       |

Every page except the landing page also carries a BreadcrumbList. A piece's Article or ScholarlyArticle has its headline, description, dates, author, image and keywords from its frontmatter; research pieces are ScholarlyArticle and labs pieces are Article. The résumé's Person and ProfilePage are built from the résumé data and add nothing the page does not show. The landing page's WebSite lists a SearchAction that points at the search endpoint, `/api/search`.

Résumé variants at `/blake/<variant>` emit the base page's tags with robots `noindex`. They are left out of the sitemap and `llms.txt` and keep a Markdown rendition of their own at `/blake/<variant>.md`.

## Indexing policy

Only Vercel production is indexable: `VERCEL_ENV=production`, or, off Vercel, a production build with `SITE_URL` set. Every other deployment sends robots `noindex, nofollow` on each page and serves a `robots.txt` that disallows everything. `sitemap.xml` lists every indexable route with its last-modified date.

## Feeds

Pieces, newest first, as RSS 2.0 at `/feed.xml` and JSON Feed 1.1 at `/feed.json`. Both are linked from the head of every page.

## Language models

`/llms.txt` indexes every page, grouped by section, with a link to its Markdown. `/llms-full.txt` holds the Markdown of all of them. Any page is at its own path plus `.md`, and the root is `/index.md`. For a piece the Markdown keeps the prose, headings, tables and links, and replaces each figure and interactive with its alt text and caption.

## Social images

Every page has a 1200 by 630 PNG at `/og/<path>/image.png` (`/og/home/image.png` for the landing page), one design per page type, each showing the title, the deck or description, and the kind or section. Colours, type sizes, spacing and font names come from the `og-*` tokens of the active theme, which `SOCIAL_THEME` can select by name. The fonts are bundled in `src/seo/image/fonts`.

## Environment

| Variable                          | Use                                            |
| --------------------------------- | ---------------------------------------------- |
| `SITE_URL`                        | The site origin. Wins over everything else.    |
| `VERCEL_PROJECT_PRODUCTION_URL`   | Origin in production when `SITE_URL` is unset. |
| `VERCEL_BRANCH_URL`, `VERCEL_URL` | Origin of a preview deployment.                |
| `VERCEL_ENV`                      | `production` makes the site indexable.         |
| `SOCIAL_THEME`                    | Optional theme name for the social images.     |

With none of these set, the origin is `http://localhost:3000` and the site is not indexable.

## Checks

`bun test` walks the inventory and fails on a missing or over-length title or description, a missing canonical, a missing social image path, a page absent from the sitemap or `llms.txt`, and a duplicate title. `bun scripts/check-site.ts <origin>` runs against a started build: every page must answer 200 with one title, one canonical and a social image that answers 200 as `image/png`.