From 8f324bb573c1bea9e81089ab2c91a7b6a2195825 Mon Sep 17 00:00:00 2001
From: Damian <hi@damianrosellen.de>
Date: Thu, 28 May 2026 17:55:45 +0200
Subject: [PATCH] docs(readme): polish for public release
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructure and tighten the root README for publication while keeping
every existing piece of accurate technical content.

What changed:
- Stronger lead: one-line tagline + a row of shields.io badges for
  Next, React, Sanity, TypeScript, Tailwind, Biome, license. No emoji.
- New "Two flavours" section right under the lead — surfaces the
  variant/document-level branch and links to PR #62 (the permanent
  side-by-side comparison and decision guide).
- "What you get" reflows the previous dense bullet sprawl into themed
  paragraphs (Next.js app, Studio, Media, Revalidation, SEO, Hardened
  defaults, Typed GROQ, Tailwind v4). Each block reads like a feature
  card, not a checklist.
- Quickstart split into clean steps instead of one bash block with
  inline numbered comments.
- "Architecture in brief" replaces the long "Core APIs & modules"
  tables; depth moves into the per-folder READMEs (already linked).
- New "License" footer; the "Requirements" block moves to the bottom
  where it belongs (you don't read it before you're sold on the repo).
- Fixed an orphan link to `packages/sanity-dataset-resolve/README.md`
  (file doesn't exist; resolver is documented inline in `src/index.ts`).
- The strip-readmes utility gets one explicit mention so consumers know
  the documentation density is opt-in.

Net result: 271 → 213 lines, 0 emoji, all links resolve.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 266 +++++++++++++++++++++---------------------------------
 1 file changed, 104 insertions(+), 162 deletions(-)

diff --git a/README.md b/README.md
index be2d2810..12800426 100644
--- a/README.md
+++ b/README.md
@@ -1,209 +1,132 @@
-# Next.js + Sanity monorepo
+# next-sanity-boilerplate
 
-Opinionated boilerplate for a **multi-language, CMS-driven site** built on **Next.js 16 (App Router, React 19)** and **Sanity Studio v5**, with optional **Mux** video and **Netlify** hosting integrations. Designed to stay slim: no unused features, production-grade defaults, and a clear path from `git clone` → first page.
+> A production-shaped starting point for a multi-language, CMS-driven site — **Next.js 16** App Router, **React 19**, **Sanity Studio v5**, with optional **Mux** video and **Netlify** hosting.
+
+[![Next.js 16](https://img.shields.io/badge/Next.js-16.2-000?logo=next.js&logoColor=white)](https://nextjs.org)
+[![React 19](https://img.shields.io/badge/React-19.2-149eca?logo=react&logoColor=white)](https://react.dev)
+[![Sanity v5](https://img.shields.io/badge/Sanity-5.27-f03e2f?logo=sanity&logoColor=white)](https://www.sanity.io)
+[![TypeScript 6](https://img.shields.io/badge/TypeScript-6-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Tailwind v4](https://img.shields.io/badge/Tailwind-4-38bdf8?logo=tailwindcss&logoColor=white)](https://tailwindcss.com)
+[![Biome](https://img.shields.io/badge/Biome-2.4-60a5fa?logo=biome&logoColor=white)](https://biomejs.dev)
+[![License: ISC](https://img.shields.io/badge/license-ISC-green)](LICENSE)
+
+It stays slim on purpose: no unused features, production-grade defaults, and a clear path from `git clone` to first published page. Documentation lives next to the code that needs it — strip the per-folder READMEs with `pnpm strip-readmes` once you're ready to ship.
 
 ---
 
-## Table of contents
+## Two flavours
+
+This boilerplate ships in **two parallel variants** so you can pick the internationalisation model that matches your editorial workflow:
+
+| Branch | i18n strategy | Pick when |
+|---|---|---|
+| **[`main`](../../tree/main)** | Field-level via `sanity-plugin-internationalized-array` | All translations of one piece of content live in one document with language tabs per field; short, UI-shaped translations. |
+| **[`variant/document-level`](../../tree/variant/document-level)** | Document-level via `@sanity/document-internationalization` | Each language is its own document — different slugs, modules, SEO per locale. GROQ does the locale matching; no runtime resolver. |
 
-- [Monorepo layout](#monorepo-layout)
-- [Feature highlights](#feature-highlights)
-- [Requirements](#requirements)
-- [Quickstart](#quickstart)
-- [Environment & dataset resolution](#environment--dataset-resolution)
-- [Core APIs & modules](#core-apis--modules)
-- [Scripts reference](#scripts-reference)
-- [Tooling](#tooling)
-- [Deployment notes](#deployment-notes)
-- [Learn more](#learn-more)
+[**PR #62**](../../pull/62) keeps a permanent side-by-side comparison + decision guide for adopters. Neither branch is a downgrade of the other; both are production-shaped.
 
 ---
 
-## Monorepo layout
+## What you get
 
-Managed with **pnpm workspaces** (`pnpm-workspace.yaml`: `web`, `studio`, `packages/*`).
+**Next.js app** — App Router with locale-aware routing (`[locale]/[slug]`), `generateStaticParams`, ISR-style revalidation via cache tags, fully wired Sanity Draft Mode + Visual Editing (`SanityLive`, Presentation, stega). `SanityLive` only mounts when it's actually useful (read token present or draft mode active).
 
-| Package | Path | Role |
-|---------|------|------|
-| **Web** | `web/` | Next.js 16 App Router app — i18n routing, GROQ data fetching, Portable Text, Mux, sitemap/robots, cache-tag revalidation |
-| **Studio** | `studio/` | Sanity Studio v5 — schema, plugins, Presentation (Visual Editing), dev/prod dataset sync |
-| **`@repo/sanity-dataset-resolve`** | `packages/sanity-dataset-resolve/` | Shared dev/prod dataset resolution used by **both** web and Studio |
-| **`@repo/strip-readmes`** | `packages/strip-readmes/` | Internal utility to bulk-clean documentation during exports |
+**Sanity Studio v5** — Vision, Dashboard, Presentation with configurable preview origin, runtime language tabs driven by a `siteLanguageSettings` singleton, deploy-on-publish via Netlify plugin, safe production → development dataset clone.
 
----
+**Media pipeline** — Native `<img>` with deterministic Sanity CDN URLs, full responsive `srcset`/`sizes`, hotspot-aware `object-position`, LQIP and zero hydration drift. Mux video via the official `<MuxPlayer />` imported `/lazy`, plus a lightweight `hls.js` background-loop player that only loads when the element enters the viewport and respects `prefers-reduced-motion`.
 
-## Feature highlights
+**Hardened revalidation** — `POST /api/revalidate` does HMAC-SHA256 signature verification (Sanity signed webhooks), payload validation, a document-type allow-list, in-memory rate limiting, and is fail-closed in production.
 
-### Next.js web app
-- **App Router** with nested `[locale]/[slug]` routing, static generation (`generateStaticParams`) and ISR-style revalidation via cache tags.
-- **Localization** driven by a Sanity singleton (`siteLanguageSettings`). The schema seeds **English + German** on first create (`initialValue`); editors own the list afterward. Routing, `<html lang>`, `hreflang` alternates, and Portable Text fallbacks read from Studio; a **minimal code fallback** (`en` only) applies only when the document is missing or invalid (CI, first deploy).
-- **Draft Mode + Visual Editing** wired through `next-sanity` (`SanityLive`, Presentation overlays, stega). `<SanityLive />` only mounts when a read token is present or draft mode is active.
-- **Webhook-hardened revalidation** at `POST /api/revalidate` — HMAC-SHA256 signature check (Sanity signed webhooks), payload validation, document-type allowlist, in-memory rate limiter, fail-closed in production.
-- **SEO out of the box** — `sitemap.ts` with per-locale `alternates` + `x-default`, staging-aware `robots.ts`, `resolveSanityMetadata` → canonical + `hreflang` metadata for every page.
-- **Security headers** via `netlify.toml` — CSP with `frame-ancestors` (Studio-friendly), HSTS preload, `Permissions-Policy`, `Referrer-Policy`. Netlify `build.ignore` skips web builds on Studio-only commits.
-- **Tailwind CSS v4** + PostCSS pipeline (`@import`, `calc()`, nested ancestors, custom `rem()` helper). Design tokens live in `web/src/assets/styles/`.
+**SEO out of the box** — `sitemap.ts` with per-locale `alternates` and `x-default`, staging-aware `robots.ts`, `resolveSanityMetadata` builds canonical + `hreflang` metadata for every route.
 
-### Media pipeline (Sanity + Mux)
-- **`MediaImage`** — native `<img>` with deterministic Sanity CDN URLs, full responsive `srcset`/`sizes`, crop/hotspot-aware `object-position`, LQIP, zero hydration drift. Lazy fade-in via a tiny inline script.
-- **`MediaVideo`** — the official Mux React element **`<MuxPlayer />`** imported from `@mux/mux-player-react/lazy` (viewport-deferred JS). Poster image comes from Sanity (hotspot-aware) or Mux's `thumbnail.jpg` sized to the container.
-- **`MediaVideoLoop`** — lightweight native `<video>` HLS loop for silent hero/background clips. `hls.js` is imported **only** when the element enters the viewport, respects `prefers-reduced-motion`, and fades the poster off when the first frame decodes.
-- **Mux utilities** (`web/src/utils/muxPlayback.ts`): `extractMuxPlaybackId`, `muxHlsSrc` (with `rendition_order=desc`), `muxThumbnailUrl({width})`, `muxThumbnailRequestWidthPx`, `getMuxDisplayDimensions`.
+**Hardened by default** — CSP with `frame-ancestors` (Studio-friendly), HSTS preload, `Permissions-Policy`, `Referrer-Policy`, `X-Content-Type-Options` via `netlify.toml`. Netlify `build.ignore` skips web builds on Studio-only commits.
 
-### Sanity Studio
-- **Sanity v5** with **Vision**, **Dashboard**, **Presentation** (preview URL configurable per deploy target).
-- **`sanity-plugin-internationalized-array`** — language tabs are generated at runtime from `siteLanguageSettings`; no manual language registration.
-- **`sanity-plugin-mux-input`** for video uploads + auto-encoding.
-- **`sanity-plugin-media`** library, **`@sanity/code-input`**, **`sanity-plugin-netlify`** for deploy-on-publish workflows.
-- **Codegen**: `sanity schema extract` + `sanity typegen generate` emit typed GROQ results consumed by `web/sanity/types/`.
-- **Dataset sync**: `pnpm studio:sync-prod-to-dev` clones production content into your development dataset safely.
-
-### Internationalization (`web/src/i18n`)
-- Config loaded from Sanity at build and request time. `FALLBACK_SITE_LOCALE_CONFIG` (`web/src/i18n/fallbackSiteLocales.ts`) is a **minimal** `en`-only escape hatch so the root layout and proxy stay valid when `siteLanguageSettings` is absent or broken — not the product locale list. See [`web/src/i18n/README.md`](web/src/i18n/README.md).
-- Helpers: `createLanguagePathUtils`, `normalizeComparablePathname`, `isCurrentNavHref`, `sanityLocalizedText`.
-- Locale-aware navigation (`LanguageSwitch`) with `<option lang="…">` for assistive tech.
-
-### Developer experience
-- **Biome** for lint + format (tabs, organized imports, Tailwind-aware CSS).
-- **TypeScript** strict across the monorepo, `target: ES2022`.
-- **Husky** pre-commit and pre-push run **`pnpm run format`** (Biome `check --write` on the repo) plus **`pnpm run typecheck`** on push.
-- **GitHub Actions CI** (`.github/workflows/ci.yml`) — `pnpm run format` + diff guard, typecheck, build-web, build-studio matrix on Node 20 + 22.
-- **Published-only caching** via `web/sanity/cachedSanityQuery.ts` with `unstable_cache` + cache tags (`page`, `sitemap`, `page-slug`, `site-language-settings`) that the revalidate webhook targets.
+**Typed GROQ pipeline** — `sanity typegen` generates result types straight from the schema, gated in CI by a `git diff --exit-code` after every regeneration. (Hybrid coverage on `main`; **full coverage** on the `variant/document-level` branch — no recursive fragment to block the analyser.)
+
+**Tailwind CSS v4** — CSS-first config (`@theme`), token-driven dark mode without class hacks, PostCSS pipeline with custom `rem()` helper. Design tokens live in `web/src/assets/styles/`.
 
 ---
 
-## Requirements
+## Stack at a glance
 
-- **Node.js** LTS (20+ recommended; aligned with Next.js 16 / React 19).
-- **pnpm** 10 (`packageManager` is pinned in root `package.json`).
-- **Sanity project** with a **project id** — you'll need it for both web and Studio.
-- **(optional)** Mux API tokens if you want to upload video through the Studio.
-- **(optional)** Netlify for hosting — the included `netlify.toml` is production-ready.
+Managed with **pnpm workspaces** (`pnpm-workspace.yaml`: `web`, `studio`, `packages/*`).
+
+| Package | Path | Role |
+|---------|------|------|
+| **Web** | `web/` | Next.js 16 App Router app — i18n routing, GROQ data fetching, Portable Text, Mux, sitemap/robots, cache-tag revalidation |
+| **Studio** | `studio/` | Sanity Studio v5 — schema, plugins, Presentation, dev/prod dataset sync |
+| **`@repo/sanity-dataset-resolve`** | `packages/sanity-dataset-resolve/` | Shared dev/prod dataset resolution used by both web and Studio |
+| **`@repo/strip-readmes`** | `packages/strip-readmes/` | Bulk-clean documentation when you ship your fork |
 
 ---
 
-## Quickstart
+## Get started
 
 ```bash
-# 1. Clone & install
 git clone <your-fork>.git my-site
 cd my-site
 pnpm install
+```
 
-# 2. Env files
+Copy the env templates and set your project id (the only required variable for local dev):
+
+```bash
 cp web/.env.example     web/.env.local
 cp studio/.env.example  studio/.env
+# Set SANITY_STUDIO_PROJECT_ID in both files (same project). Everything else has sensible defaults.
+```
 
-# 3. Set SANITY_STUDIO_PROJECT_ID in both files (same project).
-#    Everything else has sensible defaults.
-
-# 4. Create a `development` dataset in Sanity (UI or CLI) — optional but
-#    recommended so you never edit production while building.
-#    Or: pin `SANITY_STUDIO_DATASET=production` to skip dataset splitting.
-
-# 5. Start Studio — open Settings → Site languages (`siteLanguageSettings`).
-#    On first create, the form is pre-filled (en + de, default en); adjust or publish as needed.
-pnpm studio:dev                     # http://localhost:3333
+Optional but recommended: create a `development` dataset in Sanity (UI or CLI) so you never edit production while iterating — or pin `SANITY_STUDIO_DATASET=production` to skip dataset splitting.
 
-# 6. Run the web app in another terminal
-pnpm web:dev                        # http://localhost:3000
+Start Studio and the web app:
 
-# (or run both at once)
-pnpm dev
+```bash
+pnpm dev               # both in parallel
+# or:
+pnpm studio:dev        # Studio at http://localhost:3333
+pnpm web:dev           # Web at http://localhost:3000
 ```
 
-### First content
-
-1. In Studio → **Settings → Site languages**, confirm or edit languages and **Default language** (defaults are filled on first create).
-2. Create a `page` document with a unique slug per locale.
-3. Visit `http://localhost:3000/<locale>/<slug>` — done.
+In Studio, open **Settings → Site languages** (pre-filled `en` + `de` on first create, default `en`), publish, then create a `page` with a unique slug. Visit `http://localhost:3000/<locale>/<slug>` — done.
 
 ---
 
-## Environment & dataset resolution
+## Environment
 
-### Variables you actually care about
+Variables you actually care about — full comments live in [`web/.env.example`](web/.env.example) and [`studio/.env.example`](studio/.env.example).
 
 | File | Variable | Required | Purpose |
 |------|----------|----------|---------|
-| `web/.env.local` + `studio/.env` | `SANITY_STUDIO_PROJECT_ID` | ✅ | Your Sanity project id |
+| `web/.env.local` + `studio/.env` | `SANITY_STUDIO_PROJECT_ID` | yes | Your Sanity project id |
 | `web/.env.local` | `SANITY_API_READ_TOKEN` | optional | Draft mode + server-side draft reads |
-| `web/.env.local` | `SANITY_REVALIDATE_SECRET` | **prod ✅** | HMAC secret for `/api/revalidate` (fail-closed in prod) |
-| `web/.env.local` | `NEXT_PUBLIC_SITE_URL` | ✅ (prod) | Used by `sitemap.ts`, `robots.ts`, metadata base |
+| `web/.env.local` | `SANITY_REVALIDATE_SECRET` | **prod yes** | HMAC secret for `/api/revalidate` (fail-closed in prod) |
+| `web/.env.local` | `NEXT_PUBLIC_SITE_URL` | yes (prod) | Used by `sitemap.ts`, `robots.ts`, metadata base |
 | both | `SANITY_STUDIO_DEPLOYMENT_TARGET` | optional | Switch dataset per environment (`staging`, `development`, …) |
-| both | `SANITY_STUDIO_DATASET` | optional | **Hard pin** a specific dataset name (skips auto-resolution) |
-| `studio/.env` | `SANITY_STUDIO_PREVIEW_ORIGIN` | ✅ (Studio) | Origin used by Presentation iframe |
+| both | `SANITY_STUDIO_DATASET` | optional | Hard pin a specific dataset name (skips auto-resolution) |
+| `studio/.env` | `SANITY_STUDIO_PREVIEW_ORIGIN` | yes (Studio) | Origin used by the Presentation iframe |
 | `studio/.env` | `SANITY_STUDIO_MUX_TOKEN_ID` / `_SECRET` | optional | Mux uploads in Studio |
 
-Full comments in [`web/.env.example`](web/.env.example) and [`studio/.env.example`](studio/.env.example).
-
 ### How `@repo/sanity-dataset-resolve` picks a dataset
 
-1. **Explicit pin** wins: `SANITY_STUDIO_DATASET` / `NEXT_PUBLIC_SANITY_DATASET`.
-2. Otherwise, `SANITY_STUDIO_DEPLOYMENT_TARGET` decides order:
+1. **Explicit pin** wins — `SANITY_STUDIO_DATASET` / `NEXT_PUBLIC_SANITY_DATASET`.
+2. Otherwise, `SANITY_STUDIO_DEPLOYMENT_TARGET` decides preference order:
    - `production` → prefer `production`, fall back to `development`.
    - `development` / `preview` / unset → prefer `development`, fall back to `production`.
 3. Canonical names are configurable (`SANITY_STUDIO_DATASET_DEVELOPMENT` / `_PRODUCTION`).
-4. If needed, the resolver can enumerate actual datasets via the Management API (`SANITY_STUDIO_DATASET_RESOLVER_TOKEN` / `SANITY_API_READ_TOKEN`) to avoid requesting a non-existent one.
+4. If needed, the resolver enumerates actual datasets via the Management API (`SANITY_STUDIO_DATASET_RESOLVER_TOKEN` / `SANITY_API_READ_TOKEN`) to avoid requesting one that doesn't exist.
 
-Used by:
-- `web/sanity/resolveStudioDataset.ts` + `web/sanity/sanityEnv.ts`
-- `studio/config/sync/studioDataset.ts`
+Consumed by `web/sanity/resolveStudioDataset.ts` + `web/sanity/sanityEnv.ts` and `studio/config/sync/studioDataset.ts`.
 
 ---
 
-## Core APIs & modules
-
-### Web — data access
-
-| Module | Purpose |
-|--------|---------|
-| `web/sanity/client.ts` | Sanity client (read + draft variants) |
-| `web/sanity/fetchSanityData.ts` | Typed GROQ fetchers — the only place that talks to Sanity from React |
-| `web/sanity/cachedSanityQuery.ts` | `unstable_cache` wrappers for published-only fetches, tagged for the revalidate webhook |
-| `web/sanity/queries/` | GROQ strings, colocated with the components that use them |
-| `web/sanity/seo/resolveSanityMetadata.ts` | Builds Next.js `Metadata` with canonical + `hreflang` |
-| `web/sanity/live.ts` | `SanityLive` client (only mounted when useful) |
-
-### Web — routing & i18n
-
-| Module | Purpose |
-|--------|---------|
-| `web/src/app/[locale]/layout.tsx` | Locale layout — injects `LanguageProvider`, navigation chrome |
-| `web/src/app/[locale]/page.tsx` / `[slug]/page.tsx` | Home + dynamic pages, use `generateStaticParams` via `cachedPageSlugs()` |
-| `web/src/app/sitemap.ts` | Multi-locale sitemap with `alternates` (and `x-default`) |
-| `web/src/app/robots.ts` | Staging-aware `robots.txt` |
-| `web/src/app/api/revalidate/route.ts` | Signed webhook → `revalidateTag` |
-| `web/src/app/api/draft-mode/disable/route.ts` | Safe same-origin redirect after disabling draft mode |
-| `web/src/i18n/siteLocalePathUtils.ts` | `createLanguagePathUtils` — prefix/strip locale, compare hrefs |
-| `web/src/proxy.ts` | Lightweight proxy to load locale config from the Sanity CDN (middleware) |
-
-### Web — media components
-
-```tsx
-import { MediaImage, MediaVideo, MediaVideoLoop } from "@/src/components/media";
-
-<MediaImage imagePayload={image} alt="…" sizes="(max-width: 900px) 100vw, 50vw" />
-
-<MediaVideo media={muxField} posterPayload={poster} videoSettings={{ autoplay: false }} />
-
-{/* Silent background loop — used automatically when videoSettings.autoplay && !controls */}
-<MediaVideoLoop media={muxField} posterPayload={poster} fillParent />
-```
-
-Each component:
-- Measures its container (`useContainerPixelWidth`) and requests exactly the image width the layout needs.
-- Handles hydration-safe URLs (deterministic `src`, no `next/image` optimizer).
-- Uses `IntersectionObserver` / `@mux/mux-player-react/lazy` for truly lazy loading.
+## Architecture in brief
 
-### Studio
+The deep-dive lives in the per-folder READMEs (see [Going deeper](#going-deeper)). The short version:
 
-| Module | Purpose |
-|--------|---------|
-| `studio/sanity.config.ts` | Studio root — registers plugins, Presentation, dataset dropdown |
-| `studio/schemas/` | Document + object schemas (pages, modules, settings) |
-| `studio/config/sync/internationalizedArrayLanguages.ts` | Builds `internationalized-array` languages from `siteLanguageSettings` |
-| `studio/config/sync/studioDataset.ts` | Uses `@repo/sanity-dataset-resolve` for the dataset dropdown |
-| `studio/scripts/sync-prod-to-dev.mjs` | Safe production → development clone |
+- **Data access** — `web/sanity/fetchSanityData.ts` is the only place React talks to Sanity; it wraps `sanityFetch` from `defineLive` for Draft Mode / Presentation. Published-only reads (sitemap, `generateStaticParams`, no-token paths) go through `web/sanity/cachedSanityQuery.ts` (`unstable_cache` + cache tags).
+- **GROQ** — strings live under `web/sanity/queries/` (snippets, page-level queries, component projections). The final queries are wrapped in `defineQuery` so `sanity typegen` emits result types.
+- **i18n** — Sanity's `siteLanguageSettings` singleton drives URL routing, `<html lang>`, `hreflang` alternates, and the language tabs in Studio. A minimal `en`-only fallback applies only when the document is missing/invalid (CI, first deploy).
+- **Media** — `<MediaImage />`, `<MediaVideo />`, `<MediaVideoLoop />` share container measurement, hydration-safe URLs, and viewport-deferred JS.
 
 ---
 
@@ -224,6 +147,7 @@ All from the repo root.
 | `pnpm format` | Biome `--write` (repo-wide) |
 | `pnpm typecheck` | Recursive `tsc --noEmit` across workspaces |
 | `pnpm update` | `pnpm up -r` for the whole repo |
+| `pnpm strip-readmes` | Remove per-folder READMEs when shipping your fork |
 
 Per-package: `pnpm --filter <web|studio> run <script>`.
 
@@ -231,41 +155,59 @@ Per-package: `pnpm --filter <web|studio> run <script>`.
 
 ## Tooling
 
-- **Biome** — root [`biome.json`](biome.json) is the single source of truth. `web/` and `studio/` call Biome via `pnpm --workspace-root exec biome …`. Studio uses a 2-space override; the rest of the repo is tabs.
+- **Biome** — root [`biome.json`](biome.json) is the single source of truth. `web/` and `studio/` call Biome via `pnpm --workspace-root exec biome …`; Studio uses a 2-space override, the rest of the repo is tabs.
 - **Husky** — `.husky/pre-commit` runs `pnpm run format`; `.husky/pre-push` runs `pnpm run format && pnpm run typecheck`.
-- **GitHub Actions** — `.github/workflows/ci.yml` runs `pnpm run format` (Biome `check --write`) + a `git diff --exit-code` guard + `pnpm run typecheck` on Node 20 & 22, `pnpm studio:generate` with a diff guard on committed `studio/schema.json` and `studio/sanity.types.gen.ts`, plus `next build` and `sanity build` smokes.
+- **GitHub Actions** — `.github/workflows/ci.yml` runs `pnpm run format` (Biome `check --write`) + a `git diff --exit-code` guard + `pnpm run typecheck` on Node 20 & 22, `pnpm studio:generate` and `pnpm --filter web run generate` with diff guards on the committed typegen artifacts, plus `next build` and `sanity build` smokes.
+- **Dependabot** — weekly npm updates, Sanity plugins grouped, `@types/node` major bumps explicitly ignored (typings track Node 22 LTS).
 - **TypeScript** — strict, ES2022 target. Root `pnpm typecheck` walks every workspace package's own `typecheck` script.
 - **Commit hygiene** — `.DS_Store`, `*.tsbuildinfo`, `coverage/`, `.cursor/` are ignored; see root `.gitignore`.
 
 ---
 
-## Deployment notes
+## Deploy
 
 ### Netlify (web)
 
 `netlify.toml` ships with:
+
 - A **dataset-aware** `build.ignore` — commits that only touch `studio/` don't rebuild the web app.
-- **Security headers**: CSP (with `frame-ancestors` allowing `sanity.studio` for Presentation), HSTS preload, `Permissions-Policy`, `Referrer-Policy`, `X-Content-Type-Options`.
+- **Security headers** — CSP (with `frame-ancestors` allowing `sanity.studio` for Presentation), HSTS preload, `Permissions-Policy`, `Referrer-Policy`, `X-Content-Type-Options`.
 - Long-lived cache for `/_next/static/*`.
 
-Set on the host:
-- `SANITY_STUDIO_PROJECT_ID`, `SANITY_API_READ_TOKEN` (optional), `SANITY_REVALIDATE_SECRET` (required in prod), `NEXT_PUBLIC_SITE_URL`, `SANITY_STUDIO_DEPLOYMENT_TARGET` (if you want to point at a non-production dataset).
+Set on the host: `SANITY_STUDIO_PROJECT_ID`, `SANITY_API_READ_TOKEN` (optional), `SANITY_REVALIDATE_SECRET` (required in prod), `NEXT_PUBLIC_SITE_URL`, `SANITY_STUDIO_DEPLOYMENT_TARGET` (only if you want to point at a non-production dataset).
 
 ### Sanity Studio
 
-- `pnpm studio:deploy` ships to Sanity's hosted Studio (`*.sanity.studio`). The deploy script forces `SANITY_STUDIO_DEPLOYMENT_TARGET=production`.
-- Configure the **Revalidate webhook** in Sanity Manage → API → Webhooks, targeting `https://<your-site>/api/revalidate` with the same `SANITY_REVALIDATE_SECRET` (signed delivery).
+`pnpm studio:deploy` ships to Sanity's hosted Studio (`*.sanity.studio`). The deploy script forces `SANITY_STUDIO_DEPLOYMENT_TARGET=production`.
+
+Configure the **Revalidate webhook** in Sanity Manage → API → Webhooks, targeting `https://<your-site>/api/revalidate` with the same `SANITY_REVALIDATE_SECRET` (signed delivery).
 
 ### Any other host (Vercel, Docker, …)
 
-Everything is standard Next.js + Sanity. Mirror the env vars and you're done. CSP / HSTS live in `netlify.toml` — port the equivalent headers to your platform's config.
+Everything is standard Next.js + Sanity — mirror the env vars and you're done. CSP / HSTS live in `netlify.toml`; port the equivalent headers to your platform's config.
 
 ---
 
-## Learn more
+## Going deeper
 
 - [`web/README.md`](web/README.md) — app-level details, module conventions.
 - [`web/sanity/README.md`](web/sanity/README.md) — GROQ layer, client config, dataset resolution.
-- [`web/src/i18n/README.md`](web/src/i18n/README.md) — localization flow end-to-end.
-- [`studio/README.md`](studio/README.md) — Studio customization, plugins, schema patterns.
-- [`packages/sanity-dataset-resolve/README.md`](packages/sanity-dataset-resolve/README.md) — resolver API + ordering rules.
+- [`web/src/i18n/README.md`](web/src/i18n/README.md) — localisation flow end-to-end.
+- [`studio/README.md`](studio/README.md) — Studio customisation, plugins, schema patterns.
+- [`packages/sanity-dataset-resolve/src/index.ts`](packages/sanity-dataset-resolve/src/index.ts) — shared dev/prod resolver, API documented inline.
+
+---
+
+## Requirements
+
+- **Node.js** LTS — 20 minimum, 22 recommended (CI tests both).
+- **pnpm** 10 (pinned in root `package.json` `packageManager`).
+- **Sanity project** with a **project id**.
+- **(optional)** Mux API tokens for video uploads.
+- **(optional)** Netlify for hosting — the included `netlify.toml` is production-ready.
+
+---
+
+## License
+
+[ISC](LICENSE). Use it, fork it, ship it.