create-nextblock 0.12.13 → 0.12.15

package/templates/nextblock-template/docs/TECHNICAL_SPECIFICATION.md

@@ -95,7 +95,7 @@ NextBlock CMS integrates with a specific, opinionated set of external services w
 The system delivers six top-level capability families, each surfaced through dedicated route groups in the Next.js App Router:
 
 1. **Public Content Delivery** — Routes `app/[slug]`, `app/article/[slug]`, shared `app/layout.tsx`, `robots.txt`, and `sitemap.xml` serve marketing pages, articles, and product pages.
-2. **Authentication & Account Management** — The `app/(auth-pages)/*` group and `app/auth/callback/route.ts` implement Supabase Auth session exchange, GitHub OAuth (via `components/GitHubLoginButton.tsx`), and profile completion flows.
+2. **Authentication & Account Management** — The `app/(auth-pages)/*` group and `app/auth/callback/route.ts` implement Supabase Auth email/password session exchange and profile completion flows.
 3. **CMS Administration** — The `app/cms/*` route tree provides block editing, media management, product catalog management, order administration, shipping configuration, tax settings, and user administration, gated by role.
 4. **Commerce Surface** — Routes `app/product/*`, `app/cart`, and `app/checkout` implement the customer-facing storefront; `app/api/checkout/route.ts` handles server-side checkout orchestration.
 5. **Operational Endpoints** — Routes `app/api/webhooks/*` (Stripe/Freemius) and `app/api/cron/*` (sandbox reset, currency sync) provide the machine-to-machine surface; `app/api/upload` and `app/api/process-image` handle media ingestion and optimization.
@@ -269,7 +269,7 @@ The following architectural invariants are enforced at workspace level and must
 
 **Editor Capabilities** — The `@nextblock-cms/editor` library (version `0.2.24`) exports `Editor`, `NotionEditor`, `EditorToolbar`, `EditorBubbleMenu`, `EditorFloatingMenu`, `EnhancedFloatingMenu`, `SlashCommandList`, `DragHandle`, `HtmlContent`, and `editorExtensions`. Feature set includes Tiptap StarterKit rich text, syntax-highlighted code blocks, tables, task lists, slash commands, drag handles, image handling, character counting, typography, mathematics, emoji, mentions, inline alert and call-to-action widgets, and custom HTML-preserving extensions for `div`, `style`, `script`, `svg`, `span`, and catch-all attribute preservation. A media-picker bridge is exposed via `setOpenImagePicker()`.
 
-**Translation & Localization** — The system supports two locales at present (`en`, `fr` — defined as `SUPPORTED_LOCALES` in `apps/nextblock/proxy.ts`), backed by `languages` and `translations` tables from migration `00000000000001_setup_cms_core.sql`. Content revision history is stored as snapshot + JSON Patch diff (enum `revision_type: snapshot, diff`) per migration `00000000000002_setup_content_tables.sql`.
+**Translation & Localization** — The set of served locales is the active rows of the `languages` table (managed at `/cms/settings/languages`; the proxy reads them with a 60-second in-memory cache and only falls back to the hardcoded `FALLBACK_LOCALES` `en`/`fr` when the DB is unreadable), backed by `languages` and `translations` tables from migration `00000000000001_setup_cms_core.sql`. First-visit language detection is admin-configurable (see F-007): browser `Accept-Language`, IP-country via host geo headers, combined, or always-default — implemented in `apps/nextblock/lib/i18n/detection.ts` and stored in `site_settings.language_detection_settings`. Content revision history is stored as snapshot + JSON Patch diff (enum `revision_type: snapshot, diff`) per migration `00000000000002_setup_content_tables.sql`.
 
 **Page Lifecycle** — Pages move through `draft`, `published`, and `archived` statuses (enum `page_status`).
 
@@ -390,7 +390,7 @@ Based on claims and deferred items in the repository documentation, the followin
 
 #### 1.3.3.5 Integration Points Not Covered
 
-The system does not natively integrate with: alternative payment processors beyond Stripe and Freemius, alternative authentication providers beyond Supabase Auth and GitHub OAuth, alternative object-storage providers beyond S3-compatible endpoints (specifically Cloudflare R2 in reference deployments), alternative monorepo orchestrators beyond Nx, or alternative hosting platforms requiring cron-configuration formats other than Vercel's `vercel.json` schema.
+The system does not natively integrate with: alternative payment processors beyond Stripe and Freemius, alternative authentication providers beyond Supabase Auth, alternative object-storage providers beyond S3-compatible endpoints (specifically Cloudflare R2 in reference deployments), alternative monorepo orchestrators beyond Nx, or alternative hosting platforms requiring cron-configuration formats other than Vercel's `vercel.json` schema.
 
 ---
 
@@ -619,7 +619,11 @@ Media management combines a Cloudflare R2-backed object store with an image-proc
 
 **Description**
 
