@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.3

package/skills/command/references/examples/options-only.ts

@@ -0,0 +1,27 @@
+import * as DSCommand from "@duplojs/server/command";
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = await DSCommand.execOptions([
+	DSCommand.createOption("format", DDataStructure.literal(["json", "text"])),
+	DSCommand.createBooleanOption("verbose"),
+]);
+
+if (DEither.isLeft(result)) {
+	DSCommon.exitProcess(1);
+} else if (DEither.hasInformation(result, "success")) {
+	const options = DEither.unwrapRight(result);
+	type _CheckOptions = DCommon.ExpectType<
+		typeof options,
+		{
+			readonly format: "json" | "text" | undefined;
+			readonly verbose: boolean;
+		},
+		"strict"
+	>;
+
+	console.log(options);
+}
+// La branche log-help ne déclenche aucun traitement après l'aide.

package/skills/command/references/examples/preview-command.ts

@@ -0,0 +1,57 @@
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+
+export const previewCommand = DSCommand.create(
+	"preview",
+	{
+		description: "Preview export parameters without writing files",
+		subjects: [
+			DSCommand.createArgument("source", DDataStructure.string()),
+			DSCommand.createArgument("destination", DDataStructure.string(), { optional: true }),
+		],
+		options: [
+			DSCommand.createOption("format", DDataStructure.literal(["json", "text"]), {
+				required: true,
+				aliases: ["f"],
+				description: "Export format",
+			}),
+			DSCommand.createOption("limit", DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.greaterThanOrEqual(1),
+				DDataStructure.lessThanOrEqual(100),
+			]), { description: "Maximum number of entries" }),
+			DSCommand.createBooleanOption("overwrite", { description: "Allow replacement" }),
+			DSCommand.createArrayOption("include", DDataStructure.string(), {
+				required: true,
+				min: 1,
+				max: 5,
+				description: "Comma-separated entries to include",
+			}),
+		],
+	},
+	({ args, options }) => {
+		type _CheckArgs = DCommon.ExpectType<
+			typeof args,
+			{
+				readonly source: string;
+				readonly destination: string | undefined;
+			},
+			"strict"
+		>;
+		type _CheckFormat = DCommon.ExpectType<typeof options.format, "json" | "text", "strict">;
+		type _CheckFlag = DCommon.ExpectType<typeof options.overwrite, boolean, "strict">;
+
+		// La liste obligatoire et son minimum garantissent l'accès sans absence.
+		const firstEntry = DArray.first(options.include);
+		type _CheckFirstEntry = DCommon.ExpectType<typeof firstEntry, string, "strict">;
+
+		console.log({
+			...args,
+			...options,
+			limit: options.limit ?? 20,
+			firstEntry,
+		});
+	},
+);

package/skills/command/references/execution.md

