# AGENTS.md — apps/web

## `.well-known` routes

`apps/web/src/app/.well-known/` is a dot-directory, and TypeScript's `include`
wildcards skip those. Files under it are outside the tsconfig program, so path
aliases (`@/…`) do not resolve and nothing there is type-checked as part of the
app. Use relative imports (or node built-ins, as
`.well-known/agent-skills/index.json/route.ts` does) and check the output by
requesting the route.

## Search

The ⌘K search is homegrown: the ranker lives in `apps/web/src/app/api/search`
and the index in `apps/web/src/content/utils/search-index.ts`. Do not reach for
Pagefind, Orama or Algolia.

## Content pages

Content pages are MDX prose built from the existing components (`Grid`,
`Details`, …). Reach for those before inventing a bespoke layout.

Never link out to a competitor. Name them as plain text — an external link
donates domain authority and leaks the conversion.

The home and product pages (`pages/home.mdx`, `pages/product/*.mdx`) follow one
section pattern: an `h2` outside the grid, a text cell with two sentences and a
short list of internal links, and one `<Demo type="…" />` in the other cell of
a `<Grid variant="borderless">`. `content-lint.test.ts` enforces the structural
rules on those pages (registered tags, `SrOnly` next to every demo, no raw
`className`, every demo type in the kitchen sink); the rest of the rules below
are kept by hand and in review. `/kitchen-sink` (noindex) renders every
component once so drift is visible.

- Props are enums, not free JSX. `Demo` picks from `mdx-components/demo/index.tsx`;
  a new demo is a new key there, reviewed in a PR. MDX never composes status
  blocks by hand.
- Demos are compositions, not prop bags. They nest the `Cell*` parts from
  `demo/cell.tsx`, the `Slack*` parts from `demo/slack.tsx`, the block
  compositions in `demo/status-blocks.tsx` and `demo/subscribe.tsx`, and the
  `@openstatus/ui` status blocks. A repeated visual is a new part in one of
  those files, never a `title`/`items` prop or a copied class stack.
- A `<Demo>` is a picture, so the `<SrOnly>` block next to it says what it
  shows: visually hidden on the page, read by screen readers, plain copy in
  the `.md` representation (`convert.ts` unwraps it). The lint requires one in
  every section that holds a demo. Its numbers come from `data/demo-data.ts`,
  like the demo's do. Search skips it, since a hit would highlight nothing.
- One data file per concern. `data/customers.ts` feeds `LogoCloud` and `Quote`
  (the `/customers` listing comes from `pages/customers/*.mdx`).
  `data/demo-data.ts` (one fictional company, one incident) feeds every demo,
  so every demo on every page tells the same story; `demo.audit` is the
  timeline of record, and every timestamp in a demo comes from `auditRow()`.
  `--radius` is 0 on this site, so a `rounded-*` class in a demo is dead code.
- No raw `className` in `pages/`. A CTA row is `<Actions source="…">`, which
  appends the tracking `ref` to app links; never hand-write `?ref=`.
- Every capitalised tag must be registered in `mdx-components/index.tsx`.
- No new colours beyond tokens, no font sizes beyond the prose scale, no radius.
  Dark mode comes from tokens only; images get a `.dark` sibling.