-Two locales are currently supported — `en` and `fr` — defined as `SUPPORTED_LOCALES` in `apps/nextblock/proxy.ts` and seeded in migration `00000000000008_seed_platform_defaults.sql` (with `en` marked as the single default). The `languages` table enforces a single `is_default` row; the `translations` table stores translation keys with JSONB-per-locale values. Localized content entities (pages, posts, products) are clustered via `translation_group_id` UUIDs. Locale propagation uses the `NEXT_USER_LOCALE` cookie (`maxAge: 31_536_000` seconds, one year) and the `X-User-Locale` request header, both set by the request proxy. The client-side provider chain `LanguageProvider → TranslationsProvider` in `apps/nextblock/app/providers.tsx` bridges server-resolved locale into React context.
+Served locales are the active rows of the `languages` table, managed at `/cms/settings/languages` (the seed provides `en` and `fr`, with `en` as the single default; `apps/nextblock/proxy.ts` keeps `FALLBACK_LOCALES = ['en','fr']` only as a safety net when the DB is unreadable). The `languages` table enforces a single `is_default` row; the `translations` table stores translation keys with JSONB-per-locale values. Localized content entities (pages, posts, products) are clustered via `translation_group_id` UUIDs.
+
+**First-visit language detection** is admin-configurable on `/cms/settings/languages` and stored as the non-sensitive `site_settings` key `language_detection_settings` (`{ mode, rememberVisitorChoice }`). Modes: `browser` (default — full `Accept-Language` q-value parsing), `country` (visitor's country from host geo headers `x-vercel-ip-country` / `cf-ipcountry` / `cloudfront-viewer-country` / `x-country-code`, mapped through `apps/nextblock/lib/i18n/country-languages.ts`), `browser_then_country`, and `default` (no detection). The pure resolution helpers live in `apps/nextblock/lib/i18n/detection.ts`; the proxy applies them for any request without a valid locale cookie, resolving against the active languages + default language read from the DB with a 60-second in-memory cache.
+
+Locale propagation uses the `NEXT_USER_LOCALE` cookie and the `X-User-Locale` request header, both set by the request proxy. When `rememberVisitorChoice` is `true` (default) the cookie persists for one year (`maxAge: 31_536_000` seconds); when `false` it is a session cookie, so detection re-runs each new browser session (the client `LanguageProvider` mirrors the same expiry for manual switcher choices). A valid cookie always beats detection. The client-side provider chain `LanguageProvider → TranslationsProvider` in `apps/nextblock/app/providers.tsx` bridges server-resolved locale into React context.
 
 **Business Value:** Unlocks multi-market deployments without requiring adopters to integrate a separate i18n library. **User Benefits:** Language switching persists across sessions; same content IDs preserve relationships across translations. **Technical Context:** Implemented at schema level (migration `00000000000001_setup_cms_core.sql`), proxy level, and provider level.
 
@@ -700,9 +704,9 @@ Three menu locations are supported: `HEADER`, `FOOTER`, and `SIDEBAR`, encoded b
 
 **Description**
 
-Authentication is layered over Supabase Auth using `@supabase/ssr` 0.7.0 and `@supabase/supabase-js` 2.77.0. Server actions in `apps/nextblock/app/actions.ts` implement sign-in, sign-up, and forgot-password flows, complemented by GitHub OAuth via `components/GitHubLoginButton.tsx`. The `app/auth/callback/route.ts` route exchanges authorization codes for sessions (`supabase.auth.exchangeCodeForSession()`), loads the profile role, and redirects using `resolvePostAuthRedirect()`. Email templates for confirmation, email change, invitation, magic-link, reauthentication, and password recovery reside in `libs/db/src/supabase/templates/`. A `handle_new_user()` trigger function paired with the `on_auth_user_created` trigger on `auth.users` automatically provisions a `profiles` row on registration.
+Authentication is layered over Supabase Auth using `@supabase/ssr` 0.7.0 and `@supabase/supabase-js` 2.77.0. Server actions in `apps/nextblock/app/actions.ts` implement sign-in, sign-up, and forgot-password flows. The `app/auth/callback/route.ts` route exchanges authorization codes for sessions (used by the email-confirmation and recovery flows) (`supabase.auth.exchangeCodeForSession()`), loads the profile role, and redirects using `resolvePostAuthRedirect()`. Email templates for confirmation, email change, invitation, magic-link, reauthentication, and password recovery reside in `libs/db/src/supabase/templates/`. A `handle_new_user()` trigger function paired with the `on_auth_user_created` trigger on `auth.users` automatically provisions a `profiles` row on registration.
 
-**Business Value:** Eliminates the need for adopters to integrate a separate identity provider. **User Benefits:** Multiple sign-in methods (email/password, GitHub OAuth, magic link) with localized email templates. **Technical Context:** Supabase Auth session cookies are synchronized by the request proxy to Server Components.
+**Business Value:** Eliminates the need for adopters to integrate a separate identity provider. **User Benefits:** Multiple sign-in methods (email/password, magic link) with localized email templates. **Technical Context:** Supabase Auth session cookies are synchronized by the request proxy to Server Components.
 
 **Dependencies**
 
@@ -1290,7 +1294,8 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-005-RQ-002 | Editor MUST preserve custom HTML constructs (`div`, `style`, `script`, `svg`, `span`) and unrecognized attributes | Must-Have | High |
 | F-006-RQ-001 | Media uploads MUST record metadata (`object_key`, `file_type`, `size_bytes`, `width`, `height`, `blur_data_url`, `variants`) in the `media` table | Must-Have | Medium |
 | F-006-RQ-002 | `recordMediaUpload` MUST reject non-`ADMIN`/non-`WRITER` callers | Must-Have | Low |
-| F-007-RQ-001 | Locale MUST propagate via `NEXT_USER_LOCALE` cookie (1-year max age) and `X-User-Locale` header | Must-Have | Low |
+| F-007-RQ-001 | Locale MUST propagate via `NEXT_USER_LOCALE` cookie (1-year max age when `rememberVisitorChoice` is on; session cookie when off) and `X-User-Locale` header | Must-Have | Low |
+| F-007-RQ-002 | First-visit locale MUST honor the admin-configured detection mode (`browser`, `country`, `browser_then_country`, `default`) from `site_settings.language_detection_settings` | Must-Have | Medium |
 | F-008-RQ-001 | Content revisions MUST use the hybrid snapshot/diff model keyed by `revision_type` enum | Must-Have | Medium |
 | F-009-RQ-001 | Navigation items MUST support `HEADER`, `FOOTER`, `SIDEBAR` locations with hierarchy and ordering | Must-Have | Low |
 
@@ -1303,7 +1308,7 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-004-RQ-001 | Block type string, content object | Validated block content or ZodError | Schema validation synchronous |
 | F-005-RQ-002 | HTML or Tiptap JSON | Rendered editor content preserving DOM | No HTML loss across round-trip |
 | F-006-RQ-001 | Multipart file or presigned PUT | `media` row with metadata | Upload completes within browser timeout |
-| F-007-RQ-001 | `lang` URL parameter or header | Locale cookie + `X-User-Locale` header | Proxy overhead < 5 ms |
+| F-007-RQ-001 | Locale cookie, `Accept-Language`, host geo-country header | Locale cookie + `X-User-Locale` header | Proxy overhead < 5 ms on cache hit; one Supabase round-trip per isolate per 60 s on miss (loaded concurrently with the auth lookup, shared across concurrent misses) |
 
 #### 2.2.1.3 Validation Rules — Content Delivery
 
@@ -1312,7 +1317,7 @@ This subsection provides the detailed, testable requirements that operationalize
 | F-001-RQ-002 | Image MIME must be in supported list | Only R2-served URLs accepted by next/image loader |
 | F-004-RQ-001 | Block `type` MUST exist in registry; content MUST pass Zod schema | Schema prevents XSS via typed fields |
 | F-006-RQ-001 | `size_bytes` must be non-negative; `object_key` unique | RLS: ADMIN/WRITER write; public read |
-| F-007-RQ-001 | Locale MUST be in `SUPPORTED_LOCALES` (`en`, `fr`) | Cookie uses default security attributes |
+| F-007-RQ-001 | Locale MUST be an active `languages` row (hardcoded `FALLBACK_LOCALES` `en`/`fr` only when the DB is unreadable) | Cookie uses default security attributes |
 | F-008-RQ-001 | Snapshot version MUST be unique per `page_id` | Writes RLS-restricted to ADMIN/WRITER |
 | F-009-RQ-001 | `menu_location` MUST be one of the three enum values | Writes RLS-restricted to ADMIN/WRITER |
 
@@ -1323,7 +1328,7 @@ This subsection provides the detailed, testable requirements that operationalize
 | Requirement ID | Description | Priority | Complexity |
 |:--|:--|:--|:--|
 | F-002-RQ-001 | Supabase Auth session exchange MUST succeed via `app/auth/callback/route.ts` | Must-Have | Medium |
-| F-002-RQ-002 | GitHub OAuth MUST be available as an alternative sign-in path | Should-Have | Low |
+| F-002-RQ-002 | *(Removed)* Third-party OAuth sign-in is intentionally not provided — it cannot be configured as part of a one-click deployment | Won't-Have | — |
 | F-002-RQ-003 | `handle_new_user()` trigger MUST provision a `profiles` row on every `auth.users` insert | Must-Have | Medium |
 | F-003-RQ-001 | First registered user MUST become `ADMIN`; subsequent users MUST become `USER` | Must-Have | Medium |
 | F-003-RQ-002 | `/cms` MUST require `WRITER` or `ADMIN`; `/cms/admin`, `/cms/users`, `/cms/settings` MUST require `ADMIN` only | Must-Have | Medium |
@@ -1612,7 +1617,7 @@ The following matrix links features to the sections of the technical specificati
 | Build Status | `ecommerce:build` Nx standalone target currently not green (per §1.3.3.1) | F-013–F-022 |
 | Freemius Reconciliation | Webhook events acknowledged only; DB reconciliation pending (per §1.3.3.1) | F-017, F-021 |
 | Postal Code Shipping | Schema present; runtime resolver does not consume (per §1.3.3.1) | F-019 |
-| Locale Count | Only `en` and `fr` in current release (per §1.3.3.4) | F-007, F-009, F-013 |
+| Locale Count | Seed provides `en` and `fr`; additional locales are added as `languages` rows at `/cms/settings/languages` | F-007, F-009, F-013 |
 | Module Boundaries | `libs/ui` MUST NOT depend on `apps/nextblock` | F-028 |
 
 ### 2.4.2 Performance Requirements
@@ -1674,7 +1679,7 @@ The following matrix links features to the sections of the technical specificati
 | FX override | `FX_API_BASE_URL` toggle allows switching provider without code change | F-018 |
 | Sandbox dataset | `SANDBOX_RESET_SQL` in `/api/cron/reset-sandbox/route.ts` must be regenerated as schema evolves | F-025, F-026 |
 | Package alignment | `@nextblock-cms/ecom` package name vs. `@nextblock-cms/ecommerce` alias (per §1.3.3.1) requires coordination when republished | F-013–F-022 |
-| Locale expansion | Adding locales beyond `en`/`fr` requires updates to `SUPPORTED_LOCALES` and seed data | F-007 |
+| Locale expansion | Locales are DB-driven: add an active `languages` row (plus translations/content); `FALLBACK_LOCALES` in `proxy.ts` is only a DB-unreachable safety net | F-007 |
 | Block registry updates | New block types must satisfy F-024 contract and register in `blockRegistry.ts` | F-004, F-024 |
 | RLS policy review | Migration `00000000000006_setup_rls_and_grants.sql` should be audited on new table introduction | All DB-backed features |
 
@@ -2135,7 +2140,7 @@ graph TB
 
 #### 3.4.1.1 Responsibilities
 
-Supabase provides PostgreSQL data storage, Row-Level Security, authentication (F-002), and session cookie management. GitHub OAuth is layered on top via the `components/GitHubLoginButton.tsx` component. Six email templates for the authentication flow (confirmation, email change, invitation, magic-link, reauthentication, password recovery) reside in `libs/db/src/supabase/templates/` and are synchronized with Supabase through `npm run configure:supabase-auth`.
+Supabase provides PostgreSQL data storage, Row-Level Security, authentication (F-002), and session cookie management. Six email templates for the authentication flow (confirmation, email change, invitation, magic-link, reauthentication, password recovery) reside in `libs/db/src/supabase/templates/` and are synchronized with Supabase through `npm run configure:supabase-auth`.
 
 #### 3.4.1.2 Environment Variables
 
@@ -2254,7 +2259,7 @@ The workspace implements a layered caching strategy aligned with the performance
 | `unstable_cache` (package activation) | 60 s | Avoids DB hit on every F-022 license check | `libs/db/src/lib/package-validation.ts` |
 | Next.js ISR (public layout) | 60 s (`PUBLIC_LAYOUT_REVALIDATE_SECONDS`) | Public content revalidation | `apps/nextblock/app/layout.tsx` |
 | Image cache TTL | 31,536,000 s (1 year) | Immutable optimized-image responses | `next.config.js` |
-| Locale cookie | 31,536,000 s (1 year) | Persistent locale preference | `proxy.ts` |
+| Locale cookie | 31,536,000 s (1 year), or session cookie when "remember visitor's language" is off | Persistent locale preference | `proxy.ts` |
 | On-demand revalidation | N/A | Per-path invalidation via `REVALIDATE_SECRET_TOKEN` | `/api/revalidate` (F-027) |
 | bfcache-compatible HTML | `max-age=0, must-revalidate` | Preserves back-forward cache | `proxy.ts` |
 
@@ -2428,7 +2433,7 @@ The Default Technology Stack specified for this project included assumptions tha
 | **Terraform** IaC | Declarative configs (`vercel.json`, Supabase migrations, `project.json`) | Application-layer declarative configuration suffices given the managed-service stack |
 | **GitHub Actions** CI/CD | Vercel Git deploy + Node release scripts | Release cadence and library publishing managed via `tools/scripts/*` |
 | **Python / Flask** backend | TypeScript + Next.js 16 route handlers | Monolithic Next.js model enables RSC co-located with API routes |
-| **Auth0** authentication | Supabase Auth + GitHub OAuth | Supabase Auth unifies database and identity for RLS-driven authorization (F-003) |
+| **Auth0** authentication | Supabase Auth (GoTrue) | Supabase Auth unifies database and identity for RLS-driven authorization (F-003) |
 | **MongoDB** database | Supabase PostgreSQL | Relational schema with RLS is better suited to the commerce and content data model |
 | **Langchain** AI framework | Not present (structural AI-readiness only) | Per §1.3.3.1, AI runtime features are "coming soon" |
 | **React-Native** mobile | Not used — web-only Next.js | Out-of-scope per §1.3.3.5 |
@@ -2615,9 +2620,9 @@ flowchart TB
     Supabase --> SyncSession[supabase.auth.getSession<br/>Sync Cookies]
     SyncSession --> Locale{Read<br/>NEXT_USER_LOCALE<br/>Cookie}
     
-    Locale -->|Valid: en or fr| SetLocaleHeader[Set X-User-Locale]
-    Locale -->|Invalid or Missing| DefaultEn[Default to 'en']
-    DefaultEn --> SetLocaleHeader
+    Locale -->|Valid: active language| SetLocaleHeader[Set X-User-Locale]
+    Locale -->|Invalid or Missing| Detect[Detect per settings:<br/>browser / country /<br/>browser_then_country / default]
+    Detect --> SetLocaleHeader
     
     SetLocaleHeader --> GetUser[supabase.auth.getUser]
     GetUser --> CmsGuard{Path starts<br/>with /cms?}
@@ -4156,7 +4161,7 @@ The Zustand-backed cart (with `persist` middleware) captures items in the browse
 
 #### 5.1.3.3 Primary Authoring Flow
 
-Authors sign in via Supabase Auth or GitHub OAuth, whose callback is handled at `app/auth/callback/route.ts`. After the role-based redirect from `lib/auth-redirects.ts`, authors enter `/cms/*` surfaces, which use Tiptap-based editors and the in-app `blockRegistry.ts` to compose pages. Published content triggers a Supabase webhook to `/api/revalidate`, which calls `revalidatePath` for `/slug` (pages) or `/article/slug` (posts).
+Authors sign in via Supabase Auth (email/password), whose email-confirmation callback is handled at `app/auth/callback/route.ts`. After the role-based redirect from `lib/auth-redirects.ts`, authors enter `/cms/*` surfaces, which use Tiptap-based editors and the in-app `blockRegistry.ts` to compose pages. Published content triggers a Supabase webhook to `/api/revalidate`, which calls `revalidatePath` for `/slug` (pages) or `/article/slug` (posts).
 
 #### 5.1.3.4 Integration, Transformation, and Storage
 
@@ -4703,7 +4708,7 @@ The primary error notification path is the Feedback System (F-029), which allows
 
 #### 5.4.4.1 Authentication
 
-Supabase Auth provides email/password, magic-link, and GitHub OAuth. Sign-in server actions live in `app/actions.ts`; the OAuth callback resolves to `app/auth/callback/route.ts`, which exchanges the code for a session and then delegates to `lib/auth-redirects.ts` for the post-auth destination. The redirect resolver validates that any `next` parameter is a safe internal path, preserves `/reset-password`, routes `ADMIN`/`WRITER` to `safePath` or `/cms/dashboard`, sends `USER` without `full_name` to `/profile`, and otherwise falls back to `/`.
+Supabase Auth provides email/password and magic-link sign-in. Sign-in server actions live in `app/actions.ts`; the email-confirmation callback resolves to `app/auth/callback/route.ts`, which exchanges the code for a session and then delegates to `lib/auth-redirects.ts` for the post-auth destination. The redirect resolver validates that any `next` parameter is a safe internal path, preserves `/reset-password`, routes `ADMIN`/`WRITER` to `safePath` or `/cms/dashboard`, sends `USER` without `full_name` to `/profile`, and otherwise falls back to `/`.
 
 #### 5.4.4.2 Authorization Model
 
@@ -5656,7 +5661,7 @@ Declared in migration `00000000000001_setup_cms_core.sql`, these tables bootstra
 | Table | Primary Key | Key Columns / Constraints |
 |-------|-------------|----------------------------|
 | `site_settings` | `key` (text) | `value jsonb` — flat key/value store for global configuration |
-| `profiles` | `id uuid` | FK → `auth.users(id) ON DELETE CASCADE`; `role user_role NOT NULL DEFAULT 'USER'`; `full_name`, `avatar_url`, `website`, `github_username`, `phone` |
+| `profiles` | `id uuid` | FK → `auth.users(id) ON DELETE CASCADE`; `role user_role NOT NULL DEFAULT 'USER'`; `full_name`, `avatar_url`, `website`, `phone` |
 | `user_addresses` | `id` (identity) | FK → `profiles(id)`; `address_type CHECK IN ('billing','shipping')`; `is_default`, `recipient_name`, `line1/2`, `city`, `state`, `postal_code`, `country_code` |
 | `languages` | `id bigint` | `code UNIQUE`, `name`, `is_default`, `is_active DEFAULT true` |
 | `media` | `id uuid` | `uploader_id → profiles`; `object_key UNIQUE`; `variants jsonb`; `blur_data_url`; `width`, `height`, `size_bytes`, `file_path`, `folder` |
@@ -7561,16 +7566,17 @@ flowchart TB
 
 #### 6.4.2.1 Identity Management
 
-The identity provider is **Supabase Auth (GoTrue)**, consumed through the `@supabase/ssr` adapter layer. Four distinct authentication surfaces are exposed to end users:
+The identity provider is **Supabase Auth (GoTrue)**, consumed through the `@supabase/ssr` adapter layer. Three distinct authentication surfaces are exposed to end users:
 
 | Authentication Method | Entry Point | Implementation |
 |-----------------------|-------------|----------------|
 | Email/Password | `signInAction` in `app/actions.ts` | `supabase.auth.signInWithPassword` |
 | Account Registration | `signUpAction` in `app/actions.ts` | `supabase.auth.signUp` with email confirmation |
 | Password Recovery | `forgotPasswordAction` in `app/actions.ts` | `supabase.auth.resetPasswordForEmail` (OTP) |
-| GitHub OAuth | `components/GitHubLoginButton.tsx` | `supabase.auth.signInWithOAuth({ provider: 'github' })` |
 
-The OAuth callback route handler at `apps/nextblock/app/auth/callback/route.ts` receives a short-lived authorization code on the query string, invokes `supabase.auth.exchangeCodeForSession(code)` to convert the code to a session, fetches the user profile via `getProfileWithRoleServerSide(user.id)`, and delegates redirection logic to `resolvePostAuthRedirect` in `apps/nextblock/lib/auth-redirects.ts`. On any exchange failure, the handler redirects to `initialRedirectTo || '/'`.
+> **No third-party OAuth providers.** GitHub OAuth sign-in and account-linking were removed: they cannot be provisioned as part of a one-click deployment (each install needs its own GitHub OAuth app, client secret, and Supabase's manual-linking toggle, none of which can ship in a migration). The unrelated self-update "Connect GitHub" flow (`lib/updates/*`) is not an end-user auth surface and remains.
+
+The auth callback route handler at `apps/nextblock/app/auth/callback/route.ts` receives a short-lived authorization code on the query string (used by the email-confirmation and recovery flows), invokes `supabase.auth.exchangeCodeForSession(code)` to convert the code to a session, fetches the user profile via `getProfileWithRoleServerSide(user.id)`, and delegates redirection logic to `resolvePostAuthRedirect` in `apps/nextblock/lib/auth-redirects.ts`. On any exchange failure, the handler redirects to `initialRedirectTo || '/'`.
 
 Six transactional email templates reside in `libs/db/src/supabase/templates/` — covering confirmation, email change, invitation, magic-link, reauthentication, and password recovery — and are synchronized with the Supabase project via `npm run configure:supabase-auth`.
 
@@ -7652,7 +7658,7 @@ The following sequence diagram depicts the full authentication flow from credent
 sequenceDiagram
     actor User
     participant Browser
-    participant AuthPage as /sign-in or OAuth Button
+    participant AuthPage as /sign-in
     participant SbAuth as Supabase Auth (GoTrue)
     participant Callback as /auth/callback/route.ts
     participant Resolver as lib/auth-redirects.ts
@@ -7660,12 +7666,12 @@ sequenceDiagram
     participant Profiles as profiles table
     participant CMS as /cms/*
 
-    User->>Browser: Submit credentials or OAuth click
-    Browser->>AuthPage: POST (email+password) or redirect (OAuth)
-    AuthPage->>SbAuth: signInWithPassword / signInWithOAuth
-    SbAuth-->>Browser: OAuth code or Session cookies
+    User->>Browser: Submit credentials
+    Browser->>AuthPage: POST (email+password)
+    AuthPage->>SbAuth: signInWithPassword
+    SbAuth-->>Browser: Session cookies
     
-    alt OAuth flow
+    alt Email confirmation / recovery (code exchange)
         Browser->>Callback: GET /auth/callback?code=...
         Callback->>SbAuth: exchangeCodeForSession(code)
         SbAuth-->>Callback: Set-Cookie (HttpOnly, Secure)
@@ -7720,7 +7726,7 @@ Authorization is driven by the `user_role` enum declared in migration `000000000
 | `USER` | Default for new signups | Customer profile, addresses, own orders |
 | `service_role` | Supabase service-role key | Webhooks, cron, admin server actions — bypasses RLS |
 
-Role assignment at bootstrap is governed by the `handle_new_user()` SECURITY DEFINER trigger function bound to `auth.users` via `on_auth_user_created AFTER INSERT ON auth.users FOR EACH ROW`. The trigger acquires a `FOR UPDATE` lock on the `site_settings` row where `setting_key = 'is_admin_created'`, assigns `role='ADMIN'` if the latch is false (and sets the latch), otherwise assigns `role='USER'`, detects GitHub OAuth provider for the `github_username` column, and always creates a `profiles` row. The `FOR UPDATE` lock guarantees race-free first-admin election even under concurrent signup attempts.
+Role assignment at bootstrap is governed by the `handle_new_user()` SECURITY DEFINER trigger function bound to `auth.users` via `on_auth_user_created AFTER INSERT ON auth.users FOR EACH ROW`. The trigger acquires a `FOR UPDATE` lock on the `site_settings` row where `setting_key = 'is_admin_created'`, assigns `role='ADMIN'` if the latch is false (and sets the latch), otherwise assigns `role='USER'`, and always creates a `profiles` row. The `FOR UPDATE` lock guarantees race-free first-admin election even under concurrent signup attempts.
 
 #### 6.4.3.2 Permission Management and SECURITY DEFINER Helpers
 
@@ -7908,7 +7914,7 @@ The repository does not implement explicit PII masking transforms. The following
 | Error message sanitization | All error responses | Never contains JWT, service role key, or DB connection strings |
 | Admin user list | `/cms/users` | Email addresses displayed (no masking) — audience is ADMIN only |
 
-The CMS admin user-list page uses the service-role client via `supabaseAdmin.auth.admin.listUsers` to enumerate users; since the audience of that surface is already `ADMIN`-gated, no masking transform is applied. PII in `profiles` (`full_name`, `avatar_url`, `phone`, `github_username`) is protected by RLS self-scoping rather than cryptographic masking.
+The CMS admin user-list page uses the service-role client via `supabaseAdmin.auth.admin.listUsers` to enumerate users; since the audience of that surface is already `ADMIN`-gated, no masking transform is applied. PII in `profiles` (`full_name`, `avatar_url`, `phone`) is protected by RLS self-scoping rather than cryptographic masking.
 
 #### 6.4.4.4 Secure Communication
 
@@ -8202,7 +8208,6 @@ For details beyond the scope of this section, consult:
 - `apps/nextblock/app/(auth-pages)/post-sign-in/page.tsx` — 27-line post-auth routing page
 - `apps/nextblock/app/unauthorized/page.tsx` — 26-line unauthorized display
 - `apps/nextblock/context/AuthContext.tsx` — Client auth state provider
-- `apps/nextblock/components/GitHubLoginButton.tsx` — 37-line OAuth initiation
 
 #### CMS Guards and Admin Self-Protection
 
@@ -9691,7 +9696,7 @@ Four distinct persona classes consume the UI, with role-based affordances enforc
 The UI surface supports six top-level capability families, each rooted in a dedicated route group:
 
 1. **Public Content Delivery (F-001)** — locale-aware marketing, article, and product-detail rendering with SEO metadata, `robots.txt`, and `sitemap.xml`.
-2. **Authentication & Account (F-002)** — email/password, GitHub OAuth, magic-link, password reset, profile completion.
+2. **Authentication & Account (F-002)** — email/password, magic-link, password reset, profile completion.
 3. **CMS Authoring (F-004, F-005, F-006, F-007, F-008, F-009)** — block-based page building, Tiptap rich text, media library, translations, revision history, navigation management.
 4. **Commerce (F-013 through F-021)** — catalog browsing, variant selection, cart, checkout, invoicing, customer order history.
 5. **Administration (F-003, F-030)** — user management, package activation, site settings, shipping/tax configuration.
@@ -9852,8 +9857,8 @@ The auth forms consume a typed message union defined in `apps/nextblock/componen
 
 | Path | File | Purpose |
 |:--|:--|:--|
-| `/sign-in` | `app/(auth-pages)/sign-in/page.tsx` | Email/password + GitHub OAuth, forgot-password link, sandbox credentials alert |
-| `/sign-up` | `app/(auth-pages)/sign-up/page.tsx` | Registration (email or GitHub) with success confirmation view |
+| `/sign-in` | `app/(auth-pages)/sign-in/page.tsx` | Email/password, forgot-password link, sandbox credentials alert |
+| `/sign-up` | `app/(auth-pages)/sign-up/page.tsx` | Registration (email) with success confirmation view |
 | `/forgot-password` | `app/(auth-pages)/forgot-password/page.tsx` | Password reset request form |
 | `/post-sign-in` | `app/(auth-pages)/post-sign-in/page.tsx` | Server routing endpoint (non-visual redirector) |
 | `/auth/callback` | `app/auth/callback/route.ts` | OAuth authorization-code exchange handler |
@@ -10046,10 +10051,9 @@ The component consumes `useTheme` from `next-themes`, uses a mounted-state guard
 
 | Interaction | Implementation |
 |:--|:--|
-| Sign-In Form | Email/password + forgot-password link + `GitHubLoginButton` + `SandboxCredentialsAlert` when `NEXT_PUBLIC_IS_SANDBOX === 'true'`. Max-width `160` (mx-auto). Hidden `redirect` field preserved for post-sign-in routing |
+| Sign-In Form | Email/password + forgot-password link + `SandboxCredentialsAlert` when `NEXT_PUBLIC_IS_SANDBOX === 'true'`. Max-width `160` (mx-auto). Hidden `redirect` field preserved for post-sign-in routing |
 | Sign-Up Form | Shared layout with sign-in. Success view rendered when URL contains success flag: confirmation badge (`rounded-full bg-primary/10 text-primary`), `CheckCircle2` icon, email-check instructions with `Mail` icon, "Back to sign in" / "Use different email" actions |
 | Header Auth (`header-auth.tsx`) | Missing-env warning badge + disabled buttons when env vars absent; avatar dropdown (`h-8 w-8 rounded-full`) with profile/dashboard/logout when authenticated; sign-in/sign-up buttons for guests |
-| GitHub OAuth (`GitHubLoginButton.tsx`) | Outline variant, full-width button with embedded GitHub SVG; invokes `supabase.auth.signInWithOAuth({ provider: 'github' })` with callback URL |
 
 ### 7.7.6 Commerce UI Interactions
 
@@ -10275,7 +10279,7 @@ Server-resolved locale (from `X-User-Locale` header) is bridged to client via `T
 
 #### Authentication Screens
 
-- `apps/nextblock/app/(auth-pages)/sign-in/page.tsx` — Sign-in with GitHub OAuth
+- `apps/nextblock/app/(auth-pages)/sign-in/page.tsx` — Email/password sign-in
 - `apps/nextblock/app/(auth-pages)/sign-up/page.tsx` — Sign-up with success state
 - `apps/nextblock/app/(auth-pages)/forgot-password/page.tsx` — Password reset
 - `apps/nextblock/app/(auth-pages)/post-sign-in/page.tsx` — Server-routing endpoint
@@ -10298,7 +10302,6 @@ Server-resolved locale (from `X-User-Locale` header) is bridged to client via `T
 - `apps/nextblock/components/ResponsiveNav.tsx` — Hierarchical navigation
 - `apps/nextblock/components/theme-switcher.tsx` — Four-theme dropdown
 - `apps/nextblock/components/header-auth.tsx` — Authenticated vs guest auth UI
-- `apps/nextblock/components/GitHubLoginButton.tsx` — OAuth trigger button
 - `apps/nextblock/components/form-message.tsx` — Typed auth message renderer
 
 #### Client Context Providers
@@ -10627,7 +10630,7 @@ Three distinct cloud providers compose the production footprint. The rationale f
 | Provider | Role | Selection Rationale |
 |:--|:--|:--|
 | Vercel | Compute + Edge + Cron + RUM | Zero-configuration Next.js 16 hosting; built-in image optimization; native App Router support; no container orchestration overhead; cron scheduling integrated with function lifecycle |
-| Supabase | PostgreSQL + Auth + Storage metadata | Managed PostgreSQL 17 with built-in RLS; GoTrue auth service; GitHub OAuth support; SQL migration CLI; PITR included; generous free tier for open-core distribution |
+| Supabase | PostgreSQL + Auth + Storage metadata | Managed PostgreSQL 17 with built-in RLS; GoTrue auth service; SQL migration CLI; PITR included; generous free tier for open-core distribution |
 | Cloudflare R2 | S3-compatible object storage | Zero egress fees (superior to AWS S3 for media-heavy workloads); S3-compatible API usable via `@aws-sdk/client-s3 ^3.920.0`; global edge presence |
 
 **Documented deviations from the Default Technology Stack** (per §3.7.1):
@@ -10639,7 +10642,7 @@ Three distinct cloud providers compose the production footprint. The rationale f
 | Terraform | Declarative config across `vercel.json`, migrations, `config.toml`, `.env.exemple`, `nx.json` | No multi-service provisioning to orchestrate |
 | GitHub Actions | Vercel Git integration + Node release scripts in `tools/scripts/` | No CI test suite to gate; publication handled imperatively |
 | Python / Flask | TypeScript + Next.js route handlers | Unified stack across client + server |
-| Auth0 | Supabase Auth (GoTrue) + GitHub OAuth | Integrated with RLS at the database layer |
+| Auth0 | Supabase Auth (GoTrue) | Integrated with RLS at the database layer |
 | MongoDB | Supabase PostgreSQL | Relational data model + RLS + SECURITY DEFINER helpers |
 
 ### 8.3.2 Core Services and Versions
@@ -10663,7 +10666,7 @@ Three distinct cloud providers compose the production footprint. The rationale f
 | PostgreSQL | `postgres` | `^3.8` (inventory dual-path fallback) | Direct SQL when RPC unavailable |
 | SSR client | `@supabase/ssr` | `^0.7.0` | Server-side cookie-based session |
 | Browser client | `@supabase/supabase-js` | `^2.77.0` | Client components + editor |
-| Auth (GoTrue) | via `@supabase/ssr` | bundled | Email/password, GitHub OAuth, password reset |
+| Auth (GoTrue) | via `@supabase/ssr` | bundled | Email/password, password reset |
 | Realtime | bundled (enabled in `config.toml`) | bundled | WebSocket subscriptions |
 | CLI | `supabase` | invoked via `npx supabase` | Migrations, link, db push, config push |
 

package/templates/nextblock-template/lib/custom-block-relation-registry.ts

@@ -155,12 +155,12 @@ const RELATION_TARGETS: readonly CustomBlockRelationTarget[] = [
     valueType: 'string',
   },
   {
-    descriptionColumns: ['github_username', 'website'],
+    descriptionColumns: ['website'],
     displayColumn: 'full_name',
     label: 'Profiles',
     orderBy: 'full_name',
-    searchableColumns: ['full_name', 'github_username', 'website'],
-    selectColumns: ['id', 'full_name', 'avatar_url', 'github_username', 'website', 'role'],
+    searchableColumns: ['full_name', 'website'],
+    selectColumns: ['id', 'full_name', 'avatar_url', 'website', 'role'],
     table: 'profiles',
     valueColumn: 'id',
     valueType: 'string',

package/templates/nextblock-template/lib/i18n/country-languages.ts

@@ -0,0 +1,247 @@
+// Ordered ISO 3166-1 alpha-2 country -> primary language candidates (ISO 639-1).
+// Used by the "visitor's country" language-detection mode: candidates are matched
+// against the site's active language codes in order, so multilingual countries list
+// their languages by prevalence (e.g. CH tries de, then fr, then it).
+// This is a pragmatic "most likely language" map, not a census — sites that need a
+// different mapping should simply not enable country-based detection.
+export const COUNTRY_PRIMARY_LANGUAGES: Record<string, string[]> = {
+  AD: ['ca', 'es', 'fr'],
+  AE: ['ar', 'en'],
+  AF: ['fa', 'ps'],
+  AG: ['en'],
+  AI: ['en'],
+  AL: ['sq'],
+  AM: ['hy', 'ru'],
+  AO: ['pt'],
+  AR: ['es'],
+  AS: ['en'],
+  AT: ['de'],
+  AU: ['en'],
+  AW: ['nl', 'es'],
+  AX: ['sv'],
+  AZ: ['az', 'ru'],
+  BA: ['bs', 'hr', 'sr'],
+  BB: ['en'],
+  BD: ['bn'],
+  BE: ['nl', 'fr', 'de'],
+  BF: ['fr'],
+  BG: ['bg'],
+  BH: ['ar', 'en'],
+  BI: ['fr', 'rn'],
+  BJ: ['fr'],
+  BM: ['en'],
+  BN: ['ms', 'en'],
+  BO: ['es'],
+  BQ: ['nl'],
+  BR: ['pt'],
+  BS: ['en'],
+  BT: ['dz', 'en'],
+  BW: ['en', 'tn'],
+  BY: ['ru', 'be'],
+  BZ: ['en', 'es'],
+  CA: ['en', 'fr'],
+  CD: ['fr'],
+  CF: ['fr'],
+  CG: ['fr'],
+  CH: ['de', 'fr', 'it'],
+  CI: ['fr'],
+  CK: ['en'],
+  CL: ['es'],
+  CM: ['fr', 'en'],
+  CN: ['zh'],
+  CO: ['es'],
+  CR: ['es'],
+  CU: ['es'],
+  CV: ['pt'],
+  CW: ['nl', 'en', 'es'],
+  CY: ['el', 'tr', 'en'],
+  CZ: ['cs'],
+  DE: ['de'],
+  DJ: ['fr', 'ar'],
+  DK: ['da'],
+  DM: ['en'],
+  DO: ['es'],
+  DZ: ['ar', 'fr'],
+  EC: ['es'],
+  EE: ['et', 'ru'],
+  EG: ['ar', 'en'],
+  EH: ['ar'],
+  ER: ['ti', 'ar', 'en'],
+  ES: ['es', 'ca', 'gl'],
+  ET: ['am', 'en'],
+  FI: ['fi', 'sv'],
+  FJ: ['en', 'fj'],
+  FK: ['en'],
+  FM: ['en'],
+  FO: ['fo', 'da'],
+  FR: ['fr'],
+  GA: ['fr'],
+  GB: ['en'],
+  GD: ['en'],
+  GE: ['ka', 'ru'],
+  GF: ['fr'],
+  GG: ['en'],
+  GH: ['en'],
+  GI: ['en', 'es'],
+  GL: ['kl', 'da'],
+  GM: ['en'],
+  GN: ['fr'],
+  GP: ['fr'],
+  GQ: ['es', 'fr', 'pt'],
+  GR: ['el'],
+  GT: ['es'],
+  GU: ['en'],
+  GW: ['pt'],
+  GY: ['en'],
+  HK: ['zh', 'en'],
+  HN: ['es'],
+  HR: ['hr'],
+  HT: ['fr', 'ht'],
+  HU: ['hu'],
+  ID: ['id'],
+  IE: ['en', 'ga'],
+  IL: ['he', 'ar', 'en', 'ru'],
+  IM: ['en'],
+  IN: ['hi', 'en'],
+  IQ: ['ar', 'ku'],
+  IR: ['fa'],
+  IS: ['is'],
+  IT: ['it'],
+  JE: ['en'],
+  JM: ['en'],
+  JO: ['ar', 'en'],
+  JP: ['ja'],
+  KE: ['en', 'sw'],
+  KG: ['ky', 'ru'],
+  KH: ['km'],
+  KI: ['en'],
+  KM: ['fr', 'ar'],
+  KN: ['en'],
+  KP: ['ko'],
+  KR: ['ko'],
+  KW: ['ar', 'en'],
+  KY: ['en'],
+  KZ: ['kk', 'ru'],
+  LA: ['lo'],
+  LB: ['ar', 'fr', 'en'],
+  LC: ['en'],
+  LI: ['de'],
+  LK: ['si', 'ta', 'en'],
+  LR: ['en'],
+  LS: ['en', 'st'],
+  LT: ['lt', 'ru'],
+  LU: ['fr', 'de', 'lb'],
+  LV: ['lv', 'ru'],
+  LY: ['ar'],
+  MA: ['ar', 'fr'],
+  MC: ['fr'],
+  MD: ['ro', 'ru'],
+  ME: ['sr'],
+  MF: ['fr'],
+  MG: ['fr', 'mg'],
+  MH: ['en'],
+  MK: ['mk', 'sq'],
+  ML: ['fr'],
+  MM: ['my'],
+  MN: ['mn'],
+  MO: ['zh', 'pt'],
+  MP: ['en'],
+  MQ: ['fr'],
+  MR: ['ar', 'fr'],
+  MS: ['en'],
+  MT: ['mt', 'en'],
+  MU: ['en', 'fr'],
+  MV: ['dv', 'en'],
+  MW: ['en', 'ny'],
+  MX: ['es'],
+  MY: ['ms', 'en', 'zh'],
+  MZ: ['pt'],
+  NA: ['en', 'af', 'de'],
+  NC: ['fr'],
+  NE: ['fr'],
+  NF: ['en'],
+  NG: ['en'],
+  NI: ['es'],
+  NL: ['nl'],
+  NO: ['no', 'nb'],
+  NP: ['ne'],
+  NR: ['en'],
+  NU: ['en'],
+  NZ: ['en', 'mi'],
+  OM: ['ar', 'en'],
+  PA: ['es'],
+  PE: ['es'],
+  PF: ['fr'],
+  PG: ['en'],
+  PH: ['en', 'tl'],
+  PK: ['ur', 'en'],
+  PL: ['pl'],
+  PM: ['fr'],
+  PR: ['es', 'en'],
+  PS: ['ar'],
+  PT: ['pt'],
+  PW: ['en'],
+  PY: ['es', 'gn'],
+  QA: ['ar', 'en'],
+  RE: ['fr'],
+  RO: ['ro'],
+  RS: ['sr'],
+  RU: ['ru'],
+  RW: ['rw', 'en', 'fr'],
+  SA: ['ar', 'en'],
+  SB: ['en'],
+  SC: ['en', 'fr'],
+  SD: ['ar', 'en'],
+  SE: ['sv'],
+  SG: ['en', 'zh', 'ms', 'ta'],
+  SH: ['en'],
+  SI: ['sl'],
+  SJ: ['no', 'nb'],
+  SK: ['sk'],
+  SL: ['en'],
+  SM: ['it'],
+  SN: ['fr'],
+  SO: ['so', 'ar'],
+  SR: ['nl'],
+  SS: ['en', 'ar'],
+  ST: ['pt'],
+  SV: ['es'],
+  SX: ['nl', 'en'],
+  SY: ['ar'],
+  SZ: ['en', 'ss'],
+  TC: ['en'],
+  TD: ['fr', 'ar'],
+  TG: ['fr'],
+  TH: ['th'],
+  TJ: ['tg', 'ru'],
+  TK: ['en'],
+  TL: ['pt'],
+  TM: ['tk', 'ru'],
+  TN: ['ar', 'fr'],
+  TO: ['en', 'to'],
+  TR: ['tr'],
+  TT: ['en'],
+  TV: ['en'],
+  TW: ['zh'],
+  TZ: ['sw', 'en'],
+  UA: ['uk', 'ru'],
+  UG: ['en', 'sw'],
+  UM: ['en'],
+  US: ['en', 'es'],
+  UY: ['es'],
+  UZ: ['uz', 'ru'],
+  VA: ['it'],
+  VC: ['en'],
+  VE: ['es'],
+  VG: ['en'],
+  VI: ['en'],
+  VN: ['vi'],
+  VU: ['en', 'fr'],
+  WF: ['fr'],
+  WS: ['en', 'sm'],
+  YE: ['ar'],
+  YT: ['fr'],
+  ZA: ['en', 'af', 'zu'],
+  ZM: ['en'],
+  ZW: ['en', 'sn'],
+};