georeference 0.0.0-stage → 1.0.0

package/docs/architecture.fr.md

@@ -0,0 +1,105 @@
+# Architecture et adaptateurs
+
+[English](architecture.md) · [Accueil](../README.fr.md)
+
+```text
+CLI ponctuelle → téléchargement GeoNames / source conservée
+              ↓
+Entrée canonique / texte GeoNames
+              ↓
+        validation → instantané SQLite versionné
+                              ↓
+               sélection géographique + résolution des ancêtres
+                              ↓
+                    itérateur d'entités canoniques
+                              ↓
+                       adaptateur de format
+                              ↓
+                fichiers + compression + manifeste
+                              ↓
+                      paquet d'export vérifié
+
+Paquet → validation → plan d'import → adaptateur PostgreSQL → base cible
+Instantané local → SDK de lecture → recherches/itérations applicatives
+```
+
+Le contrat partagé se trouve dans `src/types.ts`. Le cœur possède les règles d'identifiants, d'intégrité du graphe, de sélection et de projection géométrique. Les adaptateurs possèdent l'encodage et la validation propres aux formats. Le coordinateur d'export gère les sorties temporaires, le packaging, les empreintes et la publication. Le seeder gère les mises à jour en base ; le SDK gère la consultation, pas la synchronisation d'une base applicative.
+
+L'orchestrateur ponctuel (`src/generate.ts`) télécharge une source countryInfo bornée ou lit un fichier local, dérive une version de son empreinte, crée un instantané temporaire et délègue au coordinateur d'export existant. Avec `--snapshot`, il utilise directement l'instantané fourni. Il gère le nettoyage sans installation persistante dans le projet. Les fichiers générés sont autonomes ; l'import du SDK reste optionnel. Voir [la génération](generation.fr.md).
+
+Le contrat `ExportAdapter` déclare `format`, `version`, `validate(request)` et `write(context)`. Le contexte contient l'itérateur canonique réutilisable, le plan résolu, le répertoire de sortie et un signal d'annulation facultatif. Le writer renvoie des noms de fichiers relatifs après fermeture de ses ressources. Il refuse les combinaisons non supportées avant génération et préserve les IDs stables.
+
+Ajouter un format consiste à implémenter ce contrat, l'enregistrer et écrire des tests de comportement/compatibilité de lecture. Les filtres géographiques et l'attribution des IDs restent dans le cœur. La fonction `registerExportAdapter(adapter)` de la bibliothèque accepte un nom de format personnalisé pour le processus courant ; les doublons et le remplacement des formats intégrés sont refusés. La CLI énumère les formats intégrés ; les writers personnalisés sont enregistrés par le code applicatif. Les formats existants ne nécessitent pas de lourdes dépendances SIG natives.
+
+## Enregistrer un writer personnalisé
+
+Cet exemple applicatif exporte un ID stable par ligne et refuse les demandes d'arborescence ou de géométrie, car ce format contient volontairement les IDs seuls :
+
+```ts
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Snapshot, exportSnapshot, registerExportAdapter } from 'georeference';
+
+registerExportAdapter({
+  format: 'entity-ids',
+  version: '1.0.0',
+  validate(request) {
+    if (request.layout === 'hierarchical' || request.coordinates || request.boundaries) {
+      throw new Error('entity-ids supports flat IDs without geometry');
+    }
+  },
+  async write({ plan, directory, signal }) {
+    const file = await open(join(directory, 'ids.txt'), 'wx');
+    try {
+      for (const entity of plan.entities()) {
+        signal?.throwIfAborted();
+        await file.write(entity.id + '\n');
+      }
+    } finally {
+      await file.close();
+    }
+    return ['ids.txt'];
+  },
+});
+
+const snapshot = Snapshot.open('data/example.sqlite');
+try {
+  await exportSnapshot(snapshot, 'exports/entity-ids', { format: 'entity-ids' });
+} finally {
+  snapshot.close();
+}
+```
+
+Renvoyez les noms relatifs après fermeture des ressources. Le coordinateur fournit aussi au format personnalisé le manifeste, les vérifications d'intégrité, la compression, l'annulation et la publication atomique. Un format personnalisé ne devient pas automatiquement une entrée du seeder.
+
+## Libérer les plans de sélection
+
+`Snapshot.select()` renvoie un plan dont l'itérateur `entities()` peut être relu jusqu'à sa libération. Les utilisateurs de cette API doivent libérer les ressources temporaires après usage :
+
+```ts
+import { Snapshot } from 'georeference';
+
+const snapshot = Snapshot.open('data/example.sqlite');
+try {
+  const plan = snapshot.select({ countries: ['XZ'] });
+  try {
+    for (const entity of plan.entities()) console.log(entity.id);
+  } finally {
+    plan.dispose?.();
+  }
+} finally {
+  snapshot.close();
+}
+```
+
+Gardez l'instantané ouvert pendant l'utilisation du plan. Le coordinateur d'export et le SDK libèrent automatiquement leurs propres plans ; les appels directs à `select()` impliquent de gérer ce cycle de vie.
+
+## Gestion des ressources
+
+Les instantanés utilisent SQLite au lieu de relire entièrement la source pour chaque export. Les itérateurs permettent une écriture progressive des formats plats ; les sorties hiérarchiques et certains imports nécessitent une matérialisation bornée. Un seul polygone peut rester volumineux. Annulation, nettoyage et publication atomique appartiennent au coordinateur ; l'application qui utilise la bibliothèque fixe l'ordonnancement et les limites de stockage.
+
+La V1 n'inclut ni file de jobs hébergée, ni tableau de bord, ni service distant de SDK, ni moteur universel de réconciliation des sources. Ces services pourront envelopper la bibliothèque sans changer le contrat des entités. Une API progressive ne constitue pas une garantie de capacité : mesurez le jeu de données, le writer, la concurrence et le déploiement.
+
+## Versions distinctes
+
+Version du jeu de données, du contrat, de l'adaptateur et du paquet ont des sens différents. Les révisions sources et empreintes rendent la provenance visible. Une même sélection logique doit préserver valeurs et IDs ; la régénération binaire identique entre bibliothèques/outils de compression différents constitue une garantie séparée.

package/docs/architecture.md

