1.2.4

Updated docs
1.2.3
2026-09-09 00:06:27 +02:00 · 2026-09-09 00:06:18 +02:00 · 2026-09-08 18:13:16 +02:00 · 2026-09-08 18:12:58 +02:00 · 2026-09-08 14:25:26 +02:00 · 2026-09-08 14:25:15 +02:00
85 changed files with 2730 additions and 267 deletions
@@ -1,6 +1,6 @@
 import type { Field } from 'payload';
 /**
 * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
 */
 export declare const generalFields: Field[];
@@ -1,6 +1,7 @@
+import { validateFaviconField } from '../../../modules/seo/index.js';
 /**
 * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
 */ export const generalFields = [
    {
        name: 'siteName',
@@ -63,7 +64,7 @@
        name: 'logo',
        type: 'upload',
        admin: {
-            description: 'Primary site logo.'
+            description: 'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).'
        },
        relationTo: 'media'
    },
@@ -79,7 +80,14 @@
        name: 'favicon',
        type: 'upload',
        admin: {
-            description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.'
+            description: 'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.'
+        },
+        hooks: {
+            // Warns the editor at save time if the favicon is too small (<48×48) or
+            // not square — Google won't display such favicons in search results.
+            beforeValidate: [
+                validateFaviconField
+            ]
        },
        relationTo: 'media'
    }
@@ -1 +1 @@
-{"version":3,"sources":["../../../../src/globals/SiteSettings/fields/general.ts"],"sourcesContent":["import type { Field } from 'payload'\n\n/**\n * General site identity fields.\n * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).\n */\nexport const generalFields: Field[] = [\n  {\n    name: 'siteName',\n    type: 'text',\n    admin: {\n      description: 'Used in page titles and Open Graph metadata.',\n    },\n    localized: true,\n    required: true,\n  },\n  {\n    name: 'titleOrder',\n    type: 'select',\n    admin: {\n      description: 'Which comes first in browser tabs.',\n    },\n    defaultValue: 'page-first',\n    options: [\n      { label: 'Page first  —  About Us | Acme', value: 'page-first' },\n      { label: 'Site first  —  Acme | About Us', value: 'site-first' },\n    ],\n  },\n  {\n    name: 'titleSeparator',\n    type: 'select',\n    admin: {\n      description: 'Separates the page title from the site name in browser tabs.',\n    },\n    defaultValue: '|',\n    options: [\n      { label: 'Pipe  —  Page | Site', value: '|' },\n      { label: 'Dash  —  Page – Site', value: '–' },\n      { label: 'Hyphen  —  Page - Site', value: '-' },\n      { label: 'Bullet  —  Page · Site', value: '·' },\n      { label: 'Slash  —  Page / Site', value: '/' },\n    ],\n  },\n  {\n    name: 'logo',\n    type: 'upload',\n    admin: {\n      description: 'Primary site logo.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'defaultShareImage',\n    type: 'upload',\n    admin: {\n      description: 'Fallback Open Graph image when a page has none.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'favicon',\n    type: 'upload',\n    admin: {\n      description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.',\n    },\n    relationTo: 'media',\n  },\n]\n"],"names":["generalFields","name","type","admin","description","localized","required","defaultValue","options","label","value","relationTo"],"mappings":"AAEA;;;CAGC,GACD,OAAO,MAAMA,gBAAyB;IACpC;QACEC,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAC,WAAW;QACXC,UAAU;IACZ;IACA;QACEL,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAkCC,OAAO;YAAa;YAC/D;gBAAED,OAAO;gBAAkCC,OAAO;YAAa;SAChE;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAAyBC,OAAO;YAAI;SAC9C;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;CACD,CAAA"}
+{"version":3,"sources":["../../../../src/globals/SiteSettings/fields/general.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport { validateFaviconField } from '../../../modules/seo/index.js'\n\n/**\n * General site identity fields.\n * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).\n */\nexport const generalFields: Field[] = [\n  {\n    name: 'siteName',\n    type: 'text',\n    admin: {\n      description: 'Used in page titles and Open Graph metadata.',\n    },\n    localized: true,\n    required: true,\n  },\n  {\n    name: 'titleOrder',\n    type: 'select',\n    admin: {\n      description: 'Which comes first in browser tabs.',\n    },\n    defaultValue: 'page-first',\n    options: [\n      { label: 'Page first  —  About Us | Acme', value: 'page-first' },\n      { label: 'Site first  —  Acme | About Us', value: 'site-first' },\n    ],\n  },\n  {\n    name: 'titleSeparator',\n    type: 'select',\n    admin: {\n      description: 'Separates the page title from the site name in browser tabs.',\n    },\n    defaultValue: '|',\n    options: [\n      { label: 'Pipe  —  Page | Site', value: '|' },\n      { label: 'Dash  —  Page – Site', value: '–' },\n      { label: 'Hyphen  —  Page - Site', value: '-' },\n      { label: 'Bullet  —  Page · Site', value: '·' },\n      { label: 'Slash  —  Page / Site', value: '/' },\n    ],\n  },\n  {\n    name: 'logo',\n    type: 'upload',\n    admin: {\n      description:\n        'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'defaultShareImage',\n    type: 'upload',\n    admin: {\n      description: 'Fallback Open Graph image when a page has none.',\n    },\n    relationTo: 'media',\n  },\n  {\n    name: 'favicon',\n    type: 'upload',\n    admin: {\n      description:\n        'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.',\n    },\n    hooks: {\n      // Warns the editor at save time if the favicon is too small (<48×48) or\n      // not square — Google won't display such favicons in search results.\n      beforeValidate: [validateFaviconField],\n    },\n    relationTo: 'media',\n  },\n]\n"],"names":["validateFaviconField","generalFields","name","type","admin","description","localized","required","defaultValue","options","label","value","relationTo","hooks","beforeValidate"],"mappings":"AAEA,SAASA,oBAAoB,QAAQ,gCAA+B;AAEpE;;;CAGC,GACD,OAAO,MAAMC,gBAAyB;IACpC;QACEC,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAC,WAAW;QACXC,UAAU;IACZ;IACA;QACEL,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAkCC,OAAO;YAAa;YAC/D;gBAAED,OAAO;gBAAkCC,OAAO;YAAa;SAChE;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAG,cAAc;QACdC,SAAS;YACP;gBAAEC,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAAwBC,OAAO;YAAI;YAC5C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAA0BC,OAAO;YAAI;YAC9C;gBAAED,OAAO;gBAAyBC,OAAO;YAAI;SAC9C;IACH;IACA;QACET,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aACE;QACJ;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aAAa;QACf;QACAO,YAAY;IACd;IACA;QACEV,MAAM;QACNC,MAAM;QACNC,OAAO;YACLC,aACE;QACJ;QACAQ,OAAO;YACL,wEAAwE;YACxE,qEAAqE;YACrEC,gBAAgB;gBAACd;aAAqB;QACxC;QACAY,YAAY;IACd;CACD,CAAA"}
@@ -29,6 +29,8 @@ export type { GlobalQueryOptions } from './modules/payload/index.js';
 export { getGlobal, getSiteIntegrations, getSiteSettings, SITE_INTEGRATIONS_SLUG, SITE_SETTINGS_SLUG, } from './modules/payload/index.js';
 export { buildSecurityHeaders } from './modules/security/index.js';
 export type { BuildSecurityHeadersArgs, SecurityHeader } from './modules/security/index.js';
+export { buildFaqJsonLd, buildIconsMetadata, buildLocalBusinessJsonLd, buildOrganizationJsonLd, buildServiceJsonLd, validateFaviconField, } from './modules/seo/index.js';
+export { buildBreadcrumbJsonLd, buildSiteNavigationJsonLd, buildWebSiteJsonLd, } from './modules/seo/index.js';
 export type { PageMetadata, SeoMeta, SeoOption } from './modules/seo/index.js';
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js';
 export type { AutoFillMapping, RobotsRules, SitemapEntry } from './modules/seo/index.js';
@@ -18,6 +18,10 @@ export { getNotificationTexts, NOTIFICATION_FALLBACK, resolveFormMessage } from
 export { ALL_SYSTEM_PAGE_ROLES, getSystemPagePath } from './modules/pages/index.js';
 export { getGlobal, getSiteIntegrations, getSiteSettings, SITE_INTEGRATIONS_SLUG, SITE_SETTINGS_SLUG } from './modules/payload/index.js';
 export { buildSecurityHeaders } from './modules/security/index.js';
+export { buildFaqJsonLd, buildIconsMetadata, buildLocalBusinessJsonLd, buildOrganizationJsonLd, buildServiceJsonLd, validateFaviconField } from './modules/seo/index.js';
+// Structured data (schema.org JSON-LD) — brand/sitelink signals for Google.
+// WebSite (+ optional SearchAction), BreadcrumbList (per page), SiteNavigation.
+export { buildBreadcrumbJsonLd, buildSiteNavigationJsonLd, buildWebSiteJsonLd } from './modules/seo/index.js';
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js';
 export { buildAutoFillMetaHook, buildRobots, buildSitemapEntries, createMetadataGenerator, createPageMetadata, injectAutoFillMeta } from './modules/seo/index.js';
 export { buildSlugField, toSlug } from './modules/slug/index.js';
@@ -1,14 +1,8 @@
 import type { BasePayload, SanitizedConfig } from 'payload';
-import type { ArchiveEntries, ContentOption, ResolvedRoute } from '../content/index.js';
+import type { ContentOption, ResolvedRoute, ArchiveEntries } from '../content/index.js';
 import type { I18nConfig } from '../i18n/index.js';
-import type { RobotsRules, SitemapEntry } from '../seo/index.js';
+import type { SitemapEntry, RobotsRules } from '../seo/index.js';
 type CreateContentHelpersArgs = {
-    /**
-     * Absolute site origin for sitemap/robots URLs. Falls back to
-     * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-     * reject, so set one in production).
-     */
-    baseUrl?: string;
    /**
     * The client's payload config promise (the default export of payload.config).
     * Passed in because the plugin never imports the client's config directly.
@@ -16,15 +10,21 @@ type CreateContentHelpersArgs = {
    config: Promise<SanitizedConfig> | SanitizedConfig;
    /** Archive-backed collections, same value as the plugin option. */
    content?: ContentOption;
+    /** SiteSettings global slug. Defaults to 'site-settings'. */
+    settingsSlug?: string;
+    /** Pages collection slug. Defaults to 'pages'. */
+    pagesSlug?: string;
    /**
     * i18n config. Required only if you want the ready-made `sitemap` / `robots`
     * handlers — they need the locale list to emit hreflang.
     */
    i18n?: I18nConfig;
-    /** Pages collection slug. Defaults to 'pages'. */
-    pagesSlug?: string;
-    /** SiteSettings global slug. Defaults to 'site-settings'. */
-    settingsSlug?: string;
+    /**
+     * Absolute site origin for sitemap/robots URLs. Falls back to
+     * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
+     * reject, so set one in production).
+     */
+    baseUrl?: string;
 };
 /**
 * Bundles the per-request data helpers a frontend needs — the same cached
@@ -52,13 +52,13 @@ type CreateContentHelpersArgs = {
 * a URL is, fetching gets the listing. Metadata generation needs the first and
 * not the second, and a page component composes them in two obvious lines.
 */