@@ -0,0 +1,31 @@
+# Arbre, aide et résultat d'exécution
+
+## Commandes nommées et racine
+
+Une commande créée par `DSCommand.create` est une valeur à exporter puis importer dans le module qui assemble le parent. La placer dans les `subjects` du parent ; il n'y a pas de découverte automatique des fichiers. L'[exemple CLI](examples/cli.ts) importe explicitement sa sous-commande.
+
+La sélection descend immédiatement vers la sous-commande lorsque le premier argument correspond à son nom. Le parent ne constitue donc ni un middleware ni une source d'options communes. Pour appeler `my-cli preview ...`, placer les options de `preview` après son nom et les déclarer sur cette commande. Mutualiser au besoin les déclarations d'options, puis les inclure dans les commandes concernées.
+
+Le callback du parent traite son invocation sans sous-commande. Lui donner un comportement utile selon le projet, par exemple indiquer les actions disponibles. L'aide intégrée répond à `my-cli --help` et `my-cli preview --help` sans exécuter les callbacks correspondants.
+
+## Résultats et erreurs
+
+`DSCommand.exec` lit les arguments du processus. Une erreur de décodage ou de validation est déjà affichée et revient dans un `DEither.Error<DSCommand.Error>` ; le callback de la commande sélectionnée ne s'exécute pas. Une exécution réussie, y compris l'affichage de l'aide, renvoie `DEither.Ok`.
+
+Ce résultat ne fixe pas à lui seul un code de sortie d'échec. À la frontière du programme, le discriminer avec `DEither.isLeft` et, si le contrat du binaire le demande, terminer avec `DSCommon.exitProcess(1)` depuis `@duplojs/server/common`, comme dans l'exemple CLI. Éviter d'afficher une seconde fois le même diagnostic.
+
+Les échecs métier restent à interpréter dans le callback qui consomme l'application : afficher le message adapté et choisir la conséquence pour le programme. Le callback attend une valeur `void` ou une promesse de `void` ; lui retourner un `Either` métier ne constitue pas un mécanisme de propagation. `exec` ne convertit pas les exceptions du callback en erreurs de validation.
+
+Pour adapter les messages des data structures, `exec` et `execOptions` acceptent `dataStructureErrorInterpreter`.
+
+## Script recevant uniquement des options
+
+`DSCommand.execOptions` renvoie un résultat à trois branches : `success` contient les options validées, `log-help` indique que l'aide a déjà été affichée, et un `Left` porte l'erreur déjà affichée. Discriminer le succès avec `DEither.hasInformation(result, "success")` avant de déballer et de lancer le travail ; une aide est aussi un `Right`.
+
+Lire l'[exemple de script](examples/options-only.ts). Réserver cette forme aux scripts sans arguments positionnels ni arbre de commandes : elle ne vérifie pas les arguments restants après extraction des options.
+
+## Exposer le binaire
+
+Réutiliser le mode d'exécution du projet. Pour un package compilé sous Node, placer un shebang `#!/usr/bin/env node` au début du point d'entrée généré et faire pointer le champ `bin` du `package.json` vers ce fichier exécutable. L'exemple `cli.ts` suppose une compilation qui conserve ce shebang. Si le projet exécute directement du TypeScript, utiliser son interpréteur et le shebang correspondants plutôt que pointer Node sur un TypeScript non pris en charge par sa configuration.
+
+Vérifier que le fichier déclaré dans `bin` est produit, inclus dans le package distribué et exécutable. Tester ensuite la commande depuis un projet consommateur ou une installation locale du package.

package/skills/command/references/inputs.md

@@ -0,0 +1,27 @@
+# Entrées et garanties
+
+Lire l'[exemple de prévisualisation](examples/preview-command.ts) pour combiner arguments, option obligatoire, option numérique facultative, flag et liste bornée. Les assertions `DCommon.ExpectType` y vérifient les garanties reçues dans le callback.
+
+## Valeurs du terminal
+
+`createArgument` reçoit le nom, la data structure et les paramètres éventuels. L'ordre dans `subjects` fixe l'ordre des valeurs positionnelles. Une déclaration facultative ajoute `undefined` à la valeur reçue ; la data structure décrit la valeur présente.
+
+`createOption` reçoit également un nom et une data structure. La syntaxe accepte `--format=json` et `--format json`, ainsi qu'un alias déclaré comme `-f json`. Déclarer les noms et les alias sans tirets. Le décodage depuis les chaînes est intégré, y compris vers un nombre : une data structure numérique peut donc valider un entier et ses bornes avant le callback.
+
+Ne pas confondre une option facultative avec une valeur par défaut : appliquer la valeur de repli au résultat validé, ou rendre l'option obligatoire selon le contrat attendu.
+
+## Flags et listes
+
+`createBooleanOption` modélise la présence : `--overwrite` active le flag. `--overwrite=false` est invalide ; ne pas le proposer comme syntaxe de désactivation.
+
+`createArrayOption` reçoit le schéma d'un **élément**, puis décode les éléments d'une valeur séparée par des virgules par défaut : `--include=src,tests`. Utiliser `separator` pour changer ce séparateur. Ne pas supposer qu'une répétition du flag accumule les valeurs.
+
+`min` et `max` contraignent la longueur d'une liste présente. Ils ne rendent pas l'option obligatoire : ajouter `required: true` si son absence doit échouer. Avec un `min` littéral de `1`, une liste obligatoire garantit un premier élément ; exploiter cette garantie sans assertion ni garde d'absence redondante.
+
+Exemple d'appel de la sous-commande exposée par [cli.ts](examples/cli.ts) :
+
+```sh
+my-cli preview ./src ./out --format=json --limit=20 --include=src,tests --overwrite
+```
+
+L'exemple affiche les paramètres d'une prévisualisation ; il n'écrit aucun fichier. L'argument `destination` et l'option `limit` peuvent être omis, tandis que `source`, `format` et `include` sont requis.

