[variant — do not merge] Document-level translation (alternative to field-level i18n)

.cursor/rules/core.mdc

@@ -0,0 +1,9 @@
+---
+description: Project-wide guardrails. Always applied.
+alwaysApply: true
+---
+
+`AGENTS.md` at the repo root is canonical: read it before writing code, and change it (not these rules) when a convention changes. The per-folder `README.md` files are the deep docs it links to.
+
+- i18n: this is `variant/document-level` — document-level i18n (one document per language), so AGENTS.md §"Branch-specific notes" wins over its field-level §i18n. Select documents in GROQ with `language == $locale`; their fields are plain and render directly. **NEVER** add `internationalizedArray*` fields or `pickLocalizedString` calls for content.
+- i18n: **NEVER** edit the plugin-managed `language` field on documents.

.cursor/rules/modules.mdc

@@ -0,0 +1,15 @@
+---
+description: Module pattern — schema, component and query of a content module.
+globs:
+  - studio/schemas/objects/modules/**
+  - web/src/components/modules/**
+  - web/sanity/queries/components/modules/**
+---
+
+The wiring checklist (six points, inline opt-in) is in `AGENTS.md` §"The module pattern". Prefer `pnpm gen:module <Name>`; `pnpm check:wiring` compares every list.
+
+- i18n: module fields are plain (`string`, `richText`, `richTextMedia`); the projection returns them as they are (the page query already selected the document's language) and the component renders them directly.
+- File `module<Name>.ts`, `export const module<Name>` and `name: "module.<id>"` must match — `check:wiring` finds a module only by all three.
+- Give every module schema a `preview`, or Studio lists each instance as "Untitled".
+- Renaming `module.<id>` once content exists needs a data migration.
+- Module components are server components. An interactive part goes behind a lazy client boundary like `web/src/components/media/LazyVideo.tsx` or `…/carousel/LazyCarouselViewport.tsx`, or it lands in every route's first-load JS.

.cursor/rules/schemas.mdc

@@ -0,0 +1,12 @@
+---
+description: Sanity schema and Studio config conventions.
+globs:
+  - studio/schemas/**
+  - studio/config/**
+---
+
+Canonical: `AGENTS.md` (Cookbook → "Add a document type"). Deep docs: `studio/schemas/README.md`, `studio/config/README.md`.
+
+- i18n: document-level — a translatable document type has the hidden, read-only `language` field (`languageField` from `studio/schemas/fields/languageField.ts`; never edit it), which puts it in `TRANSLATABLE_SCHEMA_TYPES`. Content fields are plain; languages load at runtime from `siteLanguageSettings` (`studio/config/sync/supportedLanguages.ts`).
+- `schemaTypes` alone shows editors nothing: a document type also needs a structure item, a routable one Presentation wiring, a singleton its role in `studio/config/singletons.ts`.
+- Every `SANITY_STUDIO_*` variable ends up in the public Studio bundle — never a secret under that prefix.

.cursor/rules/web.mdc

@@ -0,0 +1,13 @@
+---
+description: Next.js web app conventions — routing, i18n, components.
+globs:
+  - web/**
+---
+
+Canonical: `AGENTS.md`. Deep docs: `web/README.md`, `web/sanity/README.md`, `web/src/i18n/README.md`.
+
+- i18n: document-level — select per-language documents in GROQ with `language == $locale` (the design here, not `main`'s "no locale in GROQ" anti-pattern) and pass `{ locale, siteLocale }` to anything that builds hrefs. Fields arrive in the route's language and render directly.
+- Server components by default; `"use client"` only for state, effects or browser APIs.
+- Heavy client code that only some pages render goes behind a lazy boundary (`next/dynamic` in a `"use client"` file); CI fails a route over its first-load JS ceiling in `.github/bundle-budget.json`.
+- A module gets the locale as a prop, never from the router, the URL or cookies (`AGENTS.md` §"i18n DO / DON'T").
+- Build locale-prefixed URLs with the helpers in `web/src/i18n/`, never by concatenating prefixes.

.github/bundle-budget.json

@@ -0,0 +1,11 @@
+{
+	"$comment": "First-load JS per route, KB gzip, as `.github/scripts/bundle-report.mjs` measures it. Both branches share this file: each budget is the larger of the two measurements plus ~3 KB. Raise one only on purpose, and say why in the PR.",
+	"routes": {
+		"/[locale]": 170,
+		"/[locale]/[slug]": 170,
+		"/[locale]/work": 170,
+		"/[locale]/work/[slug]": 170,
+		"/[locale]/[...rest]": 164,
+		"/_not-found": 146
+	}
+}

.github/copilot-instructions.md

@@ -0,0 +1,13 @@
+# GitHub Copilot — repository instructions
+
+`AGENTS.md` at the repo root holds this repo's guardrails: the module pattern, generated Sanity types, i18n, commands and the definition of done. Read it before suggesting a change; the per-folder `README.md` files are the deep docs it links to.
+
+Two long-lived branches differ in one thing, where a locale lives: in the field on `main`, in the document on `variant/document-level`. Check the branch (`git rev-parse --abbrev-ref HEAD`) and read AGENTS.md → "Branch-specific notes" before touching locale code. Fixes land on `main` first and reach the variant by `git cherry-pick -x`; every PR names its `Variant-Port`. A project copied from the starter has `main` (production) and `development` (staging) instead and no `Variant-Port`; its AGENTS.md → "This repository" says so.
+
+Copilot code review reads only this file, so the rules a review most often needs are repeated here (AGENTS.md has the reasons):
+
+- Never edit generated files (`*.gen.*`, `studio/schema.json`); `pnpm generate` writes them and CI fails on a diff.
+- Full queries go through `defineQuery`; no function calls inside a query, no `as` on Sanity data.
+- Compare a fetched string to a literal only through `stegaClean` / `isStegaVariant`; never clean a whole rendered document.
+- A module is wired in six places (`pnpm check:wiring` checks them); schema and component land in one commit.
+- Locale handling differs by branch — judge it against AGENTS.md "Branch-specific notes", not against the other branch.

.github/dependabot.yml

@@ -1,21 +1,124 @@
 version: 2
+
+# Two parallel pipelines because `main` and `variant/document-level` are
+# treated as independently-shipped lines of the starter, not as
+# trunk + downstream. Dependabot reads this file from the default branch
+# only (`main`); the `target-branch` field is what fans updates out.
+#
+# Each branch gets one npm and one github-actions entry:
+#   - monthly schedule — Dependabot's `monthly` interval always runs on the
+#     1st of the month (`day` is only honored for `weekly`). The PR→Slack
+#     monthly digest runs on the 2nd on purpose, so the channel never gets
+#     bundles + digest on the same day.
+#   - npm: two catch-all groups per run instead of one PR per dependency:
+#     `all-non-major` bundles every minor + patch into one auto-mergeable
+#     PR (see dependabot-auto-merge.yml); `all-major` bundles every major
+#     into one PR that waits for manual review (e.g. Next 16→17).
+#     `@types/node` major bumps ignored (pinned to Node 22 LTS).
+#   - github-actions: every action and reusable workflow in one PR. The
+#     workflows pin them to commit SHAs; Dependabot moves the SHA and its
+#     `# vX.Y.Z` comment. Auto-merge treats the bundle like an npm one: a
+#     major inside it waits for review.
+#
+# Keep the main and variant entries in lockstep — when editing one, mirror
+# the change to the other.
+#
+# Security advisories are NOT schedule-gated and arrive immediately on
+# both branches regardless of the monthly cadence.
+
 updates:
+  # ── main ───────────────────────────────────────────────────────────────────
   - package-ecosystem: npm
     directory: "/"
     schedule:
-      interval: weekly
-      day: monday
-    open-pull-requests-limit: 10
+      interval: monthly
+      time: "13:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 5
     groups:
-      sanity-ecosystem:
+      all-non-major:
         patterns:
-          - "sanity"
-          - "@sanity/*"
-          - "sanity-plugin-*"
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      all-major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
+      # TypeScript 7 (the native compiler rewrite) breaks `next build` on
+      # Next 16: `tsc --noEmit` passes, but Next's own TypeScript detection
+      # fails ("do not have the required package(s) installed") because the
+      # package layout changed. Next's transitive @module-federation/dts-plugin
+      # also still pins `typescript@^4.9 || ^5`. Drop this entry once Next
+      # supports TS 7.
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+      time: "13:00"
+      timezone: "Europe/Berlin"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    labels:
+      - "dependencies"
+
+  # ── variant/document-level ─────────────────────────────────────────────────
+  - package-ecosystem: npm
+    directory: "/"
+    target-branch: "variant/document-level"
+    schedule:
+      interval: monthly
+      time: "13:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 5
+    groups:
+      all-non-major:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+      all-major:
+        patterns:
+          - "*"
+        update-types:
+          - "major"
     ignore:
-      # @types/node must track the runtime (Node 22 LTS), not the latest major.
-      # Allow minor/patch within v22; block major bumps (e.g. 25.x).
       - dependency-name: "@types/node"
         update-types: ["version-update:semver-major"]
+      # TypeScript 7 (the native compiler rewrite) breaks `next build` on
+      # Next 16: `tsc --noEmit` passes, but Next's own TypeScript detection
+      # fails ("do not have the required package(s) installed") because the
+      # package layout changed. Next's transitive @module-federation/dts-plugin
+      # also still pins `typescript@^4.9 || ^5`. Drop this entry once Next
+      # supports TS 7.
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    target-branch: "variant/document-level"
+    schedule:
+      interval: monthly
+      time: "13:00"
+      timezone: "Europe/Berlin"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
     labels:
       - "dependencies"

.github/pull_request_template.md

@@ -0,0 +1,8 @@
+<!-- What changes, and why. -->
+
+<!--
+`main` PR: the matching `variant/document-level` PR, or `n/a` with the reason.
+Variant PR: the `main` PR it ports, or `variant-only`.
+See AGENTS.md → "Porting fixes between branches".
+-->
+Variant-Port:

.github/scripts/bundle-report.mjs

@@ -0,0 +1,99 @@
+// @ts-check
+/**
+ * First-load JS per route of the web build, gzipped — the number the browser downloads before
+ * a page is interactive.
+ *
+ * Usage:  node .github/scripts/bundle-report.mjs   (after `pnpm --filter web run build`)
+ *
+ * Reads `web/.next/diagnostics/route-bundle-stats.json`, which `next build` writes with the
+ * chunk list of every route, and gzips each chunk (level 9). Writes a Markdown table to
+ * `$GITHUB_STEP_SUMMARY` when set (the `build (web)` job), to stdout otherwise.
+ *
+ * Budget gate: `.github/bundle-budget.json` maps routes to a ceiling in KB gzip. A route over
+ * its ceiling fails the run (exit 1) after the table is written, and so does a budget for a
+ * route the build doesn't have; a route without one only shows `—`.
+ */
+
+import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+
+const webDir = fileURLToPath(new URL("../../web", import.meta.url));
+const statsFile = join(webDir, ".next/diagnostics/route-bundle-stats.json");
+const budgetFile = fileURLToPath(
+	new URL("../bundle-budget.json", import.meta.url),
+);
+
+/** @type {Record<string, number>} route → ceiling in KB gzip */
+const budgets = JSON.parse(readFileSync(budgetFile, "utf8")).routes;
+
+/** @type {{ route: string; firstLoadChunkPaths: string[] }[]} */
+const routes = JSON.parse(readFileSync(statsFile, "utf8"));
+
+/** @type {Map<string, { raw: number; gzip: number }>} */
+const chunkSizes = new Map();
+/** @param {string} chunk */
+function sizeOf(chunk) {
+	let size = chunkSizes.get(chunk);
+	if (!size) {
+		const source = readFileSync(join(webDir, chunk));
+		size = { raw: source.length, gzip: gzipSync(source, { level: 9 }).length };
+		chunkSizes.set(chunk, size);
+	}
+	return size;
+}
+
+/** @param {number} bytes */
+const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
+
+const rows = routes.map(({ route, firstLoadChunkPaths }) => {
+	let raw = 0;
+	let gzip = 0;
+	for (const chunk of firstLoadChunkPaths) {
+		const size = sizeOf(chunk);
+		raw += size.raw;
+		gzip += size.gzip;
+	}
+	const budget = budgets[route];
+	const over = budget !== undefined && gzip / 1024 > budget;
+	return { route, chunks: firstLoadChunkPaths.length, raw, gzip, budget, over };
+});
+
+const table = [
+	"### First-load JS per route",
+	"",
+	"| Route | Chunks | Raw | Gzip | Budget |",
+	"|---|---:|---:|---:|---:|",
+	...rows.map(
+		(row) =>
+			`| \`${row.route}\` | ${row.chunks} | ${kb(row.raw)} | **${kb(row.gzip)}** | ${
+				row.budget === undefined
+					? "—"
+					: `${row.over ? "❌" : "✅"} ${row.budget} KB`
+			} |`,
+	),
+	"",
+].join("\n");
+
+const summary = process.env.GITHUB_STEP_SUMMARY;
+if (summary) appendFileSync(summary, `${table}\n`);
+else console.log(table);
+
+const overBudget = rows.filter((row) => row.over);
+for (const row of overBudget) {
+	console.error(
+		`✗ ${row.route}: ${kb(row.gzip)} gzip exceeds its ${row.budget} KB budget (.github/bundle-budget.json).`,
+	);
+}
+/* A budget for a route the build no longer has would pass forever. */
+const builtRoutes = new Set(rows.map((row) => row.route));
+const orphanBudgets = Object.keys(budgets).filter(
+	(route) => !builtRoutes.has(route),
+);
+for (const route of orphanBudgets) {
+	console.error(
+		`✗ ${route}: has a budget in .github/bundle-budget.json but no route in the build.`,
+	);
+}
+if (overBudget.length > 0 || orphanBudgets.length > 0) process.exit(1);