@@ -0,0 +1,105 @@
+# Architecture and adapters
+
+[Français](architecture.fr.md) · [Home](../README.md)
+
+```text
+One-shot CLI → GeoNames download / retained source file
+              ↓
+Canonical input / GeoNames text
+              ↓
+        validation → versioned SQLite snapshot
+                              ↓
+              geographic selection + ancestor resolution
+                              ↓
+                   canonical entity iterator
+                              ↓
+                         format adapter
+                              ↓
+             data files + compression + manifest
+                              ↓
+                    verified export package
+
+Export package → validation → import plan → PostgreSQL adapter → target database
+Local snapshot → read SDK → application lookups/iteration
+```
+
+The shared contract lives in `src/types.ts`. Core rules own identifiers, graph integrity, selection, and projected geometry. Adapters own encoding and format-specific validation. The export coordinator owns temporary output, packaging, checksums, and publication. The seeder owns database update semantics; the SDK owns read access, not database synchronization.
+
+The one-shot CLI orchestrator (`src/generate.ts`) downloads a bounded countryInfo source or reads a local file, derives a source-hash version, creates a temporary snapshot and delegates to the existing export coordinator. With `--snapshot`, it uses the supplied snapshot directly. It owns cleanup, not a persistent project installation. Generated data files are standalone; importing the SDK remains optional. See [generation](generation.md).
+
+The `ExportAdapter` contract declares `format`, `version`, `validate(request)`, and `write(context)`. Its context includes a repeatable canonical entity iterator, resolved plan, output directory, and optional cancellation signal. A writer returns relative filenames after closing its handles. It must reject unsupported combinations before producing output and preserve stable IDs.
+
+Adding a format means implementing that contract, registering it, and writing behavior/reader compatibility tests. Geographic filtering and identifier allocation do not move into the new writer. The library's `registerExportAdapter(adapter)` accepts a custom format string for the current process; duplicate registrations and overriding built-in formats are rejected. The CLI lists the built-in formats; custom writers are registered by application code. Heavy native geospatial dependencies are not required for existing formats.
+
+## Register a custom writer
+
+This application-level example exports one stable ID per line and refuses tree or geometry requests, since this format deliberately contains IDs only:
+
+```ts
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Snapshot, exportSnapshot, registerExportAdapter } from 'georeference';
+
+registerExportAdapter({
+  format: 'entity-ids',
+  version: '1.0.0',
+  validate(request) {
+    if (request.layout === 'hierarchical' || request.coordinates || request.boundaries) {
+      throw new Error('entity-ids supports flat IDs without geometry');
+    }
+  },
+  async write({ plan, directory, signal }) {
+    const file = await open(join(directory, 'ids.txt'), 'wx');
+    try {
+      for (const entity of plan.entities()) {
+        signal?.throwIfAborted();
+        await file.write(entity.id + '\n');
+      }
+    } finally {
+      await file.close();
+    }
+    return ['ids.txt'];
+  },
+});
+
+const snapshot = Snapshot.open('data/example.sqlite');
+try {
+  await exportSnapshot(snapshot, 'exports/entity-ids', { format: 'entity-ids' });
+} finally {
+  snapshot.close();
+}
+```
+
+Return relative filenames after closing resources. The coordinator supplies manifest generation, integrity checks, compression, cancellation, and atomic publication to the custom format too. A custom format is not automatically a supported seeder input.
+
+## Release selection plans
+
+`Snapshot.select()` returns a plan whose `entities()` iterator can be read repeatedly until disposal. Lower-level callers must release the plan's temporary selection resources after use:
+
+```ts
+import { Snapshot } from 'georeference';
+
+const snapshot = Snapshot.open('data/example.sqlite');
+try {
+  const plan = snapshot.select({ countries: ['XZ'] });
+  try {
+    for (const entity of plan.entities()) console.log(entity.id);
+  } finally {
+    plan.dispose?.();
+  }
+} finally {
+  snapshot.close();
+}
+```
+
+Keep the snapshot open while using the plan. The export coordinator and read SDK release their own plans automatically; consumers directly calling `select()` own that lifecycle.
+
+## Resource behavior
+
+Snapshots use SQLite rather than forcing every export to load the source file again. Iterators let flat writers process records progressively; hierarchical output and some import paths require bounded materialization. A single polygon can still be large. Cancellation, output cleanup, and atomic publication belong to the coordinator; applications embedding the library decide their job scheduling and storage limits.
+
+V1 does not include a hosted job queue, dashboard, SDK remote service, or universal source reconciliation engine. Such services can wrap the library without changing the entity contract. Do not infer an operational capacity guarantee from a streaming API: measure the chosen dataset, writer, concurrency, and deployment.
+
+## Version boundaries
+
+Dataset version, contract version, adapter version, and package version have different meanings. Source revisions and checksums make provenance visible. The same logical selection should preserve values and IDs; byte-identical regeneration across different binary libraries or compression tools is a separate guarantee.

package/docs/data-sources.fr.md