package/skills/fundamental/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: duplojs-fundamental
+description: "Appliquer les API et la philosophie fonctionnelle DuploJS pour toute tâche impliquant du code TypeScript, quel que soit le contexte d'exécution."
+---
+
+# Fondamentaux DuploJS
+
+## Trouver les concepts
+
+Appliquer la démarche du skill et lire les ressources indiquées lorsque leur condition est rencontrée. Pour rechercher un concept ou un mécanisme non couvert, consulter `docs/concepts.llms.md` du package `@duplojs/agents-kit`.
+
+Le setup indique ce chemin dans `AGENTS.md` ou `CLAUDE.md`, relativement à leur dossier. Les chemins `docs/` partent du package installé, même avec `--copy`. Les références du skill partent de son dossier ; les liens d'un document se résolvent depuis ce document.
+
+Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+## Utiliser DuploJS pour coder
+
+Utiliser obligatoirement les API et l'écosystème DuploJS dès qu'un équivalent existe, y compris dans les tests. Avant d'utiliser une API native ou tierce ou de créer un utilitaire, chercher l'équivalent DuploJS.
+
+- `@duplojs/lang` : primitives et manipulations JavaScript indépendantes de la plateforme.
+- `@duplojs/server` : interactions avec l'environnement d'exécution serveur, notamment le système de fichiers. Par exemple, calculer un chemin avec `lang/path` et lire un fichier avec `server/file`.
+- Pour un besoin spécialisé, rechercher le package et les API adaptés dans l'écosystème à partir de la documentation.
+
+Importer le sous-export du domaine avec son namespace long lorsqu'il est exposé, comme dans les exemples liés depuis les références.
+
+## Laisser les types s'inférer
+
+Dans les implémentations, laisser TypeScript inférer les retours des fonctions et les valeurs issues des appels pour que leurs types suivent le code et ses dépendances. Ne pas reconstituer manuellement un type que l'expression ou l'API peut inférer. Annoter un type de retour uniquement pour résoudre une récursivité. Les signatures d'interfaces et les déclarations de fonctions des exemples décrivent des contrats à implémenter ; elles ne demandent pas d'annoter le retour de leur implémentation.
+
+## Faire évoluer le code à l'endroit responsable
+
+Lire les définitions, les contrats et les appelants concernés, puis intégrer le besoin dans la fonction, le modèle ou le module responsable. Si les adaptations se multiplient dans le traitement ou chez ses appelants, réexaminer cette responsabilité et simplifier la partie concernée.
+
+Privilégier les fonctions pures, l'immutabilité et des transformations explicites. Isoler les interactions avec l'environnement et représenter les échecs prévisibles dans les types de retour. Recomposer les étapes ou extraire une responsabilité lorsque cela clarifie le traitement, en conservant les garanties métier et le rôle de chaque couche.
+
+Limiter le remaniement au besoin demandé, puis relire la partie modifiée avec ses usages : déroulement compréhensible, absence de duplication et complexité proportionnée. Adapter les appelants concernés et vérifier les contrats ainsi que le comportement attendu.
+
+## Composer les transformations
+
+De nombreuses fonctions proposent une forme curifiée pour `DCommon.pipe` : fournir les paramètres fixes directement dans l'étape du pipe, puis laisser celui-ci transmettre la donnée.
+
+Lorsque la fonction retournée par la forme curifiée ne déclare pas ses propres génériques, ses types sont fixés lors de l'appel de configuration. Écrire cet appel directement comme argument de `pipe` ou `asyncPipe` : le contexte doit être disponible au moment de configurer l'étape. Préparer la fonction dans une variable puis passer cette variable à un pipe reste une préparation isolée ; l'ajout du pipe ne corrige pas cet usage. Ne pas ajouter des génériques explicites, annotations ou casts pour le forcer. L'[exemple de composition](references/examples/composition.ts) montre l'appel dans le pipe et la préparation à éviter ; [Composition](references/composition.md) explique les deux niveaux de signature.
+
+Toujours écrire les appels de pipe sur plusieurs lignes : chaque argument sur sa propre ligne, une virgule après le dernier et la parenthèse de fermeture sur une ligne séparée. Appliquer ce format même avec seulement deux arguments, une donnée et une étape ; écrire l'appel curifié lui-même à la ligne de cette étape.
+
+Un appel simple peut rester direct. Préparer séparément les données issues de sources indépendantes avant de les combiner ; les appels curifiés des étapes restent dans le pipe. Pour plusieurs étapes asynchrones, `DCommon.asyncPipe` attend chaque étape ; un seul `await` sur le résultat final suffit.
+
+Lorsque les étapes doivent s'arrêter sur un `Left`, utiliser `DEither.rightPipe` ou `DEither.rightAsyncPipe` : chaque étape reçoit la valeur du `Right` précédent et le premier `Left` arrête la suite. Lire [Composition](references/composition.md) avant de construire ou modifier un tel enchaînement ; l'[exemple direct et curifié](references/examples/composition.ts) montre le cas synchrone sans échec.
+
+## Valider les entrées et conserver les garanties
+
+Aux frontières du logiciel, valider les données externes avec une `DDataStructure`, qui porte leur contrat au runtime et dans les types. Utiliser l'intégration prévue par le module récepteur lorsqu'elle existe. Dans les traitements internes, exploiter les garanties déjà établies, sans refaire une validation pour le seul passage d'une fonction à une autre.
+
+Préciser les contraintes utiles : bornes, entier, format, longueur minimale, maximale ou exacte. Une contrainte enrichit le type ; sa seule déclaration ne valide rien au runtime.
+
+Choisir la construction selon les informations disponibles :
+
+1. **Littéral ou garantie compatible** : déclaration sûre ou calcul de compatibilité avec `DCommon.cast` ; utiliser `DCommon.infer` si le littéral doit être conservé.
+2. **Valeur runtime sans preuve** : validation ou fabrique sûre renvoyant un `Either` à traiter ou propager.
+3. **Refus du compilateur** : vérifier l'inférence et l'origine de la garantie attendue ; ne pas la fabriquer avec `as`, `!` ou un helper sans preuve.
+
+`cast` et `infer` calculent une compatibilité de types, sans validation runtime. Pour écrire un contrat de validation, construire une valeur contrainte ou résoudre un refus de compatibilité, lire [Contraintes et validation](references/constraints-and-validation.md). L'[exemple de validation](references/examples/input-validation.ts) montre l'acquisition de garanties depuis une entrée inconnue.
+
+Après chaque transformation, suivre le type du résultat : une garantie peut avoir été préservée, renforcée ou perdue. Exploiter les accès garantis aux collections sans garde redondante. Si la cible de `cast` n'est pas inférée dans un appel générique, lire la difficulté d'inférence de la référence avant de modifier les types.
+
+## Distinguer les résultats des défaillances d'environnement
+
+Une issue prévisible et exploitable par le traitement appartient au contrat de résultat : réussite en `Right`, refus en `Left`. Cela comprend les validations de données externes, les absences et les manipulations impossibles, y compris techniques. L'information du résultat identifie le cas ; sa valeur transporte les données ou les détails du refus.
+
+Dès qu'une branche d'une fonction renvoie un `Right` ou un `Left`, toutes ses branches renvoient un `Either`. Envelopper les valeurs de réussite dans un `Right`, y compris avec `DEither.ok()` pour une réussite sans valeur ; ne pas mélanger des `Either` et des valeurs brutes dans le contrat de retour.
+
+Les exceptions de défaillance imprévue émises par les dépendances ou le runtime remontent implicitement. Les fonctions réutilisables n'ajoutent pas de `throw` ; elles propagent ou adaptent leurs `Left`. Discriminer le résultat avant de le déballer.
+
+Réserver les `throw` explicites et `OrThrow` à la consommation finale du résultat par la frontière d'exécution : réponse, fin du programme ou exception adaptée. Être appelé depuis cette frontière ne suffit pas à autoriser un `throw`. La rareté ou le coût de propagation d'un refus prévisible ne changent pas cette règle.
+
+Avant d'adapter une API qui lève sur un refus prévisible ou d'introduire `OrThrow`, lire [Résultats et erreurs](references/results-and-errors.md) pour choisir le traitement selon la responsabilité de l'appelant. Préférer les déclarations sûres pour les constantes connues ; l'[exemple de propagation](references/examples/error-propagation.ts) conserve les erreurs d'une opération dans le contrat de retour.