-export declare function createContentHelpers({ baseUrl, config, content, i18n, pagesSlug, settingsSlug, }: CreateContentHelpersArgs): {
+export declare function createContentHelpers({ config, content, settingsSlug, pagesSlug, i18n, baseUrl, }: CreateContentHelpersArgs): {
    getCachedPayload: () => Promise<BasePayload>;
    getConfiguredLocales: () => Promise<string[]>;
-    getEntries: (collection: string, locale: string, page: number, perPage: number) => Promise<ArchiveEntries>;
    getSettings: (locale: string) => Promise<import("payload").JsonObject>;
-    resolveRoute: (locale: string, segments: string[] | undefined, page: number) => Promise<null | ResolvedRoute>;
-    robots: () => RobotsRules;
+    resolveRoute: (locale: string, segments: string[] | undefined, page: number) => Promise<ResolvedRoute | null>;
+    getEntries: (collection: string, locale: string, page: number, perPage: number) => Promise<ArchiveEntries>;
    sitemap: () => Promise<SitemapEntry[]>;
+    robots: () => RobotsRules;
 };
 export {};
@@ -1,7 +1,7 @@
-import { getPayload } from 'payload';
 import { cache } from 'react';
-import { getArchiveEntries, resolveRoute as resolveRouteRaw } from '../content/index.js';
-import { buildRobots, buildSitemapEntries } from '../seo/index.js';
+import { getPayload } from 'payload';
+import { resolveRoute as resolveRouteRaw, getArchiveEntries } from '../content/index.js';
+import { buildSitemapEntries, buildRobots } from '../seo/index.js';
 /**
 * Bundles the per-request data helpers a frontend needs — the same cached
 * wrappers every project was writing by hand (getPayload, settings, locale
@@ -27,7 +27,7 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
 * `resolveRoute` and `getEntries` are separate on purpose: routing decides what
 * a URL is, fetching gets the listing. Metadata generation needs the first and
 * not the second, and a page component composes them in two obvious lines.
- */ export function createContentHelpers({ baseUrl, config, content, i18n, pagesSlug = 'pages', settingsSlug = 'site-settings' }) {
+ */ export function createContentHelpers({ config, content, settingsSlug = 'site-settings', pagesSlug = 'pages', i18n, baseUrl }) {
    const origin = baseUrl ?? process.env.NEXT_PUBLIC_SERVER_URL ?? '';
    const getCachedPayload = cache(async ()=>getPayload({
            config: await config
@@ -40,29 +40,29 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
        const payload = await getCachedPayload();
        return payload.findGlobal({
            slug: settingsSlug,
-            depth: 2,
-            locale: locale
+            locale: locale,
+            depth: 2
        });
    });
    /** What does this URL point at? Routing only — no listing data. */ const resolveRoute = cache(async (locale, segments, page)=>{
        const payload = await getCachedPayload();
        return resolveRouteRaw({
-            content,
-            locale,
-            page,
-            pagesSlug,
            payload,
+            locale,
            segments,
+            page,
+            content,
+            pagesSlug,
            settingsSlug
        });
    });
    /** One page of a collection's entries, for an archive listing. */ const getEntries = cache(async (collection, locale, page, perPage)=>{
        const payload = await getCachedPayload();
        return getArchiveEntries({
+            payload,
            collection,
            locale,
            page,
-            payload,
            perPage
        });
    });
@@ -73,19 +73,39 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
   * ```ts
   * // app/sitemap.ts
   * export { sitemap as default } from '@/lib/content'
+   * export const dynamic = 'force-dynamic'  // generate at runtime, not build
   * ```
+   *
+   * IMPORTANT — container deploys (Coolify/Docker/Railway/CI): Next treats
+   * sitemap.ts as STATIC by default and prerenders it during `next build`, which
+   * calls into Payload → the database. The build container usually has no access
+   * to the internal Docker network, so the DB connection fails (ENOTFOUND) and
+   * the build dies. Two defenses:
+   *   1. `export const dynamic = 'force-dynamic'` in app/sitemap.ts — skips build
+   *      prerender, generates at runtime when the DB is reachable (recommended).
+   *   2. This handler also catches DB errors and returns [] so that even without
+   *      (1) the build won't crash — it just ships an empty sitemap until the
+   *      next runtime regeneration. (1) is still preferred; (2) is a safety net.
   */ const sitemap = cache(async ()=>{
        if (!i18n) {
            throw new Error('[ipal] createContentHelpers: pass `i18n` to use the sitemap handler.');
        }
-        return buildSitemapEntries({
-            baseUrl: origin,
-            config: i18n,
-            content,
-            pagesSlug,
-            payload: await getCachedPayload(),
-            settingsSlug
-        });
+        try {
+            return await buildSitemapEntries({
+                payload: await getCachedPayload(),
+                config: i18n,
+                baseUrl: origin,
+                content,
+                pagesSlug,
+                settingsSlug
+            });
+        } catch (error) {
+            // DB unreachable (typically a container build with no DB network) — return
+            // an empty sitemap instead of failing the build. Runtime regeneration will
+            // produce the real one once the DB is reachable. See dynamic='force-dynamic'.
+            console.warn('[ipal] sitemap: could not reach the database, returning empty entries ' + "(add `export const dynamic = 'force-dynamic'` to app/sitemap.ts to " + 'generate at runtime and avoid build-time DB access):', error);
+            return [];
+        }
    });
    /**
   * Ready-made handler for Next's `app/robots.ts`. Re-export directly:
@@ -100,11 +120,11 @@ import { buildRobots, buildSitemapEntries } from '../seo/index.js';
    return {
        getCachedPayload,
        getConfiguredLocales,
-        getEntries,
        getSettings,
        resolveRoute,
-        robots,
-        sitemap
+        getEntries,
+        sitemap,
+        robots
    };
 }

@@ -1,21 +1,21 @@
-import type { I18nConfig } from './types.js';
+import type { I18nConfig } from '../i18n/index.js';
 /**
 * Minimal request shape the middleware reads. Kept structural so the plugin
 * doesn't hard-depend on next/server types; a Next.js `NextRequest` satisfies it.
 */
 type MiddlewareRequest = {
+    nextUrl: {
+        pathname: string;
+        search: string;
+        clone: () => URL;
+    };
    cookies: {
        get: (name: string) => {
            value: string;
        } | undefined;
    };
    headers: {
-        get: (name: string) => null | string;
-    };
-    nextUrl: {
-        clone: () => URL;
-        pathname: string;
-        search: string;
+        get: (name: string) => string | null;
    };
    url: string;
 };
@@ -25,21 +25,23 @@ type MiddlewareRequest = {
 * `next` means let the request pass through untouched.
 */
 export type LocaleMiddlewareResult = {
-    cookie?: {
-        name: string;
-        value: string;
-    };
-    location: string;
-    type: 'redirect';
-} | {
-    cookie?: {
-        name: string;
-        value: string;
-    };
    type: 'next';
+    cookie?: {
+        name: string;
+        value: string;
+    };
+} | {
+    type: 'redirect';
+    location: string;
+    cookie?: {
+        name: string;
+        value: string;
+    };
 };
 type CreateLocaleMiddlewareArgs = {
    config: I18nConfig;
+    /** Cookie name for the locale choice. Defaults to LOCALE_COOKIE_NAME. */
+    cookieName?: string;
    /**
     * Consent category that gates *persisting* the locale cookie. The locale is
     * always detected (routing works regardless), but the choice is only written
@@ -47,11 +49,9 @@ type CreateLocaleMiddlewareArgs = {
     * 'functional'. Pass 'necessary' to always persist (treat locale as strictly
     * necessary), which restores the pre-consent behaviour.
     */
-    consentCategory?: 'functional' | 'necessary';
+    consentCategory?: 'necessary' | 'functional';
    /** Name of the consent cookie to read. Defaults to CONSENT_COOKIE. */
    consentCookieName?: string;
-    /** Cookie name for the locale choice. Defaults to LOCALE_COOKIE_NAME. */
-    cookieName?: string;
 };
 /**
 * Builds locale-routing logic for Next.js middleware.
@@ -80,7 +80,7 @@ type CreateLocaleMiddlewareArgs = {
 *   return res
 * }
 */
-export declare function createLocaleMiddleware({ config, consentCategory, consentCookieName, cookieName, }: CreateLocaleMiddlewareArgs): (request: MiddlewareRequest) => LocaleMiddlewareResult;
+export declare function createLocaleMiddleware({ config, cookieName, consentCategory, consentCookieName, }: CreateLocaleMiddlewareArgs): (request: MiddlewareRequest) => LocaleMiddlewareResult;
 /**
 * Default Next.js middleware matcher: run on everything except API routes, the
 * admin panel, Next internals, and files with an extension (static assets).
@@ -1,5 +1,5 @@
+import { negotiateLocale, isValidLocale, LOCALE_COOKIE_NAME } from '../i18n/index.js';
 import { CONSENT_COOKIE, parseConsent } from '../consent/storage.js';
-import { isValidLocale, LOCALE_COOKIE_NAME, negotiateLocale } from '../i18n/index.js';
 /**
 * First path segment of a URL pathname, or '' for root.
 * '/pl/o-nas' → 'pl', '/o-nas' → 'o-nas', '/' → ''.
@@ -32,18 +32,26 @@ import { isValidLocale, LOCALE_COOKIE_NAME, negotiateLocale } from '../i18n/inde
 *   if (r.cookie) res.cookies.set(r.cookie.name, r.cookie.value)
 *   return res
 * }
- */ export function createLocaleMiddleware({ config, consentCategory = 'functional', consentCookieName = CONSENT_COOKIE, cookieName = LOCALE_COOKIE_NAME }) {
+ */ export function createLocaleMiddleware({ config, cookieName = LOCALE_COOKIE_NAME, consentCategory = 'functional', consentCookieName = CONSENT_COOKIE }) {
    // Whether the locale cookie may be written: 'necessary' is always granted;
    // 'functional' (default) requires the visitor to have consented.
    function mayPersistLocale(request) {
-        if (consentCategory === 'necessary') {
-            return true;
-        }
+        if (consentCategory === 'necessary') return true;
        const consent = parseConsent(request.cookies.get(consentCookieName)?.value);
        return consent?.[consentCategory] === true;
    }
    return function localeMiddleware(request) {
        const { pathname } = request.nextUrl;
+        // Single-locale sites have no /pl, /en prefix and no negotiation — one
+        // language, no redirect. The middleware becomes a pass-through: paths stay
+        // as-is (/o-nas), nothing to detect or persist. (Projects that are truly
+        // single-locale usually don't even mount this middleware, but guarding here
+        // makes it safe if they do.)
+        if (config.locales.length === 1) {
+            return {
+                type: 'next'
+            };
+        }
        // Already locale-prefixed (e.g. the visitor switched language by
        // navigating to /en). Routing is fine — but if the URL's locale differs
        // from the stored cookie, the visitor is *choosing* a language, and we
@@ -68,9 +76,9 @@ import { isValidLocale, LOCALE_COOKIE_NAME, negotiateLocale } from '../i18n/inde
        }
        // Resolve the locale to use
        const locale = negotiateLocale({
+            cookieLocale: request.cookies.get(cookieName)?.value ?? null,
            acceptLanguage: request.headers.get('accept-language'),
-            config,
-            cookieLocale: request.cookies.get(cookieName)?.value ?? null
+            config
        });
        // Redirect to the locale-prefixed path, preserving the rest
        const url = request.nextUrl.clone();
@@ -28,6 +28,12 @@ import { isValidLocale } from './helpers.js';
    if (!slug) {
        return undefined;
    }
+    // Single-locale sites have no /pl, /en prefix — the language segment is
+    // dropped entirely (path is /o-nas, not /pl/o-nas). Detected automatically:
+    // one configured locale means one language, so no prefix is needed. The
+    // project's folder structure matches (app/[[...slug]] without [locale]).
+    const singleLocale = config.locales.length === 1;
+    const localeSegment = singleLocale ? '' : `/${locale}`;
    if (prefix) {
        const segment = prefix[locale];
        // No archive slug in this locale means the entry is unreachable there —
@@ -36,12 +42,13 @@ import { isValidLocale } from './helpers.js';
        if (!segment) {
            return undefined;
        }
-        return `/${locale}/${segment}/${slug}`;
+        return `${localeSegment}/${segment}/${slug}`;
    }
    if (slug === homeSlug) {
-        return `/${locale}`;
+        // Home collapses to the root: '/' for single-locale, '/pl' otherwise.
+        return localeSegment || '/';
    }
-    return `/${locale}/${slug}`;
+    return `${localeSegment}/${slug}`;
 }
 /**
 * Resolves the equivalent path for the same document in a different locale —
@@ -0,0 +1,40 @@
+type Crumb = {
+    /** Visible name of the breadcrumb (e.g. 'Usługi'). */
+    name: string;
+    /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */
+    url: string;
+};
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */
+export declare function buildBreadcrumbJsonLd(crumbs: Crumb[]): {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        name: string;
+        '@type': string;
+        item: string;
+        position: number;
+    }[];
+} | null;
+export {};
@@ -0,0 +1,39 @@
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */ export function buildBreadcrumbJsonLd(crumbs) {
+    if (!crumbs || crumbs.length < 2) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'BreadcrumbList',
+        itemListElement: crumbs.map((crumb, index)=>({
+                name: crumb.name,
+                '@type': 'ListItem',
+                item: crumb.url,
+                position: index + 1
+            }))
+    };
+}
+
+//# sourceMappingURL=buildBreadcrumbJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildBreadcrumbJsonLd.ts"],"sourcesContent":["type Crumb = {\n  /** Visible name of the breadcrumb (e.g. 'Usługi'). */\n  name: string\n  /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */\n  url: string\n}\n\n/**\n * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site\n * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)\n * and uses them to understand structure — a signal that helps navigational\n * results and sitelinks.\n *\n * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are\n * PER-PAGE — build them from the page's ancestry and emit on that page:\n *\n *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildBreadcrumbJsonLd([\n *     { name: 'Strona główna', url: `${base}/pl` },\n *     { name: 'Usługi', url: `${base}/pl/uslugi` },\n *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },\n *   ])\n *   <script type=\"application/ld+json\" ... />\n *\n * The crumb data comes from the page's real position (parent pages / URL path),\n * NOT hardcoded. Derive it from the resolved route, not a static list.\n *\n * Returns null for an empty/single crumb list — a one-item breadcrumb isn't\n * meaningful and shouldn't be emitted.\n */\nexport function buildBreadcrumbJsonLd(crumbs: Crumb[]) {\n  if (!crumbs || crumbs.length < 2) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'BreadcrumbList',\n    itemListElement: crumbs.map((crumb, index) => ({\n      name: crumb.name,\n      '@type': 'ListItem',\n      item: crumb.url,\n      position: index + 1,\n    })),\n  }\n}\n"],"names":["buildBreadcrumbJsonLd","crumbs","length","itemListElement","map","crumb","index","name","item","url","position"],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASA,sBAAsBC,MAAe;IACnD,IAAI,CAACA,UAAUA,OAAOC,MAAM,GAAG,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,iBAAiBF,OAAOG,GAAG,CAAC,CAACC,OAAOC,QAAW,CAAA;gBAC7CC,MAAMF,MAAME,IAAI;gBAChB,SAAS;gBACTC,MAAMH,MAAMI,GAAG;gBACfC,UAAUJ,QAAQ;YACpB,CAAA;IACF;AACF"}
@@ -0,0 +1,33 @@
+type FaqItem = {
+    answer: string;
+    question: string;
+};
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */
+export declare function buildFaqJsonLd(items: FaqItem[]): {
+    '@context': string;
+    '@type': string;
+    mainEntity: {
+        name: string;
+        '@type': string;
+        acceptedAnswer: {
+            '@type': string;
+            text: string;
+        };
+    }[];
+} | null;
+export {};
@@ -0,0 +1,34 @@
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */ export function buildFaqJsonLd(items) {
+    if (!items || items.length === 0) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'FAQPage',
+        mainEntity: items.map((item)=>({
+                name: item.question,
+                '@type': 'Question',
+                acceptedAnswer: {
+                    '@type': 'Answer',
+                    text: item.answer
+                }
+            }))
+    };
+}
+
+//# sourceMappingURL=buildFaqJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildFaqJsonLd.ts"],"sourcesContent":["type FaqItem = {\n  answer: string\n  question: string\n}\n\n/**\n * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as\n * expandable FAQ rich results under the page, taking more SERP space and helping\n * with voice/AI answers. Strong for service landing pages.\n *\n * Feed it the SAME questions/answers rendered on the page (from an FAQ block in\n * the panel) — the structured data must match visible content, or Google may\n * flag it. Never invent Q&A that isn't on the page.\n *\n *   import { buildFaqJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildFaqJsonLd(\n *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))\n *   )\n *\n * Returns null for empty list.\n */\nexport function buildFaqJsonLd(items: FaqItem[]) {\n  if (!items || items.length === 0) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'FAQPage',\n    mainEntity: items.map((item) => ({\n      name: item.question,\n      '@type': 'Question',\n      acceptedAnswer: {\n        '@type': 'Answer',\n        text: item.answer,\n      },\n    })),\n  }\n}\n"],"names":["buildFaqJsonLd","items","length","mainEntity","map","item","name","question","acceptedAnswer","text","answer"],"mappings":"AAKA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASA,eAAeC,KAAgB;IAC7C,IAAI,CAACA,SAASA,MAAMC,MAAM,KAAK,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,YAAYF,MAAMG,GAAG,CAAC,CAACC,OAAU,CAAA;gBAC/BC,MAAMD,KAAKE,QAAQ;gBACnB,SAAS;gBACTC,gBAAgB;oBACd,SAAS;oBACTC,MAAMJ,KAAKK,MAAM;gBACnB;YACF,CAAA;IACF;AACF"}
@@ -0,0 +1,33 @@
+import type { Metadata } from 'next';
+type MediaLike = {
+    height?: null | number;
+    mimeType?: null | string;
+    url?: null | string;
+    width?: null | number;
+} | null | undefined;
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */
+export declare function buildIconsMetadata(favicon: MediaLike): Metadata;
+export {};
@@ -0,0 +1,54 @@
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */ export function buildIconsMetadata(favicon) {
+    const url = favicon?.url;
+    if (!url) {
+        return {};
+    }
+    const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg');
+    return {
+        icons: {
+            // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).
+            icon: isSvg ? [
+                {
+                    type: 'image/svg+xml',
+                    url
+                }
+            ] : [
+                {
+                    sizes: 'any',
+                    url
+                }
+            ],
+            // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.
+            apple: [
+                {
+                    url
+                }
+            ]
+        }
+    };
+}
+
+//# sourceMappingURL=buildIconsMetadata.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildIconsMetadata.ts"],"sourcesContent":["import type { Metadata } from 'next'\n\ntype MediaLike =\n  | { height?: null | number; mimeType?: null | string; url?: null | string; width?: null | number }\n  | null\n  | undefined\n\n/**\n * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's\n * favicon upload, so the browser tab AND Google get a proper <link rel=\"icon\">.\n *\n * Why the plugin must do this (not the project): favicon-in-Google has strict\n * rules — a real <link rel=\"icon\"> in <head>, square, ≥48×48, at a stable URL.\n * Leaving it to each project meant inconsistent hand-rolled tags and no favicon\n * in search results. This generates the tags correctly, every time, from the\n * panel field.\n *\n * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's\n * generateMetadata — not per page:\n *\n *   import { buildIconsMetadata } from '@intecion/ipal-kit'\n *   export async function generateMetadata(): Promise<Metadata> {\n *     const settings = await getSettings(locale)\n *     return buildIconsMetadata(settings.favicon)\n *   }\n *\n * Google notes: it caches favicons separately and slowly (days/weeks), and only\n * shows them for icons it deems valid. Warn on too-small icons at upload time\n * (see the media validation hook) so editors don't ship a <48px favicon Google\n * will reject.\n */\nexport function buildIconsMetadata(favicon: MediaLike): Metadata {\n  const url = favicon?.url\n  if (!url) {return {}}\n\n  const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg')\n\n  return {\n    icons: {\n      // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).\n      icon: isSvg ? [{ type: 'image/svg+xml', url }] : [{ sizes: 'any', url }],\n      // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.\n      apple: [{ url }],\n    },\n  }\n}\n"],"names":["buildIconsMetadata","favicon","url","isSvg","mimeType","endsWith","icons","icon","type","sizes","apple"],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASA,mBAAmBC,OAAkB;IACnD,MAAMC,MAAMD,SAASC;IACrB,IAAI,CAACA,KAAK;QAAC,OAAO,CAAC;IAAC;IAEpB,MAAMC,QAAQF,SAASG,aAAa,mBAAmBF,IAAIG,QAAQ,CAAC;IAEpE,OAAO;QACLC,OAAO;YACL,sEAAsE;YACtEC,MAAMJ,QAAQ;gBAAC;oBAAEK,MAAM;oBAAiBN;gBAAI;aAAE,GAAG;gBAAC;oBAAEO,OAAO;oBAAOP;gBAAI;aAAE;YACxE,yEAAyE;YACzEQ,OAAO;gBAAC;oBAAER;gBAAI;aAAE;QAClB;IACF;AACF"}
@@ -0,0 +1,71 @@
+type MediaLike = {
+    url?: null | string;
+} | null | undefined;
+type Address = {
+    city?: string;
+    country?: string;
+    postalCode?: string;
+    region?: string;
+    street?: string;
+};
+type LocalBusinessJsonLdArgs = {
+    address?: Address;
+    /** Geo coordinates for maps/local search. */
+    geo?: {
+        latitude: number;
+        longitude: number;
+    };
+    image?: MediaLike;
+    logo?: MediaLike;
+    name: string;
+    /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */
+    openingHours?: string[];
+    priceRange?: string;
+    sameAs?: string[];
+    /** Business phone, e.g. '+48 123 456 789'. */
+    telephone?: string;
+    url: string;
+};
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */
+export declare function buildLocalBusinessJsonLd({ name, address, geo, image, logo, openingHours, priceRange, sameAs, telephone, url, }: LocalBusinessJsonLdArgs): {
+    sameAs?: string[] | undefined;
+    priceRange?: string | undefined;
+    openingHours?: string[] | undefined;
+    geo?: {
+        '@type': string;
+        latitude: number;
+        longitude: number;
+    } | undefined;
+    address?: {
+        addressCountry?: string | undefined;
+        addressRegion?: string | undefined;
+        postalCode?: string | undefined;
+        addressLocality?: string | undefined;
+        streetAddress?: string | undefined;
+        '@type': string;
+    } | undefined;
+    logo?: string | undefined;
+    image?: string | undefined;
+    telephone?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};
@@ -0,0 +1,73 @@
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */ export function buildLocalBusinessJsonLd({ name, address, geo, image, logo, openingHours, priceRange, sameAs, telephone, url }) {
+    const logoUrl = logo?.url;
+    const imageUrl = image?.url ?? logoUrl;
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'LocalBusiness',
+        url,
+        ...telephone ? {
+            telephone
+        } : {},
+        ...imageUrl ? {
+            image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}`
+        } : {},
+        ...logoUrl ? {
+            logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}`
+        } : {},
+        ...address ? {
+            address: {
+                '@type': 'PostalAddress',
+                ...address.street ? {
+                    streetAddress: address.street
+                } : {},
+                ...address.city ? {
+                    addressLocality: address.city
+                } : {},
+                ...address.postalCode ? {
+                    postalCode: address.postalCode
+                } : {},
+                ...address.region ? {
+                    addressRegion: address.region
+                } : {},
+                ...address.country ? {
+                    addressCountry: address.country
+                } : {}
+            }
+        } : {},
+        ...geo ? {
+            geo: {
+                '@type': 'GeoCoordinates',
+                latitude: geo.latitude,
+                longitude: geo.longitude
+            }
+        } : {},
+        ...openingHours && openingHours.length > 0 ? {
+            openingHours
+        } : {},
+        ...priceRange ? {
+            priceRange
+        } : {},
+        ...sameAs && sameAs.length > 0 ? {
+            sameAs
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildLocalBusinessJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildLocalBusinessJsonLd.ts"],"sourcesContent":["type MediaLike = { url?: null | string } | null | undefined\n\ntype Address = {\n  city?: string\n  country?: string // ISO code, e.g. 'PL'\n  postalCode?: string\n  region?: string\n  street?: string\n}\n\ntype LocalBusinessJsonLdArgs = {\n  address?: Address\n  /** Geo coordinates for maps/local search. */\n  geo?: { latitude: number; longitude: number }\n  image?: MediaLike\n  logo?: MediaLike\n  name: string\n  /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */\n  openingHours?: string[]\n  priceRange?: string // e.g. '$$'\n  sameAs?: string[]\n  /** Business phone, e.g. '+48 123 456 789'. */\n  telephone?: string\n  url: string\n}\n\n/**\n * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL\n * SEO. Helps Google show the business in local results / map pack with address,\n * hours, phone. Strong signal for \"usługa + miasto\" queries.\n *\n * All data from the panel (company global) — nothing hardcoded. Emit once in the\n * root layout (business is site-wide):\n *\n *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildLocalBusinessJsonLd({\n *     name: company.name, url: baseUrl, telephone: company.phone,\n *     address: company.address, openingHours: company.hours,\n *   })\n *\n * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the\n * returned object — schema.org has many LocalBusiness subtypes.\n */\nexport function buildLocalBusinessJsonLd({\n  name,\n  address,\n  geo,\n  image,\n  logo,\n  openingHours,\n  priceRange,\n  sameAs,\n  telephone,\n  url,\n}: LocalBusinessJsonLdArgs) {\n  const logoUrl = logo?.url\n  const imageUrl = image?.url ?? logoUrl\n\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'LocalBusiness',\n    url,\n    ...(telephone ? { telephone } : {}),\n    ...(imageUrl ? { image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}` } : {}),\n    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),\n    ...(address\n      ? {\n          address: {\n            '@type': 'PostalAddress',\n            ...(address.street ? { streetAddress: address.street } : {}),\n            ...(address.city ? { addressLocality: address.city } : {}),\n            ...(address.postalCode ? { postalCode: address.postalCode } : {}),\n            ...(address.region ? { addressRegion: address.region } : {}),\n            ...(address.country ? { addressCountry: address.country } : {}),\n          },\n        }\n      : {}),\n    ...(geo\n      ? { geo: { '@type': 'GeoCoordinates', latitude: geo.latitude, longitude: geo.longitude } }\n      : {}),\n    ...(openingHours && openingHours.length > 0 ? { openingHours } : {}),\n    ...(priceRange ? { priceRange } : {}),\n    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),\n  }\n}\n"],"names":["buildLocalBusinessJsonLd","name","address","geo","image","logo","openingHours","priceRange","sameAs","telephone","url","logoUrl","imageUrl","startsWith","street","streetAddress","city","addressLocality","postalCode","region","addressRegion","country","addressCountry","latitude","longitude","length"],"mappings":"AA0BA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASA,yBAAyB,EACvCC,IAAI,EACJC,OAAO,EACPC,GAAG,EACHC,KAAK,EACLC,IAAI,EACJC,YAAY,EACZC,UAAU,EACVC,MAAM,EACNC,SAAS,EACTC,GAAG,EACqB;IACxB,MAAMC,UAAUN,MAAMK;IACtB,MAAME,WAAWR,OAAOM,OAAOC;IAE/B,OAAO;QACLV;QACA,YAAY;QACZ,SAAS;QACTS;QACA,GAAID,YAAY;YAAEA;QAAU,IAAI,CAAC,CAAC;QAClC,GAAIG,WAAW;YAAER,OAAOQ,SAASC,UAAU,CAAC,UAAUD,WAAW,GAAGF,MAAME,UAAU;QAAC,IAAI,CAAC,CAAC;QAC3F,GAAID,UAAU;YAAEN,MAAMM,QAAQE,UAAU,CAAC,UAAUF,UAAU,GAAGD,MAAMC,SAAS;QAAC,IAAI,CAAC,CAAC;QACtF,GAAIT,UACA;YACEA,SAAS;gBACP,SAAS;gBACT,GAAIA,QAAQY,MAAM,GAAG;oBAAEC,eAAeb,QAAQY,MAAM;gBAAC,IAAI,CAAC,CAAC;gBAC3D,GAAIZ,QAAQc,IAAI,GAAG;oBAAEC,iBAAiBf,QAAQc,IAAI;gBAAC,IAAI,CAAC,CAAC;gBACzD,GAAId,QAAQgB,UAAU,GAAG;oBAAEA,YAAYhB,QAAQgB,UAAU;gBAAC,IAAI,CAAC,CAAC;gBAChE,GAAIhB,QAAQiB,MAAM,GAAG;oBAAEC,eAAelB,QAAQiB,MAAM;gBAAC,IAAI,CAAC,CAAC;gBAC3D,GAAIjB,QAAQmB,OAAO,GAAG;oBAAEC,gBAAgBpB,QAAQmB,OAAO;gBAAC,IAAI,CAAC,CAAC;YAChE;QACF,IACA,CAAC,CAAC;QACN,GAAIlB,MACA;YAAEA,KAAK;gBAAE,SAAS;gBAAkBoB,UAAUpB,IAAIoB,QAAQ;gBAAEC,WAAWrB,IAAIqB,SAAS;YAAC;QAAE,IACvF,CAAC,CAAC;QACN,GAAIlB,gBAAgBA,aAAamB,MAAM,GAAG,IAAI;YAAEnB;QAAa,IAAI,CAAC,CAAC;QACnE,GAAIC,aAAa;YAAEA;QAAW,IAAI,CAAC,CAAC;QACpC,GAAIC,UAAUA,OAAOiB,MAAM,GAAG,IAAI;YAAEjB;QAAO,IAAI,CAAC,CAAC;IACnD;AACF"}
@@ -19,6 +19,11 @@ export type PageMetadata = {
        locale?: string;
        title: string;
    };
+    /** robots directives — set to noindex/follow for legal/thin/search pages. */
+    robots?: {
+        follow: boolean;
+        index: boolean;
+    };
    title: string;
 };
 type BuildMetadataArgs = {
@@ -35,6 +40,13 @@ type BuildMetadataArgs = {
    meta?: null | SeoMeta;
    /** Page title or site name first. Defaults to 'page-first'. */
    order?: TitleOrder;
+    /**
+     * The document's own title (e.g. page.title = 'Sprzątanie biur'). Used as the
+     * page-title source when meta.title is empty — the browser tab and search
+     * result should show the page name, not go blank, when an editor didn't fill
+     * the SEO title. Priority: titleOverride > meta.title > pageTitle.
+     */
+    pageTitle?: null | string;
    /**
     * Localized segment the document lives under (an archive page's slugs).
     * Feeds both canonical and hreflang, so /pl/artykuly/moj-post and
@@ -65,5 +77,5 @@ type BuildMetadataArgs = {
 * pieces (meta group, site name, image URL, localized slugs) and passes them
 * in — the plugin composes, it doesn't fetch.
 */
-export declare function buildMetadata({ baseUrl, config, homeSlug, imageUrl, locale, meta, order, prefix, query, separator, siteName, slugs, }: BuildMetadataArgs): PageMetadata;
+export declare function buildMetadata({ baseUrl, config, homeSlug, imageUrl, locale, meta, order, pageTitle, prefix, query, separator, siteName, slugs, }: BuildMetadataArgs): PageMetadata;
 export {};
@@ -9,13 +9,16 @@ import { buildHreflangAlternates } from './hreflang.js';
 * Designed for use inside Next.js `generateMetadata`. The caller resolves the
 * pieces (meta group, site name, image URL, localized slugs) and passes them
 * in — the plugin composes, it doesn't fetch.
- */ export function buildMetadata({ baseUrl, config, homeSlug = 'home', imageUrl, locale, meta, order, prefix, query, separator, siteName, slugs }) {
-    // titleOverride wins outright: an editor who filled it in wants that exact
-    // string in the tab, not a composition.
+ */ export function buildMetadata({ baseUrl, config, homeSlug = 'home', imageUrl, locale, meta, order, pageTitle, prefix, query, separator, siteName, slugs }) {
+    // Title source priority: titleOverride (exact, wins outright) > meta.title
+    // (SEO title an editor set) > pageTitle (the document's own name). This means
+    // a page with no SEO title still shows its name (e.g. 'Sprzątanie biur')
+    // composed with the site name, instead of just the site name or a blank.
    const override = meta?.titleOverride?.trim();
+    const resolvedPageTitle = meta?.title?.trim() || pageTitle?.trim() || undefined;
    const title = override || composeTitle({
        order,
-        pageTitle: meta?.title,
+        pageTitle: resolvedPageTitle,
        separator,
        siteName
    });
@@ -69,7 +72,15 @@ import { buildHreflangAlternates } from './hreflang.js';
                images
            },
            locale
-        }
+        },
+        // noindex → tell search engines to exclude the page but still follow links
+        // (authority flows through). For legal/thin/search-result pages.
+        ...meta?.noindex ? {
+            robots: {
+                follow: true,
+                index: false
+            }
+        } : {}
    };
 }

@@ -0,0 +1,41 @@
+type MediaLike = {
+    url?: null | string;
+} | null | undefined;
+type OrganizationJsonLdArgs = {
+    /** Logo media (from panel). Google uses this for brand knowledge panels. */
+    logo?: MediaLike;
+    /** Organization / site name. */
+    name: string;
+    /** Optional social / official profile URLs (sameAs). */
+    sameAs?: string[];
+    /** Absolute site URL (https://…). */
+    url: string;
+};
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */
+export declare function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs): {
+    sameAs?: string[] | undefined;
+    logo?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};
@@ -0,0 +1,35 @@
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */ export function buildOrganizationJsonLd({ name, logo, sameAs, url }) {
+    const logoUrl = logo?.url;
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'Organization',
+        url,
+        ...logoUrl ? {
+            logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}`
+        } : {},
+        ...sameAs && sameAs.length > 0 ? {
+            sameAs
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildOrganizationJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildOrganizationJsonLd.ts"],"sourcesContent":["type MediaLike = { url?: null | string } | null | undefined\n\ntype OrganizationJsonLdArgs = {\n  /** Logo media (from panel). Google uses this for brand knowledge panels. */\n  logo?: MediaLike\n  /** Organization / site name. */\n  name: string\n  /** Optional social / official profile URLs (sameAs). */\n  sameAs?: string[]\n  /** Absolute site URL (https://…). */\n  url: string\n}\n\n/**\n * Builds Organization JSON-LD (schema.org) — helps Google associate the site\n * with a brand: name, logo, official links. Improves how the site appears in\n * search (brand recognition, logo in knowledge panels) and is a signal used\n * alongside favicon for identity.\n *\n * Returns a plain object; the project renders it as a <script type=\"application/\n * ld+json\"> in the root layout:\n *\n *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildOrganizationJsonLd({\n *     name: settings.siteName, url: baseUrl, logo: settings.logo,\n *   })\n *   <script type=\"application/ld+json\"\n *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />\n *\n * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in\n * the root layout (Organization is site-wide, not per page).\n */\nexport function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs) {\n  const logoUrl = logo?.url\n\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'Organization',\n    url,\n    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),\n    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),\n  }\n}\n"],"names":["buildOrganizationJsonLd","name","logo","sameAs","url","logoUrl","startsWith","length"],"mappings":"AAaA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASA,wBAAwB,EAAEC,IAAI,EAAEC,IAAI,EAAEC,MAAM,EAAEC,GAAG,EAA0B;IACzF,MAAMC,UAAUH,MAAME;IAEtB,OAAO;QACLH;QACA,YAAY;QACZ,SAAS;QACTG;QACA,GAAIC,UAAU;YAAEH,MAAMG,QAAQC,UAAU,CAAC,UAAUD,UAAU,GAAGD,MAAMC,SAAS;QAAC,IAAI,CAAC,CAAC;QACtF,GAAIF,UAAUA,OAAOI,MAAM,GAAG,IAAI;YAAEJ;QAAO,IAAI,CAAC,CAAC;IACnD;AACF"}
@@ -0,0 +1,39 @@
+type ServiceJsonLdArgs = {
+    /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */
+    areaServed?: string | string[];
+    description?: string;
+    /** Service name, e.g. 'Sprzątanie biur'. */
+    name: string;
+    /** Provider (business) name. */
+    providerName: string;
+    /** Service type / category. */
+    serviceType?: string;
+    url: string;
+};
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */
+export declare function buildServiceJsonLd({ name, areaServed, description, providerName, serviceType, url, }: ServiceJsonLdArgs): {
+    serviceType?: string | undefined;
+    areaServed?: string | string[] | undefined;
+    description?: string | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    provider: {
+        name: string;
+        '@type': string;
+        url: string;
+    };
+};
+export {};
@@ -0,0 +1,35 @@
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */ export function buildServiceJsonLd({ name, areaServed, description, providerName, serviceType, url }) {
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'Service',
+        provider: {
+            name: providerName,
+            '@type': 'LocalBusiness',
+            url
+        },
+        ...description ? {
+            description
+        } : {},
+        ...areaServed ? {
+            areaServed
+        } : {},
+        ...serviceType ? {
+            serviceType
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildServiceJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildServiceJsonLd.ts"],"sourcesContent":["type ServiceJsonLdArgs = {\n  /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */\n  areaServed?: string | string[]\n  description?: string\n  /** Service name, e.g. 'Sprzątanie biur'. */\n  name: string\n  /** Provider (business) name. */\n  providerName: string\n  /** Service type / category. */\n  serviceType?: string\n  url: string\n}\n\n/**\n * Builds Service JSON-LD (schema.org) for a service offering. Helps Google\n * understand \"what this page sells\" — useful for service landing pages\n * (\"usługa + miasto\"). Pairs well with LocalBusiness (the provider).\n *\n * Per-page (each service page emits its own), data from the panel:\n *\n *   import { buildServiceJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildServiceJsonLd({\n *     name: page.serviceName, providerName: company.name,\n *     url: pageUrl, areaServed: 'Wrocław',\n *   })\n */\nexport function buildServiceJsonLd({\n  name,\n  areaServed,\n  description,\n  providerName,\n  serviceType,\n  url,\n}: ServiceJsonLdArgs) {\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'Service',\n    provider: {\n      name: providerName,\n      '@type': 'LocalBusiness',\n      url,\n    },\n    ...(description ? { description } : {}),\n    ...(areaServed ? { areaServed } : {}),\n    ...(serviceType ? { serviceType } : {}),\n  }\n}\n"],"names":["buildServiceJsonLd","name","areaServed","description","providerName","serviceType","url","provider"],"mappings":"AAaA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASA,mBAAmB,EACjCC,IAAI,EACJC,UAAU,EACVC,WAAW,EACXC,YAAY,EACZC,WAAW,EACXC,GAAG,EACe;IAClB,OAAO;QACLL;QACA,YAAY;QACZ,SAAS;QACTM,UAAU;YACRN,MAAMG;YACN,SAAS;YACTE;QACF;QACA,GAAIH,cAAc;YAAEA;QAAY,IAAI,CAAC,CAAC;QACtC,GAAID,aAAa;YAAEA;QAAW,IAAI,CAAC,CAAC;QACpC,GAAIG,cAAc;YAAEA;QAAY,IAAI,CAAC,CAAC;IACxC;AACF"}
@@ -0,0 +1,35 @@
+type NavItem = {
+    /** Visible label (e.g. 'Usługi'). */
+    name: string;
+    /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */
+    url: string;
+};
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */
+export declare function buildSiteNavigationJsonLd(items: NavItem[]): {
+    '@context': string;
+    '@type': string;
+    itemListElement: {
+        name: string;
+        '@type': string;
+        position: number;
+        url: string;
+    }[];
+} | null;
+export {};
@@ -0,0 +1,34 @@
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */ export function buildSiteNavigationJsonLd(items) {
+    if (!items || items.length === 0) {
+        return null;
+    }
+    return {
+        '@context': 'https://schema.org',
+        '@type': 'ItemList',
+        itemListElement: items.map((item, index)=>({
+                name: item.name,
+                '@type': 'SiteNavigationElement',
+                position: index + 1,
+                url: item.url
+            }))
+    };
+}
+
+//# sourceMappingURL=buildSiteNavigationJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildSiteNavigationJsonLd.ts"],"sourcesContent":["type NavItem = {\n  /** Visible label (e.g. 'Usługi'). */\n  name: string\n  /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */\n  url: string\n}\n\n/**\n * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —\n * declares the site's primary nav as structured data. A weaker sitelinks signal\n * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main\n * navigation targets.\n *\n * Feed it the SAME nav items the header renders (from the panel/nav global), so\n * the structured data matches the visible menu — not a separate hardcoded list.\n *\n *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildSiteNavigationJsonLd(\n *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))\n *   )\n *   <script type=\"application/ld+json\" ... />\n *\n * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.\n * Returns null for empty nav.\n */\nexport function buildSiteNavigationJsonLd(items: NavItem[]) {\n  if (!items || items.length === 0) {return null}\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'ItemList',\n    itemListElement: items.map((item, index) => ({\n      name: item.name,\n      '@type': 'SiteNavigationElement',\n      position: index + 1,\n      url: item.url,\n    })),\n  }\n}\n"],"names":["buildSiteNavigationJsonLd","items","length","itemListElement","map","item","index","name","position","url"],"mappings":"AAOA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASA,0BAA0BC,KAAgB;IACxD,IAAI,CAACA,SAASA,MAAMC,MAAM,KAAK,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,iBAAiBF,MAAMG,GAAG,CAAC,CAACC,MAAMC,QAAW,CAAA;gBAC3CC,MAAMF,KAAKE,IAAI;gBACf,SAAS;gBACTC,UAAUF,QAAQ;gBAClBG,KAAKJ,KAAKI,GAAG;YACf,CAAA;IACF;AACF"}
@@ -1,6 +1,6 @@
 import type { BasePayload } from 'payload';
-import type { ContentOption } from '../content/index.js';
 import type { I18nConfig } from '../i18n/index.js';
+import type { ContentOption } from '../content/index.js';
 /**
 * One sitemap entry, shaped for Next's `app/sitemap.ts`.
 *
@@ -10,31 +10,31 @@ import type { I18nConfig } from '../i18n/index.js';
 * is the common, weaker kind.
 */
 export type SitemapEntry = {
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
    alternates?: {
        languages: Record<string, string>;
    };
-    changeFrequency?: 'always' | 'daily' | 'hourly' | 'monthly' | 'never' | 'weekly' | 'yearly';
-    lastModified?: Date | string;
-    priority?: number;
-    url: string;
 };
 type BuildSitemapArgs = {
+    payload: BasePayload;
+    config: I18nConfig;
    /** Absolute origin, e.g. 'https://example.com'. Required for valid sitemap URLs. */
    baseUrl: string;
-    changeFrequency?: SitemapEntry['changeFrequency'];
-    config: I18nConfig;
+    /** Pages collection slug. Defaults to 'pages'. */
+    pagesSlug?: string;
    /** Archive-backed collections, same value as the plugin option. */
    content?: ContentOption;
+    /** SiteSettings global slug. Defaults to 'site-settings'. */
+    settingsSlug?: string;
    /**
     * Slug of the page that is the site root (collapses to /{locale}).
     * Read from System Pages when omitted.
     */
    homeSlug?: string;
-    /** Pages collection slug. Defaults to 'pages'. */
-    pagesSlug?: string;
-    payload: BasePayload;
-    /** SiteSettings global slug. Defaults to 'site-settings'. */
-    settingsSlug?: string;
+    changeFrequency?: SitemapEntry['changeFrequency'];
 };
 /**
 * Collects every public URL — pages and archive entries — as sitemap entries
@@ -57,5 +57,5 @@ type BuildSitemapArgs = {
 * }
 * ```
 */
-export declare function buildSitemapEntries({ baseUrl, changeFrequency, config, content, homeSlug, pagesSlug, payload, settingsSlug, }: BuildSitemapArgs): Promise<SitemapEntry[]>;
+export declare function buildSitemapEntries({ payload, config, baseUrl, pagesSlug, content, settingsSlug, homeSlug, changeFrequency, }: BuildSitemapArgs): Promise<SitemapEntry[]>;
 export {};
@@ -1,13 +1,31 @@
-import { archiveFieldName } from '../content/index.js';
-import { buildLocalizedPath, getLocalizedSlugs } from '../i18n/index.js';
+import { getLocalizedSlugs } from '../i18n/index.js';
+import { buildLocalizedPath } from '../i18n/index.js';
 import { buildHreflangAlternates } from './hreflang.js';
-/** Skip drafts and anything flagged noindex in the SEO tab. */ function isIndexable(doc) {
-    if (doc._status && doc._status !== 'published') {
-        return false;
-    }
-    if (doc.meta?.noindex) {
-        return false;
+import { archiveFieldName } from '../content/index.js';
+/**
+ * Slugs that must never appear in the sitemap — error/system pages that exist as
+ * documents (e.g. a '404' page in the Pages collection) but should not be
+ * indexed. A sitemap should list only real, HTTP-200 content; a '/pl/404' entry
+ * is an audit finding. Matched against the slug in any locale.
+ */ const EXCLUDED_SITEMAP_SLUGS = new Set([
+    '404',
+    '500',
+    'not-found',
+    'error'
+]);
+/** True if the doc's slug (in any locale) is an excluded system/error slug. */ function hasExcludedSlug(slug) {
+    if (typeof slug === 'string') return EXCLUDED_SITEMAP_SLUGS.has(slug);
+    if (slug && typeof slug === 'object') {
+        for (const value of Object.values(slug)){
+            if (typeof value === 'string' && EXCLUDED_SITEMAP_SLUGS.has(value)) return true;
+        }
    }
+    return false;
+}
+/** Skip drafts, noindex, and system/error pages (404 etc.). */ function isIndexable(doc) {
+    if (doc._status && doc._status !== 'published') return false;
+    if (doc.meta?.noindex) return false;
+    if (hasExcludedSlug(doc.slug)) return false;
    return true;
 }
 /**
@@ -17,26 +35,24 @@ import { buildHreflangAlternates } from './hreflang.js';
 * every locale (including itself, per Google's guidance).
 */ function entryFor(doc, locale, config, baseUrl, homeSlug, prefix, changeFrequency) {
    const slugs = doc.slug && typeof doc.slug === 'object' ? getLocalizedSlugs({
-        config,
-        slugField: doc.slug
+        slugField: doc.slug,
+        config
    }) : {};
    const path = buildLocalizedPath({
+        slugs,
+        locale,
        config,
        homeSlug,
-        locale,
-        prefix,
-        slugs
+        prefix
    });
-    if (!path) {
-        return null;
-    }
+    if (!path) return null;
    const origin = baseUrl.replace(/\/$/, '');
    const languages = buildHreflangAlternates({
-        baseUrl,
+        slugs,
        config,
+        baseUrl,
        homeSlug,
-        prefix,
-        slugs
+        prefix
    });
    return {
        url: `${origin}${path}`,
@@ -73,15 +89,15 @@ import { buildHreflangAlternates } from './hreflang.js';
 *   })
 * }
 * ```
- */ export async function buildSitemapEntries({ baseUrl, changeFrequency = 'weekly', config, content, homeSlug, pagesSlug = 'pages', payload, settingsSlug = 'site-settings' }) {
+ */ export async function buildSitemapEntries({ payload, config, baseUrl, pagesSlug = 'pages', content, settingsSlug = 'site-settings', homeSlug, changeFrequency = 'weekly' }) {
    const locales = config.locales.map((l)=>l.code);
    const defaultLocale = config.defaultLocale;
    // Resolve homeSlug and archive prefixes from System Pages (read once, in all
    // locales so archive prefixes are available per language).
    const settings = await payload.findGlobal({
        slug: settingsSlug,
-        depth: 1,
-        locale: 'all'
+        locale: 'all',
+        depth: 1
    });
    const resolvedHomeSlug = homeSlug ?? extractSlugInLocale(settings.homepage, defaultLocale) ?? 'home';
    // Which collections to walk: pages (no prefix) + each content collection with
@@ -105,32 +121,24 @@ import { buildHreflangAlternates } from './hreflang.js';
        // alternates without re-querying per locale.
        const result = await payload.find({
            collection: collection.slug,
+            locale: 'all',
            depth: 0,
            limit: 0,
-            locale: 'all',
            pagination: false
        });
        for (const raw of result.docs){
-            if (!isIndexable(raw)) {
-                continue;
-            }
+            if (!isIndexable(raw)) continue;
            // Emit the entry under the default locale's URL; alternates cover the rest.
            const entry = entryFor(raw, defaultLocale, config, baseUrl, resolvedHomeSlug, collection.prefixSlugs, changeFrequency);
-            if (entry) {
-                entries.push(entry);
-            }
+            if (entry) entries.push(entry);
        }
    }
    return entries;
 }
 /** Pulls a slug string from a populated relationship in a specific locale. */ function extractSlugInLocale(rel, locale) {
-    if (!rel || typeof rel !== 'object') {
-        return undefined;
-    }
+    if (!rel || typeof rel !== 'object') return undefined;
    const slug = rel.slug;
-    if (typeof slug === 'string') {
-        return slug;
-    }
+    if (typeof slug === 'string') return slug;
    if (slug && typeof slug === 'object') {
        const v = slug[locale];
        return typeof v === 'string' ? v : undefined;
@@ -138,19 +146,13 @@ import { buildHreflangAlternates } from './hreflang.js';
    return undefined;
 }
 /** Builds a locale→slug map from a populated archive relationship. */ function slugMapAllLocales(rel, locales) {
-    if (!rel || typeof rel !== 'object') {
-        return undefined;
-    }
+    if (!rel || typeof rel !== 'object') return undefined;
    const slug = rel.slug;
-    if (!slug || typeof slug !== 'object') {
-        return undefined;
-    }
+    if (!slug || typeof slug !== 'object') return undefined;
    const map = {};
    for (const locale of locales){
        const v = slug[locale];
-        if (typeof v === 'string') {
-            map[locale] = v;
-        }
+        if (typeof v === 'string') map[locale] = v;
    }
    return Object.keys(map).length ? map : undefined;
 }
@@ -0,0 +1,55 @@
+type SearchActionConfig = {
+    /**
+     * URL template for site search, with {search_term_string} placeholder.
+     * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if
+     * the site actually HAS a working search page — a SearchAction pointing at a
+     * non-existent search does more harm than good.
+     */
+    target: string;
+};
+type WebSiteJsonLdArgs = {
+    /** Site name (from panel — siteName). */
+    name: string;
+    /**
+     * Optional site search. Enables the "sitelinks searchbox" — a search field
+     * Google may show under the brand result. Only pass when a real search page
+     * exists. Omit entirely otherwise.
+     */
+    search?: SearchActionConfig;
+    /** Absolute site URL (https://…). */
+    url: string;
+};
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */
+export declare function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs): {
+    potentialAction?: {
+        '@type': string;
+        'query-input': string;
+        target: {
+            '@type': string;
+            urlTemplate: string;
+        };
+    } | undefined;
+    name: string;
+    '@context': string;
+    '@type': string;
+    url: string;
+};
+export {};
@@ -0,0 +1,38 @@
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */ export function buildWebSiteJsonLd({ name, search, url }) {
+    return {
+        name,
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        url,
+        ...search ? {
+            potentialAction: {
+                '@type': 'SearchAction',
+                'query-input': 'required name=search_term_string',
+                target: {
+                    '@type': 'EntryPoint',
+                    urlTemplate: search.target
+                }
+            }
+        } : {}
+    };
+}
+
+//# sourceMappingURL=buildWebSiteJsonLd.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/buildWebSiteJsonLd.ts"],"sourcesContent":["type SearchActionConfig = {\n  /**\n   * URL template for site search, with {search_term_string} placeholder.\n   * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if\n   * the site actually HAS a working search page — a SearchAction pointing at a\n   * non-existent search does more harm than good.\n   */\n  target: string\n}\n\ntype WebSiteJsonLdArgs = {\n  /** Site name (from panel — siteName). */\n  name: string\n  /**\n   * Optional site search. Enables the \"sitelinks searchbox\" — a search field\n   * Google may show under the brand result. Only pass when a real search page\n   * exists. Omit entirely otherwise.\n   */\n  search?: SearchActionConfig\n  /** Absolute site URL (https://…). */\n  url: string\n}\n\n/**\n * Builds WebSite JSON-LD (schema.org). Two jobs:\n *  - Declares the site + name (helps Google associate brand queries with the site).\n *  - Optionally declares a SearchAction, which is what can produce the \"sitelinks\n *    searchbox\" (a search field under the brand result in Google).\n *\n * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No\n * schema guarantees them; Google generates them algorithmically from site\n * structure, internal links, clear titles, and ranking. This schema is a SIGNAL\n * that improves the odds and can enable the searchbox — not a switch. Manage\n * expectations accordingly (see docs/seo.md).\n *\n * Emit once in the ROOT layout (site-wide), from panel data:\n *\n *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'\n *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })\n *   <script type=\"application/ld+json\"\n *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />\n */\nexport function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs) {\n  return {\n    name,\n    '@context': 'https://schema.org',\n    '@type': 'WebSite',\n    url,\n    ...(search\n      ? {\n          potentialAction: {\n            '@type': 'SearchAction',\n            'query-input': 'required name=search_term_string',\n            target: {\n              '@type': 'EntryPoint',\n              urlTemplate: search.target,\n            },\n          },\n        }\n      : {}),\n  }\n}\n"],"names":["buildWebSiteJsonLd","name","search","url","potentialAction","target","urlTemplate"],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASA,mBAAmB,EAAEC,IAAI,EAAEC,MAAM,EAAEC,GAAG,EAAqB;IACzE,OAAO;QACLF;QACA,YAAY;QACZ,SAAS;QACTE;QACA,GAAID,SACA;YACEE,iBAAiB;gBACf,SAAS;gBACT,eAAe;gBACfC,QAAQ;oBACN,SAAS;oBACTC,aAAaJ,OAAOG,MAAM;gBAC5B;YACF;QACF,IACA,CAAC,CAAC;IACR;AACF"}
@@ -90,6 +90,7 @@ import { slugsAcrossLocales } from './slugsAcrossLocales.js';
            ...base,
            imageUrl: resolveOgImage(doc),
            meta: doc.meta,
+            pageTitle: doc.title,
            prefix,
            query,
            slugs
@@ -1,8 +1,10 @@
 import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js';
 type BuildHreflangArgs = {
+    /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */
+    slugs: LocalizedSlugs;
+    config: I18nConfig;
    /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */
    baseUrl?: string;
-    config: I18nConfig;
    /** Home slug that collapses to the locale root. Defaults to 'home'. */
    homeSlug?: string;
    /**
@@ -11,8 +13,6 @@ type BuildHreflangArgs = {
     * are omitted — an entry with no archive in that language has no URL there.
     */
    prefix?: LocalizedSlugs;
-    /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */
-    slugs: LocalizedSlugs;
 };
 /**
 * Builds a map of locale → URL for hreflang alternate links, suitable for
@@ -30,5 +30,5 @@ type BuildHreflangArgs = {
 * })
 * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
 */
-export declare function buildHreflangAlternates({ baseUrl, config, homeSlug, prefix, slugs, }: BuildHreflangArgs): Record<string, string>;
+export declare function buildHreflangAlternates({ slugs, config, baseUrl, homeSlug, prefix, }: BuildHreflangArgs): Record<string, string>;
 export {};
@@ -14,21 +14,37 @@ import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js';
 *   baseUrl: 'https://example.com',
 * })
 * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
- */ export function buildHreflangAlternates({ baseUrl, config, homeSlug = 'home', prefix, slugs }) {
+ */ export function buildHreflangAlternates({ slugs, config, baseUrl, homeSlug = 'home', prefix }) {
    const origin = baseUrl?.replace(/\/$/, '') ?? '';
    const alternates = {};
+    // Single-locale sites have no language alternatives — hreflang describes
+    // relationships BETWEEN language versions, and there's only one. Emitting
+    // hreflang (or x-default) here would be wrong, so return empty: the page keeps
+    // its canonical, but no alternate-language links.
+    if (config.locales.length === 1) {
+        return alternates;
+    }
    for (const locale of getLocaleCodes(config)){
        const path = buildLocalizedPath({
+            slugs,
+            locale,
            config,
            homeSlug,
-            locale,
-            prefix,
-            slugs
+            prefix
        });
        if (path) {
            alternates[locale] = `${origin}${path}`;
        }
    }
+    // x-default: the version Google serves when the user's language/region doesn't
+    // match any hreflang — and, crucially here, the fallback when the root ('/')
+    // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it
+    // at the default locale (the primary market) so search shows that version by
+    // default instead of guessing. Only set when the default locale has a URL.
+    const defaultLocalePath = alternates[config.defaultLocale];
+    if (defaultLocalePath) {
+        alternates['x-default'] = defaultLocalePath;
+    }
    return alternates;
 }

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/hreflang.ts"],"sourcesContent":["import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'\n\nimport { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'\n\ntype BuildHreflangArgs = {\n  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */\n  baseUrl?: string\n  config: I18nConfig\n  /** Home slug that collapses to the locale root. Defaults to 'home'. */\n  homeSlug?: string\n  /**\n   * Localized segment the document lives under (an archive page's slugs),\n   * e.g. { pl: 'artykuly', en: 'articles' }. Locales missing from the prefix\n   * are omitted — an entry with no archive in that language has no URL there.\n   */\n  prefix?: LocalizedSlugs\n  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */\n  slugs: LocalizedSlugs\n}\n\n/**\n * Builds a map of locale → URL for hreflang alternate links, suitable for\n * Next.js Metadata `alternates.languages`.\n *\n * Bridges SEO and i18n: for each configured locale that the document has a\n * slug in, it produces the locale-aware path (via buildLocalizedPath),\n * optionally prefixed with an absolute origin.\n *\n * @example\n * buildHreflangAlternates({\n *   slugs: { pl: 'o-nas', en: 'about' },\n *   config,\n *   baseUrl: 'https://example.com',\n * })\n * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }\n */\nexport function buildHreflangAlternates({\n  baseUrl,\n  config,\n  homeSlug = 'home',\n  prefix,\n  slugs,\n}: BuildHreflangArgs): Record<string, string> {\n  const origin = baseUrl?.replace(/\\/$/, '') ?? ''\n  const alternates: Record<string, string> = {}\n\n  for (const locale of getLocaleCodes(config)) {\n    const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })\n    if (path) {\n      alternates[locale] = `${origin}${path}`\n    }\n  }\n\n  return alternates\n}\n"],"names":["buildLocalizedPath","getLocaleCodes","buildHreflangAlternates","baseUrl","config","homeSlug","prefix","slugs","origin","replace","alternates","locale","path"],"mappings":"AAEA,SAASA,kBAAkB,EAAEC,cAAc,QAAQ,mBAAkB;AAkBrE;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,wBAAwB,EACtCC,OAAO,EACPC,MAAM,EACNC,WAAW,MAAM,EACjBC,MAAM,EACNC,KAAK,EACa;IAClB,MAAMC,SAASL,SAASM,QAAQ,OAAO,OAAO;IAC9C,MAAMC,aAAqC,CAAC;IAE5C,KAAK,MAAMC,UAAUV,eAAeG,QAAS;QAC3C,MAAMQ,OAAOZ,mBAAmB;YAAEI;YAAQC;YAAUM;YAAQL;YAAQC;QAAM;QAC1E,IAAIK,MAAM;YACRF,UAAU,CAACC,OAAO,GAAG,GAAGH,SAASI,MAAM;QACzC;IACF;IAEA,OAAOF;AACT"}
+{"version":3,"sources":["../../../src/modules/seo/hreflang.ts"],"sourcesContent":["import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'\nimport { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'\n\ntype BuildHreflangArgs = {\n  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */\n  slugs: LocalizedSlugs\n  config: I18nConfig\n  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */\n  baseUrl?: string\n  /** Home slug that collapses to the locale root. Defaults to 'home'. */\n  homeSlug?: string\n  /**\n   * Localized segment the document lives under (an archive page's slugs),\n   * e.g. { pl: 'artykuly', en: 'articles' }. Locales missing from the prefix\n   * are omitted — an entry with no archive in that language has no URL there.\n   */\n  prefix?: LocalizedSlugs\n}\n\n/**\n * Builds a map of locale → URL for hreflang alternate links, suitable for\n * Next.js Metadata `alternates.languages`.\n *\n * Bridges SEO and i18n: for each configured locale that the document has a\n * slug in, it produces the locale-aware path (via buildLocalizedPath),\n * optionally prefixed with an absolute origin.\n *\n * @example\n * buildHreflangAlternates({\n *   slugs: { pl: 'o-nas', en: 'about' },\n *   config,\n *   baseUrl: 'https://example.com',\n * })\n * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }\n */\nexport function buildHreflangAlternates({\n  slugs,\n  config,\n  baseUrl,\n  homeSlug = 'home',\n  prefix,\n}: BuildHreflangArgs): Record<string, string> {\n  const origin = baseUrl?.replace(/\\/$/, '') ?? ''\n  const alternates: Record<string, string> = {}\n\n  // Single-locale sites have no language alternatives — hreflang describes\n  // relationships BETWEEN language versions, and there's only one. Emitting\n  // hreflang (or x-default) here would be wrong, so return empty: the page keeps\n  // its canonical, but no alternate-language links.\n  if (config.locales.length === 1) {\n    return alternates\n  }\n\n  for (const locale of getLocaleCodes(config)) {\n    const path = buildLocalizedPath({ slugs, locale, config, homeSlug, prefix })\n    if (path) {\n      alternates[locale] = `${origin}${path}`\n    }\n  }\n\n  // x-default: the version Google serves when the user's language/region doesn't\n  // match any hreflang — and, crucially here, the fallback when the root ('/')\n  // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it\n  // at the default locale (the primary market) so search shows that version by\n  // default instead of guessing. Only set when the default locale has a URL.\n  const defaultLocalePath = alternates[config.defaultLocale]\n  if (defaultLocalePath) {\n    alternates['x-default'] = defaultLocalePath\n  }\n\n  return alternates\n}\n"],"names":["buildLocalizedPath","getLocaleCodes","buildHreflangAlternates","slugs","config","baseUrl","homeSlug","prefix","origin","replace","alternates","locales","length","locale","path","defaultLocalePath","defaultLocale"],"mappings":"AACA,SAASA,kBAAkB,EAAEC,cAAc,QAAQ,mBAAkB;AAkBrE;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,wBAAwB,EACtCC,KAAK,EACLC,MAAM,EACNC,OAAO,EACPC,WAAW,MAAM,EACjBC,MAAM,EACY;IAClB,MAAMC,SAASH,SAASI,QAAQ,OAAO,OAAO;IAC9C,MAAMC,aAAqC,CAAC;IAE5C,yEAAyE;IACzE,0EAA0E;IAC1E,+EAA+E;IAC/E,kDAAkD;IAClD,IAAIN,OAAOO,OAAO,CAACC,MAAM,KAAK,GAAG;QAC/B,OAAOF;IACT;IAEA,KAAK,MAAMG,UAAUZ,eAAeG,QAAS;QAC3C,MAAMU,OAAOd,mBAAmB;YAAEG;YAAOU;YAAQT;YAAQE;YAAUC;QAAO;QAC1E,IAAIO,MAAM;YACRJ,UAAU,CAACG,OAAO,GAAG,GAAGL,SAASM,MAAM;QACzC;IACF;IAEA,+EAA+E;IAC/E,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAMC,oBAAoBL,UAAU,CAACN,OAAOY,aAAa,CAAC;IAC1D,IAAID,mBAAmB;QACrBL,UAAU,CAAC,YAAY,GAAGK;IAC5B;IAEA,OAAOL;AACT"}
@@ -1,11 +1,19 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js';
 export type { AutoFillMapping } from './autoFillMeta.js';
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js';
+export { buildFaqJsonLd } from './buildFaqJsonLd.js';
+export { buildIconsMetadata } from './buildIconsMetadata.js';
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js';
 export { buildMetadata } from './buildMetadata.js';
 export type { PageMetadata } from './buildMetadata.js';
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js';
 export { buildRobots } from './buildRobots.js';
 export type { RobotsRules } from './buildRobots.js';
+export { buildServiceJsonLd } from './buildServiceJsonLd.js';
 export { buildSitemapEntries } from './buildSitemapEntries.js';
 export type { SitemapEntry } from './buildSitemapEntries.js';
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js';
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js';
 export { composeTitle } from './composeTitle.js';
 export type { TitleOrder } from './composeTitle.js';
 export { createMetadataGenerator } from './createMetadataGenerator.js';
@@ -18,3 +26,4 @@ export type { SiteMetaConfig } from './readSiteMetaConfig.js';
 export { buildSeoPlugin } from './seoPluginConfig.js';
 export { slugsAcrossLocales } from './slugsAcrossLocales.js';
 export type { SeoMeta, SeoOption } from './types.js';
+export { validateFaviconField } from './validateFavicon.js';
@@ -1,7 +1,15 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js';
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js';
+export { buildFaqJsonLd } from './buildFaqJsonLd.js';
+export { buildIconsMetadata } from './buildIconsMetadata.js';
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js';
 export { buildMetadata } from './buildMetadata.js';
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js';
 export { buildRobots } from './buildRobots.js';
+export { buildServiceJsonLd } from './buildServiceJsonLd.js';
 export { buildSitemapEntries } from './buildSitemapEntries.js';
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js';
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js';
 export { composeTitle } from './composeTitle.js';
 export { createMetadataGenerator } from './createMetadataGenerator.js';
 export { createPageMetadata } from './createPageMetadata.js';
@@ -11,5 +19,6 @@ export { injectSeoTabs } from './injectSeoTabs.js';
 export { readSiteMetaConfig } from './readSiteMetaConfig.js';
 export { buildSeoPlugin } from './seoPluginConfig.js';
 export { slugsAcrossLocales } from './slugsAcrossLocales.js';
+export { validateFaviconField } from './validateFavicon.js';

 //# sourceMappingURL=index.js.map
@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/index.ts"],"sourcesContent":["export { buildAutoFillMetaHook } from './autoFillMeta.js'\nexport type { AutoFillMapping } from './autoFillMeta.js'\nexport { buildMetadata } from './buildMetadata.js'\nexport type { PageMetadata } from './buildMetadata.js'\nexport { buildRobots } from './buildRobots.js'\nexport type { RobotsRules } from './buildRobots.js'\nexport { buildSitemapEntries } from './buildSitemapEntries.js'\nexport type { SitemapEntry } from './buildSitemapEntries.js'\nexport { composeTitle } from './composeTitle.js'\nexport type { TitleOrder } from './composeTitle.js'\nexport { createMetadataGenerator } from './createMetadataGenerator.js'\nexport { createPageMetadata } from './createPageMetadata.js'\nexport { buildHreflangAlternates } from './hreflang.js'\nexport { injectAutoFillMeta } from './injectAutoFillMeta.js'\nexport { injectSeoTabs } from './injectSeoTabs.js'\nexport { readSiteMetaConfig } from './readSiteMetaConfig.js'\nexport type { SiteMetaConfig } from './readSiteMetaConfig.js'\nexport { buildSeoPlugin } from './seoPluginConfig.js'\nexport { slugsAcrossLocales } from './slugsAcrossLocales.js'\nexport type { SeoMeta, SeoOption } from './types.js'\n"],"names":["buildAutoFillMetaHook","buildMetadata","buildRobots","buildSitemapEntries","composeTitle","createMetadataGenerator","createPageMetadata","buildHreflangAlternates","injectAutoFillMeta","injectSeoTabs","readSiteMetaConfig","buildSeoPlugin","slugsAcrossLocales"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAmB;AAEzD,SAASC,aAAa,QAAQ,qBAAoB;AAElD,SAASC,WAAW,QAAQ,mBAAkB;AAE9C,SAASC,mBAAmB,QAAQ,2BAA0B;AAE9D,SAASC,YAAY,QAAQ,oBAAmB;AAEhD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,uBAAuB,QAAQ,gBAAe;AACvD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,aAAa,QAAQ,qBAAoB;AAClD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,cAAc,QAAQ,uBAAsB;AACrD,SAASC,kBAAkB,QAAQ,0BAAyB"}
+{"version":3,"sources":["../../../src/modules/seo/index.ts"],"sourcesContent":["export { buildAutoFillMetaHook } from './autoFillMeta.js'\nexport type { AutoFillMapping } from './autoFillMeta.js'\nexport { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js'\nexport { buildFaqJsonLd } from './buildFaqJsonLd.js'\nexport { buildIconsMetadata } from './buildIconsMetadata.js'\nexport { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js'\nexport { buildMetadata } from './buildMetadata.js'\nexport type { PageMetadata } from './buildMetadata.js'\nexport { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js'\nexport { buildRobots } from './buildRobots.js'\nexport type { RobotsRules } from './buildRobots.js'\nexport { buildServiceJsonLd } from './buildServiceJsonLd.js'\nexport { buildSitemapEntries } from './buildSitemapEntries.js'\nexport type { SitemapEntry } from './buildSitemapEntries.js'\nexport { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js'\nexport { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js'\nexport { composeTitle } from './composeTitle.js'\nexport type { TitleOrder } from './composeTitle.js'\nexport { createMetadataGenerator } from './createMetadataGenerator.js'\nexport { createPageMetadata } from './createPageMetadata.js'\nexport { buildHreflangAlternates } from './hreflang.js'\nexport { injectAutoFillMeta } from './injectAutoFillMeta.js'\nexport { injectSeoTabs } from './injectSeoTabs.js'\nexport { readSiteMetaConfig } from './readSiteMetaConfig.js'\nexport type { SiteMetaConfig } from './readSiteMetaConfig.js'\nexport { buildSeoPlugin } from './seoPluginConfig.js'\nexport { slugsAcrossLocales } from './slugsAcrossLocales.js'\nexport type { SeoMeta, SeoOption } from './types.js'\nexport { validateFaviconField } from './validateFavicon.js'\n"],"names":["buildAutoFillMetaHook","buildBreadcrumbJsonLd","buildFaqJsonLd","buildIconsMetadata","buildLocalBusinessJsonLd","buildMetadata","buildOrganizationJsonLd","buildRobots","buildServiceJsonLd","buildSitemapEntries","buildSiteNavigationJsonLd","buildWebSiteJsonLd","composeTitle","createMetadataGenerator","createPageMetadata","buildHreflangAlternates","injectAutoFillMeta","injectSeoTabs","readSiteMetaConfig","buildSeoPlugin","slugsAcrossLocales","validateFaviconField"],"mappings":"AAAA,SAASA,qBAAqB,QAAQ,oBAAmB;AAEzD,SAASC,qBAAqB,QAAQ,6BAA4B;AAClE,SAASC,cAAc,QAAQ,sBAAqB;AACpD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,wBAAwB,QAAQ,gCAA+B;AACxE,SAASC,aAAa,QAAQ,qBAAoB;AAElD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,WAAW,QAAQ,mBAAkB;AAE9C,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,mBAAmB,QAAQ,2BAA0B;AAE9D,SAASC,yBAAyB,QAAQ,iCAAgC;AAC1E,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,YAAY,QAAQ,oBAAmB;AAEhD,SAASC,uBAAuB,QAAQ,+BAA8B;AACtE,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,uBAAuB,QAAQ,gBAAe;AACvD,SAASC,kBAAkB,QAAQ,0BAAyB;AAC5D,SAASC,aAAa,QAAQ,qBAAoB;AAClD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,cAAc,QAAQ,uBAAsB;AACrD,SAASC,kBAAkB,QAAQ,0BAAyB;AAE5D,SAASC,oBAAoB,QAAQ,uBAAsB"}
@@ -34,6 +34,7 @@ export type SeoOption = {
 export type SeoMeta = {
    description?: null | string;
    image?: unknown;
+    noindex?: boolean | null;
    title?: null | string;
    /** When set, used as the whole title — no site name, no separator. */
    titleOverride?: null | string;
@@ -1 +1 @@
-{"version":3,"sources":["../../../src/modules/seo/types.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport type { AutoFillMapping } from './autoFillMeta.js'\n\n/**\n * SEO configuration.\n *\n * The plugin wires @payloadcms/plugin-seo into the client's config and adds\n * locale-aware metadata helpers on top. Collections come from options because\n * the plugin doesn't own the client's content collections (e.g. Pages).\n */\nexport type SeoOption = {\n  /**\n   * Auto-fill empty meta from document fields on save. Defaults to the website\n   * template mapping (title → meta.title). Set to false to disable.\n   */\n  autoFill?: AutoFillMapping | false\n  /** Collection slugs that receive SEO meta fields, e.g. ['pages', 'posts']. */\n  collections: string[]\n  /** Extra fields appended to the SEO group in the admin. */\n  fields?: Field[]\n  /** Optional: customize how meta descriptions are generated. */\n  generateDescription?: (args: { doc: Record<string, unknown> }) => string\n  /** Optional: customize how meta titles are generated in the admin preview. */\n  generateTitle?: (args: { doc: Record<string, unknown> }) => string\n}\n\n/**\n * Minimal shape of the SEO meta group as stored on a document by\n * @payloadcms/plugin-seo. The client's generated types are richer; helpers\n * depend only on this.\n */\nexport type SeoMeta = {\n  description?: null | string\n  image?: unknown\n  title?: null | string\n  /** When set, used as the whole title — no site name, no separator. */\n  titleOverride?: null | string\n}\n"],"names":[],"mappings":"AA2BA;;;;CAIC,GACD,WAMC"}
+{"version":3,"sources":["../../../src/modules/seo/types.ts"],"sourcesContent":["import type { Field } from 'payload'\n\nimport type { AutoFillMapping } from './autoFillMeta.js'\n\n/**\n * SEO configuration.\n *\n * The plugin wires @payloadcms/plugin-seo into the client's config and adds\n * locale-aware metadata helpers on top. Collections come from options because\n * the plugin doesn't own the client's content collections (e.g. Pages).\n */\nexport type SeoOption = {\n  /**\n   * Auto-fill empty meta from document fields on save. Defaults to the website\n   * template mapping (title → meta.title). Set to false to disable.\n   */\n  autoFill?: AutoFillMapping | false\n  /** Collection slugs that receive SEO meta fields, e.g. ['pages', 'posts']. */\n  collections: string[]\n  /** Extra fields appended to the SEO group in the admin. */\n  fields?: Field[]\n  /** Optional: customize how meta descriptions are generated. */\n  generateDescription?: (args: { doc: Record<string, unknown> }) => string\n  /** Optional: customize how meta titles are generated in the admin preview. */\n  generateTitle?: (args: { doc: Record<string, unknown> }) => string\n}\n\n/**\n * Minimal shape of the SEO meta group as stored on a document by\n * @payloadcms/plugin-seo. The client's generated types are richer; helpers\n * depend only on this.\n */\nexport type SeoMeta = {\n  description?: null | string\n  image?: unknown\n  noindex?: boolean | null\n  title?: null | string\n  /** When set, used as the whole title — no site name, no separator. */\n  titleOverride?: null | string\n}\n"],"names":[],"mappings":"AA2BA;;;;CAIC,GACD,WAOC"}
@@ -0,0 +1,15 @@
+import type { FieldHook } from 'payload';
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */
+export declare const validateFaviconField: FieldHook;
@@ -0,0 +1,44 @@
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */ export const validateFaviconField = async ({ req, value })=>{
+    if (!value) {
+        return value;
+    } // no favicon set → nothing to validate (optional field)
+    try {
+        const media = await req.payload.findByID({
+            id: typeof value === 'object' ? value.id : value,
+            collection: 'media',
+            depth: 0
+        });
+        const width = media.width;
+        const height = media.height;
+        const mimeType = media.mimeType;
+        // SVG scales infinitely — skip size checks.
+        if (mimeType === 'image/svg+xml') {
+            return value;
+        }
+        if (typeof width === 'number' && typeof height === 'number') {
+            if (width < 48 || height < 48) {
+                req.payload.logger.warn(`[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` + `display it in search results. Upload a larger square icon (96 or 192px).`);
+            }
+            if (width !== height) {
+                req.payload.logger.warn(`[ipal] Favicon is not square (${width}×${height}). Use a square icon ` + `so it isn't cropped in the browser tab or search results.`);
+            }
+        }
+    } catch  {
+    // Media lookup failed — don't block the save over a validation warning.
+    }
+    return value;
+};
+
+//# sourceMappingURL=validateFavicon.js.map
@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/modules/seo/validateFavicon.ts"],"sourcesContent":["import type { FieldHook } from 'payload'\n\n/**\n * Field validation for the favicon upload: Google rejects favicons under 48×48,\n * so warn the editor at save time if the uploaded icon is too small or not\n * square. This ENFORCES the requirement instead of silently shipping a favicon\n * Google won't display.\n *\n * Attach to the favicon field's validate (or as a beforeValidate hook on the\n * Media relationship). Non-blocking by default — returns a warning string that\n * Payload surfaces; make it throw if you want a hard block.\n *\n * Note: dimensions come from the related Media doc (Payload stores width/height\n * for image uploads), so this checks the resolved upload, not the raw file.\n */\nexport const validateFaviconField: FieldHook = async ({ req, value }) => {\n  if (!value) {return value} // no favicon set → nothing to validate (optional field)\n\n  try {\n    const media = await req.payload.findByID({\n      id: typeof value === 'object' ? (value as { id: string }).id : value,\n      collection: 'media',\n      depth: 0,\n    })\n\n    const width = (media as { width?: number }).width\n    const height = (media as { height?: number }).height\n    const mimeType = (media as { mimeType?: string }).mimeType\n\n    // SVG scales infinitely — skip size checks.\n    if (mimeType === 'image/svg+xml') {return value}\n\n    if (typeof width === 'number' && typeof height === 'number') {\n      if (width < 48 || height < 48) {\n        req.payload.logger.warn(\n          `[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` +\n            `display it in search results. Upload a larger square icon (96 or 192px).`,\n        )\n      }\n      if (width !== height) {\n        req.payload.logger.warn(\n          `[ipal] Favicon is not square (${width}×${height}). Use a square icon ` +\n            `so it isn't cropped in the browser tab or search results.`,\n        )\n      }\n    }\n  } catch {\n    // Media lookup failed — don't block the save over a validation warning.\n  }\n\n  return value\n}\n"],"names":["validateFaviconField","req","value","media","payload","findByID","id","collection","depth","width","height","mimeType","logger","warn"],"mappings":"AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMA,uBAAkC,OAAO,EAAEC,GAAG,EAAEC,KAAK,EAAE;IAClE,IAAI,CAACA,OAAO;QAAC,OAAOA;IAAK,EAAE,wDAAwD;IAEnF,IAAI;QACF,MAAMC,QAAQ,MAAMF,IAAIG,OAAO,CAACC,QAAQ,CAAC;YACvCC,IAAI,OAAOJ,UAAU,WAAW,AAACA,MAAyBI,EAAE,GAAGJ;YAC/DK,YAAY;YACZC,OAAO;QACT;QAEA,MAAMC,QAAQ,AAACN,MAA6BM,KAAK;QACjD,MAAMC,SAAS,AAACP,MAA8BO,MAAM;QACpD,MAAMC,WAAW,AAACR,MAAgCQ,QAAQ;QAE1D,4CAA4C;QAC5C,IAAIA,aAAa,iBAAiB;YAAC,OAAOT;QAAK;QAE/C,IAAI,OAAOO,UAAU,YAAY,OAAOC,WAAW,UAAU;YAC3D,IAAID,QAAQ,MAAMC,SAAS,IAAI;gBAC7BT,IAAIG,OAAO,CAACQ,MAAM,CAACC,IAAI,CACrB,CAAC,kBAAkB,EAAEJ,MAAM,CAAC,EAAEC,OAAO,8BAA8B,CAAC,GAClE,CAAC,wEAAwE,CAAC;YAEhF;YACA,IAAID,UAAUC,QAAQ;gBACpBT,IAAIG,OAAO,CAACQ,MAAM,CAACC,IAAI,CACrB,CAAC,8BAA8B,EAAEJ,MAAM,CAAC,EAAEC,OAAO,qBAAqB,CAAC,GACrE,CAAC,yDAAyD,CAAC;YAEjE;QACF;IACF,EAAE,OAAM;IACN,wEAAwE;IAC1E;IAEA,OAAOR;AACT,EAAC"}
@@ -10,6 +10,30 @@ registry (prop), obsługuje zagnieżdżanie i rozszerzenia per-blok. Bloki
 Brak opcji w payload.config — bloki definiujesz w swoich kolekcjach
 (pole typu `blocks`). Plugin dostarcza tylko silnik renderujący.

+## ⚠️ NIE pisz własnego renderera bloków (switch)
+
+**Renderer bloków to `RenderBlocks` z pluginu — NIGDY własny `switch`/`if`.**
+Częsty błąd: projekt pisze własny `BlockRenderer` z `switch (block.blockType)`
+i 20 case'ami. To łamie A0 — plugin ma silnik, projekt dostarcza tylko MAPĘ
+komponentów.
+
+```tsx
+// ŹLE — własny switch w projekcie (gadatliwy, bez enhanceProps, rośnie liniowo)
+switch (block.blockType) {
+  case 'hero': return <Hero {...block} />
+  case 'faq': return <FAQ {...block} />
+  // ...20 case'ów
+}
+
+// DOBRZE — mapa + RenderBlocks (silnik z pluginu)
+const registry = { hero: Hero, faq: FAQ, /* ... */ }
+<RenderBlocks blocks={page.layout} components={registry} />
+```
+
+Dlaczego RenderBlocks, nie switch: enhanceProps (anchory nav, itp.), guardy,
+obsługa zagnieżdżeń, spójność między projektami. Switch tego nie ma i rośnie
+z każdym blokiem. Mapa jest płaska i deklaratywna.
+
 ## Front — RenderBlocks

 Import z `@intecion/ipal-kit/rsc` (to komponent serwerowy):
@@ -0,0 +1,222 @@
+# Deployment — zmienne środowiskowe i produkcja
+
+Jedno źródło prawdy o zmiennych środowiskowych (wszystkie, co znaczą, wymagane
+czy nie) oraz jak wdrożyć projekt na produkcję spójnie. Env jest częścią
+deploymentu — te same zmienne w dev (.env) i na produkcji (runtime hostingu).
+
+Powiązane: [getting-started.md](./getting-started.md), [storage.md](./storage.md)
+(R2), [email.md](./email.md) (Graph), [security.md](./security.md).
+
+---
+
+## 1. ZMIENNE ŚRODOWISKOWE — pełna lista
+
+### Rdzeń (WYMAGANE — projekt bez nich nie wstanie)
+
+```bash
+# Baza danych (Mongo albo Postgres — zależnie od projektu)
+DATABASE_URI=mongodb://...          # albo postgres://... / file:./dev.db (dev)
+
+# Sekret Payload (podpisywanie sesji/tokenów) — losowy, długi
+PAYLOAD_SECRET=<losowy-ciąg-min-32-znaki>
+
+# Publiczny URL serwisu (canonical, hreflang, OG, manifest)
+NEXT_PUBLIC_SERVER_URL=https://klient.pl    # dev: http://localhost:3000
+```
+
+### Email — Graph (OPCJONALNE, agencyjne, gdy transport = Graph)
+
+```bash
+GRAPH_TENANT_ID=<azure-tenant-id>
+GRAPH_CLIENT_ID=<azure-app-client-id>
+GRAPH_CLIENT_SECRET=<azure-app-secret>
+GRAPH_SENDER=[email protected]   # wspólna skrzynka
+```
+Bez nich transport Graph nie zadziała (fallback SMTP). Patrz email.md.
+
+### Storage — R2 (OPCJONALNE, gdy media w R2)
+
+```bash
+R2_BUCKET=<nazwa-bucketa>
+R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
+R2_ACCESS_KEY_ID=<access-key>
+R2_SECRET_ACCESS_KEY=<secret-key>
+R2_PUBLIC_URL=https://media.klient.pl    # custom domena (obrazy publiczne)
+```
+Brak → fallback na lokalny dysk. Patrz storage.md.
+
+### Tabela — wszystkie zmienne
+
+| Zmienna | Wymagana | Warstwa | Opis |
+|---|---|---|---|
+| `DATABASE_URI` | ✅ | infra | połączenie z bazą |
+| `PAYLOAD_SECRET` | ✅ | infra | sekret Payload |
+| `NEXT_PUBLIC_SERVER_URL` | ✅ | infra | publiczny URL (canonical, OG) |
+| `GRAPH_TENANT_ID` | ⬜ | email | Azure tenant (Graph) |
+| `GRAPH_CLIENT_ID` | ⬜ | email | Azure app id |
+| `GRAPH_CLIENT_SECRET` | ⬜ | email | Azure secret |
+| `GRAPH_SENDER` | ⬜ | email | skrzynka nadawcza |
+| `R2_BUCKET` | ⬜ | storage | bucket R2 |
+| `R2_ENDPOINT` | ⬜ | storage | endpoint S3 R2 |
+| `R2_ACCESS_KEY_ID` | ⬜ | storage | klucz R2 |
+| `R2_SECRET_ACCESS_KEY` | ⬜ | storage | sekret R2 |
+| `R2_PUBLIC_URL` | ⬜ | storage | custom domena mediów |
+
+**Zasada:** wszystkie sekrety to zmienne agencyjne/infrastrukturalne — w `.env`
+(dev) i runtime hostingu (prod), NIGDY w repo. Dane per-projekt edytowalne przez
+redaktora idą do PANELU, nie do env (patrz architektura-tresci.md).
+
+### .env.example — zawsze w repo
+
+Każdy projekt ma `.env.example` z listą zmiennych (bez wartości/sekretów) —
+szablon dla następnej osoby. Commituj go; `.env` (z wartościami) NIGDY.
+
+---
+
+## 2. PRZED DEPLOYEM — checklist
+
+- [ ] `pnpm build --webpack` przechodzi LOKALNIE (nie tylko dev)
+- [ ] Wszystkie wymagane env ustawione na hostingu (runtime)
+- [ ] `NEXT_PUBLIC_SERVER_URL` = produkcyjny URL (nie localhost)
+- [ ] `PAYLOAD_SECRET` inny niż w dev (produkcyjny sekret)
+- [ ] Baza produkcyjna (nie dev/SQLite)
+- [ ] HSTS włączony (buildSecurityHeaders hsts: production)
+- [ ] Media: R2 z custom domeną (jeśli używane) — obrazy publiczne
+- [ ] Migracja mediów lokalne→R2 (jeśli przełączasz)
+- [ ] Strony polityk + baner cookies (patrz wymagania-prawne.md)
+
+---
+
+## 3. BUDOWANIE NA PRODUKCJĘ
+
+### Build script (Next 16 + Payload)
+
+```json
+// package.json — --webpack KONIECZNE (Turbopack konfliktuje z withPayload)
+"build": "cross-env NODE_OPTIONS=\"--max-old-space-size=3072\" next build --webpack"
+```
+
+`--max-old-space-size` — Payload + Next bywają pamięciożerne przy buildzie;
+3072 MB zapobiega OOM na mniejszych maszynach.
+
+### Kolejność build → migracje → start
+
+```bash
+pnpm install --frozen-lockfile   # dokładnie z lockfile (powtarzalny build)
+pnpm generate:types              # typy z kolekcji
+pnpm build                       # --webpack
+# migracje bazy (jeśli Postgres z migracjami):
+pnpm payload migrate
+pnpm start                       # produkcyjny serwer
+```
+
+---
+
+## 3a. Pułapka: metadata w <body> zamiast <head> (htmlLimitedBots)
+
+Next 16 streamuje metadata dynamicznych stron do `<body>` (przenosi do head
+skryptem JS). Crawlery bez JS widzą canonical/hreflang/title/favicon poza head →
+utrata SEO. **Każdy projekt** tego potrzebuje w next.config:
+
+```ts
+const nextConfig: NextConfig = {
+  htmlLimitedBots:
+    /Googlebot|Google-InspectionTool|Bingbot|Yandex|DuckDuckBot|Screaming Frog|AhrefsBot|SemrushBot/i,
+  // ...
+}
+```
+
+Weryfikacja: `curl -A "Googlebot" URL | grep canonical` — musi być w `<head>`.
+Szczegóły i objawy: seo.md (sekcja htmlLimitedBots).
+
+## 3a2. ISR — cache stron (metadata w head + szybkość)
+
+Dla stron contentowych (page.tsx) użyj ISR: `export const revalidate = 3600`.
+Cache'uje całą stronę z gotowym `<head>` → metadata zawsze w head (nie body,
+brak race condition streamingu), TTFB ~20ms, brak 503 (cold start).
+
+```ts
+// app/(frontend)/[locale]/[[...slug]]/page.tsx
+export const revalidate = 3600   // 1h; albo krócej, albo on-demand
+```
+
+UWAGA: ISR i `force-dynamic` się WYKLUCZAJĄ. Strony → ISR (revalidate).
+sitemap/robots → force-dynamic (bo generują przy żądaniu). Nie mieszaj na jednej
+trasie. Treść z panelu: ISR = redaktor czeka do rewalidacji; rozważ on-demand
+revalidation (hook afterChange → revalidatePath). Patrz seo.md, HOOKS.md.
+
+## 3b. Pułapka: prerender tras zależnych od bazy (KONIECZNE)
+
+Next domyślnie **prerenderuje** trasy typu `sitemap.ts` w czasie `next build` —
+traktuje je jako statyczne. Jeśli taka trasa czyta bazę (sitemap → Payload →
+Mongo/Postgres), build **próbuje połączyć się z bazą**. A kontener budujący
+(Coolify/Docker/Railway/CI) zwykle NIE ma dostępu do sieci bazy → połączenie
+pada (`ENOTFOUND`, `MongooseServerSelectionError`) → **build się wywala**.
+
+**Rozwiązanie — `force-dynamic` na trasach zależnych od bazy:**
+```ts
+// app/sitemap.ts
+export { sitemap as default } from '@/lib/content'
+export const dynamic = 'force-dynamic'   // generuj w runtime, nie w buildzie
+```
+
+To mówi Next: nie prerenderuj w buildzie, generuj w runtime (gdy baza jest
+dostępna). Dotyczy KAŻDEJ trasy czytającej bazę podczas renderowania:
+- `app/sitemap.ts` → `force-dynamic`
+- inne trasy/strony czytające bazę w prerenderze → rozważ `force-dynamic` albo
+  obsłuż błąd bazy (try/catch z fallbackiem)
+
+Plugin dodatkowo zabezpiecza handler sitemap (łapie błąd bazy, zwraca pustą
+mapę), więc build nie padnie nawet bez `force-dynamic` — ale to siatka
+bezpieczeństwa, nie właściwe rozwiązanie. Zawsze dodawaj `force-dynamic`.
+
+**Strona 404** (`not-found.tsx`) czytająca ustawienia z bazy — ten sam problem.
+Opakuj `getCachedPayload()` w try/catch, żeby brak bazy w buildzie nie wywalił
+prerenderu 404 (fallback na statyczne teksty).
+
+**Weryfikacja lokalna** (symuluj brak bazy):
+```bash
+DATABASE_URI=mongodb://invalid-host:27017/test pnpm build
+# build musi przejść (kod 0), mimo niedostępnej bazy
+```
+
+## 4. HOSTING (Coolify / Docker)
+
+### Zmienne runtime, nie build
+
+Zmienne środowiskowe ustaw w **runtime** hostingu (Coolify → Environment
+Variables), nie zapiekaj w build. `NEXT_PUBLIC_*` są wyjątkiem — wchodzą w build
+(bo publiczne, w bundlu klienta), więc muszą być dostępne PODCZAS buildu.
+
+### Persystencja mediów
+
+Jeśli media lokalne (nie R2) — potrzebują **wolumenu** (inaczej znikną przy
+redeployu). Dlatego R2 jest zalecane na produkcji: media poza kontenerem,
+przetrwają redeploy. Patrz storage.md.
+
+### Health check
+
+Payload wystawia panel pod `/admin` — health check może pingować stronę główną
+albo `/admin`. Nie ustawiaj health check na endpoint wymagający bazy, jeśli
+baza wstaje wolniej niż app.
+
+---
+
+## 5. PO DEPLOYU — weryfikacja
+
+- [ ] Strona główna `/` przekierowuje na locale (`/pl`)
+- [ ] Panel `/admin` działa, logowanie OK
+- [ ] Formularz wysyła (test przez panel: Send test)
+- [ ] Media się wyświetlają (jeśli R2 — custom domena działa, nie 403)
+- [ ] Favicon w `<head>` (patrz seo.md — Google cache'uje wolno)
+- [ ] HTTPS + nagłówki bezpieczeństwa (sprawdź np. securityheaders.com)
+- [ ] Sitemap `/sitemap.xml` i `/robots.txt` odpowiadają
+
+---
+
+## DLACZEGO TO WAŻNE
+
+- **Jedna lista env** — nikt nie zgaduje, czego brakuje
+- **Powtarzalny deploy** — frozen-lockfile, ta sama kolejność, każdy projekt tak samo
+- **Sekrety bezpieczne** — env/runtime, nigdy repo
+- **Media przetrwają** — R2 albo wolumen, nie znikają przy redeployu
@@ -359,7 +359,11 @@ export default async function LocaleLayout({ children, params }) {

  return (
    <html lang={locale}>
+      {/* BEZ jawnego <head>! Sztywny <head> wypycha metadata do <body>
+          (canonical/title poza head → crawlery ich nie widzą). Next zarządza
+          <head> sam; MediaPreconnect w body, React 19 hoistuje link do head. */}
      <body>
+        <MediaPreconnect />                 {/* preconnect CDN, jeśli R2 */}
        <ConsentProvider texts={texts}>
          <main>{children}</main>
          <CookieBanner />
@@ -392,6 +396,11 @@ const pageMetadata = createPageMetadata({
  baseUrl: process.env.NEXT_PUBLIC_SERVER_URL,
 })

+// ISR — cache strony z gotowym <head>. Eliminuje race condition streamingu
+// metadata (canonical/title zawsze w head, nie w body). TTFB ~20ms, brak 503.
+// Redaktor widzi zmiany po rewalidacji — patrz seo.md (ISR a treść z panelu).
+export const revalidate = 3600
+
 export async function generateMetadata({ params }): Promise<Metadata> {
  const { locale, slug } = await params
  return pageMetadata({ payload: await getCachedPayload(), locale, slug })
@@ -408,6 +417,8 @@ export default async function Page({ params, searchParams }) {

 - brak slug (`/pl`) → home przez System Pages (nie hardkod slug)
 - slug (`/pl/o-nas`) → resolveRoute po slug w danym locale
+- **ISR (`revalidate`)** → metadata zawsze w `<head>` (nie body), szybki TTFB.
+  KRYTYCZNE dla SEO — patrz seo.md (metadata w head).
 - `depth: 2` → relacje w blokach (form) się populują

 ## 11. Metadata / SEO (szczegóły)
@@ -486,10 +497,15 @@ przypisanie strony-archiwum w System Pages.
 ```ts
 // app/sitemap.ts
 export { sitemap as default } from '@/lib/content'
+export const dynamic = 'force-dynamic' // KONIECZNE dla deployu kontenerowego
 // app/robots.ts
 export { robots as default } from '@/lib/content'
 ```

+`force-dynamic` w sitemap.ts jest wymagane przy deployu w kontenerze (Coolify/
+Docker) — bez niego build próbuje prerenderować sitemap i łączy się z bazą,
+której kontener budujący nie widzi → build pada. Szczegóły: [deployment.md](./deployment.md).
+
 ---

 ## Kiedy coś nie działa
@@ -55,6 +55,21 @@ buildLocalizedPath({ slugs, locale: 'en', config })   // '/en/about'
 buildLocalizedPath({ slugs: { en: 'home' }, locale: 'en', config })  // '/en'
 ```

+> **Pułapka typu (TypeScript):** przy `locale: 'all'` Payload w RUNTIME zwraca
+> zlokalizowane pole jako obiekt `{ pl, en }`, ale wygenerowane typy Payloada
+> deklarują `doc.slug` jako `string` (typ nie odróżnia trybu `all`). `tsc`
+> zgłosi więc niezgodność. Rozwiązanie — czyste rzutowanie na oczekiwany przez
+> helper typ:
+> ```ts
+> const slugs = getLocalizedSlugs({
+>   slugField: doc.slug as unknown as Record<string, unknown>,
+>   config,
+> })
+> ```
+> To nie hack — to pomost między statycznym typem (string) a rzeczywistym
+> kształtem runtime (obiekt), którego generator typów Payloada nie modeluje.
+> `as unknown as` jest tu poprawne, bo TS nie zna trybu `all`.
+
 ### Przełącznik języka (bez 404)

 ```ts
@@ -139,4 +154,98 @@ Zmiana języka (URL `/en` różny od cookie) → zapis nowego wyboru (za zgodą)

 > **Migracja ze starej nazwy:** wcześniej cookie nazywało się `ipal-locale`.
 > Po zmianie na `NEXT_LOCALE` użytkownicy ze starą cookie przejdą raz ponowną
-> negocjację (stara cookie ignorowana). Jednorazowe, bez wpływu na nowe projekty.
+> negocjację (stara cookie ignorowana). Jednorazowe, bez wpływu na nowe projekty.
+
+## Strona jednojęzyczna (bez prefiksu /pl)
+
+Gdy projekt ma JEDEN język, adresy nie mają prefiksu locale: `/o-nas`, nie
+`/pl/o-nas`. Plugin wykrywa to automatycznie — **jeden locale w config = tryb
+jednojęzyczny**. Helpery (buildLocalizedPath, hreflang, middleware) dostosowują
+się same:
+
+- **buildLocalizedPath** → `/o-nas` (bez `/pl`), home → `/`
+- **buildHreflangAlternates** → pusto (jeden język = brak alternatyw językowych)
+- **localeMiddleware** → pass-through (brak przekierowania `/` → `/pl`, brak negocjacji)
+- **canonical** → `https://klient.pl/o-nas` (bez prefiksu)
+
+### Config — jeden locale
+
+```ts
+// i18n.config.ts
+export const i18nConfig = {
+  locales: [{ code: 'pl', label: 'Polski' }],   // JEDEN locale
+  defaultLocale: 'pl',
+}
+```
+
+### Struktura katalogów — BEZ [locale]
+
+To kluczowa różnica. Projekt jednojęzyczny NIE ma folderu `[locale]`:
+
+```
+# JEDNOJĘZYCZNY (bez [locale])
+app/(frontend)/
+  layout.tsx                    # locale stałe z config, nie z params
+  not-found.tsx
+  [[...slug]]/page.tsx          # /o-nas, /kontakt
+
+# WIELOJĘZYCZNY (z [locale]) — dla porównania
+app/(frontend)/[locale]/
+  layout.tsx                    # locale z params
+  [[...slug]]/page.tsx          # /pl/o-nas, /en/about
+```
+
+### Layout jednojęzyczny — locale z config
+
+```tsx
+// app/(frontend)/layout.tsx (bez [locale])
+import { i18nConfig } from '@/i18n.config'
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const locale = i18nConfig.defaultLocale   // stałe, nie z params
+  const settings = await getSettings(locale)
+  // ...reszta jak zwykle, ale locale jest stałe
+  return <html lang={locale}>...</html>
+}
+```
+
+### Strony jednojęzyczne — locale z config
+
+```tsx
+// app/(frontend)/[[...slug]]/page.tsx (bez [locale])
+import { i18nConfig } from '@/i18n.config'
+
+export async function generateMetadata({ params }) {
+  const { slug } = await params            // TYLKO slug, nie locale
+  const locale = i18nConfig.defaultLocale  // stałe
+  return pageMetadata({ payload: await getCachedPayload(), locale, slug })
+}
+
+export default async function Page({ params }) {
+  const { slug } = await params
+  const locale = i18nConfig.defaultLocale  // stałe
+  const route = await resolveRoute(locale, slug ?? [], pageNum)
+  // ...
+}
+```
+
+resolveRoute i inne helpery działają bez zmian — dostają stałe locale z config
+zamiast z URL. Cała różnica to: brak `[locale]` w strukturze, locale z config.
+
+### Middleware/proxy — jednojęzyczny prawie go nie potrzebuje
+
+Dla jednego locale middleware jest pass-through (nic nie przekierowuje). Możesz
+go pominąć albo zostawić — plugin i tak wykryje 1 locale i przepuści. Bez
+przełącznika języka (jeden język), bez cookie NEXT_LOCALE (nie ma co pamiętać).
+
+### Przejście jedno- → wielojęzyczny (later)
+
+Jeśli klient później doda drugi język, to PRZEBUDOWA, nie przełącznik:
+- dodaj locale do config
+- przenieś strukturę do `[locale]/`
+- layout/strony czytają locale z params
+- wróci prefiks `/pl`, `/en` + hreflang
+
+Warto to przewidzieć na starcie: jeśli jest szansa na drugi język, rozważ od razu
+strukturę wielojęzyczną (z [locale]), nawet dla jednego locale — wtedy prefiks
+`/pl` jest, ale dodanie języka to tylko config, nie przebudowa struktury.
@@ -61,4 +61,81 @@ ZAWSZE wyłączaj w dev: `hsts: process.env.NODE_ENV === 'production'`.

 `additional` z tym samym kluczem NADPISUJE domyślny (np. zmień X-Frame-Options
 na SAMEORIGIN). Nowy klucz (jak CSP) dodaje. CSP zawsze przez `additional` —
-plugin go nie generuje, bo zależy od projektu.
+plugin go nie generuje, bo zależy od projektu.
+
+### Dlaczego CSP zostaje w projekcie (nie plugin)
+
+HSTS, nosniff, Referrer-Policy są IDENTYCZNE dla każdego projektu → plugin je
+generuje. CSP wylicza KONKRETNE domeny, z których projekt ładuje (jego R2,
+analytics, Turnstile, fonty). Generyczny CSP byłby albo za luźny (`*` =
+bezużyteczny), albo psułby stronę. Więc plugin daje mechanizm (`additional`),
+projekt dostarcza CSP dopasowany do siebie.
+
+### Budowa CSP — domeny z env, nie hardkod
+
+Domenę mediów czytaj z `R2_PUBLIC_URL` (env), nie zaszywaj. Resztę źródeł
+dopasuj do tego, co projekt faktycznie ładuje:
+
+```ts
+// next.config.ts
+const r2Url = process.env.R2_PUBLIC_URL || ''
+
+const csp = [
+  "default-src 'self'",
+  // skrypty: self + Turnstile (Cloudflare) + analytics (GTM/GA jeśli używasz)
+  "script-src 'self' 'unsafe-inline' https://challenges.cloudflare.com https://www.googletagmanager.com",
+  // style: self + inline (Tailwind) + Google Fonts
+  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+  // obrazy: self + media R2 (z env!) + data:
+  `img-src 'self' data: ${r2Url}`.trim(),
+  "font-src 'self' https://fonts.gstatic.com data:",
+  "connect-src 'self' https://www.google-analytics.com",
+  // ramki: Turnstile (widget captcha)
+  "frame-src https://challenges.cloudflare.com",
+  "form-action 'self'",
+  "frame-ancestors 'none'",   // zastępuje X-Frame-Options w nowych przeglądarkach
+].join('; ')
+
+const securityHeaders = buildSecurityHeaders({
+  hsts: process.env.NODE_ENV === 'production',
+  additional: [{ key: 'Content-Security-Policy', value: csp }],
+})
+```
+
+Dopasuj źródła do projektu: mapy Google (`https://maps.googleapis.com`,
+`https://*.google.com`), inne embedy, inne analytics. To, czego nie wymienisz,
+zostanie zablokowane.
+
+### WDRAŻAJ CSP OSTROŻNIE — najpierw Report-Only
+
+CSP za ścisły **psuje stronę** (blokuje skrypty/style/obrazy). NIGDY nie wdrażaj
+enforcing CSP na ślepo. Metoda bezpieczna:
+
+1. **Najpierw raportowanie** — użyj klucza `Content-Security-Policy-Report-Only`
+   (nie `Content-Security-Policy`). Przeglądarka RAPORTUJE naruszenia w konsoli,
+   ale NIE blokuje — strona działa normalnie.
+   ```ts
+   additional: [{ key: 'Content-Security-Policy-Report-Only', value: csp }]
+   ```
+2. **Otwórz stronę** → DevTools → Console → szukaj „Content Security Policy"
+   violations. Każde naruszenie = brakująca domena. Dodaj ją do odpowiedniej
+   dyrektywy CSP.
+3. **Przejdź przez cały serwis** — strona główna, formularze (Turnstile!),
+   galeria (obrazy R2), strony z mapą/embedami. Zbierz wszystkie naruszenia.
+4. **Dopiero gdy konsola czysta** → zmień klucz na `Content-Security-Policy`
+   (enforcing). Teraz CSP chroni, nie psując.
+
+### Weryfikacja nagłówków na produkcji
+
+```bash
+# sprawdź, które nagłówki faktycznie wychodzą:
+curl -sI https://<DOMENA>/pl | grep -i "strict-transport\|content-type-options\|referrer\|content-security\|x-frame"
+```
+
+Jeśli HSTS/nosniff/Referrer są, a CSP brak → dodaj CSP (wyżej). Jeśli BRAK
+wszystkich mimo buildSecurityHeaders w config → sprawdź, czy `headers()` jest
+wpięte i czy Cloudflare (jeśli przed aplikacją) nie filtruje nagłówków.
+
+> Uwaga Cloudflare: jeśli CF jest przed aplikacją, może nadpisywać/filtrować
+> nagłówki. Wtedy ustaw je też w CF (Transform Rules → Modify Response Header)
+> albo upewnij się, że CF przepuszcza nagłówki z origin.
@@ -53,6 +53,31 @@ Per strona (tab SEO):

 Domyślnie: `Tytuł | Nazwa witryny`.

+### Skąd bierze się „Tytuł" (priorytet źródła)
+
+Tytuł strony (część przed nazwą witryny) pochodzi z, w kolejności:
+
+1. **titleOverride** — jeśli wypełniony, jest całym tytułem (bez składania).
+2. **meta.title** — tytuł SEO wpisany w tab SEO.
+3. **page.title** — nazwa dokumentu (np. „Sprzątanie biur”), gdy meta.title puste.
+
+Punkt 3 (fallback na nazwę strony) działa na dwa sposoby, uzupełniające się:
+
+- **buildAutoFillMetaHook** (przy ZAPISIE) — wypełnia puste `meta.title` z pola
+  dokumentu (`title`). Jeśli wpięty w kolekcje, meta.title nigdy nie jest puste.
+- **pageTitle w buildMetadata** (przy RENDEROWANIU) — jeśli meta.title mimo to
+  puste (np. auto-fill niewpięty), używa `page.title`. Druga linia obrony.
+
+Efekt: strona bez wypełnionego SEO title i tak pokaże swoją nazwę w karcie, nie
+pusty tytuł ani sam siteName.
+
+> **Uwaga — „Strona Główna” w tytule:** jeśli strona główna ma nazwę dokumentu
+> „Strona Główna” (i auto-fill skopiował ją do meta.title), tytuł wyjdzie
+> „Nazwa – Strona Główna” — bezużyteczne dla SEO. Napraw: wpisz **titleOverride**
+> dla strony głównej (np. „Firma X – Usługa Miasto”), albo zmień meta.title na
+> coś ze słowami kluczowymi. Fallback page.title nie pomoże, bo problemem jest
+> sama treść nazwy, nie brak tytułu.
+
 ## Front — createPageMetadata

 Dla zwykłych stron. Zna konwencje pluginu (kolekcja pages, SiteSettings, System
@@ -217,6 +242,7 @@ export const { /* ... */, sitemap, robots } = createContentHelpers({
 ```ts
 // app/sitemap.ts
 export { sitemap as default } from '@/lib/content'
+export const dynamic = 'force-dynamic' // generuj w runtime, nie w buildzie

 // app/robots.ts
 export { robots as default } from '@/lib/content'
@@ -227,6 +253,16 @@ całkiem w pluginie — Next tworzy te trasy wyłącznie z plików w `app/`, ska
 katalog projektu, nie node_modules. Ale re-eksport to maksimum redukcji: cała
 logika jest w pluginie.

+> **Deploy kontenerowy (Coolify/Docker/Railway/CI) — WAŻNE:** `export const
+> dynamic = 'force-dynamic'` w `app/sitemap.ts` jest KONIECZNE. Bez niego Next
+> traktuje sitemap jako statyczny i prerenderuje go w `next build` — a to
+> wywołuje Payload → bazę. Kontener budujący zwykle nie ma dostępu do sieci
+> Docker, więc połączenie z bazą pada (`ENOTFOUND`) i build się wywala. Z
+> `force-dynamic` sitemap generuje się w runtime, gdy baza jest dostępna.
+> (Plugin dodatkowo łapie błąd bazy i zwraca pusty sitemap zamiast wywalić build
+> — ale `force-dynamic` to właściwe rozwiązanie, nie poleganie na fallbacku.)
+> Opcjonalnie `export const revalidate = 3600` — cache sitemap na godzinę.
+
 Co zawiera sitemapa:
 - każdą stronę i wpis bloga, URL w domyślnym locale
 - `alternates.languages` → Next renderuje `<xhtml:link rel="alternate" hreflang>`
@@ -247,4 +283,505 @@ const entries = await buildSitemapEntries({
 ```

 Przy dziesiątkach tysięcy URL-i Next ma `generateSitemaps` do dzielenia na
-części — dodasz, gdyby realnie było ich tyle. Jedna sitemapa wystarcza do ~50k.
+części — dodasz, gdyby realnie było ich tyle. Jedna sitemapa wystarcza do ~50k.
+
+## Favicon w Google + Organization (branding w wyszukiwarce)
+
+Favicon i structured data wpływają na to, jak strona wygląda w wynikach Google.
+Plugin generuje jedno i drugie z panelu — projekt tylko wpina w root layout.
+
+### Favicon — format: PNG, nie SVG (ważne)
+
+**Dla Google użyj PNG (≥48×48), nie SVG.** Zweryfikowane: Google niezawodnie
+wspiera PNG i ICO, ale **SVG w wynikach Google jest zawodny** — często pokazuje
+glob mimo że w karcie przeglądarki favicon renderuje się dobrze. Oficjalna
+dokumentacja Google nie wymienia SVG. Jeśli zależy Ci na faviconie w wyszukiwarce
+— wgraj PNG.
+
+- **PNG ≥48×48** (idealnie 96 lub 192), kwadratowy → działa w Google ✓
+- **SVG** → działa w przeglądarce, ale w Google glob (zawodne) ✗
+- Walidacja pola favicon OSTRZEGA, gdy wgrasz SVG (żebyś wiedział, że dla search
+  potrzebny PNG).
+
+### Favicon — dlaczego się nie pokazywał
+
+Google ma twarde wymogi: `<link rel="icon">` w `<head>`, kwadratowy, **≥48×48px**,
+stały URL. Gdy projekt renderował favicon „po swojemu", często był za mały, źle
+otagowany albo nieobecny w head → Google go nie pokazywał. Plugin robi to teraz
+poprawnie.
+
+### Wpięcie favicon (root layout)
+
+Favicon jest GLOBALNY (ten sam wszędzie) — wpina się RAZ w root layout, nie per strona:
+
+```tsx
+// app/(frontend)/[locale]/layout.tsx
+import type { Metadata } from 'next'
+import { buildIconsMetadata } from '@intecion/ipal-kit'
+import { getSettings } from '@/lib/payload'
+
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const { locale } = await params
+  const settings = await getSettings(locale)
+  return buildIconsMetadata(settings.favicon)   // z pola favicon (panel)
+}
+```
+
+`buildIconsMetadata` generuje poprawne `icons` (favicon + apple-touch) z pola
+favicon. SVG → skaluje się; PNG → powinien być ≥48×48 (walidacja ostrzega, patrz niżej).
+
+### Wymuszenie rozmiaru (walidacja)
+
+Pole favicon w SiteSettings ma walidację `validateFaviconField` — ostrzega
+redaktora przy zapisie, jeśli favicon jest <48×48 albo nie kwadratowy. Redaktor
+widzi ostrzeżenie, zamiast po cichu wgrać favicon, którego Google nie pokaże.
+
+### Organization JSON-LD (branding)
+
+Pomaga Google powiązać stronę z marką (nazwa, logo) — lepsze wyświetlanie w
+wynikach, logo w knowledge panel.
+
+```tsx
+// root layout — RAZ (Organization jest globalny)
+import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+
+const jsonLd = buildOrganizationJsonLd({
+  name: settings.siteName,
+  url: process.env.NEXT_PUBLIC_SERVER_URL!,
+  logo: settings.logo,
+  sameAs: settings.socialLinks,   // opcjonalne: profile społecznościowe
+})
+
+// w JSX layoutu:
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+/>
+```
+
+Dane z panelu (siteName, logo) — nic na sztywno.
+
+### Po wdrożeniu — cierpliwość z Google
+
+Google **cache'uje favicon osobno i wolno** (dni, czasem tygodnie). Po poprawnym
+wpięciu favicon nie pojawi się natychmiast — Googlebot musi ponownie odwiedzić
+stronę główną. Przyspieszenie: Search Console → prośba o ponowne indeksowanie
+strony głównej. Sprawdź też, czy `/` nie blokuje Googlebota (robots) i czy
+favicon URL jest publiczny (nie za auth).
+
+### Weryfikacja
+
+1. Otwórz stronę → DevTools → Elements → `<head>` → sprawdź `<link rel="icon">`
+   z poprawnym URL.
+2. Otwórz sam URL favicon w przeglądarce — obraz się pokazuje, ≥48×48.
+3. Rich Results Test (Google) — wklej URL strony, sprawdź Organization.
+4. Search Console → poproś o ponowne indeksowanie strony głównej.
+
+## Ręczne rozszerzenia SEO/PWA (manifest itp.) — z panelu, NIE hardkod
+
+Niektóre rzeczy SEO/PWA są na tyle projekt-specyficzne i jednorazowe, że plugin
+ich nie dostarcza (byłoby przeinżynierowaniem). Robisz je w projekcie — ALE
+poprawnie: czytając z panelu/env, nie zaszywając wartości klienta.
+
+> **Zasada:** nawet gdy coś robisz ręcznie w projekcie, dane (nazwa, kolory,
+> opis, logo) czytaj z panelu (SiteSettings) albo env. Zaszyta nazwa/kolor
+> klienta = antywzorzec (patrz standardy-kodu.md). Manifest „R Custom Cars" z
+> hardkodem zadziała tylko dla jednego klienta.
+
+### Web App Manifest (PWA) — jak zrobić DOBRZE
+
+Zasada nadrzędna: **brak danych → POMIŃ pole, NIE zaszywaj wartości.** Manifest
+jest ważny bez `name`? Nie — ale lepszy manifest bez nazwy niż z cudzą nazwą
+klienta w fallbacku. Fallback z nazwą/kolorem klienta to ukryty hardkod.
+
+```ts
+// app/manifest.ts
+import type { MetadataRoute } from 'next'
+import { getCachedPayload } from '@/lib/content'
+import { getSiteSettings } from '@intecion/ipal-kit'
+import { i18nConfig } from '@/i18n.config'
+import type { SiteSetting } from '@/payload-types'
+
+export default async function manifest(): Promise<MetadataRoute.Manifest> {
+  const payload = await getCachedPayload()
+  const settings = await getSiteSettings<SiteSetting>(payload, {
+    locale: i18nConfig.defaultLocale as never,
+  })
+
+  const siteName = settings?.siteName?.trim()
+
+  // Ikona z panelu (favicon → logo). Dla PNG podaj KONKRETNY rozmiar z media
+  // (nie 'any' — 'any' jest tylko dla SVG). Bez ikony → pomiń pole icons.
+  const icon = settings?.favicon ?? settings?.logo
+  const iconEntry =
+    typeof icon === 'object' && icon?.url
+      ? (() => {
+          const isSvg = icon.mimeType === 'image/svg+xml' || icon.url.endsWith('.svg')
+          const size =
+            typeof icon.width === 'number' && typeof icon.height === 'number'
+              ? `${Math.min(icon.width, icon.height)}x${Math.min(icon.width, icon.height)}`
+              : '512x512'
+          return {
+            src: icon.url,
+            type: icon.mimeType ?? 'image/png',
+            sizes: isSvg ? 'any' : size, // 'any' tylko dla SVG
+          }
+        })()
+      : undefined
+
+  // Buduj TYLKO z tego, co jest. Brak pola → nie ma go w manifeście (zamiast
+  // zaszytego fallbacku). start_url z configu, nie zaszyte '/pl'.
+  return {
+    ...(siteName ? { name: siteName, short_name: siteName } : {}),
+    start_url: `/${i18nConfig.defaultLocale}`,
+    display: 'standalone',
+    ...(iconEntry ? { icons: [iconEntry] } : {}),
+    // theme_color / background_color / description — TYLKO jeśli dodasz pola w
+    // panelu i je odczytasz. NIE zaszywaj '#0e1e24' ani opisu klienta.
+  }
+}
+```
+
+**Kluczowe różnice od częstego błędu agenta:**
+- **Brak fallbacku z nazwą klienta** — `siteName` puste → pomijamy `name`, nie
+  wstawiamy „Kancelaria X" na sztywno. Cudza nazwa w fallbacku = hardkod.
+- **PNG dostaje konkretny `sizes`** z wymiarów media (nie `sizes: 'any'` — to
+  ten sam błąd co przy favicon; `any` tylko dla SVG).
+- **Brak bloku `catch` z hardkodami** — jeśli boisz się błędu, opakuj samo
+  `getSiteSettings` i przy błędzie zwróć minimalny manifest (start_url + display),
+  BEZ zaszytej nazwy/kolorów.
+- **start_url z i18nConfig**, nie zaszyte `/pl`.
+
+**Kontrast — czego NIE robić** (realne błędy z projektów):
+
+```ts
+// ŹLE — hardkod jawny (rcustomcars)
+let name = 'R Custom Cars'; short_name: 'RCC'
+background_color: '#08080a', theme_color: '#d4af37'
+icons: [{ src: '/logo/rcc-logo.svg' }]              // statyczna ścieżka
+
+// ŹLE — hardkod UKRYTY w fallbacku (kancelaria)
+siteName || 'Kancelaria Adwokacka Adwokat Romuald Kędzierski'   // cudza nazwa w ||
+sizes: 'any', type: mimeType                        // 'any' na PNG = źle
+catch { return { name: 'Kancelaria...', theme_color: '#0e1e24' } }  // hardkod w catch
+```
+
+Fallback `|| 'Nazwa Klienta'` wygląda niewinnie, ale to hardkod — inny projekt
+skopiuje i pokaże cudzą nazwę, gdy panel zawiedzie. Brak danych → pomiń pole.
+
+Jeśli klient potrzebuje kolorów motywu / opisu w manifeście — **dodaj pola**
+`themeColor`, `manifestDescription` w SiteSettings (przez opcje pluginu
+SiteSettingsFields) i czytaj z panelu. Wtedy redaktor je zmienia, nie są zaszyte.
+
+### Inne ręczne rozszerzenia — ta sama zasada
+
+Cokolwiek dodajesz ręcznie (dodatkowe meta tagi, structured data konkretnego
+typu, itp.):
+- dane z panelu (SiteSettings / pola strony) albo env
+- nic zaszytego per klient (nazwa, kolor, adres, domena)
+- jeśli to uniwersalne i powtarzalne → rozważ zgłoszenie do pluginu zamiast
+  ręcznie (patrz ANTIGRAVITY-ZASADY-AGENT.md A0)
+
+## KRYTYCZNE: metadata w <head> dla Google
+
+**Największa pułapka SEO w Next.js — dotyczy KAŻDEGO projektu.** Dla dynamicznie
+renderowanych stron (SSR) Next.js **streamuje metadata do `<body>`**, nie `<head>`,
+i przenosi ją do head skryptem JS. Skutek: canonical, hreflang, title, favicon
+lądują w body w surowym HTML. Crawlery bez JS (Screaming Frog, część botów) widzą
+je poza head → ignorują → utrata SEO.
+
+**To wyścig czasowy (race condition):** gdy baza odpowie szybko, metadata zdąży
+do head; gdy wolniej (albo crawler odpytuje wiele stron naraz, obciążając bazę),
+Next zamyka `</head>` i dokleja metadata w `<body>`. Dlatego pojedynczy `curl`
+może pokazać head OK, a test 10 zapytań — 5/10 w body. **Testuj wielokrotnie.**
+
+### Rozwiązanie GŁÓWNE — ISR (revalidate) w stronach
+
+Najskuteczniejsze: **cache całej strony (ISR)**. Strona generowana raz z gotowym
+`<head>`, kolejne żądania serwują cache — zero zapytań do bazy przy renderowaniu,
+więc race condition ZNIKA (metadata zawsze w head). Bonus: TTFB spada z ~500ms do
+~20ms, znikają sporadyczne 503 (cold start).
+
+```ts
+// app/(frontend)/[locale]/[[...slug]]/page.tsx
+export const revalidate = 3600   // cache 1h, regeneracja w tle
+```
+
+> **UWAGA — ISR a treść z panelu:** strona cache'owana `revalidate` sekund NIE
+> pokaże zmian redaktora od razu (czeka do rewalidacji). Dla treści zmienianej
+> rzadko OK. Jeśli redaktor ma widzieć zmiany natychmiast — użyj **on-demand
+> revalidation**: hook `afterChange` w kolekcji → `revalidatePath(path)` (patrz
+> HOOKS.md). Albo krótszy `revalidate` (np. 300 = 5 min). NIE łącz ISR z
+> `force-dynamic` — wykluczają się.
+
+### Rozwiązanie DRUGIE — usuń jawny <head> z layoutu
+
+Sztywny `<head>` w layoucie App Router wymusza przedwczesne zamknięcie head —
+zanim strona wygeneruje metadane. To pcha metadata do body. NIE deklaruj `<head>`:
+
+```tsx
+// ŹLE — jawny <head> zamyka head za wcześnie
+<html lang={locale}>
+  <head><MediaPreconnect /></head>
+  <body>{children}</body>
+</html>
+
+// DOBRZE — MediaPreconnect w body, React 19 hoistuje link do head
+<html lang={locale}>
+  <body>
+    <MediaPreconnect />
+    {children}
+  </body>
+</html>
+```
+
+React 19 sam przenosi `<link rel="preconnect">` do head. Jawny `<head>` jest
+zbędny i szkodliwy (wymusza wczesne zamknięcie).
+
+### Rozwiązanie TRZECIE — htmlLimitedBots (uzupełnienie)
+
+Dodatkowo można wymusić blocking metadata dla crawlerów (przydatne, gdy strona
+z jakiegoś powodu nie może być ISR):
+
+```ts
+// next.config.ts
+const nextConfig: NextConfig = {
+  htmlLimitedBots:
+    /Googlebot|Google-InspectionTool|Storebot-Google|Bingbot|Yandex|DuckDuckBot|Baiduspider|Screaming Frog|AhrefsBot|SemrushBot/i,
+}
+```
+
+`htmlLimitedBots` wyłącza streaming dla tych User-Agentów (metadata w head). ALE
+to słabsze niż ISR — bo strona dalej renderuje dynamicznie (zapytanie do bazy →
+wolniej, ryzyko race). **ISR eliminuje przyczynę, htmlLimitedBots łagodzi objaw.**
+Najlepiej: ISR + brak jawnego head. htmlLimitedBots jako dodatkowa warstwa.
+
+### Objawy (że masz ten problem)
+
+- Screaming Frog: „canonical/hreflang/title outside <head>" (na wielu podstronach)
+- Search Console: „brak canonical", favicon glob
+- Surowy HTML: canonical/title PO `</head>`, na końcu body, ze skryptem appendChild
+- Test 10 zapytań: część w head, część w body (race condition)
+
+### Weryfikacja — TESTUJ WIELOKROTNIE (nie pojedynczo)
+
+Pojedynczy `curl` może trafić w „szczęśliwy" timing. Testuj 10 razy:
+
+```bash
+# 10 zapytań jako Googlebot — ile ma canonical w <head>
+for i in $(seq 1 10); do
+  curl -s -A "Googlebot" https://twojadomena.pl/pl/strona | \
+  python3 -c "import sys; h=sys.stdin.read(); e=h.find('</head>'); c=h.find('rel=\"canonical\"'); print('head' if 0<c<e else 'BODY')"
+done
+# Cel: 10x 'head'. Jeśli część 'BODY' → race condition, dodaj ISR.
+```
+
+Testuj też PODSTRONY (nie tylko główną) — race częściej dotyka podstron.
+DevTools (F12) NIE nadaje się do testu — hoistuje tagi do head automatycznie,
+pokazując fałszywie poprawny head. Używaj `curl` / Ctrl+U (surowe źródło).
+
+## SEO wielojęzyczne — hreflang, x-default, redirect roota
+
+Przekierowanie `/` → `/pl` (negocjacja locale) może wpływać na SEO. Kluczowe:
+plugin generuje hreflang, więc Google rozumie, że `/pl` i `/en` to wersje
+językowe (nie duplikaty). Ale są niuanse.
+
+### hreflang + x-default (generowane przez plugin)
+
+`buildHreflangAlternates` generuje `alternates.languages` z wpisami per locale
+ORAZ **`x-default`** wskazujący na defaultLocale. x-default mówi Google: „gdy
+język/region użytkownika nie pasuje do żadnej wersji, użyj TEJ" — co pokrywa
+sytuację roota (Googlebot bez preferencji językowej). Bez x-default Google
+zgadywałby; z nim dostaje jasną wskazówkę (domyślnie pl).
+
+Działa automatycznie przez createPageMetadata (canonical + hreflang + x-default).
+
+### Redirect roota — na co uważać
+
+- **307 (temporary)** na `/` → `/pl` — plugin tak robi. Dla warunkowego redirectu
+  (zależnego od negocjacji) to obronne. Google i tak podąża.
+- **Negocjacja Accept-Language** — Googlebot bywa z `Accept-Language: en` albo
+  bez. Może trafić na `/en`. x-default (→ pl) łagodzi to: Google wie, że
+  domyślna wersja to polska.
+- **Root nie ma własnej treści** — cała moc idzie przez redirect na locale. To
+  normalne dla i18n stron, hreflang to obsługuje.
+
+### Weryfikacja SEO wielojęzycznego
+
+1. Search Console → Inspekcja URL dla `/` — zobacz, na co Google przekierowuje
+   i co indeksuje.
+2. Sprawdź, czy `/pl` i `/en` są indeksowane osobno (nie jako duplikaty).
+3. Rich Results / źródło strony → potwierdź `<link rel="alternate" hreflang="...">`
+   z wpisami per locale + `hreflang="x-default"`.
+4. Search Console → raport Międzynarodowe targetowanie (jeśli dostępny) — błędy
+   hreflang.
+
+### Częste błędy (nie rób tak)
+
+- Brak hreflang → Google traktuje wersje jako duplikaty (plugin to ma, nie usuwaj).
+- Zaszyta mapa ścieżek zamiast getLocalizedSlugs → hreflang się rozjedzie z bazą.
+- `noindex` na `/pl` przez pomyłkę → wypada z indeksu. Sprawdź robots meta.
+- Redirect roota na twardo 301 do jednego języka → tracisz negocjację i drugą
+  wersję. Zostaw negocjację + hreflang.
+
+## Sitelinks i structured data (branding w wynikach Google)
+
+Cel: żeby wyszukanie marki („rcustomcars") pokazało stronę główną + podlinki
+(sitelinks) z opisami. Ważne — **sitelinków NIE DA SIĘ wymusić.** Google
+generuje je algorytmicznie ze struktury strony, linkowania wewnętrznego, jasnych
+tytułów i rankingu. Żaden kod ich nie włączy. Plugin dostarcza SYGNAŁY, które
+zwiększają szansę — nie gwarancję.
+
+### Co realnie wpływa na sitelinki (kolejność wg wagi)
+
+1. **Ranking na 1. stronie Google** — bez tego sitelinków nie ma. To robota SEO
+   (treść, linki), nie kodu.
+2. **Czysta struktura + jasne tytuły** — logiczna hierarchia stron, opisowe title
+   (nie „Strona 1"). Patrz fundamenty-projektu.md.
+3. **Linkowanie wewnętrzne** — ważne strony podlinkowane z głównej.
+4. **Structured data** (poniżej) — sygnał pomocniczy, nie przełącznik.
+5. **Sitemap + robots** — żeby Google w ogóle widział wszystkie strony (patrz
+   niżej — to fundament, sprawdź czy działa!).
+
+### Structured data z pluginu — 3 helpery
+
+Wszystkie emitowane jako `<script type="application/ld+json">`, dane z panelu.
+
+**1. WebSite + SearchAction (największy realny efekt)** — może dać sitelinks
+searchbox (pole wyszukiwania pod wynikiem marki). RAZ w root layout:
+```tsx
+import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildWebSiteJsonLd({
+  name: settings.siteName,
+  url: baseUrl,
+  // TYLKO jeśli masz działającą stronę wyszukiwania:
+  search: { target: `${baseUrl}/szukaj?q={search_term_string}` },
+})
+```
+Pomiń `search`, jeśli nie ma realnej wyszukiwarki — SearchAction wskazujący na
+nieistniejącą stronę szkodzi.
+
+**2. BreadcrumbList (realny efekt)** — okruszki w wynikach (Dom › Usługi ›
+Detailing) + Google rozumie hierarchię. PER STRONA, z pozycji strony:
+```tsx
+import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildBreadcrumbJsonLd([
+  { name: 'Strona główna', url: `${base}/pl` },
+  { name: 'Usługi', url: `${base}/pl/uslugi` },
+  { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+])
+```
+Okruszki buduj z RZECZYWISTEJ pozycji strony (resolveRoute / ścieżka URL), NIE z
+zaszytej listy.
+
+**3. SiteNavigationElement (słabszy, tani)** — nawigacja jako dane. RAZ, z tych
+samych pozycji co menu w headerze:
+```tsx
+import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildSiteNavigationJsonLd(
+  navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+)
+```
+Dane z tego samego źródła co widoczne menu — nie osobna zaszyta lista.
+
+### Realne oczekiwania (ważne)
+
+- Structured data **nie gwarantuje** sitelinków — to sygnał wśród wielu.
+- Efekt (jeśli będzie) pojawia się **po tygodniach**, gdy Google przecrawluje i
+  strona rankuje.
+- Największy wpływ ma **ranking + struktura + linkowanie**, nie schema. Schema
+  pomaga Google zrozumieć, ale nie zastąpi bycia na 1. stronie.
+- Weryfikuj: Google Rich Results Test (czy schema poprawna) + Search Console
+  (co Google pokazuje dla marki).
+
+### To, co ZALEŻY OD PROJEKTU (obowiązki wpięcia)
+
+Plugin dostarcza helpery — projekt MUSI je wpiąć i podać dane z panelu:
+
+- [ ] `buildWebSiteJsonLd` w root layout (search tylko jeśli jest wyszukiwarka)
+- [ ] `buildOrganizationJsonLd` w root layout (logo, nazwa)
+- [ ] `buildBreadcrumbJsonLd` na podstronach (z realnej ścieżki)
+- [ ] `buildSiteNavigationJsonLd` z pozycji menu (jeśli jest header nav)
+- [ ] `app/robots.ts` i `app/sitemap.ts` wystawione (patrz niżej — bez tego
+  Google nie widzi stron!)
+- [ ] Jasne, opisowe tytuły stron (nie generyczne)
+- [ ] Logiczna hierarchia + linkowanie wewnętrzne z głównej
+
+Dane WSZĘDZIE z panelu (siteName, nav, logo), nigdy zaszyte.
+
+## noindex per strona (strony prawne, cienkie, wyniki wyszukiwania)
+
+Niektóre strony NIE powinny być w indeksie Google: polityki/regulamin (kanibalizują
+frazy), strony z parametrami, wyniki wyszukiwania. Plugin wspiera to przez pole
+`noindex` w meta SEO.
+
+```ts
+// w danych strony (meta): noindex: true
+// buildMetadata automatycznie doda robots: { index: false, follow: true }
+```
+
+`noindex, follow` — strona wypada z indeksu, ale linki dalej przekazują moc
+(follow). Ustaw dla:
+- polityka prywatności, regulamin, polityka cookies
+- strony z parametrami kalkulatorów, filtrów
+- wyniki wewnętrznej wyszukiwarki
+
+Redaktor zaznacza `noindex` w panelu (pole SEO strony), plugin generuje tag.
+Alternatywnie: dodaj `noindex` do System Pages o rolach prawnych automatycznie.
+
+## robots.txt — blokada parametrów (crawl budget)
+
+URL-e z parametrami (`?meter=101-120m2`, `?s=fraza`) marnują budżet indeksowania —
+Google skanuje dziesiątki pustych wariantów. Zablokuj je w robots:
+
+```ts
+// app/robots.ts
+import { buildRobots } from '@intecion/ipal-kit'
+export default function robots() {
+  return buildRobots({
+    baseUrl: process.env.NEXT_PUBLIC_SERVER_URL!,
+    disallow: ['/admin', '/api', '/*?meter=*', '/*?s=*'],  // + parametry
+  })
+}
+```
+
+Wzorce `/*?param=*` odcinają parametryzowane URL-e. Realne z audytu: 55
+niezindeksowanych stron kalkulatora — blokada w robots by temu zapobiegła.
+
+## Local SEO — LocalBusiness, Service, FAQPage (structured data)
+
+Dla firm lokalnych (usługi + miasto) — trzy schematy zwiększające widoczność
+w wynikach lokalnych i rich results.
+
+**LocalBusiness (map pack, wyniki lokalne)** — RAZ w root layout, z globala company:
+```ts
+import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildLocalBusinessJsonLd({
+  name: company.name, url: baseUrl, telephone: company.phone,
+  address: company.address, openingHours: company.hours,
+  geo: company.geo, priceRange: '$$',
+})
+```
+Najważniejsze dla „usługa + miasto". Dla konkretnego typu (Dentist, Plumber)
+nadpisz `@type`.
+
+**Service (co strona oferuje)** — per strona usługowa:
+```ts
+import { buildServiceJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildServiceJsonLd({
+  name: 'Sprzątanie biur', providerName: company.name,
+  url: pageUrl, areaServed: 'Wrocław',
+})
+```
+
+**FAQPage (rich results FAQ)** — per strona z FAQ, z bloku FAQ w panelu:
+```ts
+import { buildFaqJsonLd } from '@intecion/ipal-kit'
+const jsonLd = buildFaqJsonLd(
+  faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+)
+```
+WAŻNE: Q&A musi odpowiadać widocznej treści strony (Google flaguje rozbieżność).
+Nie wymyślaj pytań, których nie ma na stronie.
+
+Wszystkie: dane z panelu (company, bloki), jako `<script type="application/ld+json">`.
@@ -133,6 +133,27 @@ pnpm dev
 # wgraj obraz w panelu (Media) → sprawdź w Cloudflare R2, czy plik się pojawił
 ```

+## Root subdomeny media zwraca 404 (to normalne)
+
+`media.klient.pl/plik.jpg` → R2 zwraca plik. Ale `media.klient.pl/` (sam root,
+bez pliku) → **404**, bo R2 nie ma obiektu pod rootem. To NORMALNE zachowanie
+R2, nie błąd.
+
+Audyty SEO (Screaming Frog) czasem zgłaszają to 404 — bo crawler widzi URL-e
+plików (`media.../logo.svg`) i próbuje roota. Ale:
+- **NIE linkuj do samego roota** `media.klient.pl/` — tylko do plików. Kod nie
+  powinien nigdzie mieć `media.klient.pl/` bez nazwy pliku.
+- Root media 404 **nie szkodzi SEO** głównej domeny (Google indeksuje klient.pl,
+  nie media.klient.pl). Nikt nie trafia na root media.
+
+**Plugin tego nie naprawi** — subdomena media to serwis R2/Cloudflare, nie
+aplikacja Next. Żądania do media.klient.pl nie docierają do Twojego kodu.
+
+Jeśli chcesz „czysto" w Search Console (opcjonalne): Cloudflare → Rules →
+Redirect Rules → gdy hostname = `media.klient.pl` i path = `/` → 301 na
+`klient.pl`. Jednorazowo w panelu CF. Ale to kosmetyka — root media 404 jest
+nieszkodliwe.
+
 ## Dev na lokalnym I na R2 (seedowanie podczas developmentu)

 Fallback (brak zmiennych → lokalny dysk) oznacza, że **dev działa w obu trybach**:
@@ -1,6 +1,6 @@
 {
  "name": "@intecion/ipal-kit",
-  "version": "1.1.0",
+  "version": "1.2.4",
  "description": "Intecion Payload Advanced Library — a Payload CMS 3 plugin: i18n, SEO, forms, consent, analytics, blog/archives.",
  "license": "MIT",
  "repository": {
@@ -1,8 +1,10 @@
 import type { Field } from 'payload'

+import { validateFaviconField } from '../../../modules/seo/index.js'
+
 /**
 * General site identity fields.
- * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo).
+ * Consumed by SEO/OG (siteName, defaultShareImage) and frontend (logo, favicon).
 */
 export const generalFields: Field[] = [
  {
@@ -45,7 +47,8 @@ export const generalFields: Field[] = [
    name: 'logo',
    type: 'upload',
    admin: {
-      description: 'Primary site logo.',
+      description:
+        'Primary site logo. Also used for Organization structured data (buildOrganizationJsonLd).',
    },
    relationTo: 'media',
  },
@@ -61,7 +64,13 @@ export const generalFields: Field[] = [
    name: 'favicon',
    type: 'upload',
    admin: {
-      description: 'Square source icon (PNG or SVG) for the browser tab. Rendered by the frontend.',
+      description:
+        'Square icon, PNG or SVG, min. 48×48px (Google requires this to show it in search). Rendered via buildIconsMetadata.',
+    },
+    hooks: {
+      // Warns the editor at save time if the favicon is too small (<48×48) or
+      // not square — Google won't display such favicons in search results.
+      beforeValidate: [validateFaviconField],
    },
    relationTo: 'media',
  },
@@ -99,6 +99,21 @@ export {
 } from './modules/payload/index.js'
 export { buildSecurityHeaders } from './modules/security/index.js'
 export type { BuildSecurityHeadersArgs, SecurityHeader } from './modules/security/index.js'
+export {
+  buildFaqJsonLd,
+  buildIconsMetadata,
+  buildLocalBusinessJsonLd,
+  buildOrganizationJsonLd,
+  buildServiceJsonLd,
+  validateFaviconField,
+} from './modules/seo/index.js'
+// Structured data (schema.org JSON-LD) — brand/sitelink signals for Google.
+// WebSite (+ optional SearchAction), BreadcrumbList (per page), SiteNavigation.
+export {
+  buildBreadcrumbJsonLd,
+  buildSiteNavigationJsonLd,
+  buildWebSiteJsonLd,
+} from './modules/seo/index.js'
 export type { PageMetadata, SeoMeta, SeoOption } from './modules/seo/index.js'
 export { buildHreflangAlternates, buildMetadata, composeTitle } from './modules/seo/index.js'
 export type { AutoFillMapping, RobotsRules, SitemapEntry } from './modules/seo/index.js'
@@ -1,22 +1,14 @@
-import type { BasePayload, SanitizedConfig } from 'payload'
-
-import { getPayload } from 'payload'
 import { cache } from 'react'
+import type { BasePayload, SanitizedConfig } from 'payload'
+import { getPayload } from 'payload'

-import type { ArchiveEntries, ContentOption, ResolvedRoute } from '../content/index.js'
+import type { ContentOption, ResolvedRoute, ArchiveEntries } from '../content/index.js'
+import { resolveRoute as resolveRouteRaw, getArchiveEntries } from '../content/index.js'
 import type { I18nConfig } from '../i18n/index.js'
-import type { RobotsRules, SitemapEntry } from '../seo/index.js'
-
-import { getArchiveEntries, resolveRoute as resolveRouteRaw } from '../content/index.js'
-import { buildRobots, buildSitemapEntries } from '../seo/index.js'
+import type { SitemapEntry, RobotsRules } from '../seo/index.js'
+import { buildSitemapEntries, buildRobots } from '../seo/index.js'

 type CreateContentHelpersArgs = {
-  /**
-   * Absolute site origin for sitemap/robots URLs. Falls back to
-   * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
-   * reject, so set one in production).
-   */
-  baseUrl?: string
  /**
   * The client's payload config promise (the default export of payload.config).
   * Passed in because the plugin never imports the client's config directly.
@@ -24,15 +16,21 @@ type CreateContentHelpersArgs = {
  config: Promise<SanitizedConfig> | SanitizedConfig
  /** Archive-backed collections, same value as the plugin option. */
  content?: ContentOption
+  /** SiteSettings global slug. Defaults to 'site-settings'. */
+  settingsSlug?: string
+  /** Pages collection slug. Defaults to 'pages'. */
+  pagesSlug?: string
  /**
   * i18n config. Required only if you want the ready-made `sitemap` / `robots`
   * handlers — they need the locale list to emit hreflang.
   */
  i18n?: I18nConfig
-  /** Pages collection slug. Defaults to 'pages'. */
-  pagesSlug?: string
-  /** SiteSettings global slug. Defaults to 'site-settings'. */
-  settingsSlug?: string
+  /**
+   * Absolute site origin for sitemap/robots URLs. Falls back to
+   * NEXT_PUBLIC_SERVER_URL, then to a relative origin (which most crawlers
+   * reject, so set one in production).
+   */
+  baseUrl?: string
 }

 /**
@@ -62,12 +60,12 @@ type CreateContentHelpersArgs = {
 * not the second, and a page component composes them in two obvious lines.
 */
 export function createContentHelpers({
-  baseUrl,
  config,
  content,
-  i18n,
-  pagesSlug = 'pages',
  settingsSlug = 'site-settings',
+  pagesSlug = 'pages',
+  i18n,
+  baseUrl,
 }: CreateContentHelpersArgs) {
  const origin = baseUrl ?? process.env.NEXT_PUBLIC_SERVER_URL ?? ''
  const getCachedPayload = cache(async (): Promise<BasePayload> =>
@@ -81,7 +79,7 @@ export function createContentHelpers({

  const getSettings = cache(async (locale: string) => {
    const payload = await getCachedPayload()
-    return payload.findGlobal({ slug: settingsSlug as never, depth: 2, locale: locale as never })
+    return payload.findGlobal({ slug: settingsSlug as never, locale: locale as never, depth: 2 })
  })

  /** What does this URL point at? Routing only — no listing data. */
@@ -90,9 +88,9 @@ export function createContentHelpers({
      locale: string,
      segments: string[] | undefined,
      page: number,
-    ): Promise<null | ResolvedRoute> => {
+    ): Promise<ResolvedRoute | null> => {
      const payload = await getCachedPayload()
-      return resolveRouteRaw({ content, locale, page, pagesSlug, payload, segments, settingsSlug })
+      return resolveRouteRaw({ payload, locale, segments, page, content, pagesSlug, settingsSlug })
    },
  )

@@ -105,7 +103,7 @@ export function createContentHelpers({
      perPage: number,
    ): Promise<ArchiveEntries> => {
      const payload = await getCachedPayload()
-      return getArchiveEntries({ collection, locale, page, payload, perPage })
+      return getArchiveEntries({ payload, collection, locale, page, perPage })
    },
  )

@@ -116,20 +114,45 @@ export function createContentHelpers({
   * ```ts
   * // app/sitemap.ts
   * export { sitemap as default } from '@/lib/content'
+   * export const dynamic = 'force-dynamic'  // generate at runtime, not build
   * ```
+   *
+   * IMPORTANT — container deploys (Coolify/Docker/Railway/CI): Next treats
+   * sitemap.ts as STATIC by default and prerenders it during `next build`, which
+   * calls into Payload → the database. The build container usually has no access
+   * to the internal Docker network, so the DB connection fails (ENOTFOUND) and
+   * the build dies. Two defenses:
+   *   1. `export const dynamic = 'force-dynamic'` in app/sitemap.ts — skips build
+   *      prerender, generates at runtime when the DB is reachable (recommended).
+   *   2. This handler also catches DB errors and returns [] so that even without
+   *      (1) the build won't crash — it just ships an empty sitemap until the
+   *      next runtime regeneration. (1) is still preferred; (2) is a safety net.
   */
  const sitemap = cache(async (): Promise<SitemapEntry[]> => {
    if (!i18n) {
      throw new Error('[ipal] createContentHelpers: pass `i18n` to use the sitemap handler.')
    }
-    return buildSitemapEntries({
-      baseUrl: origin,
-      config: i18n,
-      content,
-      pagesSlug,
-      payload: await getCachedPayload(),
-      settingsSlug,
-    })
+    try {
+      return await buildSitemapEntries({
+        payload: await getCachedPayload(),
+        config: i18n,
+        baseUrl: origin,
+        content,
+        pagesSlug,
+        settingsSlug,
+      })
+    } catch (error) {
+      // DB unreachable (typically a container build with no DB network) — return
+      // an empty sitemap instead of failing the build. Runtime regeneration will
+      // produce the real one once the DB is reachable. See dynamic='force-dynamic'.
+      console.warn(
+        '[ipal] sitemap: could not reach the database, returning empty entries ' +
+          "(add `export const dynamic = 'force-dynamic'` to app/sitemap.ts to " +
+          'generate at runtime and avoid build-time DB access):',
+        error,
+      )
+      return []
+    }
  })

  /**
@@ -145,10 +168,10 @@ export function createContentHelpers({
  return {
    getCachedPayload,
    getConfiguredLocales,
-    getEntries,
    getSettings,
    resolveRoute,
-    robots,
+    getEntries,
    sitemap,
+    robots,
  }
 }
@@ -1,16 +1,15 @@
-import type { I18nConfig } from './types.js'
-
+import type { I18nConfig } from '../i18n/index.js'
+import { negotiateLocale, isValidLocale, LOCALE_COOKIE_NAME } from '../i18n/index.js'
 import { CONSENT_COOKIE, parseConsent } from '../consent/storage.js'
-import { isValidLocale, LOCALE_COOKIE_NAME, negotiateLocale } from '../i18n/index.js'

 /**
 * Minimal request shape the middleware reads. Kept structural so the plugin
 * doesn't hard-depend on next/server types; a Next.js `NextRequest` satisfies it.
 */
 type MiddlewareRequest = {
+  nextUrl: { pathname: string; search: string; clone: () => URL }
  cookies: { get: (name: string) => { value: string } | undefined }
-  headers: { get: (name: string) => null | string }
-  nextUrl: { clone: () => URL; pathname: string; search: string }
+  headers: { get: (name: string) => string | null }
  url: string
 }

@@ -20,11 +19,13 @@ type MiddlewareRequest = {
 * `next` means let the request pass through untouched.
 */
 export type LocaleMiddlewareResult =
-  | { cookie?: { name: string; value: string }; location: string; type: 'redirect' }
-  | { cookie?: { name: string; value: string }; type: 'next' }
+  | { type: 'next'; cookie?: { name: string; value: string } }
+  | { type: 'redirect'; location: string; cookie?: { name: string; value: string } }

 type CreateLocaleMiddlewareArgs = {
  config: I18nConfig
+  /** Cookie name for the locale choice. Defaults to LOCALE_COOKIE_NAME. */
+  cookieName?: string
  /**
   * Consent category that gates *persisting* the locale cookie. The locale is
   * always detected (routing works regardless), but the choice is only written
@@ -32,11 +33,9 @@ type CreateLocaleMiddlewareArgs = {
   * 'functional'. Pass 'necessary' to always persist (treat locale as strictly
   * necessary), which restores the pre-consent behaviour.
   */
-  consentCategory?: 'functional' | 'necessary'
+  consentCategory?: 'necessary' | 'functional'
  /** Name of the consent cookie to read. Defaults to CONSENT_COOKIE. */
  consentCookieName?: string
-  /** Cookie name for the locale choice. Defaults to LOCALE_COOKIE_NAME. */
-  cookieName?: string
 }

 /**
@@ -76,14 +75,14 @@ function firstSegment(pathname: string): string {
 */
 export function createLocaleMiddleware({
  config,
+  cookieName = LOCALE_COOKIE_NAME,
  consentCategory = 'functional',
  consentCookieName = CONSENT_COOKIE,
-  cookieName = LOCALE_COOKIE_NAME,
 }: CreateLocaleMiddlewareArgs) {
  // Whether the locale cookie may be written: 'necessary' is always granted;
  // 'functional' (default) requires the visitor to have consented.
  function mayPersistLocale(request: MiddlewareRequest): boolean {
-    if (consentCategory === 'necessary') {return true}
+    if (consentCategory === 'necessary') return true
    const consent = parseConsent(request.cookies.get(consentCookieName)?.value)
    return consent?.[consentCategory] === true
  }
@@ -91,6 +90,15 @@ export function createLocaleMiddleware({
  return function localeMiddleware(request: MiddlewareRequest): LocaleMiddlewareResult {
    const { pathname } = request.nextUrl

+    // Single-locale sites have no /pl, /en prefix and no negotiation — one
+    // language, no redirect. The middleware becomes a pass-through: paths stay
+    // as-is (/o-nas), nothing to detect or persist. (Projects that are truly
+    // single-locale usually don't even mount this middleware, but guarding here
+    // makes it safe if they do.)
+    if (config.locales.length === 1) {
+      return { type: 'next' }
+    }
+
    // Already locale-prefixed (e.g. the visitor switched language by
    // navigating to /en). Routing is fine — but if the URL's locale differs
    // from the stored cookie, the visitor is *choosing* a language, and we
@@ -108,9 +116,9 @@ export function createLocaleMiddleware({

    // Resolve the locale to use
    const locale = negotiateLocale({
+      cookieLocale: request.cookies.get(cookieName)?.value ?? null,
      acceptLanguage: request.headers.get('accept-language'),
      config,
-      cookieLocale: request.cookies.get(cookieName)?.value ?? null,
    })

    // Redirect to the locale-prefixed path, preserving the rest
@@ -71,6 +71,13 @@ export function buildLocalizedPath({
    return undefined
  }

+  // Single-locale sites have no /pl, /en prefix — the language segment is
+  // dropped entirely (path is /o-nas, not /pl/o-nas). Detected automatically:
+  // one configured locale means one language, so no prefix is needed. The
+  // project's folder structure matches (app/[[...slug]] without [locale]).
+  const singleLocale = config.locales.length === 1
+  const localeSegment = singleLocale ? '' : `/${locale}`
+
  if (prefix) {
    const segment = prefix[locale]
    // No archive slug in this locale means the entry is unreachable there —
@@ -79,14 +86,15 @@ export function buildLocalizedPath({
    if (!segment) {
      return undefined
    }
-    return `/${locale}/${segment}/${slug}`
+    return `${localeSegment}/${segment}/${slug}`
  }

  if (slug === homeSlug) {
-    return `/${locale}`
+    // Home collapses to the root: '/' for single-locale, '/pl' otherwise.
+    return localeSegment || '/'
  }

-  return `/${locale}/${slug}`
+  return `${localeSegment}/${slug}`
 }

 type SwitchLocaleArgs = {
@@ -0,0 +1,44 @@
+type Crumb = {
+  /** Visible name of the breadcrumb (e.g. 'Usługi'). */
+  name: string
+  /** Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). */
+  url: string
+}
+
+/**
+ * Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site
+ * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)
+ * and uses them to understand structure — a signal that helps navigational
+ * results and sitelinks.
+ *
+ * Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are
+ * PER-PAGE — build them from the page's ancestry and emit on that page:
+ *
+ *   import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildBreadcrumbJsonLd([
+ *     { name: 'Strona główna', url: `${base}/pl` },
+ *     { name: 'Usługi', url: `${base}/pl/uslugi` },
+ *     { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },
+ *   ])
+ *   <script type="application/ld+json" ... />
+ *
+ * The crumb data comes from the page's real position (parent pages / URL path),
+ * NOT hardcoded. Derive it from the resolved route, not a static list.
+ *
+ * Returns null for an empty/single crumb list — a one-item breadcrumb isn't
+ * meaningful and shouldn't be emitted.
+ */
+export function buildBreadcrumbJsonLd(crumbs: Crumb[]) {
+  if (!crumbs || crumbs.length < 2) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((crumb, index) => ({
+      name: crumb.name,
+      '@type': 'ListItem',
+      item: crumb.url,
+      position: index + 1,
+    })),
+  }
+}
@@ -0,0 +1,37 @@
+type FaqItem = {
+  answer: string
+  question: string
+}
+
+/**
+ * Builds FAQPage JSON-LD (schema.org) from Q&A pairs. Google can show these as
+ * expandable FAQ rich results under the page, taking more SERP space and helping
+ * with voice/AI answers. Strong for service landing pages.
+ *
+ * Feed it the SAME questions/answers rendered on the page (from an FAQ block in
+ * the panel) — the structured data must match visible content, or Google may
+ * flag it. Never invent Q&A that isn't on the page.
+ *
+ *   import { buildFaqJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildFaqJsonLd(
+ *     faqBlock.items.map(i => ({ question: i.question, answer: i.answer }))
+ *   )
+ *
+ * Returns null for empty list.
+ */
+export function buildFaqJsonLd(items: FaqItem[]) {
+  if (!items || items.length === 0) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: items.map((item) => ({
+      name: item.question,
+      '@type': 'Question',
+      acceptedAnswer: {
+        '@type': 'Answer',
+        text: item.answer,
+      },
+    })),
+  }
+}
@@ -0,0 +1,46 @@
+import type { Metadata } from 'next'
+
+type MediaLike =
+  | { height?: null | number; mimeType?: null | string; url?: null | string; width?: null | number }
+  | null
+  | undefined
+
+/**
+ * Builds Next.js `icons` metadata (favicon / apple-touch-icon) from the panel's
+ * favicon upload, so the browser tab AND Google get a proper <link rel="icon">.
+ *
+ * Why the plugin must do this (not the project): favicon-in-Google has strict
+ * rules — a real <link rel="icon"> in <head>, square, ≥48×48, at a stable URL.
+ * Leaving it to each project meant inconsistent hand-rolled tags and no favicon
+ * in search results. This generates the tags correctly, every time, from the
+ * panel field.
+ *
+ * Favicon is GLOBAL (same across pages), so call this once in the ROOT layout's
+ * generateMetadata — not per page:
+ *
+ *   import { buildIconsMetadata } from '@intecion/ipal-kit'
+ *   export async function generateMetadata(): Promise<Metadata> {
+ *     const settings = await getSettings(locale)
+ *     return buildIconsMetadata(settings.favicon)
+ *   }
+ *
+ * Google notes: it caches favicons separately and slowly (days/weeks), and only
+ * shows them for icons it deems valid. Warn on too-small icons at upload time
+ * (see the media validation hook) so editors don't ship a <48px favicon Google
+ * will reject.
+ */
+export function buildIconsMetadata(favicon: MediaLike): Metadata {
+  const url = favicon?.url
+  if (!url) {return {}}
+
+  const isSvg = favicon?.mimeType === 'image/svg+xml' || url.endsWith('.svg')
+
+  return {
+    icons: {
+      // Main favicon. SVG scales; PNG should be ≥48×48 (ideally 96 or 192).
+      icon: isSvg ? [{ type: 'image/svg+xml', url }] : [{ sizes: 'any', url }],
+      // Apple touch icon (home-screen bookmark on iOS). Reuses the same asset.
+      apple: [{ url }],
+    },
+  }
+}
@@ -0,0 +1,86 @@
+type MediaLike = { url?: null | string } | null | undefined
+
+type Address = {
+  city?: string
+  country?: string // ISO code, e.g. 'PL'
+  postalCode?: string
+  region?: string
+  street?: string
+}
+
+type LocalBusinessJsonLdArgs = {
+  address?: Address
+  /** Geo coordinates for maps/local search. */
+  geo?: { latitude: number; longitude: number }
+  image?: MediaLike
+  logo?: MediaLike
+  name: string
+  /** Opening hours, e.g. ['Mo-Fr 08:00-18:00', 'Sa 09:00-14:00']. */
+  openingHours?: string[]
+  priceRange?: string // e.g. '$$'
+  sameAs?: string[]
+  /** Business phone, e.g. '+48 123 456 789'. */
+  telephone?: string
+  url: string
+}
+
+/**
+ * Builds LocalBusiness JSON-LD (schema.org) — the key structured data for LOCAL
+ * SEO. Helps Google show the business in local results / map pack with address,
+ * hours, phone. Strong signal for "usługa + miasto" queries.
+ *
+ * All data from the panel (company global) — nothing hardcoded. Emit once in the
+ * root layout (business is site-wide):
+ *
+ *   import { buildLocalBusinessJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildLocalBusinessJsonLd({
+ *     name: company.name, url: baseUrl, telephone: company.phone,
+ *     address: company.address, openingHours: company.hours,
+ *   })
+ *
+ * For a more specific type (e.g. 'Dentist', 'Plumber'), override @type in the
+ * returned object — schema.org has many LocalBusiness subtypes.
+ */
+export function buildLocalBusinessJsonLd({
+  name,
+  address,
+  geo,
+  image,
+  logo,
+  openingHours,
+  priceRange,
+  sameAs,
+  telephone,
+  url,
+}: LocalBusinessJsonLdArgs) {
+  const logoUrl = logo?.url
+  const imageUrl = image?.url ?? logoUrl
+
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'LocalBusiness',
+    url,
+    ...(telephone ? { telephone } : {}),
+    ...(imageUrl ? { image: imageUrl.startsWith('http') ? imageUrl : `${url}${imageUrl}` } : {}),
+    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),
+    ...(address
+      ? {
+          address: {
+            '@type': 'PostalAddress',
+            ...(address.street ? { streetAddress: address.street } : {}),
+            ...(address.city ? { addressLocality: address.city } : {}),
+            ...(address.postalCode ? { postalCode: address.postalCode } : {}),
+            ...(address.region ? { addressRegion: address.region } : {}),
+            ...(address.country ? { addressCountry: address.country } : {}),
+          },
+        }
+      : {}),
+    ...(geo
+      ? { geo: { '@type': 'GeoCoordinates', latitude: geo.latitude, longitude: geo.longitude } }
+      : {}),
+    ...(openingHours && openingHours.length > 0 ? { openingHours } : {}),
+    ...(priceRange ? { priceRange } : {}),
+    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),
+  }
+}
@@ -22,6 +22,11 @@ export type PageMetadata = {
    locale?: string
    title: string
  }
+  /** robots directives — set to noindex/follow for legal/thin/search pages. */
+  robots?: {
+    follow: boolean
+    index: boolean
+  }
  title: string
 }

@@ -39,6 +44,13 @@ type BuildMetadataArgs = {
  meta?: null | SeoMeta
  /** Page title or site name first. Defaults to 'page-first'. */
  order?: TitleOrder
+  /**
+   * The document's own title (e.g. page.title = 'Sprzątanie biur'). Used as the
+   * page-title source when meta.title is empty — the browser tab and search
+   * result should show the page name, not go blank, when an editor didn't fill
+   * the SEO title. Priority: titleOverride > meta.title > pageTitle.
+   */
+  pageTitle?: null | string
  /**
   * Localized segment the document lives under (an archive page's slugs).
   * Feeds both canonical and hreflang, so /pl/artykuly/moj-post and
@@ -78,16 +90,21 @@ export function buildMetadata({
  locale,
  meta,
  order,
+  pageTitle,
  prefix,
  query,
  separator,
  siteName,
  slugs,
 }: BuildMetadataArgs): PageMetadata {
-  // titleOverride wins outright: an editor who filled it in wants that exact
-  // string in the tab, not a composition.
+  // Title source priority: titleOverride (exact, wins outright) > meta.title
+  // (SEO title an editor set) > pageTitle (the document's own name). This means
+  // a page with no SEO title still shows its name (e.g. 'Sprzątanie biur')
+  // composed with the site name, instead of just the site name or a blank.
  const override = meta?.titleOverride?.trim()
-  const title = override || composeTitle({ order, pageTitle: meta?.title, separator, siteName })
+  const resolvedPageTitle = meta?.title?.trim() || pageTitle?.trim() || undefined
+  const title =
+    override || composeTitle({ order, pageTitle: resolvedPageTitle, separator, siteName })
  const description = meta?.description?.trim() || undefined
  const origin = baseUrl?.replace(/\/$/, '') ?? ''

@@ -118,5 +135,8 @@ export function buildMetadata({
      ...(images && { images }),
      locale,
    },
+    // noindex → tell search engines to exclude the page but still follow links
+    // (authority flows through). For legal/thin/search-result pages.
+    ...(meta?.noindex ? { robots: { follow: true, index: false } } : {}),
  }
 }
@@ -0,0 +1,44 @@
+type MediaLike = { url?: null | string } | null | undefined
+
+type OrganizationJsonLdArgs = {
+  /** Logo media (from panel). Google uses this for brand knowledge panels. */
+  logo?: MediaLike
+  /** Organization / site name. */
+  name: string
+  /** Optional social / official profile URLs (sameAs). */
+  sameAs?: string[]
+  /** Absolute site URL (https://…). */
+  url: string
+}
+
+/**
+ * Builds Organization JSON-LD (schema.org) — helps Google associate the site
+ * with a brand: name, logo, official links. Improves how the site appears in
+ * search (brand recognition, logo in knowledge panels) and is a signal used
+ * alongside favicon for identity.
+ *
+ * Returns a plain object; the project renders it as a <script type="application/
+ * ld+json"> in the root layout:
+ *
+ *   import { buildOrganizationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildOrganizationJsonLd({
+ *     name: settings.siteName, url: baseUrl, logo: settings.logo,
+ *   })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ *
+ * Data comes from the panel (siteName, logo) — nothing hardcoded. Emit once in
+ * the root layout (Organization is site-wide, not per page).
+ */
+export function buildOrganizationJsonLd({ name, logo, sameAs, url }: OrganizationJsonLdArgs) {
+  const logoUrl = logo?.url
+
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    url,
+    ...(logoUrl ? { logo: logoUrl.startsWith('http') ? logoUrl : `${url}${logoUrl}` } : {}),
+    ...(sameAs && sameAs.length > 0 ? { sameAs } : {}),
+  }
+}
@@ -0,0 +1,48 @@
+type ServiceJsonLdArgs = {
+  /** Area served, e.g. 'Wrocław' or ['Wrocław', 'Oława']. */
+  areaServed?: string | string[]
+  description?: string
+  /** Service name, e.g. 'Sprzątanie biur'. */
+  name: string
+  /** Provider (business) name. */
+  providerName: string
+  /** Service type / category. */
+  serviceType?: string
+  url: string
+}
+
+/**
+ * Builds Service JSON-LD (schema.org) for a service offering. Helps Google
+ * understand "what this page sells" — useful for service landing pages
+ * ("usługa + miasto"). Pairs well with LocalBusiness (the provider).
+ *
+ * Per-page (each service page emits its own), data from the panel:
+ *
+ *   import { buildServiceJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildServiceJsonLd({
+ *     name: page.serviceName, providerName: company.name,
+ *     url: pageUrl, areaServed: 'Wrocław',
+ *   })
+ */
+export function buildServiceJsonLd({
+  name,
+  areaServed,
+  description,
+  providerName,
+  serviceType,
+  url,
+}: ServiceJsonLdArgs) {
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'Service',
+    provider: {
+      name: providerName,
+      '@type': 'LocalBusiness',
+      url,
+    },
+    ...(description ? { description } : {}),
+    ...(areaServed ? { areaServed } : {}),
+    ...(serviceType ? { serviceType } : {}),
+  }
+}
@@ -0,0 +1,39 @@
+type NavItem = {
+  /** Visible label (e.g. 'Usługi'). */
+  name: string
+  /** Absolute URL (e.g. 'https://example.com/pl/uslugi'). */
+  url: string
+}
+
+/**
+ * Builds SiteNavigationElement JSON-LD (schema.org) from the main navigation —
+ * declares the site's primary nav as structured data. A weaker sitelinks signal
+ * than WebSite/breadcrumbs, but cheap: it tells Google which pages are the main
+ * navigation targets.
+ *
+ * Feed it the SAME nav items the header renders (from the panel/nav global), so
+ * the structured data matches the visible menu — not a separate hardcoded list.
+ *
+ *   import { buildSiteNavigationJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildSiteNavigationJsonLd(
+ *     navItems.map(i => ({ name: i.label, url: `${base}${i.href}` }))
+ *   )
+ *   <script type="application/ld+json" ... />
+ *
+ * Emit once (site-wide, root layout). Data from the nav source, never hardcoded.
+ * Returns null for empty nav.
+ */
+export function buildSiteNavigationJsonLd(items: NavItem[]) {
+  if (!items || items.length === 0) {return null}
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'ItemList',
+    itemListElement: items.map((item, index) => ({
+      name: item.name,
+      '@type': 'SiteNavigationElement',
+      position: index + 1,
+      url: item.url,
+    })),
+  }
+}
@@ -1,11 +1,10 @@
 import type { BasePayload } from 'payload'
-
-import type { ContentOption } from '../content/index.js'
 import type { I18nConfig } from '../i18n/index.js'
-
-import { archiveFieldName } from '../content/index.js'
-import { buildLocalizedPath, getLocalizedSlugs  } from '../i18n/index.js'
+import { getLocalizedSlugs } from '../i18n/index.js'
+import { buildLocalizedPath } from '../i18n/index.js'
 import { buildHreflangAlternates } from './hreflang.js'
+import type { ContentOption } from '../content/index.js'
+import { archiveFieldName } from '../content/index.js'

 /**
 * One sitemap entry, shaped for Next's `app/sitemap.ts`.
@@ -16,50 +15,70 @@ import { buildHreflangAlternates } from './hreflang.js'
 * is the common, weaker kind.
 */
 export type SitemapEntry = {
-  alternates?: { languages: Record<string, string> }
-  changeFrequency?: 'always' | 'daily' | 'hourly' | 'monthly' | 'never' | 'weekly' | 'yearly'
-  lastModified?: Date | string
-  priority?: number
  url: string
+  lastModified?: string | Date
+  changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
+  priority?: number
+  alternates?: { languages: Record<string, string> }
 }

 type CollectionEntry = {
+  slug: string
  /** Localized segment for entries (archive page slugs), when applicable. */
  prefixSlugs?: Record<string, string>
-  slug: string
 }

 type BuildSitemapArgs = {
+  payload: BasePayload
+  config: I18nConfig
  /** Absolute origin, e.g. 'https://example.com'. Required for valid sitemap URLs. */
  baseUrl: string
-  changeFrequency?: SitemapEntry['changeFrequency']
-  config: I18nConfig
+  /** Pages collection slug. Defaults to 'pages'. */
+  pagesSlug?: string
  /** Archive-backed collections, same value as the plugin option. */
  content?: ContentOption
+  /** SiteSettings global slug. Defaults to 'site-settings'. */
+  settingsSlug?: string
  /**
   * Slug of the page that is the site root (collapses to /{locale}).
   * Read from System Pages when omitted.
   */
  homeSlug?: string
-  /** Pages collection slug. Defaults to 'pages'. */
-  pagesSlug?: string
-  payload: BasePayload
-  /** SiteSettings global slug. Defaults to 'site-settings'. */
-  settingsSlug?: string
+  changeFrequency?: SitemapEntry['changeFrequency']
 }

 type DocRow = {
-  _status?: string
-  id: number | string
-  meta?: { noindex?: boolean } | null
+  id: string | number
  slug?: unknown
  updatedAt?: string
+  _status?: string
+  meta?: { noindex?: boolean } | null
 }

-/** Skip drafts and anything flagged noindex in the SEO tab. */
+/**
+ * Slugs that must never appear in the sitemap — error/system pages that exist as
+ * documents (e.g. a '404' page in the Pages collection) but should not be
+ * indexed. A sitemap should list only real, HTTP-200 content; a '/pl/404' entry
+ * is an audit finding. Matched against the slug in any locale.
+ */
+const EXCLUDED_SITEMAP_SLUGS = new Set(['404', '500', 'not-found', 'error'])
+
+/** True if the doc's slug (in any locale) is an excluded system/error slug. */
+function hasExcludedSlug(slug: unknown): boolean {
+  if (typeof slug === 'string') return EXCLUDED_SITEMAP_SLUGS.has(slug)
+  if (slug && typeof slug === 'object') {
+    for (const value of Object.values(slug as Record<string, unknown>)) {
+      if (typeof value === 'string' && EXCLUDED_SITEMAP_SLUGS.has(value)) return true
+    }
+  }
+  return false
+}
+
+/** Skip drafts, noindex, and system/error pages (404 etc.). */
 function isIndexable(doc: DocRow): boolean {
-  if (doc._status && doc._status !== 'published') {return false}
-  if (doc.meta?.noindex) {return false}
+  if (doc._status && doc._status !== 'published') return false
+  if (doc.meta?.noindex) return false
+  if (hasExcludedSlug(doc.slug)) return false
  return true
 }

@@ -77,17 +96,17 @@ function entryFor(
  homeSlug: string | undefined,
  prefix: Record<string, string> | undefined,
  changeFrequency: SitemapEntry['changeFrequency'],
-): null | SitemapEntry {
+): SitemapEntry | null {
  const slugs =
    doc.slug && typeof doc.slug === 'object'
-      ? getLocalizedSlugs({ config, slugField: doc.slug as Record<string, unknown> })
+      ? getLocalizedSlugs({ slugField: doc.slug as Record<string, unknown>, config })
      : {}

-  const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })
-  if (!path) {return null}
+  const path = buildLocalizedPath({ slugs, locale, config, homeSlug, prefix })
+  if (!path) return null

  const origin = baseUrl.replace(/\/$/, '')
-  const languages = buildHreflangAlternates({ baseUrl, config, homeSlug, prefix, slugs })
+  const languages = buildHreflangAlternates({ slugs, config, baseUrl, homeSlug, prefix })

  return {
    url: `${origin}${path}`,
@@ -119,14 +138,14 @@ function entryFor(
 * ```
 */
 export async function buildSitemapEntries({
-  baseUrl,
-  changeFrequency = 'weekly',
-  config,
-  content,
-  homeSlug,
-  pagesSlug = 'pages',
  payload,
+  config,
+  baseUrl,
+  pagesSlug = 'pages',
+  content,
  settingsSlug = 'site-settings',
+  homeSlug,
+  changeFrequency = 'weekly',
 }: BuildSitemapArgs): Promise<SitemapEntry[]> {
  const locales = config.locales.map((l) => l.code)
  const defaultLocale = config.defaultLocale
@@ -135,8 +154,8 @@ export async function buildSitemapEntries({
  // locales so archive prefixes are available per language).
  const settings = (await payload.findGlobal({
    slug: settingsSlug as never,
-    depth: 1,
    locale: 'all' as never,
+    depth: 1,
  })) as Record<string, unknown>

  const resolvedHomeSlug =
@@ -159,14 +178,14 @@ export async function buildSitemapEntries({
    // alternates without re-querying per locale.
    const result = await payload.find({
      collection: collection.slug as never,
+      locale: 'all' as never,
      depth: 0,
      limit: 0, // no pagination — sitemap wants everything
-      locale: 'all' as never,
      pagination: false as never,
    })

    for (const raw of result.docs as DocRow[]) {
-      if (!isIndexable(raw)) {continue}
+      if (!isIndexable(raw)) continue

      // Emit the entry under the default locale's URL; alternates cover the rest.
      const entry = entryFor(
@@ -178,7 +197,7 @@ export async function buildSitemapEntries({
        collection.prefixSlugs,
        changeFrequency,
      )
-      if (entry) {entries.push(entry)}
+      if (entry) entries.push(entry)
    }
  }

@@ -187,9 +206,9 @@ export async function buildSitemapEntries({

 /** Pulls a slug string from a populated relationship in a specific locale. */
 function extractSlugInLocale(rel: unknown, locale: string): string | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
  const slug = (rel as { slug?: unknown }).slug
-  if (typeof slug === 'string') {return slug}
+  if (typeof slug === 'string') return slug
  if (slug && typeof slug === 'object') {
    const v = (slug as Record<string, unknown>)[locale]
    return typeof v === 'string' ? v : undefined
@@ -199,14 +218,14 @@ function extractSlugInLocale(rel: unknown, locale: string): string | undefined {

 /** Builds a locale→slug map from a populated archive relationship. */
 function slugMapAllLocales(rel: unknown, locales: string[]): Record<string, string> | undefined {
-  if (!rel || typeof rel !== 'object') {return undefined}
+  if (!rel || typeof rel !== 'object') return undefined
  const slug = (rel as { slug?: unknown }).slug
-  if (!slug || typeof slug !== 'object') {return undefined}
+  if (!slug || typeof slug !== 'object') return undefined

  const map: Record<string, string> = {}
  for (const locale of locales) {
    const v = (slug as Record<string, unknown>)[locale]
-    if (typeof v === 'string') {map[locale] = v}
+    if (typeof v === 'string') map[locale] = v
  }
  return Object.keys(map).length ? map : undefined
 }
@@ -0,0 +1,62 @@
+type SearchActionConfig = {
+  /**
+   * URL template for site search, with {search_term_string} placeholder.
+   * e.g. 'https://example.com/szukaj?q={search_term_string}'. Only include if
+   * the site actually HAS a working search page — a SearchAction pointing at a
+   * non-existent search does more harm than good.
+   */
+  target: string
+}
+
+type WebSiteJsonLdArgs = {
+  /** Site name (from panel — siteName). */
+  name: string
+  /**
+   * Optional site search. Enables the "sitelinks searchbox" — a search field
+   * Google may show under the brand result. Only pass when a real search page
+   * exists. Omit entirely otherwise.
+   */
+  search?: SearchActionConfig
+  /** Absolute site URL (https://…). */
+  url: string
+}
+
+/**
+ * Builds WebSite JSON-LD (schema.org). Two jobs:
+ *  - Declares the site + name (helps Google associate brand queries with the site).
+ *  - Optionally declares a SearchAction, which is what can produce the "sitelinks
+ *    searchbox" (a search field under the brand result in Google).
+ *
+ * IMPORTANT — sitelinks (the sub-links under a result) CANNOT be forced. No
+ * schema guarantees them; Google generates them algorithmically from site
+ * structure, internal links, clear titles, and ranking. This schema is a SIGNAL
+ * that improves the odds and can enable the searchbox — not a switch. Manage
+ * expectations accordingly (see docs/seo.md).
+ *
+ * Emit once in the ROOT layout (site-wide), from panel data:
+ *
+ *   import { buildWebSiteJsonLd } from '@intecion/ipal-kit'
+ *   const jsonLd = buildWebSiteJsonLd({ name: settings.siteName, url: baseUrl })
+ *   <script type="application/ld+json"
+ *     dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
+ */
+export function buildWebSiteJsonLd({ name, search, url }: WebSiteJsonLdArgs) {
+  return {
+    name,
+    '@context': 'https://schema.org',
+    '@type': 'WebSite',
+    url,
+    ...(search
+      ? {
+          potentialAction: {
+            '@type': 'SearchAction',
+            'query-input': 'required name=search_term_string',
+            target: {
+              '@type': 'EntryPoint',
+              urlTemplate: search.target,
+            },
+          },
+        }
+      : {}),
+  }
+}
@@ -43,6 +43,8 @@ type PageMetadataContext = {
 type DocShape = {
  id: number | string
  meta?: null | SeoMeta
+  /** The document's own title (page name), used as the fallback page title. */
+  title?: null | string
 }

 /** plugin-seo stores the OG image as an upload relationship. */
@@ -151,6 +153,7 @@ export function createPageMetadata(args: CreatePageMetadataArgs) {
      ...base,
      imageUrl: resolveOgImage(doc),
      meta: doc.meta,
+      pageTitle: doc.title,
      prefix,
      query,
      slugs,
@@ -1,11 +1,12 @@
 import type { I18nConfig, LocalizedSlugs } from '../i18n/index.js'
-
 import { buildLocalizedPath, getLocaleCodes } from '../i18n/index.js'

 type BuildHreflangArgs = {
+  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */
+  slugs: LocalizedSlugs
+  config: I18nConfig
  /** Absolute site origin, e.g. 'https://example.com'. Omit for relative paths. */
  baseUrl?: string
-  config: I18nConfig
  /** Home slug that collapses to the locale root. Defaults to 'home'. */
  homeSlug?: string
  /**
@@ -14,8 +15,6 @@ type BuildHreflangArgs = {
   * are omitted — an entry with no archive in that language has no URL there.
   */
  prefix?: LocalizedSlugs
-  /** slug per locale for the current document, e.g. { pl: 'o-nas', en: 'about' } */
-  slugs: LocalizedSlugs
 }

 /**
@@ -35,21 +34,39 @@ type BuildHreflangArgs = {
 * // → { pl: 'https://example.com/pl/o-nas', en: 'https://example.com/en/about' }
 */
 export function buildHreflangAlternates({
-  baseUrl,
+  slugs,
  config,
+  baseUrl,
  homeSlug = 'home',
  prefix,
-  slugs,
 }: BuildHreflangArgs): Record<string, string> {
  const origin = baseUrl?.replace(/\/$/, '') ?? ''
  const alternates: Record<string, string> = {}

+  // Single-locale sites have no language alternatives — hreflang describes
+  // relationships BETWEEN language versions, and there's only one. Emitting
+  // hreflang (or x-default) here would be wrong, so return empty: the page keeps
+  // its canonical, but no alternate-language links.
+  if (config.locales.length === 1) {
+    return alternates
+  }
+
  for (const locale of getLocaleCodes(config)) {
-    const path = buildLocalizedPath({ config, homeSlug, locale, prefix, slugs })
+    const path = buildLocalizedPath({ slugs, locale, config, homeSlug, prefix })
    if (path) {
      alternates[locale] = `${origin}${path}`
    }
  }

+  // x-default: the version Google serves when the user's language/region doesn't
+  // match any hreflang — and, crucially here, the fallback when the root ('/')
+  // redirect is ambiguous (Googlebot with no/foreign Accept-Language). Point it
+  // at the default locale (the primary market) so search shows that version by
+  // default instead of guessing. Only set when the default locale has a URL.
+  const defaultLocalePath = alternates[config.defaultLocale]
+  if (defaultLocalePath) {
+    alternates['x-default'] = defaultLocalePath
+  }
+
  return alternates
 }
@@ -1,11 +1,19 @@
 export { buildAutoFillMetaHook } from './autoFillMeta.js'
 export type { AutoFillMapping } from './autoFillMeta.js'
+export { buildBreadcrumbJsonLd } from './buildBreadcrumbJsonLd.js'
+export { buildFaqJsonLd } from './buildFaqJsonLd.js'
+export { buildIconsMetadata } from './buildIconsMetadata.js'
+export { buildLocalBusinessJsonLd } from './buildLocalBusinessJsonLd.js'
 export { buildMetadata } from './buildMetadata.js'
 export type { PageMetadata } from './buildMetadata.js'
+export { buildOrganizationJsonLd } from './buildOrganizationJsonLd.js'
 export { buildRobots } from './buildRobots.js'
 export type { RobotsRules } from './buildRobots.js'
+export { buildServiceJsonLd } from './buildServiceJsonLd.js'
 export { buildSitemapEntries } from './buildSitemapEntries.js'
 export type { SitemapEntry } from './buildSitemapEntries.js'
+export { buildSiteNavigationJsonLd } from './buildSiteNavigationJsonLd.js'
+export { buildWebSiteJsonLd } from './buildWebSiteJsonLd.js'
 export { composeTitle } from './composeTitle.js'
 export type { TitleOrder } from './composeTitle.js'
 export { createMetadataGenerator } from './createMetadataGenerator.js'
@@ -18,3 +26,4 @@ export type { SiteMetaConfig } from './readSiteMetaConfig.js'
 export { buildSeoPlugin } from './seoPluginConfig.js'
 export { slugsAcrossLocales } from './slugsAcrossLocales.js'
 export type { SeoMeta, SeoOption } from './types.js'
+export { validateFaviconField } from './validateFavicon.js'
@@ -33,6 +33,7 @@ export type SeoOption = {
 export type SeoMeta = {
  description?: null | string
  image?: unknown
+  noindex?: boolean | null
  title?: null | string
  /** When set, used as the whole title — no site name, no separator. */
  titleOverride?: null | string
@@ -0,0 +1,52 @@
+import type { FieldHook } from 'payload'
+
+/**
+ * Field validation for the favicon upload: Google rejects favicons under 48×48,
+ * so warn the editor at save time if the uploaded icon is too small or not
+ * square. This ENFORCES the requirement instead of silently shipping a favicon
+ * Google won't display.
+ *
+ * Attach to the favicon field's validate (or as a beforeValidate hook on the
+ * Media relationship). Non-blocking by default — returns a warning string that
+ * Payload surfaces; make it throw if you want a hard block.
+ *
+ * Note: dimensions come from the related Media doc (Payload stores width/height
+ * for image uploads), so this checks the resolved upload, not the raw file.
+ */
+export const validateFaviconField: FieldHook = async ({ req, value }) => {
+  if (!value) {return value} // no favicon set → nothing to validate (optional field)
+
+  try {
+    const media = await req.payload.findByID({
+      id: typeof value === 'object' ? (value as { id: string }).id : value,
+      collection: 'media',
+      depth: 0,
+    })
+
+    const width = (media as { width?: number }).width
+    const height = (media as { height?: number }).height
+    const mimeType = (media as { mimeType?: string }).mimeType
+
+    // SVG scales infinitely — skip size checks.
+    if (mimeType === 'image/svg+xml') {return value}
+
+    if (typeof width === 'number' && typeof height === 'number') {
+      if (width < 48 || height < 48) {
+        req.payload.logger.warn(
+          `[ipal] Favicon is ${width}×${height}px. Google requires ≥48×48 to ` +
+            `display it in search results. Upload a larger square icon (96 or 192px).`,
+        )
+      }
+      if (width !== height) {
+        req.payload.logger.warn(
+          `[ipal] Favicon is not square (${width}×${height}). Use a square icon ` +
+            `so it isn't cropped in the browser tab or search results.`,
+        )
+      }
+    }
+  } catch {
+    // Media lookup failed — don't block the save over a validation warning.
+  }
+
+  return value
+}
Author	SHA1	Message	Date
radoslaw.smolinski	db2ac80a1e	1.2.4	2026-09-09 00:06:27 +02:00
radoslaw.smolinski	99490bfc4d	Updated docs	2026-09-09 00:06:18 +02:00
radoslaw.smolinski	fce17654f8	1.2.3	2026-09-08 18:13:16 +02:00
radoslaw.smolinski	419207ac12	Added support for single localization	2026-09-08 18:12:58 +02:00
radoslaw.smolinski	e30ac71044	1.2.2	2026-09-08 14:25:26 +02:00
radoslaw.smolinski	781e348ded	Page title generator on browser tab rebuilded.	2026-09-08 14:25:15 +02:00
radoslaw.smolinski	e16a18e488	1.2.1	2026-09-08 13:14:15 +02:00
radoslaw.smolinski	7cd3cbaae5	1.2.0: local SEO structured data (LocalBusiness, Service, FAQPage), noindex per page, exclude 404 from sitemap, robots param docs	2026-09-08 13:14:05 +02:00
radoslaw.smolinski	60f07fddc9	1.2.0	2026-09-08 12:49:49 +02:00
radoslaw.smolinski	068415849f	1.2.0: local SEO structured data (LocalBusiness, Service, FAQPage), noindex per page	2026-09-08 12:49:49 +02:00
radoslaw.smolinski	e39e2a361a	1.1.2	2026-08-28 15:51:02 +02:00
radoslaw.smolinski	9d3e749c38	1.1.1	2026-08-28 15:50:42 +02:00
radoslaw.smolinski	b7c6cb4d81	1.1.0	2026-08-28 15:50:29 +02:00
radoslaw.smolinski	c41b75e364	1.1.0: R2 storage, media preconnect/normalization, favicon + SEO structured data, x-default hreflang	2026-08-28 15:50:25 +02:00
radoslaw.smolinski	41630bb8c5	1.1.1	2026-08-28 00:09:20 +02:00
radoslaw.smolinski	b9430e7ab6	SEO: favicon metadata, Organization JSON-LD, favicon validation; R2 media (preconnect, generateFileURL per-collection), filename normalization	2026-08-28 00:08:35 +02:00
				`@@ -0,0 +1 @@`
				{"version":3,"sources":["../../../src/modules/seo/buildBreadcrumbJsonLd.ts"],"sourcesContent":["type Crumb = {\n /** Visible name of the breadcrumb (e.g. 'Usługi'). /\n name: string\n /* Absolute URL of this crumb (e.g. 'https://example.com/pl/uslugi'). /\n url: string\n}\n\n/\n Builds BreadcrumbList JSON-LD (schema.org) for a page's position in the site\n * hierarchy. Google can show breadcrumbs in the result (Dom › Usługi › Detailing)\n * and uses them to understand structure — a signal that helps navigational\n * results and sitelinks.\n \n Unlike Organization/WebSite (site-wide, root layout), breadcrumbs are\n * PER-PAGE — build them from the page's ancestry and emit on that page:\n \n import { buildBreadcrumbJsonLd } from '@intecion/ipal-kit'\n * const jsonLd = buildBreadcrumbJsonLd([\n * { name: 'Strona główna', url: `${base}/pl` },\n * { name: 'Usługi', url: `${base}/pl/uslugi` },\n * { name: 'Detailing', url: `${base}/pl/uslugi/detailing` },\n * ])\n * <script type=\"application/ld+json\" ... />\n \n The crumb data comes from the page's real position (parent pages / URL path),\n * NOT hardcoded. Derive it from the resolved route, not a static list.\n \n Returns null for an empty/single crumb list — a one-item breadcrumb isn't\n * meaningful and shouldn't be emitted.\n */\nexport function buildBreadcrumbJsonLd(crumbs: Crumb[]) {\n if (!crumbs \|\| crumbs.length < 2) {return null}\n\n return {\n '@context': 'https://schema.org',\n '@type': 'BreadcrumbList',\n itemListElement: crumbs.map((crumb, index) => ({\n name: crumb.name,\n '@type': 'ListItem',\n item: crumb.url,\n position: index + 1,\n })),\n }\n}\n"],"names":["buildBreadcrumbJsonLd","crumbs","length","itemListElement","map","crumb","index","name","item","url","position"],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,SAASA,sBAAsBC,MAAe;IACnD,IAAI,CAACA,UAAUA,OAAOC,MAAM,GAAG,GAAG;QAAC,OAAO;IAAI;IAE9C,OAAO;QACL,YAAY;QACZ,SAAS;QACTC,iBAAiBF,OAAOG,GAAG,CAAC,CAACC,OAAOC,QAAW,CAAA;gBAC7CC,MAAMF,MAAME,IAAI;gBAChB,SAAS;gBACTC,MAAMH,MAAMI,GAAG;gBACfC,UAAUJ,QAAQ;YACpB,CAAA;IACF;AACF"}