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

.cursor/rules/core.mdc

@@ -0,0 +1,14 @@
+---
+description: Project-wide guardrails. Always applied.
+alwaysApply: true
+---
+
+Canonical guardrails: `/AGENTS.md`. Read it before writing code in this repo.
+
+Top-level rules (do not duplicate — see AGENTS.md for the full context):
+
+- Reuse before invention; grep `studio/schemas/objects/modules/`, `web/src/components/modules/`, `web/sanity/queries/snippets/` first.
+- Content blocks are **modules** — paired Sanity object + React component, wired in 8 places. Skipping any one is a bug.
+- Locale-aware at render time, never inside GROQ. Always use `pickLocalizedString` / `parseLocalizedText` from `web/sanity/utils/sanityLocalizedText.ts`.
+- After schema edits: `pnpm studio:generate` → `pnpm typecheck` → `pnpm format`. Never edit `studio/sanity.types.gen.ts` or `studio/schema.json`.
+- `web/sanity/types/*` are hand-maintained; keep aligned with field changes.

.cursor/rules/modules.mdc

@@ -0,0 +1,36 @@
+---
+description: Module pattern — 8-step wiring. Applies when editing modules anywhere.
+globs:
+  - studio/schemas/objects/modules/**
+  - web/src/components/modules/**
+  - web/sanity/queries/components/modules/**
+  - web/sanity/types/modules/**
+---
+
+A **module** is a paired Sanity object (`module.<id>`) plus a React component (`Module<Name>.tsx`). Adding, renaming, or removing one is atomic across **8 files**:
+
+1. `studio/schemas/objects/modules/module<Name>.ts` — `defineType`, `name: "module.<id>"`, fields, `preview`, optional `icon`.
+2. `studio/schemas/index.ts` — import + add to `schemaTypes`.
+3. `studio/schemas/objects/editors/richTextMedia.ts` — append `{ type: "module.<id>" }` to `of`.
+4. `studio/schemas/fields/modulesArrayField.ts` — append `{ type: "module.<id>" }` to `moduleTypes`.
+5. `web/src/components/modules/Module<Name>.tsx` — accepts `{ data, locale, siteLocale }`, sets `data-sanity` attrs.
+6. `web/src/components/modules/index.ts` — re-export from barrel and register in `ModulesRenderer.tsx`.
+7. `web/sanity/queries/components/modules/<name>.ts` — GROQ projection, full i18n arrays, re-export from `index.ts`.
+8. `web/sanity/types/modules/<name>.ts` — hand-maintained TS shape, re-export from `index.ts`.
+
+After steps 1–4 land, run `pnpm studio:generate` and commit the gen artifacts.
+
+DO:
+
+- Ship all 8 in a single commit.
+- Reuse `media.image`, `media.video`, `media.videoLoop` from `studio/schemas/objects/media/`.
+- Project i18n fields as full `{ _key, _type, language, value }` arrays.
+- Read i18n via `pickLocalizedString` / `parseLocalizedText`.
+
+DON'T:
+
+- Land schema without component (or vice versa).
+- Add `{ type: "module.<id>" }` to only one of `richTextMedia.ts` / `modulesArrayField.ts`.
+- Index i18n arrays directly (`title[0].value`).
+- `coalesce(field[language==$locale].value, ...)` in GROQ.
+- Hand-edit `studio/sanity.types.gen.ts` or `studio/schema.json`.

.cursor/rules/schemas.mdc

@@ -0,0 +1,36 @@
+---
+description: Sanity schema conventions and typegen workflow.
+globs:
+  - studio/schemas/**
+  - studio/config/**
+---
+
+Sanity Studio v5. Schemas live under `studio/schemas/`. Indent 2 spaces, double quotes.
+
+Hard rules:
+
+- A new type is invisible until exported and added to `schemaTypes` in `studio/schemas/index.ts`.
+- New document types also need a structure item under `studio/config/structure/items/` and registration in `studio/config/structure/index.ts`. The sidebar does NOT auto-populate from schemas.
+- Routable types must be wired into Presentation: `studio/config/presentation/conventions.ts` (`SLUG_BASED_DOCUMENT_TYPES`, `SITE_ROOT_DOCUMENT_TYPES`, `DOCUMENT_TYPES_WITHOUT_WEB_PREVIEW`) and `resolve.ts` / `locationsResolver.ts`.
+- Internally linkable types go into `studio/schemas/constants/references.ts` (`PAGE_REFERENCES`).
+- Translatable fields use `internationalizedArrayString` / `internationalizedArrayRichText` / `internationalizedArrayRichTextMedia` — never plain `string` for translatable content.
+- Slug fields use `validateSlug` from `studio/utils/validateSlug.ts`.
+- Reuse `media.image`, `media.video`, `media.videoLoop` from `studio/schemas/objects/media/`.
+
+After every schema edit:
+
+```
+pnpm studio:generate
+git add studio/schema.json studio/sanity.types.gen.ts
+pnpm typecheck
+```
+
+CI rejects any uncommitted gen diff.
+
+NEVER edit:
+
+- `studio/sanity.types.gen.ts`
+- `studio/schema.json`
+- Anything under `studio/.sanity/`
+
+Languages come from the `siteLanguageSettings` singleton — add new languages there, not in source. `web/src/i18n/fallbackSiteLocales.ts` is the offline fallback only.

.cursor/rules/web.mdc

@@ -0,0 +1,33 @@
+---
+description: Next.js web app conventions — routing, i18n, components.
+globs:
+  - web/**
+---
+
+Next.js 16 App Router. RSC by default; `"use client"` only when needed (state, effects, browser APIs). Tailwind v4. Biome: tabs, double quotes. Path alias `@/*` → `web/`.
+
+Hard rules:
+
+- Thread `{ locale, siteLocale }` through every render path that touches Sanity content.
+- Resolve translatable fields via `pickLocalizedString` / `parseLocalizedText` from `web/sanity/utils/sanityLocalizedText.ts`. Never index i18n arrays.
+- No locale filtering inside GROQ — projections return full `{ _key, _type, language, value }` arrays.
+- Content blocks are **modules** (see `.cursor/rules/modules.mdc`). No ad-hoc `<section>` in route files.
+- `web/sanity/types/*` are hand-maintained. Update them in the same commit as the GROQ projection.
+- Set `data-sanity` attrs on Sanity-rendered roots (copy from `ModuleText.tsx` / `MediaImage.tsx`) — Visual Editing depends on it.
+- Never read locale from `useRouter()`, `usePathname()`, `window.location`, or cookies inside a module — breaks SSR + Presentation iframes.
+- No hardcoded locale codes outside `web/src/i18n/`.
+
+URL/locale helpers live in `web/src/i18n/` (`paths.ts`, `siteLocalePathUtils.ts`, `site-locales.ts`, `proxyLocaleFetch.ts`). Use them; do not concatenate locale prefixes by hand.
+
+After web changes:
+
+```
+pnpm typecheck
+pnpm format
+```
+
+NEVER edit:
+
+- `web/.next/`
+- Any `*.gen.*` files
+- Imports from `studio/...` (use `packages/*` for shared code).

.github/copilot-instructions.md

@@ -0,0 +1,57 @@
+# GitHub Copilot — repository instructions
+
+Full guardrails live in `AGENTS.md` at the repo root. This file is a condensed mirror for inline suggestions.
+
+## Repo at a glance
+
+- pnpm monorepo: `web` (Next.js 16 App Router), `studio` (Sanity v5), shared `packages/*`.
+- Editorial content is rendered via the **module pattern**: every content block is a paired `module.<name>` Sanity object + `Module<Name>.tsx` React component, wired in 8 places.
+- Multilingual content uses `@sanity/internationalized-array`. Locale is resolved at **render time** via `web/sanity/utils/sanityLocalizedText.ts`, never inside GROQ.
+
+## Top rules
+
+1. Reuse before invention — check `studio/schemas/objects/modules/`, `web/src/components/modules/`, `web/sanity/queries/snippets/`, `web/sanity/utils/` first.
+2. New content block → it is a **module**. Touch all 8 wiring points or revert:
+   - `studio/schemas/objects/modules/module<Name>.ts`
+   - `studio/schemas/index.ts`
+   - `studio/schemas/objects/editors/richTextMedia.ts`
+   - `studio/schemas/fields/modulesArrayField.ts`
+   - `web/src/components/modules/Module<Name>.tsx`
+   - `web/src/components/modules/index.ts` (+ register in `ModulesRenderer.tsx`)
+   - `web/sanity/queries/components/modules/<name>.ts` (+ barrel)
+   - `web/sanity/types/modules/<name>.ts` (+ barrel)
+3. After every schema edit: `pnpm studio:generate`, then `pnpm typecheck`, then `pnpm format`.
+4. Never edit `studio/sanity.types.gen.ts` or `studio/schema.json` — generated.
+5. `web/sanity/types/*` are hand-maintained — update them when schema fields change.
+6. Locale-aware always: use `pickLocalizedString(field, locale, siteLocale)` or `parseLocalizedText({ value, locale, siteLocale, as })`. Never `field[0].value` or `field.find(t => t.language === locale)`. Never `coalesce(field[language==$locale].value, ...)` in GROQ.
+7. Add a new language only via the `siteLanguageSettings` Studio singleton (offline fallback: `web/src/i18n/fallbackSiteLocales.ts`). No schema, query, or component change.
+8. No hardcoded locale codes outside `web/src/i18n/`.
+9. No imports from `studio/` inside `web/` (or vice versa). Share via `packages/*`.
+
+## Naming
+
+- Sanity module name `module.<id>` ↔ React component `Module<Name>.tsx`.
+- Path alias `@/*` resolves to `web/` only.
+- Biome: tabs (web + root), 2 spaces (studio), double quotes throughout.
+
+## Decision tree — where things live
+
+- Authored content block? → module.
+- Layout primitive (header, footer, container)? → `web/src/components/{navigation,theme,…}/`.
+- Sanity-only helper? → `studio/utils/` or `studio/config/`.
+- Shared between web + studio? → a package in `packages/*`.
+- Locale string / URL helper? → `web/src/i18n/`.
+- Reusable GROQ fragment? → `web/sanity/queries/snippets/`.
+
+## Branches
+
+The repo has two long-lived branches with non-trivial differences:
+
+- `main` — document types `page`, `project`, `projectCategory`, `work`; four web module renderers all under `web/src/components/modules/` with an `index.ts` barrel; `module.contentRefs` schema supports project filtering.
+- `variant/document-level` — only `page` (no projects/work); all four module schemas exist but only `ModuleMedia` and `ModuleText` have local renderers — `ModuleCarousel` lives in `web/src/components/carousel/`, `ModuleContentRefs` has a dev-only placeholder. No `web/src/components/modules/index.ts` barrel. `module.contentRefs` is simplified to `PAGE_REFERENCES` with an `allowMultiple` toggle. `page` has a `language` string field set by the i18n plugin — **never edit manually**.
+
+Check `git rev-parse --abbrev-ref HEAD` and the actual file layout on the branch before adding modules.
+
+## Definition of done
+
+`pnpm typecheck` passes, `pnpm format` clean, gen artifacts committed if schema changed, all 8 module wiring points touched (when applicable), no `--no-verify`.

.github/dependabot.yml

@@ -1,20 +1,64 @@
 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.
+#
+# Both entries share the same shape:
+#   - monthly schedule (first Monday 06:00 CET)
+#   - one catch-all `all-non-major` group bundles every minor + patch
+#     across the workspace into a single PR per run; majors stay
+#     individual for manual review (e.g. Next 16→17, React 19→20)
+#   - `@types/node` major bumps ignored (pinned to Node 22 LTS)
+#
+# Keep the two entries in lockstep — when editing either, 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
+      interval: monthly
       day: monday
-    open-pull-requests-limit: 10
+      time: "06:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 5
     groups:
-      sanity-ecosystem:
+      all-non-major:
         patterns:
-          - "sanity"
-          - "@sanity/*"
-          - "sanity-plugin-*"
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+    ignore:
+      - dependency-name: "@types/node"
+        update-types: ["version-update:semver-major"]
+    labels:
+      - "dependencies"
+
+  # ── variant/document-level ─────────────────────────────────────────────────
+  - package-ecosystem: npm
+    directory: "/"
+    target-branch: "variant/document-level"
+    schedule:
+      interval: monthly
+      day: monday
+      time: "06:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 5
+    groups:
+      all-non-major:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
     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"]
     labels:

.github/workflows/ci.yml

@@ -36,6 +36,11 @@ jobs:
       - name: Ensure formatter produced no changes
         run: git diff --exit-code
       - run: pnpm run typecheck
+      # Wiring drift between schema, component, query, and type files is a
+      # silent bug class — `pnpm gen:module` creates them atomically, but
+      # hand-edits routinely miss a file. This gate catches partial wirings
+      # before they reach main.
+      - run: pnpm run check:wiring
 
   schema-typegen:
     name: schema typegen
@@ -84,7 +89,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm --filter web run build
         env:
-          # Builds without a project must still succeed (boilerplate). Real
+          # Builds without a project must still succeed (starter). Real
           # deploys provide SANITY_STUDIO_PROJECT_ID via the host's env.
           NEXT_TELEMETRY_DISABLED: "1"
 

.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,43 @@
+name: Dependabot auto-merge
+
+# Enables GitHub auto-merge on Dependabot PRs for patch + minor bumps
+# (including grouped PRs). GitHub then waits for ALL required checks to
+# pass before squash-merging. Auto-merge ≠ merge-regardless — failing CI
+# leaves the PR sitting open until you act on it.
+#
+# Major bumps fall through and remain manual: fetch-metadata reports the
+# highest update-type across a group, and our dependabot.yml group filter
+# (`update-types: [minor, patch]`) excludes majors, so single-major PRs
+# return `version-update:semver-major` and skip the merge step.
+
+on:
+  pull_request:
+    # Both branches are treated as parallel main lines; Dependabot opens
+    # PRs against both (see dependabot.yml).
+    branches:
+      - main
+      - variant/document-level
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch dependabot metadata
+        id: meta
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Enable auto-merge for patch + minor
+        if: |
+          steps.meta.outputs.update-type == 'version-update:semver-patch' ||
+          steps.meta.outputs.update-type == 'version-update:semver-minor'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pr-slack-notify.yml

@@ -0,0 +1,13 @@
+name: PR Slack notify
+
+on:
+  pull_request:
+    types: [opened, ready_for_review, closed]
+    branches:
+      - main
+      - variant/document-level
+
+jobs:
+  notify:
+    uses: backendforth/.github/.github/workflows/pr-slack-summary.yml@main
+    secrets: inherit

.github/workflows/strip-readmes.yml

@@ -29,4 +29,4 @@ jobs:
       - name: Commit changes
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
-          commit_message: "chore: remove README files (boilerplate cleanup)"
+          commit_message: "chore: remove README files (starter cleanup)"

.gitignore

@@ -23,7 +23,8 @@ out/
 
 # Editors / agents
 .claude
-.cursor
+.cursor/*
+!.cursor/rules/
 
 # Coverage / test artefacts
 coverage/