package/skills/fundamental/references/composition.md

@@ -0,0 +1,35 @@
+# Composer une opération
+
+## Forme directe et forme curifiée
+
+La forme directe reçoit la donnée et les paramètres. La forme curifiée reçoit les paramètres dans l'étape du pipe, puis retourne la fonction qui recevra la donnée.
+
+Lire la surcharge curifiée en distinguant les génériques de l'appel de configuration de ceux de la fonction retournée. Quand cette dernière ne déclare pas ses propres génériques, ses types sont déjà fixés à la configuration ; un appel ultérieur avec la donnée ne les infère pas à nouveau. Les génériques présents sur la surcharge extérieure ne rendent pas la fonction retournée générique.
+
+Cette signature indique un usage directement dans `DCommon.pipe` ou `DCommon.asyncPipe`, dont le contexte fournit le type de la donnée lors de la configuration. Écrire l'appel de la forme curifiée à l'intérieur des arguments du pipe. Une fonction préparée dans une variable reste hors de ce contexte, même si cette variable est ensuite utilisée comme étape d'un pipe. Ne pas ajouter annotations, génériques explicites ou casts pour rendre cette préparation typable. Pour réutiliser le traitement, écrire une fonction qui reçoit la donnée et construit son pipe, ou utiliser la forme directe avec cette donnée.
+
+Comparer les formes directe et curifiée dans [cet exemple de transformation](examples/composition.ts). Les vérifications de type montrent l'inférence lorsque les appels sont écrits dans le pipe. Le cas à éviter utilise des génériques explicites pour préparer une fonction, puis la passe à un pipe : ce code peut compiler tout en contredisant l'usage attendu.
+
+Le pipe suit ici une même donnée : utilisateurs, utilisateurs actifs, noms. Une fonction déjà unaire de l'API peut être passée directement, comme `DString.trim`. Pour une forme curifiée, écrire son appel de configuration dans l'étape. Ne pas supposer que toutes les fonctions exposent les mêmes surcharges.
+
+## Mise en forme des pipes
+
+Écrire tous les appels de pipe sur plusieurs lignes, avec chaque argument sur sa propre ligne, une virgule après le dernier argument et la parenthèse de fermeture sur une ligne séparée. Ce format s'applique aussi à une donnée suivie d'une seule étape, comme dans le premier pipe de l'exemple. L'appel qui configure la forme curifiée occupe la ligne de l'étape ; une variable préparée auparavant ne le remplace pas.
+
+## Plusieurs sources indépendantes
+
+Quand plusieurs données indépendantes demandent chacune leur propre préparation, les nommer avant de les combiner. Cette préparation concerne les données ; les appels curifiés restent écrits dans les étapes de leur pipe.
+
+Voir [la préparation de deux arguments indépendants](examples/independent-inputs.ts).
+
+Le résultat de cet appel peut ensuite devenir l'entrée d'un autre pipe si plusieurs transformations se suivent.
+
+## Asynchronisme et résultats
+
+`DCommon.asyncPipe` attend chaque étape avant la suivante. Un seul `await` sur le pipe suffit pour obtenir le résultat final.
+
+Voir [un enchaînement asynchrone](examples/async-composition.ts).
+
+Si chaque étape peut renvoyer un `Either`, utiliser `DEither.rightPipe` ou `DEither.rightAsyncPipe` pour propager automatiquement le premier `Left`. Un pipe ordinaire ne décide pas à lui seul comment traiter un `Left`. Les pipes de `DEither` transmettent la valeur du `Right` à l'étape suivante, et non son wrapper.
+
+Pour approfondir, rechercher la currification et la composition des `Either` dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée dans les instructions du projet.