@@ -0,0 +1,39 @@
+# Sources et licences des données
+
+[English](data-sources.md) · [Accueil](../README.fr.md)
+
+## La licence du logiciel n'est pas celle des données
+
+Le code, la documentation et les exemples fictifs de GeoReference sont sous MIT. Les données géographiques tierces conservent leur licence et leurs exigences d'attribution. Le manifeste transporte les métadonnées sources pour que les destinataires les conservent. Vérifiez les droits de redistribution avant d'ajouter ou de publier une source ; un writer fonctionnel n'accorde aucun droit sur ses données d'entrée.
+
+## Entrées GeoNames
+
+L'importeur local accepte les fichiers GeoNames UTF-8 séparés par tabulations :
+
+| Option CLI | Entrée | Couverture de cet importeur |
+|---|---|---|
+| `--countries` | `countryInfo.txt` | Noms/codes pays et identifiants sources ; obligatoire |
+| `--admin1` | `admin1CodesASCII.txt` | Premier niveau administratif ; facultatif |
+| `--admin2` | `admin2Codes.txt` | Deuxième niveau administratif ; facultatif |
+| `--places` | Fichier d'entités GeoNames extrait, par exemple `cities1000.txt` | Lieux habités (classe `P`) et coordonnées ponctuelles ; facultatif |
+
+GeoNames publie ses extraits sous [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/). Consultez [la documentation officielle](https://download.geonames.org/export/dump/readme.txt) et [le répertoire de téléchargement](https://download.geonames.org/export/dump/). GeoReference enregistre l'attribution GeoNames, l'URL source et une révision SHA-256 de chaque fichier. Cette empreinte identifie les octets locaux ; elle ne certifie pas que tous les fichiers proviennent de la même date de publication.
+
+Téléchargez et extrayez avant ingestion. Conservez les fichiers téléchargés pour reproduire un instantané ; attribuez une `--version` pertinente sans remplacer silencieusement une version publiée. Ce parcours hors ligne ne demande ni compte GeoNames ni clé API.
+
+Le [générateur ponctuel de pays](generation.fr.md) télécharge automatiquement uniquement `countryInfo.txt`, avec une limite de 2 Mio et un délai de 30 secondes. Il dérive les versions du SHA-256 de la source et conserve licence/attribution dans les fichiers générés. `--source-file` évite le réseau avec un fichier conservé ; subdivisions, localités et frontières demandent un instantané fourni ou le parcours d'ingestion avancé.
+
+## Limites de couverture explicites
+
+- L'importeur exploite les fichiers administratifs de niveau 1/2 fournis ; il ne promet pas tous les niveaux administratifs ni toutes les localités mondiales. Les petits extraits de villes sont des sous-ensembles.
+- Un fichier ou rattachement administratif absent conduit au plus proche ancêtre fourni. Le code brut `geonamesAdmin` reste disponible ; cela n'affirme pas l'absence de niveaux intermédiaires.
+- CountryInfo seul ne fournit pas les géométries ponctuelles facultatives dans cet importeur. Aucun point n'est inventé pour les pays/subdivisions. Cet adaptateur n'importe ni frontières ni noms alternatifs avec langue.
+- Le cœur accepte des polygones/multipolygones canoniques depuis vos propres sources dûment licenciées. Il ne reconstitue pas une frontière à partir de points et ne tranche pas les revendications territoriales.
+- La lecture des fichiers est progressive, mais cet importeur conserve les entités canoniques et tables de correspondance en mémoire avant création de l'instantané. Il convient à des entrées mesurées, sans garantie illimitée pour `allCountries`. Utilisez des entrées bornées par pays/taille et mesurez les ressources.
+- Les doublons, IDs/coordonnées mal formés et références vers des pays inconnus font échouer l'ingestion. Modifications, suppressions, fusions et scissions exigent des règles d'identité explicites ; les IDs stables ne réconcilient pas automatiquement l'historique.
+
+Les jeux générés, instantanés, téléchargements sources et exports restent dans des répertoires locaux ignorés comme `data/` et `exports/`. Ils ne sont pas commités dans le dépôt logiciel.
+
+## Exemple fictif
+
+L'[exemple suivi](../examples/README.md) décrit des lieux fictifs, une frontière carrée inventée et des coordonnées de démonstration. Son URL source est réservée et invalide ; sa licence est MIT. Il sert aux tutoriels et tests, pas à des décisions géographiques.

package/docs/data-sources.md

@@ -0,0 +1,39 @@
+# Data sources and licenses
+
+[Français](data-sources.fr.md) · [Home](../README.md)
+
+## Software is not a dataset license
+
+GeoReference's code, documentation, and synthetic examples are MIT licensed. Third-party geographic data retains its own license and attribution requirements. An export manifest carries source metadata so recipients can retain that information. Check redistribution rights before adding or publishing any source; a working writer cannot grant rights to its input data.
+
+## GeoNames input
+
+The local importer accepts UTF-8, tab-separated GeoNames files:
+
+| CLI option | Input | Coverage in this importer |
+|---|---|---|
+| `--countries` | `countryInfo.txt` | Country names/codes and source identifiers; required |
+| `--admin1` | `admin1CodesASCII.txt` | First administrative level; optional |
+| `--admin2` | `admin2Codes.txt` | Second administrative level; optional |
+| `--places` | An extracted GeoNames feature file, e.g. `cities1000.txt` | Populated places (feature class `P`) and point coordinates; optional |
+
+GeoNames publishes its extracts under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/). See its [official extract documentation](https://download.geonames.org/export/dump/readme.txt) and [download directory](https://download.geonames.org/export/dump/). GeoReference records GeoNames attribution, the source URL, and a SHA-256 revision of each input file. The checksum identifies the actual local bytes, not a claim that all source files came from the same upstream date.
+
+Download and extract files before ingestion. Keep the same downloaded files to reproduce a snapshot; assign a meaningful `--version` and do not silently replace published versions. No GeoNames username or API key is required for this offline path.
+
+The [one-shot country generator](generation.md) automatically downloads only `countryInfo.txt`, bounded to 2 MiB with a 30-second timeout. It derives dataset versions from source SHA-256 and retains the license/attribution in generated files. `--source-file` bypasses the network with a retained file; subdivisions, localities and boundaries require a supplied snapshot or the advanced ingestion workflow.
+
+## Deliberate coverage limits
+
+- The importer maps supplied level 1/2 administrative files; it does not claim every administrative level or every locality worldwide. Smaller city extracts are subsets.
+- Missing administrative files or entries attach a locality/subdivision to its nearest supplied ancestor. The raw `geonamesAdmin` code remains available; this does not assert there are no intermediate administrative levels.
+- CountryInfo alone does not provide the optional point geometries in this importer. Countries/subdivisions have no invented coordinates. Boundaries and language-tagged alternate names are not ingested by this adapter.
+- The core accepts canonical polygons/multipolygons from your own appropriately licensed input. It cannot reconstruct boundaries from points or settle contested administrative claims.
+- Parsing reads files progressively, but this GeoNames importer retains canonical records and lookup maps in memory before snapshot creation. It is intended for measured inputs, not an unbounded `allCountries` ingestion guarantee. Use country/size-limited inputs and measure resources.
+- Duplicate IDs, malformed IDs/coordinates, and unknown country references fail ingestion. Source changes, deletions, mergers, and splits need explicit identity policies; exported stable IDs do not by themselves reconcile history.
+
+Generated datasets, snapshots, source downloads, and exports belong in ignored local directories such as `data/` and `exports/`. They are not committed into this software repository.
+
+## Synthetic example
+
+The committed [example](../examples/README.md) describes fictional places, an invented square boundary, and demonstration coordinates. It uses a reserved invalid source URL and MIT licensing. It is suitable for tutorials and tests, not for geographical decisions.

package/docs/format-decisions.fr.md

@@ -0,0 +1,54 @@
+# Choix des formats
+
+[English](format-decisions.md) · [Formats pris en charge](formats.fr.md) · [Accueil](../README.fr.md)
+
+Décisions réexaminées le 12 novembre 2026.
+
+Cette comparaison explique le périmètre V1 et les besoins auxquels répondrait un autre adaptateur. **V1** désigne l'un des six adaptateurs intégrés ; **ultérieur** signifie évalué mais non pris en charge par la CLI livrée. Les priorités suivantes dépendent d'une demande d'intégration concrète, sans engagement à développer tous les formats.
+
+La complexité inclut génération et validation d'interopérabilité : **faible**, **moyenne** ou **élevée**, par rapport au contrat canonique commun. Les dépendances des formats ultérieurs sont des catégories probables, pas des paquets installés ni des versions approuvées. Qualité, couverture et droits de redistribution restent des prérequis pour chaque format.
+
+## Comparaison
+
+| Format | Usages concrets | Pertinence pour GeoReference | Complexité de génération | Dépendances | Limites principales | Priorité |
+|---|---|---|---|---|---|---|
+| JSON | Échanges applicatifs, fixtures, arbres de pays/subdivisions | Très forte pour les intégrations générales | Faible en plat ; moyenne en hiérarchie | Sérialisation JSON native et flux de fichiers | Verbeux ; de nombreux lecteurs chargent tout ; sortie hiérarchique V1 bornée à 50 000 entités | **V1**, `json` |
+| JSON Lines / NDJSON | ETL, lecture progressive, amorçage par lots | Très forte pour les pipelines plats | Faible | Sérialisation JSON native et flux | Une entité complète par ligne ; une grande frontière reste un grand enregistrement ; schéma/provenance dans le manifeste | **V1**, `ndjson` |
+| CSV | Tableurs, BI, intégrations tabulaires traditionnelles | Très forte pour l'accessibilité | Faible à moyenne | V1 utilise `csv-stringify` ; `csv-parse` pour l'import de paquets | Pas de types ni de hiérarchie intrinsèques ; conversion des IDs/formules en tableur à traiter explicitement ; cellules structurées selon le contrat machine | **V1**, `csv` |
+| SQL PostgreSQL | Initialisation du schéma standard, scripts de base examinables | Forte pour les applications serveur et la première cible d'amorçage | Moyenne | Générateur SQL ; PostgreSQL pour validation ; `pg` pour l'amorçage connecté | Dialecte PostgreSQL seul ; création ≠ migration ; data-only exige des tables compatibles ; grands scripts potentiellement peu efficaces | **V1**, `sql-postgres` |
+| SQL MySQL / MariaDB | Applications utilisant déjà ces moteurs | Forte lorsque les destinataires l'exigent | Moyenne à élevée | Profils/générateurs séparés et tests indépendants des moteurs | DDL, échappement, collations et expressions UPSERT varient selon moteur/version ; une histoire commune ne prouve pas la compatibilité | **Ultérieur**, selon la demande |
+| Script SQL SQLite | Reconstruction textuelle examinable d'une base locale | Moyenne ; recoupe le fichier SQLite prêt à l'emploi | Moyenne | Générateur SQL SQLite ; moteur SQLite pour validation | Chargement texte encore nécessaire ; typage, limites de lots et activation des clés étrangères propres au moteur ; pas du SQL PostgreSQL | **Ultérieur**, sur besoin de script démontré |
+| SQLite prêt à l'emploi | Applications hors ligne, requêtes locales, inspection de base | Très forte pour un artefact portable directement interrogeable | Moyenne | V1 utilise `node:sqlite` intégré | Nécessite finalisation/fermeture ; base relationnelle exportée distincte du contrat d'instantané interne ; SQLite ordinaire n'est pas GeoPackage | **V1**, `sqlite` |
+| Modules de données TypeScript | Petites listes de pays et imports à la compilation côté frontend | Forte pour de petits sous-ensembles ; faible pour toutes les géométries mondiales | Faible à moyenne | Générateur de modules et validation par compilateur TypeScript | Coût de compilation/bundle ; types statiques sans validation des entrées arbitraires à l'exécution ; données en code distinctes d'un SDK | **Ultérieur** ; SDK de lecture déjà en V1 |
+| YAML | Configuration modifiée à la main et petites fixtures lisibles | Faible à moyenne ; peu d'apport face à JSON pour le transport massif | Faible à moyenne | Sérialiseur YAML 1.2 | Citations de scalaires/choix du schéma influent sur les lecteurs ; peu adapté aux gros jeux ; préserver les IDs en chaînes | **Ultérieur**, selon un besoin de configuration |
+| GeoJSON | Cartes web, inspection spatiale, échange de points/frontières | Très forte si les géométries sont disponibles et redistribuables | Moyenne | JSON natif et validation géométrique du cœur | Ordre WGS84 longitude/latitude ; frontières volumineuses ; couches points/frontières séparées ; géométrie absente conservée null | **V1**, `geojson` |
+| Parquet | Analyse, entrepôts, lecture de colonnes choisies | Forte pour des traitements analytiques importants | Moyenne à élevée | Writer Parquet et codecs ; outils fondés sur Arrow possibles | Schéma binaire, dimensionnement des groupes de lignes, compatibilité lecteurs ; pas de clés étrangères imposées ; non lisible directement | **Ultérieur**, premier candidat analytique |
+| GeoParquet | Analyse spatiale de grandes collections de points/frontières | Forte une fois un public d'analyse SIG identifié | Élevée | Writer Parquet/géospatial compatible et profil GeoParquet fixé | Typage/encodage, CRS, métadonnées et versions des lecteurs doivent s'accorder ; une colonne géométrique binaire seule ne suffit pas | **Ultérieur**, après le parcours Parquet |
+| GeoPackage | Échange SIG bureautique, bases spatiales hors ligne, couches multiples | Forte pour les usages QGIS/SIG | Élevée | Writer conforme, souvent GDAL/OGR avec support SQLite | Métadonnées et encodage OGC requis ; renommer SQLite ne suffit pas ; règles de couches/géométries à valider | **Ultérieur**, préféré avant Shapefile pour les nouveaux parcours SIG |
+| Shapefile livré en ZIP | Anciennes chaînes SIG imposant ce format | Faible par défaut ; forte pour un destinataire historique précis | Élevée | Writer SIG comme GDAL/OGR, support DBF/encodage, ZIP multifichier | Noms traditionnellement limités à 10 caractères, attributs limités, troncatures possibles ; viser au plus 2 Go par composant pour l'interopérabilité | **Ultérieur**, exigence de compatibilité explicite |
+
+Références de format : [spécification NDJSON](https://github.com/ndjson/ndjson-spec), [CSV RFC 4180](https://www.rfc-editor.org/rfc/rfc4180), [modules TypeScript](https://www.typescriptlang.org/docs/handbook/2/modules.html), [YAML 1.2.2](https://yaml.org/spec/1.2.2/), [GeoJSON RFC 7946](https://www.rfc-editor.org/rfc/rfc7946), [Apache Parquet](https://parquet.apache.org/docs/), [spécification GeoParquet](https://geoparquet.org/), [GeoPackage OGC](https://www.ogc.org/standards/geopackage/) et [limites Shapefile GDAL](https://gdal.org/en/stable/drivers/vector/shapefile.html).
+
+## Pourquoi PostgreSQL en premier
+
+Un parcours d'import complet apporte davantage que plusieurs variantes SQL non vérifiées. PostgreSQL donne à la V1 une cible de conflit explicite avec `ON CONFLICT`, des mises à jour transactionnelles et un seul moteur à valider pour le schéma standard comme pour les tables applicatives mappées. Il s'agit d'un choix de périmètre, sans affirmer que les autres moteurs empêchent un amorçage fiable. Voir [INSERT PostgreSQL](https://www.postgresql.org/docs/current/sql-insert.html).
+
+MySQL et MariaDB utilisent `ON DUPLICATE KEY UPDATE`, avec leurs règles de conflits de clés uniques et de valeurs entrantes. Un adaptateur devra fixer les moteurs/versions et tester séparément échappement, collations, DDL et mises à jour. SQLite nécessite aussi son profil SQL ; les clés étrangères doivent être activées explicitement par connexion. Références : [MySQL](https://dev.mysql.com/doc/refman/8.4/en/insert-on-duplicate.html), [MariaDB](https://mariadb.com/docs/server/reference/sql-statements/data-manipulation/inserting-loading-data/insert-on-duplicate-key-update), [clés étrangères SQLite](https://www.sqlite.org/foreignkeys.html).
+
+## Fichiers, amorçage et SDK sont des choix distincts
+
+| Besoin | Réponse V1 | Pourquoi le format seul ne suffit pas |
+|---|---|---|
+| Échanger ou archiver un instantané versionné | Adaptateur de fichiers, compression, manifeste, empreintes | Le destinataire a encore besoin d'un lecteur compatible et des licences sources |
+| Initialiser/actualiser une base applicative existante | Seeder PostgreSQL avec aperçu, mapping, champs gérés, révisions et reprise | Un fichier SQL ne résout pas les clés locales, la propriété des champs, les mises à jour anciennes ni les interruptions |
+| Consulter des entités depuis une application | SDK de lecture sur instantané local | Un module de données TypeScript ne fournit pas à lui seul chargement/requêtes ou synchronisation d'une base |
+
+Le [guide d'amorçage](seeding.fr.md) définit les garanties de mise à jour ; la [prise en main](getting-started.fr.md) montre le SDK. Ajouter un export SQL MySQL ne créerait pas automatiquement un seeder MySQL. Ajouter un export de modules TypeScript ne remplacerait pas le SDK.
+
+## Étendre les formats
+
+L'[API d'adaptateur](architecture.fr.md) ajoute un encodage sans déplacer sélection et IDs stables hors du cœur. Un adaptateur peut utiliser un stockage temporaire/à accès aléatoire si le streaming seul ne convient pas. Les dépendances géospatiales spécialisées restent facultatives pour le parcours léger existant.
+
+Avant d'annoncer un format, identifiez destinataire/lecteur réel, versions testées, pertes déclarées, couverture géométrique, licences, limites de ressources et relecture indépendante. Pour GeoParquet, choisissez le profil d'interopérabilité selon les lecteurs visés sans supposer que la spécification la plus récente est partout disponible ; le site actuel comprend la version 2.0. La documentation du pilote Parquet GDAL décrit ses profils GeoParquet pris en charge. Références : [GeoParquet](https://geoparquet.org/), [pilote Parquet GDAL](https://gdal.org/en/stable/drivers/vector/parquet.html).
+
+Pour un public SIG bureautique, GeoPackage peut précéder Parquet ; pour l'analyse en entrepôt, l'ordre peut s'inverser. Préservez l'ID stable GeoReference en attribut même si le format utilise son propre identifiant technique de ligne. Validez tables/encodage GeoPackage avec un lecteur conforme ; voir [le pilote GeoPackage GDAL](https://gdal.org/en/stable/drivers/vector/gpkg.html). Ces évaluations n'activent aucun format absent de la CLI V1 livrée.

package/docs/format-decisions.md

@@ -0,0 +1,54 @@
+# Format decisions
+
+[Français](format-decisions.fr.md) · [Supported formats](formats.md) · [Home](../README.md)
+
+Decision record reviewed November 12, 2026.
+
+This comparison explains the V1 boundary and where another adapter would be useful. **V1** means one of the six implemented built-in adapters; **later** means evaluated but unsupported by the shipped CLI. Later priorities are driven by a concrete integration request, not a promise to implement every format.
+
+Complexity includes generation and interoperability validation: **low**, **medium**, or **high**, relative to the shared canonical contract. Dependencies for later formats are likely categories, not installed packages or approved version choices. Data quality, coverage, and redistribution rights remain prerequisites for every format.
+
+## Comparison
+
+| Format | Concrete uses | Relevance to GeoReference | Generation complexity | Dependencies | Main limits | Priority |
+|---|---|---|---|---|---|---|
+| JSON | Application exchange, fixtures, nested country/subdivision trees | Very high for general integrations | Low flat; medium hierarchical | Native JSON serialization and file streams | Verbose; many readers materialize the whole document; hierarchical V1 output is bounded to 50,000 entities | **V1**, `json` |
+| JSON Lines / NDJSON | ETL, incremental reads, batch seeding | Very high for flat pipelines | Low | Native JSON serialization and streams | One complete entity per line; a large boundary still creates a large record; schema/provenance are in the manifest | **V1**, `ndjson` |
+| CSV | Spreadsheets, BI, traditional tabular integrations | Very high for broad accessibility | Low to medium | V1 uses `csv-stringify`; `csv-parse` for package import | No intrinsic types or hierarchy; spreadsheet ID conversion and formula-like cells need explicit profiles; structured cells follow the documented machine contract | **V1**, `csv` |
+| PostgreSQL SQL | Standard-schema initialization, reviewable database scripts | High for server applications and the first seeding target | Medium | SQL generator; PostgreSQL for validation; `pg` belongs to live seeding | PostgreSQL dialect only; schema creation is not migration; data-only needs compatible tables; large scripts can be inefficient | **V1**, `sql-postgres` |
+| MySQL / MariaDB SQL | Applications already using those database engines | High when recipients require them | Medium to high | Separate dialect profiles/generators and independent engine tests | DDL, quoting, collations, and UPSERT expressions vary by engine/version; shared product history does not establish compatibility | **Later**, demand-driven |
+| SQLite SQL script | Reviewable textual reconstruction of a local database | Medium; overlaps with the ready-to-use SQLite file | Medium | SQLite SQL generator; SQLite engine for validation | Text loading step still needed; engine-specific typing, batch limits, and foreign-key activation; not a PostgreSQL script | **Later**, after a demonstrated script use case |
+| Ready-to-use SQLite | Offline applications, local queries, database inspection | Very high for a portable, directly queryable artifact | Medium | V1 uses built-in `node:sqlite` | Requires finalization/closed handles; exported relational database differs from the internal snapshot contract; ordinary SQLite is not GeoPackage | **V1**, `sqlite` |
+| TypeScript data modules | Small country lists and compile-time imports in frontend applications | High for small subsets; low for worldwide geometry bundles | Low to medium | Module generator and TypeScript compiler validation | Compile/bundle cost; static types do not validate arbitrary runtime input; data-as-code is not an SDK | **Later**; the read SDK is already V1 |
+| YAML | Human-edited configuration and small readable fixtures | Low to medium; limited benefit over JSON for bulk transfer | Low to medium | A YAML 1.2 serializer | Scalar quoting/schema choices affect reader interpretation; inefficient for large datasets; must preserve string IDs | **Later**, if a configuration workflow needs it |
+| GeoJSON | Web maps, spatial inspection, point/boundary exchange | Very high when licensed geometries exist | Medium | Native JSON output plus core geometry validation | WGS84 longitude/latitude order; verbose boundaries; separate point/boundary layers; absent geometry remains null | **V1**, `geojson` |
+| Parquet | Analytics, data warehouses, selective column reads | High for substantial analytical workloads | Medium to high | A Parquet writer and codecs; Arrow-based tooling is a candidate | Binary schema, row-group sizing, reader compatibility; no enforced relational foreign keys; not a human-readable interchange | **Later**, first analytical candidate |
+| GeoParquet | Spatial analytics over large point/boundary collections | High once a spatial analytics audience is established | High | Compatible Parquet/geospatial writer and a pinned GeoParquet profile | Geometry typing/encoding, CRS, metadata, and reader versions must agree; a binary geometry column alone is insufficient | **Later**, following the Parquet path |
+| GeoPackage | Desktop GIS exchange, offline spatial databases, multiple layers | High for QGIS/GIS workflows | High | A conforming writer, commonly GDAL/OGR with SQLite support | OGC metadata and geometry encoding required; a renamed SQLite file is not compliant; layer/geometry rules must be validated | **Later**, preferred before Shapefile for new GIS workflows |
+| Shapefile, delivered as ZIP | Older GIS pipelines that require this interchange | Low by default; high for a specific legacy recipient | High | GIS writer such as GDAL/OGR, DBF/encoding support, multifile ZIP | Traditional 10-character field names, limited attributes, possible truncation; target at most 2 GB per component for interoperability | **Later**, explicit compatibility requirement |
+
+Format references: [NDJSON specification](https://github.com/ndjson/ndjson-spec), [CSV RFC 4180](https://www.rfc-editor.org/rfc/rfc4180), [TypeScript modules](https://www.typescriptlang.org/docs/handbook/2/modules.html), [YAML 1.2.2](https://yaml.org/spec/1.2.2/), [GeoJSON RFC 7946](https://www.rfc-editor.org/rfc/rfc7946), [Apache Parquet](https://parquet.apache.org/docs/), [GeoParquet specification](https://geoparquet.org/), [OGC GeoPackage](https://www.ogc.org/standards/geopackage/), and [GDAL Shapefile limits](https://gdal.org/en/stable/drivers/vector/shapefile.html).
+
+## Why PostgreSQL first
+
+One complete import path is more useful than several unverified SQL variants. PostgreSQL gives V1 an explicit conflict target through `ON CONFLICT`, transactional updates, and one engine to validate for both the standard schema and mapped application tables. This is a product scope choice, not a claim that other engines cannot support reliable seeding. See [PostgreSQL INSERT](https://www.postgresql.org/docs/current/sql-insert.html).
+
+MySQL and MariaDB use `ON DUPLICATE KEY UPDATE`, with their own handling of unique-key conflicts and incoming values. A future adapter must pin each supported engine/version and test its quoting, collations, DDL, and update behavior separately. SQLite likewise needs its own SQL profile; foreign-key enforcement must be explicitly enabled per connection. References: [MySQL](https://dev.mysql.com/doc/refman/8.4/en/insert-on-duplicate.html), [MariaDB](https://mariadb.com/docs/server/reference/sql-statements/data-manipulation/inserting-loading-data/insert-on-duplicate-key-update), [SQLite foreign keys](https://www.sqlite.org/foreignkeys.html).
+
+## Files, seeding, and SDK are separate choices
+
+| Need | V1 answer | Why a format alone is insufficient |
+|---|---|---|
+| Exchange or archive a versioned snapshot | File adapter, compression, manifest, checksums | A recipient still needs a compatible reader and source license information |
+| Initialize/update an existing application database | PostgreSQL seeder with preview, mapping, managed fields, revisions, and recovery | An SQL file does not resolve local keys, field ownership, stale updates, or interrupted imports |
+| Look up entities from application code | Read SDK over a local snapshot | A generated TypeScript dataset module does not supply loading/query semantics or database synchronization |
+
+The [seeding guide](seeding.md) defines database update guarantees; the [getting-started guide](getting-started.md) shows SDK use. Adding MySQL SQL output would not automatically add a MySQL seeder. Adding TypeScript module output would not replace the SDK.
+
+## Extending the format set
+
+Use the [adapter API](architecture.md) to add encoding without moving selection rules or stable-ID handling out of the core. An adapter may use temporary/random-access storage when pure streaming is inappropriate. Specialized geospatial dependencies should remain optional to the existing lightweight path.
+
+Before advertising a new format, identify its real recipient/reader, test versions, declared losses, geometry coverage, licensing, resource limits, and independent read-back. For GeoParquet, choose an interoperability profile from the actual reader matrix rather than assuming the newest specification is universally available; the current specification site includes version 2.0. GDAL's documented Parquet implementation describes specific supported GeoParquet profiles. References: [GeoParquet](https://geoparquet.org/), [GDAL Parquet driver](https://gdal.org/en/stable/drivers/vector/parquet.html).
+
+For a desktop GIS audience, GeoPackage can precede Parquet; for warehouse analytics, the order can reverse. Preserve GeoReference's stable string ID as an attribute even if the target format also uses its own technical row identifier. Validate GeoPackage's required tables/encoding with a conforming reader; consult the [GDAL GeoPackage driver](https://gdal.org/en/stable/drivers/vector/gpkg.html). None of these future evaluations enables an unsupported format in the shipped V1 CLI.

package/docs/formats.fr.md

@@ -0,0 +1,34 @@
+# Formats pris en charge et limites
+
+[English](formats.md) · [Accueil](../README.fr.md)
+
+Tous les exports utilisent la même sélection et les mêmes IDs stables. Le manifeste précise version des données, provenance, options, ancêtres de contexte, références externes, couverture géométrique et sommes de contrôle. Voici les valeurs de `--format`.
+
+Pour les usages, complexités, dépendances, limites et priorités de tous les formats évalués, consultez [les choix des formats](format-decisions.fr.md).
+
+| Format | Usage en V1 | Organisation et géométries | Limites |
+|---|---|---|---|
+| `json` | Échange applicatif général | Entités plates ou `--layout hierarchical` ; coordonnées/frontières facultatives | Sortie hiérarchique limitée à 50 000 entités ; beaucoup de lecteurs chargent tout le document |
+| `ndjson` | Pipelines par lots et entrée du seeder | Une entité plate par ligne ; coordonnées/frontières facultatives | Schéma/métadonnées dans le manifeste ; une grande géométrie reste un grand enregistrement |
+| `csv` | Tableurs et échange tabulaire normalisé | Entités plates ; champs structurés en cellules JSON | Aucun typage intrinsèque ; importer les IDs comme texte dans un tableur ; pas d'arborescence |
+| `sql-postgres` | Scripts pour le schéma standard PostgreSQL | `--schema-mode schema-and-data` ou `data-only` ; `--sql-mode upsert` ou `insert-only` | Spécifique PostgreSQL, pas du SQL MySQL/MariaDB/SQLite ; data-only exige la table standard compatible |
+| `sqlite` | Base locale prête à interroger | Fichier autonome avec relations/index | Ce n'est ni GeoPackage ni SpatiaLite ; une géométrie JSON n'implique pas d'index spatial natif |
+| `geojson` | Couches cartographiques de points et frontières | FeatureCollections distinctes pour points/frontières demandés | WGS84 `[longitude, latitude]` ; les frontières ne sont pas déduites des points |
+
+Coordonnées et frontières sont indépendantes. Une géométrie absente ne devient ni `(0,0)` ni un polygone inventé. L'inclusion des ancêtres préserve par défaut l'intégrité relationnelle ; `--no-ancestors` déclare les dépendances externes.
+
+Le profil machine CSV préserve les valeurs sources. `id`, `entityType`, `name` et `countryId` sont des chaînes ordinaires ; `parentId` est une chaîne JSON ou `null`. Les champs facultatifs `codes`, `names`, `level`, `coordinates` et `boundary` sont des cellules JSON : cellule vide signifie absent, `null` littéral signifie null explicite. Les colonnes coordonnées/frontière sont omises si non demandées. `--spreadsheet-safe` est un profil de présentation explicite pour les cellules pouvant être interprétées comme formules ; cette sortie transformée ne sert pas d'échange machine sans perte.
+
+Le mode de création SQL crée le schéma standard ; ce n'est pas un moteur de migration. `CREATE TABLE IF NOT EXISTS` ne rend pas une table existante compatible. Pour actualiser une base applicative, utilisez [le seeder](seeding.fr.md) et ses règles de champs gérés/révisions.
+
+## Compression et reproduction
+
+`--compression none`, `gzip` ou `zip` contrôle le transport. Les fichiers gzip sont lus directement. Une sortie ZIP contient `manifest.json` et `package.zip` ; l'archive contient son propre manifeste et les fichiers. Vérifiez le paquet externe pour l'intégrité de l'archive ; extrayez le ZIP dans un nouveau répertoire pour vérifier/importer les fichiers. Les exports terminés sont publiés après génération ; les destinations existantes sont refusées. Une annulation/erreur ne doit pas publier un paquet partiellement complet.
+
+Conservez les artefacts publiés si les octets exacts comptent. La reproductibilité sémantique signifie qu'un même instantané et une même requête normalisée sélectionnent les mêmes valeurs/IDs ; les métadonnées binaires/compressées peuvent varier avec les versions des outils. Les sommes de contrôle vérifient l'artefact reçu, pas toute régénération future.
+
+## Formats absents de la V1
+
+SQL MySQL/MariaDB, scripts SQL SQLite, modules de données TypeScript, YAML, Parquet, GeoParquet, GeoPackage et Shapefile ne sont pas annoncés comme pris en charge. Des adaptateurs pourront les ajouter selon des besoins concrets. Un SDK TypeScript existe déjà ; il est distinct de l'export de données sous forme de code TypeScript.
+
+GeoPackage exige les métadonnées et l'encodage géométrique OGC ; renommer un `.sqlite` ne suffit pas. GeoParquet nécessite un profil/version testé, pas simplement une colonne WKB. Shapefile restreint noms/types de champs et impose plusieurs fichiers : il répond à un besoin de compatibilité plutôt qu'au choix géographique par défaut.

package/docs/formats.md

@@ -0,0 +1,34 @@
+# Supported formats and limits
+
+[Français](formats.fr.md) · [Home](../README.md)
+
+Every export uses the same selected entities and stable IDs. Its manifest records the data version, provenance, options, context ancestors, external references, geometry coverage, and checksums. `--format` names are listed below.
+
+For the uses, complexity, dependencies, limits, and priorities of all evaluated formats, read [format decisions](format-decisions.md).
+
+| Format | V1 purpose | Layout and geometry | Limitations |
+|---|---|---|---|
+| `json` | General application exchange | Flat records or `--layout hierarchical`; optional coordinates/boundaries | Hierarchical output is limited to 50,000 entities; many consumers load the whole document |
+| `ndjson` | Batch pipelines and seeder input | One flat entity per line; optional coordinates/boundaries | Schema/metadata live in the manifest; a single large geometry still makes a large record |
+| `csv` | Spreadsheets and normalized tabular exchange | Flat records; structured fields use JSON cells | No intrinsic type system; preserve IDs as text in spreadsheet import; not a hierarchical format |
+| `sql-postgres` | PostgreSQL standard-schema scripts | `--schema-mode schema-and-data` or `data-only`; `--sql-mode upsert` or `insert-only` | PostgreSQL-specific, not MySQL/MariaDB/SQLite SQL; data-only requires the compatible standard table |
+| `sqlite` | A ready-to-query local database | Standalone file with relationships/indexes | Not GeoPackage or SpatiaLite; JSON geometry does not imply native spatial indexing |
+| `geojson` | Point and boundary map layers | Separate point/boundary FeatureCollections when requested | WGS84 `[longitude, latitude]`; polygon boundaries are not inferred from points |
+
+Coordinates and boundaries are separate options. Missing geometry must not become `(0,0)` or an invented polygon. Ancestor inclusion is the default for relational integrity; `--no-ancestors` declares dependencies outside the export.
+
+CSV's machine profile preserves source values. `id`, `entityType`, `name`, and `countryId` are plain strings; `parentId` is a JSON string or `null`. Optional `codes`, `names`, `level`, `coordinates`, and `boundary` are JSON-valued cells: an empty cell means absent, literal `null` means explicitly null. Coordinate/boundary columns are omitted when not requested. `--spreadsheet-safe` is an explicit presentation profile for spreadsheet formula-like cells; do not use that transformed output as a lossless machine interchange source.
+
+SQL creation mode creates the standard schema; it is not a migration engine. An existing table is not made compatible by `CREATE TABLE IF NOT EXISTS`. For updates to an application database use the [seeder](seeding.md), which has its own field ownership and revision policy.
+
+## Compression and reproduction
+
+`--compression none`, `gzip`, or `zip` controls transport packaging. Gzip payloads are read transparently. ZIP output contains `manifest.json` plus `package.zip`; the archive contains its own manifest and payloads. Verify the outer package for archive integrity; extract the ZIP to a new directory for payload verification and seeding. Completed exports are published only after generation; existing output directories are rejected. Cancellation/failure must not publish a partially complete package.
+
+Retain published artifacts when exact bytes matter. Semantic reproducibility means the same snapshot and normalized request select the same values/IDs; binary formats and compression metadata may differ between generator/tool versions. Manifest checksums validate the artifact you received, not every possible future regeneration.
+
+## Formats not included in V1
+
+MySQL/MariaDB SQL, SQLite SQL scripts, generated TypeScript data modules, YAML, Parquet, GeoParquet, GeoPackage, and Shapefile are not advertised as supported. They can be added as adapters when a concrete integration needs them. A TypeScript SDK is already available; that is separate from exporting datasets as TypeScript source.
+
+GeoPackage requires OGC metadata and geometry encoding; renaming a `.sqlite` file is insufficient. GeoParquet needs a tested version/profile, not simply a WKB column. Shapefile has restrictive field names/types and multifile packaging, so it is a compatibility target rather than the default geographic format.

package/docs/generation.fr.md

@@ -0,0 +1,29 @@
+# Générer les fichiers dans votre projet
+
+[English](generation.md) · [Accueil](../README.fr.md)
+
+Utilisez Node.js 24.18.x et npm. Exécutez l'outil une fois depuis le projet cible. Pour utiliser une version locale, construisez le dépôt puis remplacez `npx georeference` par `node /chemin/vers/georeference/dist/cli.js`.
+
+```sh
+npx georeference
+npx georeference countries --country FR,CG --format csv --output ./data/countries
+npx georeference countries --format sqlite --output ./data/countries-db
+npx georeference countries --source-file ./sources/countryInfo.txt --output ./data/offline
+```
+
+Sans commande, l'outil génère les pays : téléchargement HTTPS de `countryInfo.txt` depuis GeoNames, puis création de `./data/georeference/entities.json` et `manifest.json`. Le JSON contient `{ metadata, entities }` ; utilisez le lecteur JSON de votre application. `npx` met en cache l'exécutable et ses dépendances hors du projet. Votre `package.json`, votre fichier de verrouillage et les dépendances restent intacts. Les fichiers générés ne nécessitent aucune installation de GeoReference à l'exécution.
+
+`--output` désigne un **nouveau dossier**, pas un nom de fichier. Les destinations existantes sont refusées, y compris lors d'une seconde génération. Générez dans un autre dossier puis examinez/remplacez vous-même les données applicatives. La génération n'amorce jamais une base. Les six [formats d'export](formats.fr.md) sont disponibles ; CSV utilise le profil machine documenté. Conservez le manifeste avec les données pour l'attribution, les versions et les empreintes.
+
+La source par défaut fournit les noms de pays, codes et IDs stables, sans coordonnées ni frontières. Pour des données enrichies, utilisez un instantané existant :
+
+```sh
+npx georeference generate --snapshot ./sources/world.sqlite --types locality --country CG --coordinates --format ndjson --output ./data/places
+npx georeference countries --snapshot ./sources/world.sqlite --boundaries --format geojson --output ./data/borders
+```
+
+`countries` sélectionne uniquement les pays ; `generate` accepte les filtres de type/subdivision sur l'instantané. Sans instantané, les deux utilisent countryInfo. GeoJSON exige les options de géométrie et conserve les géométries indisponibles à null. Une base SQLite exportée diffère d'un instantané interne ; voir [les formats](formats.fr.md).
+
+Les téléchargements sont limités à 30 secondes et la source à 2 Mio. Une erreur de connexion fait échouer la génération ; `--source-file` utilise un fichier GeoNames conservé hors ligne. Aucun repli silencieux sur d'anciennes données, ni cache persistant des données. Les versions dérivent du SHA-256 de la source : des octets amont modifiés donnent une nouvelle version. Conservez le fichier source et la version du générateur pour reproduire la sortie. Les téléchargements/instantanés temporaires sont nettoyés après succès ou échec. Métadonnées/manifestes conservent l'attribution GeoNames et CC BY 4.0 ; préservez-les lors de la redistribution. Voir [les sources](data-sources.fr.md).
+
+Le [SDK](getting-started.fr.md#sdk-optionnel) est optionnel pour consulter un instantané local depuis une application. La génération de fichiers n'en a pas besoin.

package/docs/generation.md

@@ -0,0 +1,29 @@
+# Generate files in your project
+
+[Français](generation.fr.md) · [Home](../README.md)
+
+Use Node.js 24.18.x and npm. Run the tool once from your target project. To use a local build instead, build the repository and replace `npx georeference` with `node /path/to/georeference/dist/cli.js`.
+
+```sh
+npx georeference
+npx georeference countries --country FR,CG --format csv --output ./data/countries
+npx georeference countries --format sqlite --output ./data/countries-db
+npx georeference countries --source-file ./sources/countryInfo.txt --output ./data/offline
+```
+
+No command means country generation: download GeoNames `countryInfo.txt` over HTTPS, then create `./data/georeference/entities.json` and `manifest.json`. JSON contains `{ metadata, entities }`; use your application's own JSON reader. `npx` caches the executable and its dependencies outside the project. Your `package.json`, lockfile, and project dependencies are untouched. Generated files require no GeoReference runtime installation.
+
+`--output` is a **new directory**, not a filename. Existing destinations are refused, including repeated generation. Generate into another directory, then review/replace application data yourself. Generation never seeds a database. All six [export formats](formats.md) are available; CSV uses the documented machine profile. Keep the manifest with the data for attribution, versions, and checksums.
+
+The default source supplies country names, codes, and stable IDs, without coordinates or boundaries. For richer data, use an existing snapshot:
+
+```sh
+npx georeference generate --snapshot ./sources/world.sqlite --types locality --country CG --coordinates --format ndjson --output ./data/places
+npx georeference countries --snapshot ./sources/world.sqlite --boundaries --format geojson --output ./data/borders
+```
+
+`countries` selects countries only; `generate` accepts type/subdivision filters on the snapshot. Without a snapshot both use countryInfo. GeoJSON requires geometry flags and preserves unavailable geometry as null. An exported SQLite database differs from an internal snapshot; see [formats](formats.md).
+
+Downloads have a 30-second timeout and a 2 MiB source limit. Connection failures fail generation; `--source-file` uses a retained GeoNames file offline. There is no silent stale-data fallback or persistent data cache. Dataset versions derive from source SHA-256, so changed upstream bytes produce a new version. Retain the source file and generator version to reproduce output. Temporary downloads/snapshots are cleaned up after success or failure. Generated metadata/manifests retain GeoNames attribution and CC BY 4.0; preserve them when redistributing data. See [sources](data-sources.md).
+
+The [SDK](getting-started.md#optional-sdk) is optional for applications that want to query a local snapshot. File generation does not need it.