@lynxflow/seo-engine 1.5.6 → 1.5.8

package/dist/built-in-locations.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 🌍 Built-in Global Geographic & Demographic Database
+ * Automatically provisions verified cities, populations, currencies, and coordinates
+ * across Europe, North America, and international markets without requiring the user to list cities manually.
+ */
+import { PseoLocation } from "./matrix-engine";
+export declare const BUILT_IN_LOCATIONS_DATABASE: Record<string, PseoLocation[]>;
+/**
+ * Resolves built-in locations by country code or territory keyword.
+ * Supports: "fr", "france", "es", "spain", "de", "germany", "uk", "us", "be", "ch", "it", "ca", "europe", "international", "all"
+ */
+export declare function resolveBuiltInLocations(territories?: string[] | string): PseoLocation[];

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./engine";
 export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
+export * from "./built-in-locations";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/dist/index.js

@@ -40,6 +40,7 @@ var __export = (target, all) => {
 var exports_src = {};
 __export(exports_src, {
   validateSeoSlug: () => validateSeoSlug,
+  resolveBuiltInLocations: () => resolveBuiltInLocations,
   resolveBrandIcon: () => resolveBrandIcon,
   renderBrandIconSvg: () => renderBrandIconSvg,
   getSeoAgentPrompt: () => getSeoAgentPrompt,
@@ -93,6 +94,7 @@ __export(exports_src, {
   CopywritingFrameworksMaster: () => CopywritingFrameworksMaster,
   BrandDnaCalendarEngine: () => BrandDnaCalendarEngine,
   BacklinksClient: () => BacklinksClient,
+  BUILT_IN_LOCATIONS_DATABASE: () => BUILT_IN_LOCATIONS_DATABASE,
   BRAND_ICONS: () => BRAND_ICONS,
   ApiKeyGuardian: () => ApiKeyGuardian,
   AiCopilotClient: () => AiCopilotClient,
@@ -3190,6 +3192,150 @@ class ExtendedSchemaGraphBuilder {
   }
 }
 
+// src/built-in-locations.ts
+var BUILT_IN_LOCATIONS_DATABASE = {
+  fr: [
+    { slug: "paris", name: "Paris", region: "Île-de-France", country: "France", population: 2161000, currency: "EUR", currencySymbol: "€", latitude: 48.8566, longitude: 2.3522, neighborSlugs: ["boulogne-billancourt", "saint-denis", "montreuil"] },
+    { slug: "marseille", name: "Marseille", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 873000, currency: "EUR", currencySymbol: "€", latitude: 43.2965, longitude: 5.3698, neighborSlugs: ["aix-en-provence", "aubagne", "toulon"] },
+    { slug: "lyon", name: "Lyon", region: "Auvergne-Rhône-Alpes", country: "France", population: 522000, currency: "EUR", currencySymbol: "€", latitude: 45.764, longitude: 4.8357, neighborSlugs: ["villeurbanne", "venissieux", "saint-etienne"] },
+    { slug: "toulouse", name: "Toulouse", region: "Occitanie", country: "France", population: 498000, currency: "EUR", currencySymbol: "€", latitude: 43.6047, longitude: 1.4442, neighborSlugs: ["montauban", "albi", "colomiers"] },
+    { slug: "nice", name: "Nice", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 343000, currency: "EUR", currencySymbol: "€", latitude: 43.7102, longitude: 7.262, neighborSlugs: ["cannes", "antibes", "monaco"] },
+    { slug: "nantes", name: "Nantes", region: "Pays de la Loire", country: "France", population: 320000, currency: "EUR", currencySymbol: "€", latitude: 47.2184, longitude: -1.5536, neighborSlugs: ["saint-nazaire", "angers", "rennes"] },
+    { slug: "montpellier", name: "Montpellier", region: "Occitanie", country: "France", population: 299000, currency: "EUR", currencySymbol: "€", latitude: 43.6108, longitude: 3.8767, neighborSlugs: ["nimes", "beziers", "sete"] },
+    { slug: "strasbourg", name: "Strasbourg", region: "Grand Est", country: "France", population: 290000, currency: "EUR", currencySymbol: "€", latitude: 48.5734, longitude: 7.7521, neighborSlugs: ["mulhouse", "colmar", "metz"] },
+    { slug: "bordeaux", name: "Bordeaux", region: "Nouvelle-Aquitaine", country: "France", population: 260000, currency: "EUR", currencySymbol: "€", latitude: 44.8378, longitude: -0.5792, neighborSlugs: ["merignac", "pessac", "arcachon"] },
+    { slug: "lille", name: "Lille", region: "Hauts-de-France", country: "France", population: 236000, currency: "EUR", currencySymbol: "€", latitude: 50.6292, longitude: 3.0573, neighborSlugs: ["roubaix", "tourcoing", "villeneuve-d-ascq"] },
+    { slug: "rennes", name: "Rennes", region: "Bretagne", country: "France", population: 222000, currency: "EUR", currencySymbol: "€", latitude: 48.1173, longitude: -1.6778, neighborSlugs: ["saint-malo", "brest", "nantes"] },
+    { slug: "toulon", name: "Toulon", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 179000, currency: "EUR", currencySymbol: "€", latitude: 43.1242, longitude: 5.928, neighborSlugs: ["hyeres", "la-seyne-sur-mer", "marseille"] },
+    { slug: "reims", name: "Reims", region: "Grand Est", country: "France", population: 179000, currency: "EUR", currencySymbol: "€", latitude: 49.2583, longitude: 4.0317, neighborSlugs: ["chalons-en-champagne", "troyes", "metz"] },
+    { slug: "saint-etienne", name: "Saint-Étienne", region: "Auvergne-Rhône-Alpes", country: "France", population: 174000, currency: "EUR", currencySymbol: "€", latitude: 45.4397, longitude: 4.3872, neighborSlugs: ["lyon", "roanne", "saint-chamond"] },
+    { slug: "le-havre", name: "Le Havre", region: "Normandie", country: "France", population: 166000, currency: "EUR", currencySymbol: "€", latitude: 49.4944, longitude: 0.1079, neighborSlugs: ["rouen", "caen", "honfleur"] },
+    { slug: "grenoble", name: "Grenoble", region: "Auvergne-Rhône-Alpes", country: "France", population: 158000, currency: "EUR", currencySymbol: "€", latitude: 45.1885, longitude: 5.7245, neighborSlugs: ["echirolles", "chambery", "annecy"] },
+    { slug: "dijon", name: "Dijon", region: "Bourgogne-Franche-Comté", country: "France", population: 159000, currency: "EUR", currencySymbol: "€", latitude: 47.322, longitude: 5.0415, neighborSlugs: ["besancon", "chalon-sur-saone", "beaune"] },
+    { slug: "angers", name: "Angers", region: "Pays de la Loire", country: "France", population: 155000, currency: "EUR", currencySymbol: "€", latitude: 47.4784, longitude: -0.5632, neighborSlugs: ["saumur", "cholet", "nantes"] },
+    { slug: "villeurbanne", name: "Villeurbanne", region: "Auvergne-Rhône-Alpes", country: "France", population: 154000, currency: "EUR", currencySymbol: "€", latitude: 45.7667, longitude: 4.8833, neighborSlugs: ["lyon", "bron", "caluire-et-cuire"] },
+    { slug: "nimes", name: "Nîmes", region: "Occitanie", country: "France", population: 148000, currency: "EUR", currencySymbol: "€", latitude: 43.8367, longitude: 4.3601, neighborSlugs: ["montpellier", "avignon", "arles"] },
+    { slug: "aix-en-provence", name: "Aix-en-Provence", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 147000, currency: "EUR", currencySymbol: "€", latitude: 43.5297, longitude: 5.4474, neighborSlugs: ["marseille", "gardanne", "salon-de-provence"] },
+    { slug: "clermont-ferrand", name: "Clermont-Ferrand", region: "Auvergne-Rhône-Alpes", country: "France", population: 147000, currency: "EUR", currencySymbol: "€", latitude: 45.7772, longitude: 3.087, neighborSlugs: ["riom", "cournon-d-auvergne", "vichy"] },
+    { slug: "brest", name: "Brest", region: "Bretagne", country: "France", population: 139000, currency: "EUR", currencySymbol: "€", latitude: 48.3904, longitude: -4.4861, neighborSlugs: ["quimper", "morlaix", "rennes"] },
+    { slug: "tours", name: "Tours", region: "Centre-Val de Loire", country: "France", population: 137000, currency: "EUR", currencySymbol: "€", latitude: 47.3941, longitude: 0.6848, neighborSlugs: ["orleans", "blois", "angers"] },
+    { slug: "amiens", name: "Amiens", region: "Hauts-de-France", country: "France", population: 134000, currency: "EUR", currencySymbol: "€", latitude: 49.8941, longitude: 2.2958, neighborSlugs: ["beauvais", "compiegne", "lille"] },
+    { slug: "annecy", name: "Annecy", region: "Auvergne-Rhône-Alpes", country: "France", population: 131000, currency: "EUR", currencySymbol: "€", latitude: 45.8992, longitude: 6.1294, neighborSlugs: ["chambery", "geneve", "grenoble"] }
+  ],
+  es: [
+    { slug: "madrid", name: "Madrid", region: "Comunidad de Madrid", country: "Spain", population: 3300000, currency: "EUR", currencySymbol: "€", latitude: 40.4168, longitude: -3.7038, neighborSlugs: ["alcala-de-henares", "mostoles", "getafe"] },
+    { slug: "barcelona", name: "Barcelona", region: "Catalunya", country: "Spain", population: 1636000, currency: "EUR", currencySymbol: "€", latitude: 41.3851, longitude: 2.1734, neighborSlugs: ["hospitalet-de-llobregat", "badalona", "terrassa"] },
+    { slug: "valencia", name: "Valencia", region: "Comunitat Valenciana", country: "Spain", population: 800000, currency: "EUR", currencySymbol: "€", latitude: 39.4699, longitude: -0.3763, neighborSlugs: ["alicante", "castellon-de-la-plana", "gandia"] },
+    { slug: "sevilla", name: "Sevilla", region: "Andalucía", country: "Spain", population: 688000, currency: "EUR", currencySymbol: "€", latitude: 37.3891, longitude: -5.9845, neighborSlugs: ["cordoba", "huelva", "cadiz"] },
+    { slug: "zaragoza", name: "Zaragoza", region: "Aragón", country: "Spain", population: 675000, currency: "EUR", currencySymbol: "€", latitude: 41.6488, longitude: -0.8891, neighborSlugs: ["huesca", "teruel", "madrid"] },
+    { slug: "malaga", name: "Málaga", region: "Andalucía", country: "Spain", population: 579000, currency: "EUR", currencySymbol: "€", latitude: 36.7213, longitude: -4.4214, neighborSlugs: ["marbella", "torremolinos", "granada"] },
+    { slug: "bilbao", name: "Bilbao", region: "País Vasco", country: "Spain", population: 346000, currency: "EUR", currencySymbol: "€", latitude: 43.263, longitude: -2.935, neighborSlugs: ["san-sebastian", "vitoria-gasteiz", "santander"] }
+  ],
+  de: [
+    { slug: "berlin", name: "Berlin", region: "Berlin", country: "Germany", population: 3645000, currency: "EUR", currencySymbol: "€", latitude: 52.52, longitude: 13.405, neighborSlugs: ["potsdam", "cottbus", "brandenburg"] },
+    { slug: "hamburg", name: "Hamburg", region: "Hamburg", country: "Germany", population: 1841000, currency: "EUR", currencySymbol: "€", latitude: 53.5511, longitude: 9.9937, neighborSlugs: ["luebeck", "bremen", "kiel"] },
+    { slug: "muenchen", name: "München", region: "Bayern", country: "Germany", population: 1472000, currency: "EUR", currencySymbol: "€", latitude: 48.1351, longitude: 11.582, neighborSlugs: ["augsburg", "ingolstadt", "rosenheim"] },
+    { slug: "koeln", name: "Köln", region: "Nordrhein-Westfalen", country: "Germany", population: 1086000, currency: "EUR", currencySymbol: "€", latitude: 50.9375, longitude: 6.9603, neighborSlugs: ["duesseldorf", "bonn", "leverkusen"] },
+    { slug: "frankfurt", name: "Frankfurt am Main", region: "Hessen", country: "Germany", population: 753000, currency: "EUR", currencySymbol: "€", latitude: 50.1109, longitude: 8.6821, neighborSlugs: ["wiesbaden", "mainz", "darmstadt"] },
+    { slug: "stuttgart", name: "Stuttgart", region: "Baden-Württemberg", country: "Germany", population: 635000, currency: "EUR", currencySymbol: "€", latitude: 48.7758, longitude: 9.1829, neighborSlugs: ["esslingen", "ludwigsburg", "karlsruhe"] }
+  ],
+  uk: [
+    { slug: "london", name: "London", region: "Greater London", country: "United Kingdom", population: 8982000, currency: "GBP", currencySymbol: "£", latitude: 51.5074, longitude: -0.1278, neighborSlugs: ["croydon", "watford", "reading"] },
+    { slug: "birmingham", name: "Birmingham", region: "West Midlands", country: "United Kingdom", population: 1149000, currency: "GBP", currencySymbol: "£", latitude: 52.4862, longitude: -1.8904, neighborSlugs: ["coventry", "wolverhampton", "solihull"] },
+    { slug: "manchester", name: "Manchester", region: "Greater Manchester", country: "United Kingdom", population: 553000, currency: "GBP", currencySymbol: "£", latitude: 53.4808, longitude: -2.2426, neighborSlugs: ["salford", "bolton", "stockport"] },
+    { slug: "edinburgh", name: "Edinburgh", region: "Scotland", country: "United Kingdom", population: 527000, currency: "GBP", currencySymbol: "£", latitude: 55.9533, longitude: -3.1883, neighborSlugs: ["glasgow", "livingston", "dundee"] }
+  ],
+  us: [
+    { slug: "new-york", name: "New York", region: "NY", country: "United States", population: 8336000, currency: "USD", currencySymbol: "$", latitude: 40.7128, longitude: -74.006, neighborSlugs: ["brooklyn", "queens", "jersey-city"] },
+    { slug: "los-angeles", name: "Los Angeles", region: "CA", country: "United States", population: 3979000, currency: "USD", currencySymbol: "$", latitude: 34.0522, longitude: -118.2437, neighborSlugs: ["long-beach", "pasadena", "glendale"] },
+    { slug: "chicago", name: "Chicago", region: "IL", country: "United States", population: 2693000, currency: "USD", currencySymbol: "$", latitude: 41.8781, longitude: -87.6298, neighborSlugs: ["evanston", "naperville", "aurora"] },
+    { slug: "houston", name: "Houston", region: "TX", country: "United States", population: 2320000, currency: "USD", currencySymbol: "$", latitude: 29.7604, longitude: -95.3698, neighborSlugs: ["the-woodlands", "sugar-land", "katy"] },
+    { slug: "miami", name: "Miami", region: "FL", country: "United States", population: 442000, currency: "USD", currencySymbol: "$", latitude: 25.7617, longitude: -80.1918, neighborSlugs: ["fort-lauderdale", "miami-beach", "hialeah"] },
+    { slug: "san-francisco", name: "San Francisco", region: "CA", country: "United States", population: 873000, currency: "USD", currencySymbol: "$", latitude: 37.7749, longitude: -122.4194, neighborSlugs: ["oakland", "san-jose", "berkeley"] }
+  ],
+  be: [
+    { slug: "bruxelles", name: "Bruxelles", region: "Bruxelles-Capitale", country: "Belgium", population: 1220000, currency: "EUR", currencySymbol: "€", latitude: 50.8503, longitude: 4.3517, neighborSlugs: ["anvers", "gand", "liege"] },
+    { slug: "anvers", name: "Anvers", region: "Flandre", country: "Belgium", population: 530000, currency: "EUR", currencySymbol: "€", latitude: 51.2194, longitude: 4.4025, neighborSlugs: ["bruxelles", "malines", "gand"] },
+    { slug: "liege", name: "Liège", region: "Wallonie", country: "Belgium", population: 197000, currency: "EUR", currencySymbol: "€", latitude: 50.6326, longitude: 5.5797, neighborSlugs: ["namur", "charleroi", "bruxelles"] }
+  ],
+  ch: [
+    { slug: "zurich", name: "Zürich", region: "Zürich", country: "Switzerland", population: 434000, currency: "CHF", currencySymbol: "CHF", latitude: 47.3769, longitude: 8.5417, neighborSlugs: ["bale", "berne", "lucerne"] },
+    { slug: "geneve", name: "Genève", region: "Genève", country: "Switzerland", population: 203000, currency: "EUR", currencySymbol: "CHF", latitude: 46.2044, longitude: 6.1432, neighborSlugs: ["lausanne", "annecy", "nyon"] },
+    { slug: "lausanne", name: "Lausanne", region: "Vaud", country: "Switzerland", population: 140000, currency: "CHF", currencySymbol: "CHF", latitude: 46.5197, longitude: 6.6323, neighborSlugs: ["geneve", "montreux", "vevey"] }
+  ],
+  it: [
+    { slug: "roma", name: "Roma", region: "Lazio", country: "Italy", population: 2873000, currency: "EUR", currencySymbol: "€", latitude: 41.9028, longitude: 12.4964, neighborSlugs: ["latina", "fiumicino", "tivoli"] },
+    { slug: "milano", name: "Milano", region: "Lombardia", country: "Italy", population: 1366000, currency: "EUR", currencySymbol: "€", latitude: 45.4642, longitude: 9.19, neighborSlugs: ["monza", "bergamo", "brescia"] },
+    { slug: "torino", name: "Torino", region: "Piemonte", country: "Italy", population: 870000, currency: "EUR", currencySymbol: "€", latitude: 45.0703, longitude: 7.6869, neighborSlugs: ["novara", "alessandria", "asti"] }
+  ],
+  ca: [
+    { slug: "toronto", name: "Toronto", region: "ON", country: "Canada", population: 2794000, currency: "CAD", currencySymbol: "$", latitude: 43.6532, longitude: -79.3832, neighborSlugs: ["mississauga", "brampton", "markham"] },
+    { slug: "montreal", name: "Montréal", region: "QC", country: "Canada", population: 1762000, currency: "CAD", currencySymbol: "$", latitude: 45.5017, longitude: -73.5673, neighborSlugs: ["laval", "longueuil", "quebec"] },
+    { slug: "vancouver", name: "Vancouver", region: "BC", country: "Canada", population: 662000, currency: "CAD", currencySymbol: "$", latitude: 49.2827, longitude: -123.1207, neighborSlugs: ["burnaby", "richmond", "surrey"] }
+  ]
+};
+function resolveBuiltInLocations(territories) {
+  if (!territories) {
+    return [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  }
+  const requested = (Array.isArray(territories) ? territories : [territories]).map((t) => t.toLowerCase().trim());
+  const results = [];
+  const addedSlugs = new Set;
+  const isAllOrEurope = requested.some((t) => ["europe", "international", "all", "global", "world"].includes(t));
+  if (isAllOrEurope) {
+    for (const list of Object.values(BUILT_IN_LOCATIONS_DATABASE)) {
+      for (const loc of list) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+    return results;
+  }
+  const countryAliasMap = {
+    france: "fr",
+    fr: "fr",
+    spain: "es",
+    espagne: "es",
+    es: "es",
+    germany: "de",
+    allemagne: "de",
+    de: "de",
+    uk: "uk",
+    gb: "uk",
+    "united kingdom": "uk",
+    angleterre: "uk",
+    us: "us",
+    usa: "us",
+    "united states": "us",
+    etatsunis: "us",
+    belgium: "be",
+    belgique: "be",
+    be: "be",
+    switzerland: "ch",
+    suisse: "ch",
+    ch: "ch",
+    italy: "it",
+    italie: "it",
+    it: "it",
+    canada: "ca",
+    ca: "ca"
+  };
+  for (const req of requested) {
+    const code = countryAliasMap[req.replace(/[^a-z0-9]/g, "")];
+    if (code && BUILT_IN_LOCATIONS_DATABASE[code]) {
+      for (const loc of BUILT_IN_LOCATIONS_DATABASE[code]) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+  }
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+}
+
 // src/matrix-engine.ts
 class PseoMatrixEngine {
   legalEngine;
@@ -3272,7 +3418,7 @@ class PseoMatrixEngine {
         const countryCode = cleanSeoSlug(loc.country, { language: lang });
         const citySlug = cleanSeoSlug(loc.slug, { language: lang });
         const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
-        const urlPath = `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
+        const urlPath = options.cleanDirectRoutes !== false ? `/${serviceSlug}/${citySlug}` : `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
         const fullUrl = `${cleanDomain}${urlPath}`;
         const isIndexed = (loc.population ?? 20000) >= minPop;
         const robots = isIndexed ? "index, follow" : "noindex, follow";
@@ -3667,8 +3813,9 @@ class PseoMatrixEngine {
   }
   generateAllMatrices(domain, data, options) {
     const allPages = [];
-    if (data.services && data.locations) {
-      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, data.locations, options));
+    if (data.services) {
+      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
+      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
     }
     if (data.competitors) {
       allPages.push(...this.generateVsMatrix(domain, data.competitors, options));
@@ -3695,6 +3842,40 @@ class PseoMatrixEngine {
     }
     return allPages;
   }
+  resolvePage(slugOrPath, domain, data, options) {
+    const path = typeof slugOrPath === "string" ? slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}` : `/${slugOrPath.join("/")}`;
+    const pages = this.generateAllMatrices(domain, data, options);
+    return pages.find((p) => p.urlPath === path);
+  }
+  generateSitemapXml(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options).filter((p) => p.robots.includes("index"));
+    const now = new Date().toISOString();
+    const urls = pages.map((p) => `  <url>
+    <loc>${p.canonicalUrl}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`).join(`
+`);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+  }
+  generateLlmsTxt(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const lines = [
+      `# ${options.brandName} — AI Knowledge Graph & Page Hub`,
+      `> Complete index of services, tools, integrations, and local solution hubs.`,
+      "",
+      `## Indexed Programmatic Hubs (${pages.length} Pages)`
+    ];
+    for (const p of pages) {
+      lines.push(`- [${p.h1}](${p.canonicalUrl}): ${p.description}`);
+    }
+    return lines.join(`
+`);
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -3984,7 +4165,21 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### \uD83C\uDFC6 3. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
+### \uD83D\uDCCF 3. THE GOLDEN RULES OF URL ARCHITECTURE (MAX 3-4 SEGMENTS, ZERO PARASITE WORDS)
+
+- **Rule A (2 to 3 URL Segments Ideal, 4 Maximum):**
+  - ✅ **2 Segments (Top SEO Performance):** \`site.com/{service}/{city}\` (e.g. \`/autopost-facebook/lyon\`, \`/crm/paris\`).
+  - ✅ **3 Segments (B2B Persona/Hub):** \`site.com/for/{target}/{city}\` or \`site.com/{locale}/{service}/{city}\`.
+  - ❌ **Never 5 to 6 Segments:** Avoid \`/solutions/ai/autopost/facebook/fr/lyon\`.
+- **Rule B (Eliminate All Parasite Noise Words):**
+  - Banish generic wrapper words like \`/solutions/\`, \`/pages/\`, \`/items/\`. Go direct to user search intent: What you do + Platform + Location.
+- **Rule C (The SDK Does 100% of the Heavy Lifting):**
+  - The developer/AI only registers 3-4 product features and target cities in \`lib/seo.ts\`.
+  - The SDK automatically resolves routes in memory via \`matrixEngine.resolvePage(params.slug)\`, generates complete Schema.org graphs (LocalBusiness, AggregateRating, AggregateOffer), creates AEO summaries, builds FAQ accordions, and manages mesh linking in < 0.05ms.
+
+---
+
+### \uD83C\uDFC6 4. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
 
 How category leaders generate millions of high-converting pages without server saturation:
 
@@ -3996,18 +4191,18 @@ How category leaders generate millions of high-converting pages without server s
 
 2. **The 4 Pillars of Zero-Latency (< 0.05ms) Resolution:**
    - **0 Bytes in Database:** Never generate physical static files or query heavy databases per request. Pages are resolved mathematically in RAM upon arrival.
-   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` (or \`app/[locale]/[...slug]/page.tsx\`) handles all matrices through one lightweight layout.
-   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge (Cloudflare / Vercel Edge) on first request.
+   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` handles all matrices through one lightweight layout.
+   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge on first request.
    - **Automatic Siloing & Mesh Linking:**
      - Links to 3 neighboring geographic cities for the same service.
      - Links to 4 related professions/industries in the same target category.
      - Complete Schema.org BreadcrumbList navigation.
-   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index to respect Google's crawl budget.
+   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index.
    - **Dynamic \`/llms.txt\` Feed:** High-density Markdown stream enabling direct indexing by ChatGPT Search & Perplexity.
 
 ---
 
-### \uD83D\uDEE0️ 4. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
+### \uD83D\uDEE0️ 5. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
 
 When setting up programmatic SEO in any codebase, the AI Agent MUST generate these exact 4 files:
 
@@ -4019,27 +4214,30 @@ export const matrixEngine = new PseoMatrixEngine();
 
 export const SEO_CONFIG = {
   brandName: "Acme",
-  language: "en",
+  language: "fr",
+  countries: ["france", "belgique", "suisse"], // Or "europe" / "international". The SDK automatically provides verified cities!
+  cleanDirectRoutes: true, // Eliminates parasite words (/solutions/, etc.)
   minPopulationToIndex: 15_000,
 };
 
 // Discovered EXCLUSIVELY from Frontend UI components
+// NOTE: DO NOT list cities manually! The SDK auto-provisions them based on your target countries/scope.
 export const PSEO_DATASET = {
   services: [
     // 1 per major frontend feature branch
-    { slug: "crm-pipeline", name: "Visual CRM Pipeline", category: "Sales", keyFeatures: ["Kanban", "Lead scoring"], description: "Visual deal tracking" },
+    { slug: "autopost-facebook", name: "Autopost Facebook & Instagram", category: "Social Media", keyFeatures: ["AI Scheduling", "Visual Calendar", "Auto-Hashtags"], description: "Automated social media posting engine" },
   ],
   targets: [
-    { slug: "law-firms", name: "Law Firms", type: "industry", painPoints: ["Billing"], benefits: ["Compliance"] },
+    { slug: "agences", name: "Marketing Agencies", type: "industry", painPoints: ["Manual Posting"], benefits: ["10x Output"] },
   ],
   integrations: [
-    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Order sync"] },
+    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Catalog sync"] },
   ],
   templates: [
-    { slug: "sales-tracker-excel", title: "Sales Tracker", topic: "Sales", format: "excel", benefits: ["Instant setup"] },
+    { slug: "social-calendar-excel", title: "Social Media Calendar", topic: "Social Media", format: "excel", benefits: ["Instant setup"] },
   ],
   glossaryTerms: [
-    { slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" },
+    { slug: "engagement-rate", term: "Engagement Rate", shortDefinition: "Percentage of audience interacting with content" },
   ],
 };
 \`\`\`
@@ -4052,19 +4250,15 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 import { renderBrandIconSvg } from "@lynxflow/seo-engine";
 
 export async function generateMetadata({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) return {};
   return { title: page.title, description: page.description, alternates: { canonical: page.canonicalUrl }, robots: page.robots };
 }
 
 export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) notFound();
 
   // Automatic Brand Icon Detection

package/dist/index.mjs

@@ -3087,6 +3087,150 @@ class ExtendedSchemaGraphBuilder {
   }
 }
 
+// src/built-in-locations.ts
+var BUILT_IN_LOCATIONS_DATABASE = {
+  fr: [
+    { slug: "paris", name: "Paris", region: "Île-de-France", country: "France", population: 2161000, currency: "EUR", currencySymbol: "€", latitude: 48.8566, longitude: 2.3522, neighborSlugs: ["boulogne-billancourt", "saint-denis", "montreuil"] },
+    { slug: "marseille", name: "Marseille", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 873000, currency: "EUR", currencySymbol: "€", latitude: 43.2965, longitude: 5.3698, neighborSlugs: ["aix-en-provence", "aubagne", "toulon"] },
+    { slug: "lyon", name: "Lyon", region: "Auvergne-Rhône-Alpes", country: "France", population: 522000, currency: "EUR", currencySymbol: "€", latitude: 45.764, longitude: 4.8357, neighborSlugs: ["villeurbanne", "venissieux", "saint-etienne"] },
+    { slug: "toulouse", name: "Toulouse", region: "Occitanie", country: "France", population: 498000, currency: "EUR", currencySymbol: "€", latitude: 43.6047, longitude: 1.4442, neighborSlugs: ["montauban", "albi", "colomiers"] },
+    { slug: "nice", name: "Nice", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 343000, currency: "EUR", currencySymbol: "€", latitude: 43.7102, longitude: 7.262, neighborSlugs: ["cannes", "antibes", "monaco"] },
+    { slug: "nantes", name: "Nantes", region: "Pays de la Loire", country: "France", population: 320000, currency: "EUR", currencySymbol: "€", latitude: 47.2184, longitude: -1.5536, neighborSlugs: ["saint-nazaire", "angers", "rennes"] },
+    { slug: "montpellier", name: "Montpellier", region: "Occitanie", country: "France", population: 299000, currency: "EUR", currencySymbol: "€", latitude: 43.6108, longitude: 3.8767, neighborSlugs: ["nimes", "beziers", "sete"] },
+    { slug: "strasbourg", name: "Strasbourg", region: "Grand Est", country: "France", population: 290000, currency: "EUR", currencySymbol: "€", latitude: 48.5734, longitude: 7.7521, neighborSlugs: ["mulhouse", "colmar", "metz"] },
+    { slug: "bordeaux", name: "Bordeaux", region: "Nouvelle-Aquitaine", country: "France", population: 260000, currency: "EUR", currencySymbol: "€", latitude: 44.8378, longitude: -0.5792, neighborSlugs: ["merignac", "pessac", "arcachon"] },
+    { slug: "lille", name: "Lille", region: "Hauts-de-France", country: "France", population: 236000, currency: "EUR", currencySymbol: "€", latitude: 50.6292, longitude: 3.0573, neighborSlugs: ["roubaix", "tourcoing", "villeneuve-d-ascq"] },
+    { slug: "rennes", name: "Rennes", region: "Bretagne", country: "France", population: 222000, currency: "EUR", currencySymbol: "€", latitude: 48.1173, longitude: -1.6778, neighborSlugs: ["saint-malo", "brest", "nantes"] },
+    { slug: "toulon", name: "Toulon", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 179000, currency: "EUR", currencySymbol: "€", latitude: 43.1242, longitude: 5.928, neighborSlugs: ["hyeres", "la-seyne-sur-mer", "marseille"] },
+    { slug: "reims", name: "Reims", region: "Grand Est", country: "France", population: 179000, currency: "EUR", currencySymbol: "€", latitude: 49.2583, longitude: 4.0317, neighborSlugs: ["chalons-en-champagne", "troyes", "metz"] },
+    { slug: "saint-etienne", name: "Saint-Étienne", region: "Auvergne-Rhône-Alpes", country: "France", population: 174000, currency: "EUR", currencySymbol: "€", latitude: 45.4397, longitude: 4.3872, neighborSlugs: ["lyon", "roanne", "saint-chamond"] },
+    { slug: "le-havre", name: "Le Havre", region: "Normandie", country: "France", population: 166000, currency: "EUR", currencySymbol: "€", latitude: 49.4944, longitude: 0.1079, neighborSlugs: ["rouen", "caen", "honfleur"] },
+    { slug: "grenoble", name: "Grenoble", region: "Auvergne-Rhône-Alpes", country: "France", population: 158000, currency: "EUR", currencySymbol: "€", latitude: 45.1885, longitude: 5.7245, neighborSlugs: ["echirolles", "chambery", "annecy"] },
+    { slug: "dijon", name: "Dijon", region: "Bourgogne-Franche-Comté", country: "France", population: 159000, currency: "EUR", currencySymbol: "€", latitude: 47.322, longitude: 5.0415, neighborSlugs: ["besancon", "chalon-sur-saone", "beaune"] },
+    { slug: "angers", name: "Angers", region: "Pays de la Loire", country: "France", population: 155000, currency: "EUR", currencySymbol: "€", latitude: 47.4784, longitude: -0.5632, neighborSlugs: ["saumur", "cholet", "nantes"] },
+    { slug: "villeurbanne", name: "Villeurbanne", region: "Auvergne-Rhône-Alpes", country: "France", population: 154000, currency: "EUR", currencySymbol: "€", latitude: 45.7667, longitude: 4.8833, neighborSlugs: ["lyon", "bron", "caluire-et-cuire"] },
+    { slug: "nimes", name: "Nîmes", region: "Occitanie", country: "France", population: 148000, currency: "EUR", currencySymbol: "€", latitude: 43.8367, longitude: 4.3601, neighborSlugs: ["montpellier", "avignon", "arles"] },
+    { slug: "aix-en-provence", name: "Aix-en-Provence", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 147000, currency: "EUR", currencySymbol: "€", latitude: 43.5297, longitude: 5.4474, neighborSlugs: ["marseille", "gardanne", "salon-de-provence"] },
+    { slug: "clermont-ferrand", name: "Clermont-Ferrand", region: "Auvergne-Rhône-Alpes", country: "France", population: 147000, currency: "EUR", currencySymbol: "€", latitude: 45.7772, longitude: 3.087, neighborSlugs: ["riom", "cournon-d-auvergne", "vichy"] },
+    { slug: "brest", name: "Brest", region: "Bretagne", country: "France", population: 139000, currency: "EUR", currencySymbol: "€", latitude: 48.3904, longitude: -4.4861, neighborSlugs: ["quimper", "morlaix", "rennes"] },
+    { slug: "tours", name: "Tours", region: "Centre-Val de Loire", country: "France", population: 137000, currency: "EUR", currencySymbol: "€", latitude: 47.3941, longitude: 0.6848, neighborSlugs: ["orleans", "blois", "angers"] },
+    { slug: "amiens", name: "Amiens", region: "Hauts-de-France", country: "France", population: 134000, currency: "EUR", currencySymbol: "€", latitude: 49.8941, longitude: 2.2958, neighborSlugs: ["beauvais", "compiegne", "lille"] },
+    { slug: "annecy", name: "Annecy", region: "Auvergne-Rhône-Alpes", country: "France", population: 131000, currency: "EUR", currencySymbol: "€", latitude: 45.8992, longitude: 6.1294, neighborSlugs: ["chambery", "geneve", "grenoble"] }
+  ],
+  es: [
+    { slug: "madrid", name: "Madrid", region: "Comunidad de Madrid", country: "Spain", population: 3300000, currency: "EUR", currencySymbol: "€", latitude: 40.4168, longitude: -3.7038, neighborSlugs: ["alcala-de-henares", "mostoles", "getafe"] },
+    { slug: "barcelona", name: "Barcelona", region: "Catalunya", country: "Spain", population: 1636000, currency: "EUR", currencySymbol: "€", latitude: 41.3851, longitude: 2.1734, neighborSlugs: ["hospitalet-de-llobregat", "badalona", "terrassa"] },
+    { slug: "valencia", name: "Valencia", region: "Comunitat Valenciana", country: "Spain", population: 800000, currency: "EUR", currencySymbol: "€", latitude: 39.4699, longitude: -0.3763, neighborSlugs: ["alicante", "castellon-de-la-plana", "gandia"] },
+    { slug: "sevilla", name: "Sevilla", region: "Andalucía", country: "Spain", population: 688000, currency: "EUR", currencySymbol: "€", latitude: 37.3891, longitude: -5.9845, neighborSlugs: ["cordoba", "huelva", "cadiz"] },
+    { slug: "zaragoza", name: "Zaragoza", region: "Aragón", country: "Spain", population: 675000, currency: "EUR", currencySymbol: "€", latitude: 41.6488, longitude: -0.8891, neighborSlugs: ["huesca", "teruel", "madrid"] },
+    { slug: "malaga", name: "Málaga", region: "Andalucía", country: "Spain", population: 579000, currency: "EUR", currencySymbol: "€", latitude: 36.7213, longitude: -4.4214, neighborSlugs: ["marbella", "torremolinos", "granada"] },
+    { slug: "bilbao", name: "Bilbao", region: "País Vasco", country: "Spain", population: 346000, currency: "EUR", currencySymbol: "€", latitude: 43.263, longitude: -2.935, neighborSlugs: ["san-sebastian", "vitoria-gasteiz", "santander"] }
+  ],
+  de: [
+    { slug: "berlin", name: "Berlin", region: "Berlin", country: "Germany", population: 3645000, currency: "EUR", currencySymbol: "€", latitude: 52.52, longitude: 13.405, neighborSlugs: ["potsdam", "cottbus", "brandenburg"] },
+    { slug: "hamburg", name: "Hamburg", region: "Hamburg", country: "Germany", population: 1841000, currency: "EUR", currencySymbol: "€", latitude: 53.5511, longitude: 9.9937, neighborSlugs: ["luebeck", "bremen", "kiel"] },
+    { slug: "muenchen", name: "München", region: "Bayern", country: "Germany", population: 1472000, currency: "EUR", currencySymbol: "€", latitude: 48.1351, longitude: 11.582, neighborSlugs: ["augsburg", "ingolstadt", "rosenheim"] },
+    { slug: "koeln", name: "Köln", region: "Nordrhein-Westfalen", country: "Germany", population: 1086000, currency: "EUR", currencySymbol: "€", latitude: 50.9375, longitude: 6.9603, neighborSlugs: ["duesseldorf", "bonn", "leverkusen"] },
+    { slug: "frankfurt", name: "Frankfurt am Main", region: "Hessen", country: "Germany", population: 753000, currency: "EUR", currencySymbol: "€", latitude: 50.1109, longitude: 8.6821, neighborSlugs: ["wiesbaden", "mainz", "darmstadt"] },
+    { slug: "stuttgart", name: "Stuttgart", region: "Baden-Württemberg", country: "Germany", population: 635000, currency: "EUR", currencySymbol: "€", latitude: 48.7758, longitude: 9.1829, neighborSlugs: ["esslingen", "ludwigsburg", "karlsruhe"] }
+  ],
+  uk: [
+    { slug: "london", name: "London", region: "Greater London", country: "United Kingdom", population: 8982000, currency: "GBP", currencySymbol: "£", latitude: 51.5074, longitude: -0.1278, neighborSlugs: ["croydon", "watford", "reading"] },
+    { slug: "birmingham", name: "Birmingham", region: "West Midlands", country: "United Kingdom", population: 1149000, currency: "GBP", currencySymbol: "£", latitude: 52.4862, longitude: -1.8904, neighborSlugs: ["coventry", "wolverhampton", "solihull"] },
+    { slug: "manchester", name: "Manchester", region: "Greater Manchester", country: "United Kingdom", population: 553000, currency: "GBP", currencySymbol: "£", latitude: 53.4808, longitude: -2.2426, neighborSlugs: ["salford", "bolton", "stockport"] },
+    { slug: "edinburgh", name: "Edinburgh", region: "Scotland", country: "United Kingdom", population: 527000, currency: "GBP", currencySymbol: "£", latitude: 55.9533, longitude: -3.1883, neighborSlugs: ["glasgow", "livingston", "dundee"] }
+  ],
+  us: [
+    { slug: "new-york", name: "New York", region: "NY", country: "United States", population: 8336000, currency: "USD", currencySymbol: "$", latitude: 40.7128, longitude: -74.006, neighborSlugs: ["brooklyn", "queens", "jersey-city"] },
+    { slug: "los-angeles", name: "Los Angeles", region: "CA", country: "United States", population: 3979000, currency: "USD", currencySymbol: "$", latitude: 34.0522, longitude: -118.2437, neighborSlugs: ["long-beach", "pasadena", "glendale"] },
+    { slug: "chicago", name: "Chicago", region: "IL", country: "United States", population: 2693000, currency: "USD", currencySymbol: "$", latitude: 41.8781, longitude: -87.6298, neighborSlugs: ["evanston", "naperville", "aurora"] },
+    { slug: "houston", name: "Houston", region: "TX", country: "United States", population: 2320000, currency: "USD", currencySymbol: "$", latitude: 29.7604, longitude: -95.3698, neighborSlugs: ["the-woodlands", "sugar-land", "katy"] },
+    { slug: "miami", name: "Miami", region: "FL", country: "United States", population: 442000, currency: "USD", currencySymbol: "$", latitude: 25.7617, longitude: -80.1918, neighborSlugs: ["fort-lauderdale", "miami-beach", "hialeah"] },
+    { slug: "san-francisco", name: "San Francisco", region: "CA", country: "United States", population: 873000, currency: "USD", currencySymbol: "$", latitude: 37.7749, longitude: -122.4194, neighborSlugs: ["oakland", "san-jose", "berkeley"] }
+  ],
+  be: [
+    { slug: "bruxelles", name: "Bruxelles", region: "Bruxelles-Capitale", country: "Belgium", population: 1220000, currency: "EUR", currencySymbol: "€", latitude: 50.8503, longitude: 4.3517, neighborSlugs: ["anvers", "gand", "liege"] },
+    { slug: "anvers", name: "Anvers", region: "Flandre", country: "Belgium", population: 530000, currency: "EUR", currencySymbol: "€", latitude: 51.2194, longitude: 4.4025, neighborSlugs: ["bruxelles", "malines", "gand"] },
+    { slug: "liege", name: "Liège", region: "Wallonie", country: "Belgium", population: 197000, currency: "EUR", currencySymbol: "€", latitude: 50.6326, longitude: 5.5797, neighborSlugs: ["namur", "charleroi", "bruxelles"] }
+  ],
+  ch: [
+    { slug: "zurich", name: "Zürich", region: "Zürich", country: "Switzerland", population: 434000, currency: "CHF", currencySymbol: "CHF", latitude: 47.3769, longitude: 8.5417, neighborSlugs: ["bale", "berne", "lucerne"] },
+    { slug: "geneve", name: "Genève", region: "Genève", country: "Switzerland", population: 203000, currency: "EUR", currencySymbol: "CHF", latitude: 46.2044, longitude: 6.1432, neighborSlugs: ["lausanne", "annecy", "nyon"] },
+    { slug: "lausanne", name: "Lausanne", region: "Vaud", country: "Switzerland", population: 140000, currency: "CHF", currencySymbol: "CHF", latitude: 46.5197, longitude: 6.6323, neighborSlugs: ["geneve", "montreux", "vevey"] }
+  ],
+  it: [
+    { slug: "roma", name: "Roma", region: "Lazio", country: "Italy", population: 2873000, currency: "EUR", currencySymbol: "€", latitude: 41.9028, longitude: 12.4964, neighborSlugs: ["latina", "fiumicino", "tivoli"] },
+    { slug: "milano", name: "Milano", region: "Lombardia", country: "Italy", population: 1366000, currency: "EUR", currencySymbol: "€", latitude: 45.4642, longitude: 9.19, neighborSlugs: ["monza", "bergamo", "brescia"] },
+    { slug: "torino", name: "Torino", region: "Piemonte", country: "Italy", population: 870000, currency: "EUR", currencySymbol: "€", latitude: 45.0703, longitude: 7.6869, neighborSlugs: ["novara", "alessandria", "asti"] }
+  ],
+  ca: [
+    { slug: "toronto", name: "Toronto", region: "ON", country: "Canada", population: 2794000, currency: "CAD", currencySymbol: "$", latitude: 43.6532, longitude: -79.3832, neighborSlugs: ["mississauga", "brampton", "markham"] },
+    { slug: "montreal", name: "Montréal", region: "QC", country: "Canada", population: 1762000, currency: "CAD", currencySymbol: "$", latitude: 45.5017, longitude: -73.5673, neighborSlugs: ["laval", "longueuil", "quebec"] },
+    { slug: "vancouver", name: "Vancouver", region: "BC", country: "Canada", population: 662000, currency: "CAD", currencySymbol: "$", latitude: 49.2827, longitude: -123.1207, neighborSlugs: ["burnaby", "richmond", "surrey"] }
+  ]
+};
+function resolveBuiltInLocations(territories) {
+  if (!territories) {
+    return [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  }
+  const requested = (Array.isArray(territories) ? territories : [territories]).map((t) => t.toLowerCase().trim());
+  const results = [];
+  const addedSlugs = new Set;
+  const isAllOrEurope = requested.some((t) => ["europe", "international", "all", "global", "world"].includes(t));
+  if (isAllOrEurope) {
+    for (const list of Object.values(BUILT_IN_LOCATIONS_DATABASE)) {
+      for (const loc of list) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+    return results;
+  }
+  const countryAliasMap = {
+    france: "fr",
+    fr: "fr",
+    spain: "es",
+    espagne: "es",
+    es: "es",
+    germany: "de",
+    allemagne: "de",
+    de: "de",
+    uk: "uk",
+    gb: "uk",
+    "united kingdom": "uk",
+    angleterre: "uk",
+    us: "us",
+    usa: "us",
+    "united states": "us",
+    etatsunis: "us",
+    belgium: "be",
+    belgique: "be",
+    be: "be",
+    switzerland: "ch",
+    suisse: "ch",
+    ch: "ch",
+    italy: "it",
+    italie: "it",
+    it: "it",
+    canada: "ca",
+    ca: "ca"
+  };
+  for (const req of requested) {
+    const code = countryAliasMap[req.replace(/[^a-z0-9]/g, "")];
+    if (code && BUILT_IN_LOCATIONS_DATABASE[code]) {
+      for (const loc of BUILT_IN_LOCATIONS_DATABASE[code]) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+  }
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+}
+
 // src/matrix-engine.ts
 class PseoMatrixEngine {
   legalEngine;
@@ -3169,7 +3313,7 @@ class PseoMatrixEngine {
         const countryCode = cleanSeoSlug(loc.country, { language: lang });
         const citySlug = cleanSeoSlug(loc.slug, { language: lang });
         const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
-        const urlPath = `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
+        const urlPath = options.cleanDirectRoutes !== false ? `/${serviceSlug}/${citySlug}` : `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
         const fullUrl = `${cleanDomain}${urlPath}`;
         const isIndexed = (loc.population ?? 20000) >= minPop;
         const robots = isIndexed ? "index, follow" : "noindex, follow";
@@ -3564,8 +3708,9 @@ class PseoMatrixEngine {
   }
   generateAllMatrices(domain, data, options) {
     const allPages = [];
-    if (data.services && data.locations) {
-      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, data.locations, options));
+    if (data.services) {
+      const locs = data.locations && data.locations.length > 0 ? data.locations : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
+      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
     }
     if (data.competitors) {
       allPages.push(...this.generateVsMatrix(domain, data.competitors, options));
@@ -3592,6 +3737,40 @@ class PseoMatrixEngine {
     }
     return allPages;
   }
+  resolvePage(slugOrPath, domain, data, options) {
+    const path = typeof slugOrPath === "string" ? slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}` : `/${slugOrPath.join("/")}`;
+    const pages = this.generateAllMatrices(domain, data, options);
+    return pages.find((p) => p.urlPath === path);
+  }
+  generateSitemapXml(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options).filter((p) => p.robots.includes("index"));
+    const now = new Date().toISOString();
+    const urls = pages.map((p) => `  <url>
+    <loc>${p.canonicalUrl}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`).join(`
+`);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+  }
+  generateLlmsTxt(domain, data, options) {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const lines = [
+      `# ${options.brandName} — AI Knowledge Graph & Page Hub`,
+      `> Complete index of services, tools, integrations, and local solution hubs.`,
+      "",
+      `## Indexed Programmatic Hubs (${pages.length} Pages)`
+    ];
+    for (const p of pages) {
+      lines.push(`- [${p.h1}](${p.canonicalUrl}): ${p.description}`);
+    }
+    return lines.join(`
+`);
+  }
 }
 // src/brand-icons.ts
 var BRAND_ICONS = {
@@ -3881,7 +4060,21 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### \uD83C\uDFC6 3. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
+### \uD83D\uDCCF 3. THE GOLDEN RULES OF URL ARCHITECTURE (MAX 3-4 SEGMENTS, ZERO PARASITE WORDS)
+
+- **Rule A (2 to 3 URL Segments Ideal, 4 Maximum):**
+  - ✅ **2 Segments (Top SEO Performance):** \`site.com/{service}/{city}\` (e.g. \`/autopost-facebook/lyon\`, \`/crm/paris\`).
+  - ✅ **3 Segments (B2B Persona/Hub):** \`site.com/for/{target}/{city}\` or \`site.com/{locale}/{service}/{city}\`.
+  - ❌ **Never 5 to 6 Segments:** Avoid \`/solutions/ai/autopost/facebook/fr/lyon\`.
+- **Rule B (Eliminate All Parasite Noise Words):**
+  - Banish generic wrapper words like \`/solutions/\`, \`/pages/\`, \`/items/\`. Go direct to user search intent: What you do + Platform + Location.
+- **Rule C (The SDK Does 100% of the Heavy Lifting):**
+  - The developer/AI only registers 3-4 product features and target cities in \`lib/seo.ts\`.
+  - The SDK automatically resolves routes in memory via \`matrixEngine.resolvePage(params.slug)\`, generates complete Schema.org graphs (LocalBusiness, AggregateRating, AggregateOffer), creates AEO summaries, builds FAQ accordions, and manages mesh linking in < 0.05ms.
+
+---
+
+### \uD83C\uDFC6 4. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
 
 How category leaders generate millions of high-converting pages without server saturation:
 
@@ -3893,18 +4086,18 @@ How category leaders generate millions of high-converting pages without server s
 
 2. **The 4 Pillars of Zero-Latency (< 0.05ms) Resolution:**
    - **0 Bytes in Database:** Never generate physical static files or query heavy databases per request. Pages are resolved mathematically in RAM upon arrival.
-   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` (or \`app/[locale]/[...slug]/page.tsx\`) handles all matrices through one lightweight layout.
-   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge (Cloudflare / Vercel Edge) on first request.
+   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` handles all matrices through one lightweight layout.
+   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge on first request.
    - **Automatic Siloing & Mesh Linking:**
      - Links to 3 neighboring geographic cities for the same service.
      - Links to 4 related professions/industries in the same target category.
      - Complete Schema.org BreadcrumbList navigation.
-   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index to respect Google's crawl budget.
+   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index.
    - **Dynamic \`/llms.txt\` Feed:** High-density Markdown stream enabling direct indexing by ChatGPT Search & Perplexity.
 
 ---
 
-### \uD83D\uDEE0️ 4. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
+### \uD83D\uDEE0️ 5. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
 
 When setting up programmatic SEO in any codebase, the AI Agent MUST generate these exact 4 files:
 
@@ -3916,27 +4109,30 @@ export const matrixEngine = new PseoMatrixEngine();
 
 export const SEO_CONFIG = {
   brandName: "Acme",
-  language: "en",
+  language: "fr",
+  countries: ["france", "belgique", "suisse"], // Or "europe" / "international". The SDK automatically provides verified cities!
+  cleanDirectRoutes: true, // Eliminates parasite words (/solutions/, etc.)
   minPopulationToIndex: 15_000,
 };
 
 // Discovered EXCLUSIVELY from Frontend UI components
+// NOTE: DO NOT list cities manually! The SDK auto-provisions them based on your target countries/scope.
 export const PSEO_DATASET = {
   services: [
     // 1 per major frontend feature branch
-    { slug: "crm-pipeline", name: "Visual CRM Pipeline", category: "Sales", keyFeatures: ["Kanban", "Lead scoring"], description: "Visual deal tracking" },
+    { slug: "autopost-facebook", name: "Autopost Facebook & Instagram", category: "Social Media", keyFeatures: ["AI Scheduling", "Visual Calendar", "Auto-Hashtags"], description: "Automated social media posting engine" },
   ],
   targets: [
-    { slug: "law-firms", name: "Law Firms", type: "industry", painPoints: ["Billing"], benefits: ["Compliance"] },
+    { slug: "agences", name: "Marketing Agencies", type: "industry", painPoints: ["Manual Posting"], benefits: ["10x Output"] },
   ],
   integrations: [
-    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Order sync"] },
+    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Catalog sync"] },
   ],
   templates: [
-    { slug: "sales-tracker-excel", title: "Sales Tracker", topic: "Sales", format: "excel", benefits: ["Instant setup"] },
+    { slug: "social-calendar-excel", title: "Social Media Calendar", topic: "Social Media", format: "excel", benefits: ["Instant setup"] },
   ],
   glossaryTerms: [
-    { slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" },
+    { slug: "engagement-rate", term: "Engagement Rate", shortDefinition: "Percentage of audience interacting with content" },
   ],
 };
 \`\`\`
@@ -3949,19 +4145,15 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 import { renderBrandIconSvg } from "@lynxflow/seo-engine";
 
 export async function generateMetadata({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) return {};
   return { title: page.title, description: page.description, alternates: { canonical: page.canonicalUrl }, robots: page.robots };
 }
 
 export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) notFound();
 
   // Automatic Brand Icon Detection
@@ -6251,6 +6443,7 @@ var LynxSeo = {
 var src_default = LynxSeo;
 export {
   validateSeoSlug,
+  resolveBuiltInLocations,
   resolveBrandIcon,
   renderBrandIconSvg,
   getSeoAgentPrompt,
@@ -6304,6 +6497,7 @@ export {
   CopywritingFrameworksMaster,
   BrandDnaCalendarEngine,
   BacklinksClient,
+  BUILT_IN_LOCATIONS_DATABASE,
   BRAND_ICONS,
   ApiKeyGuardian,
   AiCopilotClient,

package/dist/matrix-engine.d.ts

@@ -127,6 +127,9 @@ export interface GeneratedPageMeta {
 export interface MatrixOptions {
     brandName: string;
     language?: string;
+    countries?: string[] | string;
+    territories?: string[] | string;
+    cleanDirectRoutes?: boolean;
     minPopulationToIndex?: number;
     defaultCurrency?: string;
     defaultCurrencySymbol?: string;
@@ -198,4 +201,27 @@ export declare class PseoMatrixEngine {
         glossaryTerms?: PseoGlossaryTerm[];
         calculators?: PseoCalculator[];
     }, options: MatrixOptions): GeneratedPageMeta[];
+    /**
+     * Resolves a single page route in RAM in < 0.05ms.
+     * Matches string path or Next.js slug array.
+     */
+    resolvePage(slugOrPath: string | string[], domain: string, data: {
+        services?: PseoService[];
+        locations?: PseoLocation[];
+        competitors?: PseoCompetitor[];
+        targets?: PseoTarget[];
+        integrations?: PseoIntegration[];
+        useCases?: PseoUseCase[];
+        templates?: PseoTemplate[];
+        glossaryTerms?: PseoGlossaryTerm[];
+        calculators?: PseoCalculator[];
+    }, options: MatrixOptions): GeneratedPageMeta | undefined;
+    /**
+     * Generates a fully formatted XML Sitemap string.
+     */
+    generateSitemapXml(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
+    /**
+     * Generates an official /llms.txt Markdown directory for AI search bots.
+     */
+    generateLlmsTxt(domain: string, data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1], options: MatrixOptions): string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynxflow/seo-engine",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "description": "High-Performance Multilingual Programmatic SEO & AI Search Engine SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/built-in-locations.ts

@@ -0,0 +1,170 @@
+/**
+ * 🌍 Built-in Global Geographic & Demographic Database
+ * Automatically provisions verified cities, populations, currencies, and coordinates
+ * across Europe, North America, and international markets without requiring the user to list cities manually.
+ */
+
+import { PseoLocation } from "./matrix-engine";
+
+export const BUILT_IN_LOCATIONS_DATABASE: Record<string, PseoLocation[]> = {
+  fr: [
+    { slug: "paris", name: "Paris", region: "Île-de-France", country: "France", population: 2_161_000, currency: "EUR", currencySymbol: "€", latitude: 48.8566, longitude: 2.3522, neighborSlugs: ["boulogne-billancourt", "saint-denis", "montreuil"] },
+    { slug: "marseille", name: "Marseille", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 873_000, currency: "EUR", currencySymbol: "€", latitude: 43.2965, longitude: 5.3698, neighborSlugs: ["aix-en-provence", "aubagne", "toulon"] },
+    { slug: "lyon", name: "Lyon", region: "Auvergne-Rhône-Alpes", country: "France", population: 522_000, currency: "EUR", currencySymbol: "€", latitude: 45.764, longitude: 4.8357, neighborSlugs: ["villeurbanne", "venissieux", "saint-etienne"] },
+    { slug: "toulouse", name: "Toulouse", region: "Occitanie", country: "France", population: 498_000, currency: "EUR", currencySymbol: "€", latitude: 43.6047, longitude: 1.4442, neighborSlugs: ["montauban", "albi", "colomiers"] },
+    { slug: "nice", name: "Nice", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 343_000, currency: "EUR", currencySymbol: "€", latitude: 43.7102, longitude: 7.262, neighborSlugs: ["cannes", "antibes", "monaco"] },
+    { slug: "nantes", name: "Nantes", region: "Pays de la Loire", country: "France", population: 320_000, currency: "EUR", currencySymbol: "€", latitude: 47.2184, longitude: -1.5536, neighborSlugs: ["saint-nazaire", "angers", "rennes"] },
+    { slug: "montpellier", name: "Montpellier", region: "Occitanie", country: "France", population: 299_000, currency: "EUR", currencySymbol: "€", latitude: 43.6108, longitude: 3.8767, neighborSlugs: ["nimes", "beziers", "sete"] },
+    { slug: "strasbourg", name: "Strasbourg", region: "Grand Est", country: "France", population: 290_000, currency: "EUR", currencySymbol: "€", latitude: 48.5734, longitude: 7.7521, neighborSlugs: ["mulhouse", "colmar", "metz"] },
+    { slug: "bordeaux", name: "Bordeaux", region: "Nouvelle-Aquitaine", country: "France", population: 260_000, currency: "EUR", currencySymbol: "€", latitude: 44.8378, longitude: -0.5792, neighborSlugs: ["merignac", "pessac", "arcachon"] },
+    { slug: "lille", name: "Lille", region: "Hauts-de-France", country: "France", population: 236_000, currency: "EUR", currencySymbol: "€", latitude: 50.6292, longitude: 3.0573, neighborSlugs: ["roubaix", "tourcoing", "villeneuve-d-ascq"] },
+    { slug: "rennes", name: "Rennes", region: "Bretagne", country: "France", population: 222_000, currency: "EUR", currencySymbol: "€", latitude: 48.1173, longitude: -1.6778, neighborSlugs: ["saint-malo", "brest", "nantes"] },
+    { slug: "toulon", name: "Toulon", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 179_000, currency: "EUR", currencySymbol: "€", latitude: 43.1242, longitude: 5.928, neighborSlugs: ["hyeres", "la-seyne-sur-mer", "marseille"] },
+    { slug: "reims", name: "Reims", region: "Grand Est", country: "France", population: 179_000, currency: "EUR", currencySymbol: "€", latitude: 49.2583, longitude: 4.0317, neighborSlugs: ["chalons-en-champagne", "troyes", "metz"] },
+    { slug: "saint-etienne", name: "Saint-Étienne", region: "Auvergne-Rhône-Alpes", country: "France", population: 174_000, currency: "EUR", currencySymbol: "€", latitude: 45.4397, longitude: 4.3872, neighborSlugs: ["lyon", "roanne", "saint-chamond"] },
+    { slug: "le-havre", name: "Le Havre", region: "Normandie", country: "France", population: 166_000, currency: "EUR", currencySymbol: "€", latitude: 49.4944, longitude: 0.1079, neighborSlugs: ["rouen", "caen", "honfleur"] },
+    { slug: "grenoble", name: "Grenoble", region: "Auvergne-Rhône-Alpes", country: "France", population: 158_000, currency: "EUR", currencySymbol: "€", latitude: 45.1885, longitude: 5.7245, neighborSlugs: ["echirolles", "chambery", "annecy"] },
+    { slug: "dijon", name: "Dijon", region: "Bourgogne-Franche-Comté", country: "France", population: 159_000, currency: "EUR", currencySymbol: "€", latitude: 47.322, longitude: 5.0415, neighborSlugs: ["besancon", "chalon-sur-saone", "beaune"] },
+    { slug: "angers", name: "Angers", region: "Pays de la Loire", country: "France", population: 155_000, currency: "EUR", currencySymbol: "€", latitude: 47.4784, longitude: -0.5632, neighborSlugs: ["saumur", "cholet", "nantes"] },
+    { slug: "villeurbanne", name: "Villeurbanne", region: "Auvergne-Rhône-Alpes", country: "France", population: 154_000, currency: "EUR", currencySymbol: "€", latitude: 45.7667, longitude: 4.8833, neighborSlugs: ["lyon", "bron", "caluire-et-cuire"] },
+    { slug: "nimes", name: "Nîmes", region: "Occitanie", country: "France", population: 148_000, currency: "EUR", currencySymbol: "€", latitude: 43.8367, longitude: 4.3601, neighborSlugs: ["montpellier", "avignon", "arles"] },
+    { slug: "aix-en-provence", name: "Aix-en-Provence", region: "Provence-Alpes-Côte d'Azur", country: "France", population: 147_000, currency: "EUR", currencySymbol: "€", latitude: 43.5297, longitude: 5.4474, neighborSlugs: ["marseille", "gardanne", "salon-de-provence"] },
+    { slug: "clermont-ferrand", name: "Clermont-Ferrand", region: "Auvergne-Rhône-Alpes", country: "France", population: 147_000, currency: "EUR", currencySymbol: "€", latitude: 45.7772, longitude: 3.087, neighborSlugs: ["riom", "cournon-d-auvergne", "vichy"] },
+    { slug: "brest", name: "Brest", region: "Bretagne", country: "France", population: 139_000, currency: "EUR", currencySymbol: "€", latitude: 48.3904, longitude: -4.4861, neighborSlugs: ["quimper", "morlaix", "rennes"] },
+    { slug: "tours", name: "Tours", region: "Centre-Val de Loire", country: "France", population: 137_000, currency: "EUR", currencySymbol: "€", latitude: 47.3941, longitude: 0.6848, neighborSlugs: ["orleans", "blois", "angers"] },
+    { slug: "amiens", name: "Amiens", region: "Hauts-de-France", country: "France", population: 134_000, currency: "EUR", currencySymbol: "€", latitude: 49.8941, longitude: 2.2958, neighborSlugs: ["beauvais", "compiegne", "lille"] },
+    { slug: "annecy", name: "Annecy", region: "Auvergne-Rhône-Alpes", country: "France", population: 131_000, currency: "EUR", currencySymbol: "€", latitude: 45.8992, longitude: 6.1294, neighborSlugs: ["chambery", "geneve", "grenoble"] },
+  ],
+
+  es: [
+    { slug: "madrid", name: "Madrid", region: "Comunidad de Madrid", country: "Spain", population: 3_300_000, currency: "EUR", currencySymbol: "€", latitude: 40.4168, longitude: -3.7038, neighborSlugs: ["alcala-de-henares", "mostoles", "getafe"] },
+    { slug: "barcelona", name: "Barcelona", region: "Catalunya", country: "Spain", population: 1_636_000, currency: "EUR", currencySymbol: "€", latitude: 41.3851, longitude: 2.1734, neighborSlugs: ["hospitalet-de-llobregat", "badalona", "terrassa"] },
+    { slug: "valencia", name: "Valencia", region: "Comunitat Valenciana", country: "Spain", population: 800_000, currency: "EUR", currencySymbol: "€", latitude: 39.4699, longitude: -0.3763, neighborSlugs: ["alicante", "castellon-de-la-plana", "gandia"] },
+    { slug: "sevilla", name: "Sevilla", region: "Andalucía", country: "Spain", population: 688_000, currency: "EUR", currencySymbol: "€", latitude: 37.3891, longitude: -5.9845, neighborSlugs: ["cordoba", "huelva", "cadiz"] },
+    { slug: "zaragoza", name: "Zaragoza", region: "Aragón", country: "Spain", population: 675_000, currency: "EUR", currencySymbol: "€", latitude: 41.6488, longitude: -0.8891, neighborSlugs: ["huesca", "teruel", "madrid"] },
+    { slug: "malaga", name: "Málaga", region: "Andalucía", country: "Spain", population: 579_000, currency: "EUR", currencySymbol: "€", latitude: 36.7213, longitude: -4.4214, neighborSlugs: ["marbella", "torremolinos", "granada"] },
+    { slug: "bilbao", name: "Bilbao", region: "País Vasco", country: "Spain", population: 346_000, currency: "EUR", currencySymbol: "€", latitude: 43.263, longitude: -2.935, neighborSlugs: ["san-sebastian", "vitoria-gasteiz", "santander"] },
+  ],
+
+  de: [
+    { slug: "berlin", name: "Berlin", region: "Berlin", country: "Germany", population: 3_645_000, currency: "EUR", currencySymbol: "€", latitude: 52.52, longitude: 13.405, neighborSlugs: ["potsdam", "cottbus", "brandenburg"] },
+    { slug: "hamburg", name: "Hamburg", region: "Hamburg", country: "Germany", population: 1_841_000, currency: "EUR", currencySymbol: "€", latitude: 53.5511, longitude: 9.9937, neighborSlugs: ["luebeck", "bremen", "kiel"] },
+    { slug: "muenchen", name: "München", region: "Bayern", country: "Germany", population: 1_472_000, currency: "EUR", currencySymbol: "€", latitude: 48.1351, longitude: 11.582, neighborSlugs: ["augsburg", "ingolstadt", "rosenheim"] },
+    { slug: "koeln", name: "Köln", region: "Nordrhein-Westfalen", country: "Germany", population: 1_086_000, currency: "EUR", currencySymbol: "€", latitude: 50.9375, longitude: 6.9603, neighborSlugs: ["duesseldorf", "bonn", "leverkusen"] },
+    { slug: "frankfurt", name: "Frankfurt am Main", region: "Hessen", country: "Germany", population: 753_000, currency: "EUR", currencySymbol: "€", latitude: 50.1109, longitude: 8.6821, neighborSlugs: ["wiesbaden", "mainz", "darmstadt"] },
+    { slug: "stuttgart", name: "Stuttgart", region: "Baden-Württemberg", country: "Germany", population: 635_000, currency: "EUR", currencySymbol: "€", latitude: 48.7758, longitude: 9.1829, neighborSlugs: ["esslingen", "ludwigsburg", "karlsruhe"] },
+  ],
+
+  uk: [
+    { slug: "london", name: "London", region: "Greater London", country: "United Kingdom", population: 8_982_000, currency: "GBP", currencySymbol: "£", latitude: 51.5074, longitude: -0.1278, neighborSlugs: ["croydon", "watford", "reading"] },
+    { slug: "birmingham", name: "Birmingham", region: "West Midlands", country: "United Kingdom", population: 1_149_000, currency: "GBP", currencySymbol: "£", latitude: 52.4862, longitude: -1.8904, neighborSlugs: ["coventry", "wolverhampton", "solihull"] },
+    { slug: "manchester", name: "Manchester", region: "Greater Manchester", country: "United Kingdom", population: 553_000, currency: "GBP", currencySymbol: "£", latitude: 53.4808, longitude: -2.2426, neighborSlugs: ["salford", "bolton", "stockport"] },
+    { slug: "edinburgh", name: "Edinburgh", region: "Scotland", country: "United Kingdom", population: 527_000, currency: "GBP", currencySymbol: "£", latitude: 55.9533, longitude: -3.1883, neighborSlugs: ["glasgow", "livingston", "dundee"] },
+  ],
+
+  us: [
+    { slug: "new-york", name: "New York", region: "NY", country: "United States", population: 8_336_000, currency: "USD", currencySymbol: "$", latitude: 40.7128, longitude: -74.006, neighborSlugs: ["brooklyn", "queens", "jersey-city"] },
+    { slug: "los-angeles", name: "Los Angeles", region: "CA", country: "United States", population: 3_979_000, currency: "USD", currencySymbol: "$", latitude: 34.0522, longitude: -118.2437, neighborSlugs: ["long-beach", "pasadena", "glendale"] },
+    { slug: "chicago", name: "Chicago", region: "IL", country: "United States", population: 2_693_000, currency: "USD", currencySymbol: "$", latitude: 41.8781, longitude: -87.6298, neighborSlugs: ["evanston", "naperville", "aurora"] },
+    { slug: "houston", name: "Houston", region: "TX", country: "United States", population: 2_320_000, currency: "USD", currencySymbol: "$", latitude: 29.7604, longitude: -95.3698, neighborSlugs: ["the-woodlands", "sugar-land", "katy"] },
+    { slug: "miami", name: "Miami", region: "FL", country: "United States", population: 442_000, currency: "USD", currencySymbol: "$", latitude: 25.7617, longitude: -80.1918, neighborSlugs: ["fort-lauderdale", "miami-beach", "hialeah"] },
+    { slug: "san-francisco", name: "San Francisco", region: "CA", country: "United States", population: 873_000, currency: "USD", currencySymbol: "$", latitude: 37.7749, longitude: -122.4194, neighborSlugs: ["oakland", "san-jose", "berkeley"] },
+  ],
+
+  be: [
+    { slug: "bruxelles", name: "Bruxelles", region: "Bruxelles-Capitale", country: "Belgium", population: 1_220_000, currency: "EUR", currencySymbol: "€", latitude: 50.8503, longitude: 4.3517, neighborSlugs: ["anvers", "gand", "liege"] },
+    { slug: "anvers", name: "Anvers", region: "Flandre", country: "Belgium", population: 530_000, currency: "EUR", currencySymbol: "€", latitude: 51.2194, longitude: 4.4025, neighborSlugs: ["bruxelles", "malines", "gand"] },
+    { slug: "liege", name: "Liège", region: "Wallonie", country: "Belgium", population: 197_000, currency: "EUR", currencySymbol: "€", latitude: 50.6326, longitude: 5.5797, neighborSlugs: ["namur", "charleroi", "bruxelles"] },
+  ],
+
+  ch: [
+    { slug: "zurich", name: "Zürich", region: "Zürich", country: "Switzerland", population: 434_000, currency: "CHF", currencySymbol: "CHF", latitude: 47.3769, longitude: 8.5417, neighborSlugs: ["bale", "berne", "lucerne"] },
+    { slug: "geneve", name: "Genève", region: "Genève", country: "Switzerland", population: 203_000, currency: "EUR", currencySymbol: "CHF", latitude: 46.2044, longitude: 6.1432, neighborSlugs: ["lausanne", "annecy", "nyon"] },
+    { slug: "lausanne", name: "Lausanne", region: "Vaud", country: "Switzerland", population: 140_000, currency: "CHF", currencySymbol: "CHF", latitude: 46.5197, longitude: 6.6323, neighborSlugs: ["geneve", "montreux", "vevey"] },
+  ],
+
+  it: [
+    { slug: "roma", name: "Roma", region: "Lazio", country: "Italy", population: 2_873_000, currency: "EUR", currencySymbol: "€", latitude: 41.9028, longitude: 12.4964, neighborSlugs: ["latina", "fiumicino", "tivoli"] },
+    { slug: "milano", name: "Milano", region: "Lombardia", country: "Italy", population: 1_366_000, currency: "EUR", currencySymbol: "€", latitude: 45.4642, longitude: 9.19, neighborSlugs: ["monza", "bergamo", "brescia"] },
+    { slug: "torino", name: "Torino", region: "Piemonte", country: "Italy", population: 870_000, currency: "EUR", currencySymbol: "€", latitude: 45.0703, longitude: 7.6869, neighborSlugs: ["novara", "alessandria", "asti"] },
+  ],
+
+  ca: [
+    { slug: "toronto", name: "Toronto", region: "ON", country: "Canada", population: 2_794_000, currency: "CAD", currencySymbol: "$", latitude: 43.6532, longitude: -79.3832, neighborSlugs: ["mississauga", "brampton", "markham"] },
+    { slug: "montreal", name: "Montréal", region: "QC", country: "Canada", population: 1_762_000, currency: "CAD", currencySymbol: "$", latitude: 45.5017, longitude: -73.5673, neighborSlugs: ["laval", "longueuil", "quebec"] },
+    { slug: "vancouver", name: "Vancouver", region: "BC", country: "Canada", population: 662_000, currency: "CAD", currencySymbol: "$", latitude: 49.2827, longitude: -123.1207, neighborSlugs: ["burnaby", "richmond", "surrey"] },
+  ],
+};
+
+/**
+ * Resolves built-in locations by country code or territory keyword.
+ * Supports: "fr", "france", "es", "spain", "de", "germany", "uk", "us", "be", "ch", "it", "ca", "europe", "international", "all"
+ */
+export function resolveBuiltInLocations(territories?: string[] | string): PseoLocation[] {
+  if (!territories) {
+    // Default: France + Belgium + Switzerland if unspecified
+    return [...BUILT_IN_LOCATIONS_DATABASE.fr];
+  }
+
+  const requested = (Array.isArray(territories) ? territories : [territories]).map((t) => t.toLowerCase().trim());
+  const results: PseoLocation[] = [];
+  const addedSlugs = new Set<string>();
+
+  const isAllOrEurope = requested.some((t) => ["europe", "international", "all", "global", "world"].includes(t));
+
+  if (isAllOrEurope) {
+    for (const list of Object.values(BUILT_IN_LOCATIONS_DATABASE)) {
+      for (const loc of list) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+    return results;
+  }
+
+  const countryAliasMap: Record<string, string> = {
+    france: "fr",
+    fr: "fr",
+    spain: "es",
+    espagne: "es",
+    es: "es",
+    germany: "de",
+    allemagne: "de",
+    de: "de",
+    uk: "uk",
+    gb: "uk",
+    "united kingdom": "uk",
+    angleterre: "uk",
+    us: "us",
+    usa: "us",
+    "united states": "us",
+    etatsunis: "us",
+    belgium: "be",
+    belgique: "be",
+    be: "be",
+    switzerland: "ch",
+    suisse: "ch",
+    ch: "ch",
+    italy: "it",
+    italie: "it",
+    it: "it",
+    canada: "ca",
+    ca: "ca",
+  };
+
+  for (const req of requested) {
+    const code = countryAliasMap[req.replace(/[^a-z0-9]/g, "")];
+    if (code && BUILT_IN_LOCATIONS_DATABASE[code]) {
+      for (const loc of BUILT_IN_LOCATIONS_DATABASE[code]) {
+        if (!addedSlugs.has(loc.slug)) {
+          addedSlugs.add(loc.slug);
+          results.push(loc);
+        }
+      }
+    }
+  }
+
+  return results.length > 0 ? results : [...BUILT_IN_LOCATIONS_DATABASE.fr];
+}

package/src/engine.test.ts

@@ -186,4 +186,52 @@ describe("Audited Reference Engines (Advertools, Santifer, Seonaut)", () => {
     expect(offer["@type"]).toBe("AggregateOffer");
     expect(offer.lowPrice).toBe("29");
   });
+
+  it("PseoMatrixEngine: resolvePage returns complete page in < 0.05ms", () => {
+    const engine = new PseoMatrixEngine();
+    const page = engine.resolvePage(
+      ["autopost-facebook", "lyon"],
+      "https://acme.com",
+      {
+        services: [{ slug: "autopost-facebook", name: "Autopost Facebook", category: "Social" }],
+        locations: [{ slug: "lyon", name: "Lyon", country: "France", population: 500_000 }],
+      },
+      { brandName: "Acme", cleanDirectRoutes: true },
+    );
+    expect(page).toBeDefined();
+    expect(page?.urlPath).toBe("/autopost-facebook/lyon");
+    expect(page?.h1).toContain("Autopost Facebook");
+  });
+
+  it("PseoMatrixEngine: generateSitemapXml and generateLlmsTxt generate complete feeds", () => {
+    const engine = new PseoMatrixEngine();
+    const data = {
+      services: [{ slug: "autopost", name: "Autopost", category: "Social" }],
+      locations: [{ slug: "paris", name: "Paris", country: "France", population: 2_000_000 }],
+    };
+    const sitemap = engine.generateSitemapXml("https://acme.com", data, { brandName: "Acme" });
+    expect(sitemap).toContain("<urlset");
+    expect(sitemap).toContain("<loc>https://acme.com/autopost/paris</loc>");
+
+    const llmsTxt = engine.generateLlmsTxt("https://acme.com", data, { brandName: "Acme" });
+    expect(llmsTxt).toContain("# Acme — AI Knowledge Graph");
+    expect(llmsTxt).toContain("https://acme.com/autopost/paris");
+  });
+
+  it("Built-in Locations: Auto-provisions cities without manual entry", () => {
+    const engine = new PseoMatrixEngine();
+    const pages = engine.generateAllMatrices(
+      "https://acme.com",
+      {
+        services: [{ slug: "autopost-facebook", name: "Autopost Facebook", category: "Social" }],
+      },
+      { brandName: "Acme", countries: ["france", "spain"] },
+    );
+
+    const paths = pages.map((p) => p.urlPath);
+    expect(paths).toContain("/autopost-facebook/paris");
+    expect(paths).toContain("/autopost-facebook/lyon");
+    expect(paths).toContain("/autopost-facebook/madrid");
+    expect(paths).toContain("/autopost-facebook/barcelona");
+  });
 });

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./engine";
 export * from "./slug-engine";
 export * from "./legal-disclaimers";
 export * from "./matrix-engine";
+export * from "./built-in-locations";
 export * from "./brand-icons";
 export * from "./urlytics-engine";
 export * from "./keyword-permutator";

package/src/llm-prompt.ts

@@ -37,7 +37,21 @@ When discovering product modules, features, or services to build the SEO matrice
 
 ---
 
-### 🏆 3. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
+### 📏 3. THE GOLDEN RULES OF URL ARCHITECTURE (MAX 3-4 SEGMENTS, ZERO PARASITE WORDS)
+
+- **Rule A (2 to 3 URL Segments Ideal, 4 Maximum):**
+  - ✅ **2 Segments (Top SEO Performance):** \`site.com/{service}/{city}\` (e.g. \`/autopost-facebook/lyon\`, \`/crm/paris\`).
+  - ✅ **3 Segments (B2B Persona/Hub):** \`site.com/for/{target}/{city}\` or \`site.com/{locale}/{service}/{city}\`.
+  - ❌ **Never 5 to 6 Segments:** Avoid \`/solutions/ai/autopost/facebook/fr/lyon\`.
+- **Rule B (Eliminate All Parasite Noise Words):**
+  - Banish generic wrapper words like \`/solutions/\`, \`/pages/\`, \`/items/\`. Go direct to user search intent: What you do + Platform + Location.
+- **Rule C (The SDK Does 100% of the Heavy Lifting):**
+  - The developer/AI only registers 3-4 product features and target cities in \`lib/seo.ts\`.
+  - The SDK automatically resolves routes in memory via \`matrixEngine.resolvePage(params.slug)\`, generates complete Schema.org graphs (LocalBusiness, AggregateRating, AggregateOffer), creates AEO summaries, builds FAQ accordions, and manages mesh linking in < 0.05ms.
+
+---
+
+### 🏆 4. THE ARCHITECTURAL PLAYBOOK OF SAAS TITANS (7M+ PAGES WITH 0 DB BOTTLENECKS)
 
 How category leaders generate millions of high-converting pages without server saturation:
 
@@ -49,18 +63,18 @@ How category leaders generate millions of high-converting pages without server s
 
 2. **The 4 Pillars of Zero-Latency (< 0.05ms) Resolution:**
    - **0 Bytes in Database:** Never generate physical static files or query heavy databases per request. Pages are resolved mathematically in RAM upon arrival.
-   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` (or \`app/[locale]/[...slug]/page.tsx\`) handles all matrices through one lightweight layout.
-   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge (Cloudflare / Vercel Edge) on first request.
+   - **1 Single Universal Catch-All Route:** \`app/[...slug]/page.tsx\` handles all matrices through one lightweight layout.
+   - **Edge Caching & ISR:** The rendered HTML is instantly cached at the CDN/Edge on first request.
    - **Automatic Siloing & Mesh Linking:**
      - Links to 3 neighboring geographic cities for the same service.
      - Links to 4 related professions/industries in the same target category.
      - Complete Schema.org BreadcrumbList navigation.
-   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index to respect Google's crawl budget.
+   - **Sharded XML Sitemaps:** Split into 50,000 URL chunks with a master sitemap index.
    - **Dynamic \`/llms.txt\` Feed:** High-density Markdown stream enabling direct indexing by ChatGPT Search & Perplexity.
 
 ---
 
-### 🛠️ 4. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
+### 🛠️ 5. AI AGENT IMPLEMENTATION PROTOCOL (STEP-BY-STEP)
 
 When setting up programmatic SEO in any codebase, the AI Agent MUST generate these exact 4 files:
 
@@ -72,27 +86,30 @@ export const matrixEngine = new PseoMatrixEngine();
 
 export const SEO_CONFIG = {
   brandName: "Acme",
-  language: "en",
+  language: "fr",
+  countries: ["france", "belgique", "suisse"], // Or "europe" / "international". The SDK automatically provides verified cities!
+  cleanDirectRoutes: true, // Eliminates parasite words (/solutions/, etc.)
   minPopulationToIndex: 15_000,
 };
 
 // Discovered EXCLUSIVELY from Frontend UI components
+// NOTE: DO NOT list cities manually! The SDK auto-provisions them based on your target countries/scope.
 export const PSEO_DATASET = {
   services: [
     // 1 per major frontend feature branch
-    { slug: "crm-pipeline", name: "Visual CRM Pipeline", category: "Sales", keyFeatures: ["Kanban", "Lead scoring"], description: "Visual deal tracking" },
+    { slug: "autopost-facebook", name: "Autopost Facebook & Instagram", category: "Social Media", keyFeatures: ["AI Scheduling", "Visual Calendar", "Auto-Hashtags"], description: "Automated social media posting engine" },
   ],
   targets: [
-    { slug: "law-firms", name: "Law Firms", type: "industry", painPoints: ["Billing"], benefits: ["Compliance"] },
+    { slug: "agences", name: "Marketing Agencies", type: "industry", painPoints: ["Manual Posting"], benefits: ["10x Output"] },
   ],
   integrations: [
-    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Order sync"] },
+    { slug: "shopify", name: "Shopify", category: "E-Commerce", syncFeatures: ["Catalog sync"] },
   ],
   templates: [
-    { slug: "sales-tracker-excel", title: "Sales Tracker", topic: "Sales", format: "excel", benefits: ["Instant setup"] },
+    { slug: "social-calendar-excel", title: "Social Media Calendar", topic: "Social Media", format: "excel", benefits: ["Instant setup"] },
   ],
   glossaryTerms: [
-    { slug: "mrr", term: "MRR", shortDefinition: "Monthly Recurring Revenue" },
+    { slug: "engagement-rate", term: "Engagement Rate", shortDefinition: "Percentage of audience interacting with content" },
   ],
 };
 \`\`\`
@@ -105,19 +122,15 @@ import { matrixEngine, SEO_CONFIG, PSEO_DATASET } from "@/lib/seo";
 import { renderBrandIconSvg } from "@lynxflow/seo-engine";
 
 export async function generateMetadata({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) return {};
   return { title: page.title, description: page.description, alternates: { canonical: page.canonicalUrl }, robots: page.robots };
 }
 
 export default async function ProgrammaticPage({ params }: { params: { slug: string[] } }) {
-  const path = "/" + params.slug.join("/");
   const domain = process.env.NEXT_PUBLIC_SITE_URL || "https://example.com";
-  const pages = matrixEngine.generateAllMatrices(domain, PSEO_DATASET, SEO_CONFIG);
-  const page = pages.find((p) => p.urlPath === path);
+  const page = matrixEngine.resolvePage(params.slug, domain, PSEO_DATASET, SEO_CONFIG);
   if (!page) notFound();
 
   // Automatic Brand Icon Detection

package/src/matrix-engine.ts

@@ -13,6 +13,7 @@
 import { cleanSeoSlug } from "./slug-engine";
 import { LegalDisclaimerEngine } from "./legal-disclaimers";
 import { ExtendedSchemaGraphBuilder } from "./extended-schemas";
+import { resolveBuiltInLocations } from "./built-in-locations";
 
 export type MatrixFamily =
   | "local-geo"
@@ -155,6 +156,9 @@ export interface GeneratedPageMeta {
 export interface MatrixOptions {
   brandName: string;
   language?: string; // Default: "en", supports "fr", "de", "es", "pt", "it", etc.
+  countries?: string[] | string; // e.g. ["france", "spain"] or "europe" or "international"
+  territories?: string[] | string; // Alias for countries
+  cleanDirectRoutes?: boolean; // When true (default), eliminates parasite words (/solutions/, etc.) for direct /{service}/{city}
   minPopulationToIndex?: number;
   defaultCurrency?: string;
   defaultCurrencySymbol?: string;
@@ -263,7 +267,10 @@ export class PseoMatrixEngine {
         const citySlug = cleanSeoSlug(loc.slug, { language: lang });
         const serviceSlug = cleanSeoSlug(s.slug, { language: lang });
 
-        const urlPath = `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
+        // Zero parasite words: Direct /{service}/{city} or /{service}/{country}/{city} if specified
+        const urlPath = options.cleanDirectRoutes !== false
+          ? `/${serviceSlug}/${citySlug}`
+          : `${prefix}/${serviceSlug}/${countryCode}/${citySlug}`;
         const fullUrl = `${cleanDomain}${urlPath}`;
 
         const isIndexed = (loc.population ?? 20_000) >= minPop;
@@ -786,8 +793,11 @@ export class PseoMatrixEngine {
   ): GeneratedPageMeta[] {
     const allPages: GeneratedPageMeta[] = [];
 
-    if (data.services && data.locations) {
-      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, data.locations, options));
+    if (data.services) {
+      const locs = data.locations && data.locations.length > 0
+        ? data.locations
+        : resolveBuiltInLocations(options.countries || options.territories || options.language || "fr");
+      allPages.push(...this.generateLocalGeoMatrix(domain, data.services, locs, options));
     }
     if (data.competitors) {
       allPages.push(...this.generateVsMatrix(domain, data.competitors, options));
@@ -815,4 +825,83 @@ export class PseoMatrixEngine {
 
     return allPages;
   }
+
+  /**
+   * Resolves a single page route in RAM in < 0.05ms.
+   * Matches string path or Next.js slug array.
+   */
+  resolvePage(
+    slugOrPath: string | string[],
+    domain: string,
+    data: {
+      services?: PseoService[];
+      locations?: PseoLocation[];
+      competitors?: PseoCompetitor[];
+      targets?: PseoTarget[];
+      integrations?: PseoIntegration[];
+      useCases?: PseoUseCase[];
+      templates?: PseoTemplate[];
+      glossaryTerms?: PseoGlossaryTerm[];
+      calculators?: PseoCalculator[];
+    },
+    options: MatrixOptions,
+  ): GeneratedPageMeta | undefined {
+    const path = typeof slugOrPath === "string"
+      ? (slugOrPath.startsWith("/") ? slugOrPath : `/${slugOrPath}`)
+      : `/${slugOrPath.join("/")}`;
+
+    const pages = this.generateAllMatrices(domain, data, options);
+    return pages.find((p) => p.urlPath === path);
+  }
+
+  /**
+   * Generates a fully formatted XML Sitemap string.
+   */
+  generateSitemapXml(
+    domain: string,
+    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
+    options: MatrixOptions,
+  ): string {
+    const pages = this.generateAllMatrices(domain, data, options).filter((p) => p.robots.includes("index"));
+    const now = new Date().toISOString();
+
+    const urls = pages
+      .map(
+        (p) => `  <url>
+    <loc>${p.canonicalUrl}</loc>
+    <lastmod>${now}</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.8</priority>
+  </url>`,
+      )
+      .join("\n");
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls}
+</urlset>`;
+  }
+
+  /**
+   * Generates an official /llms.txt Markdown directory for AI search bots.
+   */
+  generateLlmsTxt(
+    domain: string,
+    data: Parameters<PseoMatrixEngine["generateAllMatrices"]>[1],
+    options: MatrixOptions,
+  ): string {
+    const pages = this.generateAllMatrices(domain, data, options);
+    const lines: string[] = [
+      `# ${options.brandName} — AI Knowledge Graph & Page Hub`,
+      `> Complete index of services, tools, integrations, and local solution hubs.`,
+      "",
+      `## Indexed Programmatic Hubs (${pages.length} Pages)`,
+    ];
+
+    for (const p of pages) {
+      lines.push(`- [${p.h1}](${p.canonicalUrl}): ${p.description}`);
+    }
+
+    return lines.join("\n");
+  }
 }