package/skills/fundamental/references/constraints-and-validation.md

@@ -0,0 +1,61 @@
+# Contraintes, déclarations et validation
+
+## Une garantie doit avoir une origine
+
+Une contrainte exprime dans le typage une propriété de la valeur : entier, borne, longueur ou format. Une intersection cumule les garanties, par exemple `number & DNumber.Integer & DNumber.LessThan<25>`.
+
+Déclarer ce type ne valide rien et ne transforme pas la valeur. La garantie vient d'une validation runtime, d'un prédicat qui affine le type, d'une fonction qui préserve cette propriété ou d'un calcul de compatibilité sur une information déjà connue statiquement.
+
+## Entrées : décrire le contrat complet
+
+Une donnée reçue à une frontière externe passe par un data parser avant d'être considérée fiable. Une `DDataStructure` porte un schéma commun au runtime et au typage ; ses contraintes précisent le contrat au-delà de la nature de la donnée. Dans les fonctions internes, réutiliser les garanties déjà établies et suivre celles que les transformations conservent.
+
+Voir [un contrat et sa validation](examples/input-validation.ts).
+
+Choisir les contraintes selon les règles du besoin : bornes inclusives ou exclusives des nombres, minimum, maximum ou longueur exacte des chaînes et tableaux, formats, etc. Chaque contrainte d'une structure doit être compatible avec le type de donnée décrit.
+
+Pour les entrées gérées par l'écosystème, chercher comment le module qui les reçoit accepte des structures et lui fournir le contrat. Exploiter ensuite les valeurs déjà validées. À une frontière qui n'offre pas cette intégration, appeler explicitement la validation et traiter son `Either`.
+
+Exemples d'intégrations : `DSCommand.createArgument` et `DSCommand.createOption` pour une commande ; `.extract(...)` pour une route `@duplojs/http`. La règle s'applique à tout module qui reçoit des données externes.
+
+## `cast` : compatibilité calculée par TypeScript
+
+`DCommon.cast` restitue la valeur sans validation runtime. Le type attendu donne la cible du calcul. Une garantie plus forte peut impliquer une garantie plus faible ; un littéral peut aussi fournir assez d'information.
+
+Voir [les conversions de contraintes et les déclarations littérales](examples/cast.ts).
+
+Ce calcul de types comble les implications que TypeScript ne déduit pas de lui-même. Il n'y a pas de calcul dynamique de validité lors de l'exécution. Une simple `string` ou un simple `number` provenant du runtime ne prouve pas une longueur, un format ou une borne.
+
+Si `cast` émet une erreur, considérer que la compatibilité n'est pas établie. Une règle personnalisée peut ne pas avoir de support de calcul enregistré. Ne pas remplacer ce refus par `as`, une double assertion ou un helper qui fabrique la contrainte sans preuve. Vérifier l'inférence, valider par une structure ou un prédicat adapté, ou utiliser une autre construction sûre.
+
+## `infer` : conserver également le littéral
+
+Préférer `cast` dans le cas courant. Utiliser `DCommon.infer` lorsqu'une valeur connue statiquement doit garder son type littéral en plus des contraintes calculées. Cette fonction exige une entrée littérale ; elle ne sert pas à valider une donnée runtime.
+
+Voir [la conservation du littéral dans une propriété](examples/infer.ts).
+
+## Difficulté d'inférence : cible d'un paramètre générique direct
+
+Lorsque `cast` ou `infer` est passé à un paramètre lui-même générique, TypeScript peut ne pas fournir une cible assez précise au calcul. Si le type attendu n'est pas inféré dans cette situation, l'expliciter avec `satisfies` immédiatement après l'appel. Ce traitement répond à une difficulté de contexte ; il n'est pas nécessaire à chaque utilisation de ces fonctions.
+
+Voir [le calcul des contraintes avec un paramètre générique direct](examples/generic-inference.ts).
+
+`satisfies` fournit le contexte du calcul ; il ne contourne pas la validation. Une propriété contrainte d'un objet générique peut déjà fournir ce contexte, comme dans [l'exemple de propriété littérale](examples/infer.ts) : ne pas ajouter ce contournement d'inférence partout.
+
+## Déclarations spécialisées et Chrono
+
+Les domaines proposent aussi des helpers pour les valeurs connues. Préférer ces déclarations sûres à `OrThrow`.
+
+Voir [les déclarations de chemins et de valeurs Chrono](examples/safe-declarations.ts).
+
+Vérifier la surcharge réellement utilisée : le type de l'argument détermine si la fonction retourne directement la valeur ou un `Either`.
+
+## Les contraintes simplifient les opérations suivantes
+
+Voir [les accès garantis après validation du tableau](examples/guaranteed-array-access.ts).
+
+`MinElements<2>` garantit les indices `0` et `1` et l'existence du dernier élément. L'indice `2` reste incertain : un minimum de deux n'impose pas un maximum de deux. Les éléments garantis sont retournés directement, sans `Maybe` ni `undefined` ajouté pour une éventuelle absence. Une borne maximale ou une longueur exacte peut aussi permettre de prouver qu'un indice est absent.
+
+Exploiter ces garanties sans garde redondante ni assertion. Respecter cependant le type propre aux éléments : un tableau dont les éléments peuvent eux-mêmes être `undefined` conserve cette possibilité. Après une transformation, suivre les contraintes du résultat ; un filtre peut supprimer des éléments et perdre une garantie de minimum.
+
+Pour approfondir, rechercher les contraintes, les data structures, Chrono ou l'intégration du module concerné dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée par les instructions du projet.

package/skills/fundamental/references/examples/async-composition.ts

@@ -0,0 +1,15 @@
+/**
+ * @title Composer des étapes asynchrones.
+ *
+ * Attendre le résultat final avec asyncPipe.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+declare function loadName(): Promise<string>;
+
+const name = await DCommon.asyncPipe(
+	loadName(),
+	DString.trim,
+	DString.toLowerCase,
+);

package/skills/fundamental/references/examples/cast.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Établir la compatibilité des contraintes.
+ *
+ * Convertir une garantie existante ou déclarer une valeur littérale.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DPath from "@duplojs/lang/path";
+
+declare const belowTen: number & DNumber.LessThan<10>;
+const belowTwentyFive: number & DNumber.LessThan<25> = DCommon.cast(belowTen);
+
+const age: number & DNumber.GreaterThanOrEqual<18> = DCommon.cast(20);
+const path: string & DPath.Path = DCommon.cast("resources/config.json");
+
+// Une valeur incompatible ne peut pas acquérir la contrainte par cast.
+// @ts-expect-error 10 ne respecte pas la borne minimale de 18.
+const invalidAge: number & DNumber.GreaterThanOrEqual<18> = DCommon.cast(10);

package/skills/fundamental/references/examples/composition.ts

@@ -0,0 +1,40 @@
+/**
+ * @title Composer une transformation.
+ *
+ * Appels curifiés dans un pipe multiligne, avec inférence depuis la donnée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const users: readonly {
+	enabled: boolean;
+	name: string;
+}[];
+
+const enabledUsers = DArray.filter(users, (user) => user.enabled);
+
+// Même avec deux arguments, le pipe place la donnée et l'étape sur deux lignes.
+// L'appel curifié est écrit ici, dans le contexte fourni par le pipe.
+const names = DCommon.pipe(
+	users,
+	DArray.map((user) => user.name),
+);
+
+type _CheckNames = DCommon.ExpectType<typeof names, readonly string[], "strict">;
+
+// Plusieurs transformations s'enchaînent avec leurs appels curifiés à leur place.
+const enabledNames = DCommon.pipe(
+	users,
+	DArray.filter((user) => user.enabled),
+	DArray.map((user) => user.name),
+);
+
+type _CheckEnabledNames = DCommon.ExpectType<typeof enabledNames, readonly string[], "strict">;
+
+// À éviter : les génériques explicites rendent la préparation typable, mais le
+// pipe ajouté ensuite ne déplace pas l'appel de configuration dans son contexte.
+const preparedNames = DArray.map<typeof users, string>((user) => user.name);
+const namesFromPreparedStep = DCommon.pipe(
+	users,
+	preparedNames,
+);

package/skills/fundamental/references/examples/environment-initialization.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Valider la configuration au démarrage.
+ *
+ * Utiliser une exception au point d’initialisation du programme.
+ */
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Initialisation du programme, avant de commencer les traitements.
+const environment = await DSCommon.environmentVariableOrThrow({
+	PORT: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(1),
+		DDataStructure.lessThanOrEqual(65535),
+	]),
+});
+
+// Ici, l'initialisation exige un dossier de travail accessible pour démarrer.
+const currentDirectory = DSCommon.getCurrentWorkDirectoryOrThrow();

package/skills/fundamental/references/examples/error-propagation.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Propager les échecs dans le contrat de retour.
+ *
+ * Conserver les Left d’une opération dans une fonction réutilisable.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DSFile from "@duplojs/server/file";
+import type * as DPath from "@duplojs/lang/path";
+
+async function loadText(path: string & DPath.Path) {
+	const result = await DSFile.readTextFile(path);
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	return DEither.right("text-loaded", DEither.unwrapRight(result));
+}
+
+type _CheckResult = DCommon.ExpectType<
+	Awaited<ReturnType<typeof loadText>>,
+	Exclude<DSFile.ReadTextFileResult, DEither.Right> | DEither.Right<"text-loaded", string>,
+	"strict"
+>;

package/skills/fundamental/references/examples/generic-inference.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Fournir une cible de calcul en contexte générique.
+ *
+ * Utiliser satisfies avec cast et infer sur un paramètre générique direct.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineName<GenericName extends string & DString.MinCharacters<3>>(
+	name: GenericName,
+): GenericName;
+
+const name = defineName(
+	DCommon.cast("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+const literalName = defineName(
+	DCommon.infer("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+type _CheckName = DCommon.ExpectType<
+	typeof name,
+	string & DString.MinCharacters<3>,
+	"strict"
+>;
+
+type _CheckLiteralName = DCommon.ExpectType<
+	typeof literalName,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/guaranteed-array-access.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Exploiter une taille minimale de tableau.
+ *
+ * Distinguer les indices garantis et les accès potentiellement absents.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+const namesStructure = DDataStructure.array(
+	DDataStructure.string(),
+	[DDataStructure.minElements(2)],
+);
+
+declare const input: unknown;
+const result = namesStructure.check(input);
+if (DEither.isRight(result)) {
+	const names = DEither.unwrapRight(result);
+	const first = DArray.first(names);
+	const last = DArray.last(names);
+	const atZero = DArray.at(names, 0);
+	const atOne = DArray.at(names, 1);
+	const atTwo = DArray.at(names, 2);
+
+	type _CheckAccess = DCommon.ExpectType<
+		[typeof first, typeof last, typeof atZero, typeof atOne, typeof atTwo],
+		[string, string, string, string, string | undefined],
+		"strict"
+	>;
+}

package/skills/fundamental/references/examples/independent-inputs.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Combiner des sources indépendantes.
+ *
+ * Préparer les arguments séparément avant leur combinaison.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+declare const users: readonly {
+	enabled: boolean;
+	name: string;
+}[];
+declare const rawSearch: string;
+declare function searchUsers(names: readonly string[], search: string): readonly string[];
+
+const names = DArray.map(users, (user) => user.name);
+const search = DString.trim(rawSearch);
+const matches = searchUsers(names, search);

package/skills/fundamental/references/examples/infer.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Conserver une valeur littérale contrainte.
+ *
+ * Garder le littéral lors de la déclaration d’une propriété.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineSettings<GenericSettings extends {
+	name: string & DString.MinCharacters<3>;
+}>(settings: GenericSettings): GenericSettings;
+
+const settings = defineSettings({
+	name: DCommon.infer("Alice"),
+});
+
+type _CheckName = DCommon.ExpectType<
+	typeof settings.name,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/input-validation.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Valider un contrat de données.
+ *
+ * Décrire les contraintes puis discriminer le résultat de validation.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const requestStructure = DDataStructure.object({
+	name: DDataStructure.string([
+		DDataStructure.minCharacters(3),
+		DDataStructure.maxCharacters(40),
+	]),
+	age: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(18),
+	]),
+	tags: DDataStructure.array(
+		DDataStructure.string(),
+		[DDataStructure.minElements(2)],
+	),
+});
+
+type Request = DDataStructure.StructureValue<typeof requestStructure>;
+
+function validateRequest(input: unknown) {
+	return requestStructure.check(input);
+}
+
+declare const input: unknown;
+const result = validateRequest(input);
+if (DEither.isRight(result)) {
+	const request = DEither.unwrapRight(result);
+
+	type _CheckRequest = DCommon.ExpectType<typeof request, Request, "strict">;
+}

package/skills/fundamental/references/examples/safe-declarations.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Déclarer une valeur connue ou traiter une entrée runtime.
+ *
+ * Distinguer les déclarations sûres et les fabriques renvoyant un Either.
+ */
+import * as DChrono from "@duplojs/lang/chrono";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+
+const configPath = DPath.declarePath("resources/config.json");
+const releaseDate = DChrono.createDate("2026-09-30");
+const timeout = DChrono.createTime(2, "hour");
+
+declare const dateInput: string;
+declare const timeInput: number;
+
+// Les surcharges runtime renvoient des Either à traiter ou propager.
+const dateResult = DChrono.createDate({ value: dateInput });
+const timeResult = DChrono.createTime(timeInput);
+
+type _CheckCreation = DCommon.ExpectType<
+	[typeof releaseDate, typeof timeout, typeof dateResult, typeof timeResult],
+	[DChrono.TheDate, DChrono.TheTime, DChrono.MayBeDate, DChrono.MayBeTime],
+	"strict"
+>;