@supersoniks/concorde 4.6.0 → 4.7.3

package/ai/skills/concorde/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: concorde
+description: >-
+  Composants Web Concorde (Lit) : DataProvider, scope, theme, Endpoint,
+  formDataProvider, sonic-list/sonic-queue, @subscribe/@handle/@get.
+  @subscribe feuille par feuille (pas d’objet parent + getters).
+  Imports courts (@supersoniks/concorde/menu, /list, /utils…).
+---
+
+# Concorde — patterns et migrations
+
+Source de vérité : fichiers `.md` dans `node_modules/@supersoniks/concorde/src/` (composants, décorateurs, docs).
+
+**Imports** : toujours les chemins **les plus courts** — voir skill `concorde-imports` et section ci-dessous.
+
+**Vocabulaire** : toujours **DataProvider**. Accès programmatique : **`get(chemin)`** (alias Concorde `dp`), **`set(chemin, valeur)`**. **Pas** `PublisherManager` ni `getDataProvider`.
+
+## Imports (règle prioritaire)
+
+Préférer `@supersoniks/concorde/menu`, `/list`, etc. **dans les apps consommatrices**. Dans le **dépôt Concorde** (lib + doc), utiliser `core/components/…` ou imports relatifs — voir skill `concorde-imports` (section « Dans le dépôt Concorde »).
+
+Référence complète : skill **`concorde-imports`** (`.cursor/skills/concorde-imports/SKILL.md`).
+
+## Interdits pour du **nouveau** code
+
+- **Ne pas** étendre les mixins `Subscriber` / `Fetcher` sur des composants métier.
+- **Ne pas** utiliser `data-bind`, `data-publish`, `data-subscribe` en HTML.
+- **Ne pas** mettre `@input`, `@change` ou `.value` + assignation manuelle sur **`sonic-input`** quand `formDataProvider` + `name` suffit.
+- **Ne pas** introduire `@onAssign` — préférer `@handle` + `DataProviderKey`.
+- **Ne pas** utiliser **`@bind`** sur les composants métier — préférer **`@subscribe`** + `DataProviderKey<T, U>` (typage + placeholders `${prop}` sur l’hôte).
+- **Ne pas** utiliser **`sonic-fetch`** — préférer **`sonic-queue`** (+ filtre `formDataProvider`) ou **`@get`** + `Endpoint`.
+- **Ne pas** importer **`PublisherManager`** — utiliser **`get` / `set`** (réexport Concorde ou wrapper projet).
+- **Ne pas** promouvoir les templates HTML (`<template>`, `data-value`) pour **`sonic-list`** / **`sonic-queue`** — préférer **`.items`**, **`.noItems`**, **`.skeleton`**, **`.separator`** (binding propriété Lit obligatoire pour les fonctions).
+
+## DataProvider
+
+Store observable adressé par un chemin string :
+
+```typescript
+import { dp, get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const counterKey = new DataProviderKey<{ count: number }>("myCounter");
+
+set(counterKey, { count: 0 });
+dp(counterKey.count).set(1);
+get(counterKey); // snapshot { count: 1 }
+```
+
+Chemins **statiques** uniquement pour `get` / `set` / `dp`. Clés avec `${…}` → décorateurs ou **`sub(clé)`** dans les templates. Migration : skill **`concorde-get-set-dp`**.
+
+Attributs HTML courants :
+
+| Attribut | Rôle |
+|----------|------|
+| `dataProvider` | Lie un composant au DataProvider à ce chemin |
+| `formDataProvider` | Conteneur de formulaire — les champs `name` écrivent dedans |
+| `dataFilterProvider` | Filtre lu par `sonic-queue` (relance les requêtes) |
+
+## DataProviderKey
+
+### Chemins statiques
+
+```typescript
+const counterKey = new DataProviderKey<{ count: number }>("myCounter");
+counterKey.count.path; // "myCounter.count"
+```
+
+### Chemins dynamiques (placeholder)
+
+Placeholder `${prop}` dans une **chaîne normale** (pas de backticks). Résolu depuis les propriétés du composant hôte ; ré-abonnement automatique quand elles changent.
+
+```typescript
+export const userKey = new DataProviderKey<User, { userIndex: number }>(
+  "users.${userIndex}",
+);
+
+@property({ type: Number }) userIndex = 0;
+
+@subscribe(userKey)
+@state() user: User | null = null;
+```
+
+Même mécanisme pour `@handle`, `@publish`, `@subscribe`. Éviter `@bind` (bidirectionnel / chemins string legacy).
+
+Doc : `src/docs/_misc/dataProviderKey.md`, `src/docs/_decorators/subscribe.md`, `handle.md`.
+
+## Endpoint
+
+```typescript
+const users = new Endpoint<UsersResponse>("users?offset=$offset&limit=$limit");
+users.path;
+```
+
+Utilisé avec `@get(endpoint)` ou `@get(endpoint, apiConfigKey)` — voir **Scope** ci-dessous.
+
+## Scope — defaults hérités
+
+Skill dédié : **`concorde-scope`**.
+
+`<sonic-scope>` (light DOM) : les descendants héritent des attributs (`serviceURL`, `token`, `formDataProvider`, icônes custom…).
+
+```typescript
+import "@supersoniks/concorde/sonic-scope";
+```
+
+```html
+<sonic-scope serviceURL="https://api.example.com" formDataProvider="checkout">
+  …app…
+</sonic-scope>
+```
+
+**API** — type `APIConfiguration` (`@supersoniks/concorde/utils/api`) :
+
+| Mode | `@get` | Config |
+|------|--------|--------|
+| Scope | `@get(endpoint)` | hérite `serviceURL`, `token`, … du scope |
+| DataProvider | `@get(endpoint, apiConfigKey)` | objet publié via `set(apiConfigKey, { … })` |
+
+Champs courants : `serviceURL`, `token`, `userName`/`password`, `credentials`, `authToken`, `tokenProvider`.  
+Avancés : `cache`, `blockUntilDone`, `keepAlive`, `addHTTPResponse`.
+
+**Ne pas confondre** avec **theme** (couleurs / typo) — skill **`concorde-theme`**.
+
+## Theme — design tokens
+
+Skill dédié : **`concorde-theme`**.
+
+`<sonic-theme background color font>` + variables CSS `--sc-*` (surfaces, sémantique, typo). Pas pour l’API.
+
+```typescript
+import "@supersoniks/concorde/theme";
+```
+
+## @publish / @subscribe
+
+```typescript
+@publish(counterKey.count)
+@state()
+count = 0;
+
+@subscribe(counterKey.count)
+@state()
+subscribedCount = 0;
+```
+
+### Règle impérative — une souscription par valeur affichée
+
+Sur un composant **`LitElement`** métier, chaque donnée lue dans `render()` doit avoir **son propre** `@subscribe` + `@state()` (ou `@property` si besoin explicite) sur le **publisher feuille** — jamais un abonnement à l’objet parent + getters.
+
+| Anti-pattern | Pourquoi |
+|--------------|----------|
+| `@subscribe(dpKeys.currentSession)` + `get edito()` | Si seul `edito` change (même référence `Session`), Lit peut **ne pas** re-rendre |
+| `@subscribe` sur un parent + `sub()` enfant pour le détail | Mélange deux modèles ; préférer des feuilles cohérentes |
+
+```typescript
+// ❌ — re-render non garanti sur sous-clés
+@subscribe(dpKeys.currentSession)
+@state() session?: Session;
+get edito() { return this.session?.edito; }
+
+// ✅ — une propriété réactive par champ du template
+@subscribe(dpKeys.currentSession.slug)
+@state() slug = "";
+
+@subscribe(dpKeys.currentSession.edito)
+@state() edito: Edito | null = null;
+
+@subscribe(dpKeys.currentSession.settings)
+@state() settings: SettingsSessionAPI | null = null;
+```
+
+**Navigation typée** : chaîner `DataProviderKey` — `dpKeys.currentSession.edito` → `"app.currentSession.edito"`.
+
+**Granularité** : descendre jusqu’à la **feuille** réellement affichée si les mutations ne remplacent pas l’objet intermédiaire (ex. `@subscribe(dpKeys.currentSession.edito.title)` si seul `title` change sans nouvel objet `edito`).
+
+**Templates** : même règle avec `sub(dpKeys.currentSession.edito.title)` plutôt que `sub(dpKeys.currentSession)` + accès JS.
+
+### Cas hybride — hôte `Subscriber` + enfants sonic
+
+Des composants catalogue (`sonic-event-location-hall`, `sonic-date`, `sonic-product-title`, …) remontent l’arbre pour `dataProvider` et utilisent le **template filling** du mixin `Subscriber` — pas un `@subscribe` local.
+
+| Situation | Approche |
+|-----------|----------|
+| Composant métier **sans** enfants `Subscriber` | `LitElement` + `@subscribe` **feuille par feuille** |
+| Composant **hôte** d’enfants sonic `Subscriber` | `extends Subscriber(LitElement)` + `@property` remplies par template filling ; **exposer** `dataProvider` aux descendants |
+
+**`dataProvider` imbriqué** (éviter la clé plate `"app.currentSession"`) :
+
+```html
+<mon-composant-hote dataProvider="app" subDataProvider="currentSession"></mon-composant-hote>
+```
+
+Après `initPublisher`, refléter le chemin résolu sur l’attribut (ex. `app/currentSession`) pour que les **enfants** héritent le bon publisher — ils ne lisent pas `subDataProvider` sur l’ancêtre.
+
+**Liste / queue** : chaque ligne a son publisher — l’hôte **hérite** de l’ancêtre ; ne pas forcer `app.currentSession` sur un item de liste.
+
+## formDataProvider
+
+```html
+<div formDataProvider="myForm">
+  <sonic-input name="value" label="Texte"></sonic-input>
+</div>
+```
+
+Initialisation : `set("myForm", { value: "" })`.
+
+## sonic-queue — scroll infini + recherche
+
+Pagination (`$offset` / `$limit`) **automatisée** avec `lazyload`.
+
+```html
+<div formDataProvider="myFilter">
+  <sonic-input name="q" type="search" label="Rechercher"></sonic-input>
+</div>
+<sonic-queue
+  lazyload
+  dataFilterProvider="myFilter"
+  dataProviderExpression="users?offset=$offset&limit=$limit"
+  serviceurl="…"
+  key="data"
+  limit="4"
+  .items=${renderUser}
+></sonic-queue>
+```
+
+## Templates sonic-list / sonic-queue
+
+Propriétés Lit (recommandé) :
+
+| Propriété | Rôle |
+|-----------|------|
+| `.items=${fn}` | Rendu de chaque ligne — **point obligatoire** (Lit ne passe pas les fonctions en attribut HTML) |
+| `.separator` | Entre chaque item (pas après le dernier) |
+| `.noItems` | Liste vide |
+| `.skeleton` | Chargement pendant un `fetch` |
+
+`sonic-queue` transmet ces propriétés à chaque lot (`sonic-list` interne). `.noItems` ne s’applique qu’au **premier** lot.
+
+## Décorateurs
+
+| Besoin | API |
+|--------|-----|
+| Lire (affichage Lit) | `@subscribe(dpKey.leaf)` + `@state()` — **une fois par champ** du `render()` |
+| Effet typé | `@handle(dpKey.a, …)` |
+| API HTTP | `@get(Endpoint)` ou `@get(Endpoint, apiConfigKey)` |
+| Écriture classe (hors form) | `@publish` |
+| Lecture classe (hors form) | `@subscribe` + `DataProviderKey` — pas `@bind` |
+
+## Migrations courantes
+
+| Ancien | Nouveau |
+|--------|---------|
+| `PublisherManager.get(…)` | `get(…)` ou `set(…)` |
+| « publisher » | DataProvider |
+| `sonic-input` + `@input` | `formDataProvider` + `name` |
+| `sonic-fetch` | `sonic-queue` + filtre, ou `@get` |
+| `extends Subscriber(LitElement)` (métier seul) | `LitElement` + `@subscribe` feuille par feuille / `sub()` |
+| `extends Subscriber` (hôte d’enfants sonic) | Conserver `Subscriber` + `dataProvider` / `subDataProvider` corrects |
+| `data-bind` HTML | `@subscribe` / `sub()` |
+| `@bind` décorateur | `@subscribe` + `DataProviderKey` (lecture) ou `@publish` (écriture) |
+| `@onAssign` | `@handle` + `DataProviderKey` |
+| Templates HTML list/queue | `items`, `.separator`, `.noItems`, `.skeleton` (propriétés Lit) |
+
+## Recettes
+
+- **Initialiser un DataProvider** : `set(key, { … })` ou `set(key.path, { … })`.
+- **Formulaire** : `formDataProvider` + `name` → `sub()` ou `@subscribe`.
+- **Liste scroll infini** : `sonic-queue` + `lazyload` + `dataFilterProvider`.
+- **Templates list/queue** : `items`, `separator`, `noItems`, `skeleton` (depuis un parent Lit).
+- **Config API app-wide** : `<sonic-scope serviceURL="…">` ou `DataProviderKey<APIConfiguration>`.
+- **Theme / couleurs** : `<sonic-theme>` + CSS `--sc-*`.
+- **Clé dynamique** : `"chemin.${prop}"` + `DataProviderKey<T, { prop: … }>`.

package/ai/skills/concorde-get-set-dp/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: concorde-get-set-dp
+description: >-
+  Migration et usage de get/set/dp avec DataProviderKey statique.
+  Rejet des placeholders ${} par resolveStaticPublisherPath ; sub() et
+  décorateurs pour le dynamique.
+---
+
+# Concorde — get / set / dp (chemins statiques)
+
+Skill de **migration** vers Concorde ≥ 4.6 avec `resolveStaticPublisherPath`.
+À activer quand un projet monte de version ou refactorise vers `DataProviderKey`.
+
+Référence framework : skill **`concorde`**, doc `src/docs/_misc/dataProviderKey.md`.
+
+## Quand utiliser cette skill
+
+- Monter `@supersoniks/concorde` avec garde statique sur `get` / `set` / `dp`.
+- Auditer un codebase TypeScript existant avant/après upgrade.
+- Distinguer **chemin évalué en JS** vs **placeholder Concorde** `${prop}` / `{$prop}`.
+- Choisir entre API programmatique (`get/set/dp`) et réactivité (`sub`, décorateurs).
+
+## Règle de rejet (runtime)
+
+`resolveStaticPublisherPath` lève une erreur si la string passée à `get`, `set` ou `dp` contient **`${`** ou **`{$`** :
+
+| Appel | Résultat |
+|-------|----------|
+| `dp(new DataProviderKey("users.${userIndex}"))` | **throw** |
+| `get("users.${userIndex}")` | **throw** |
+| `dp(staticKey.path)` si `.path` contient `${` | **throw** |
+
+**OK** — le chemin est résolu **avant** l'appel (pas de placeholder littéral) :
+
+```typescript
+set(`app.pages.${index}.isComplete`, true); // → "app.pages.2.isComplete"
+dp(`${this.formDataProvider}/fieldName`); // → "checkoutForm/email"
+```
+
+**Faux positif fréquent** : grep `${` dans les sources TS ne suffit pas — vérifier la **valeur runtime** passée à `get/set/dp`.
+
+## Rétrocompatibilité
+
+| Avant | Après (recommandé) | Statut |
+|-------|-------------------|--------|
+| `dp(key.path)` | `dp(key)` | Équivalent si clé statique |
+| `set(key.path, v)` | `set(key, v)` | Équivalent |
+| `get("myCounter.count")` | `get(key.count)` | Typage amélioré |
+| `key.path` dans attribut HTML | Inchangé | Toujours valide |
+| `@onAssign(key.path)` | `@handle(key.leaf)` | Migration parallèle (skill `concorde`) |
+
+Aucune rupture pour le code qui passait déjà des **strings résolues** ou des clés **statiques**.
+
+## Trois niveaux d'accès DataProvider
+
+| Mécanisme | Contexte | Dynamique |
+|-----------|----------|-----------|
+| **`get` / `set` / `dp`** | Code impératif, snapshot instant T | **Non** (placeholder `${` interdit) |
+| **`sub(chemin \| clé)`** | Template Lit, réactivité | **Oui** — string, concat JS, ou `DataProviderKey` avec `${prop}` |
+| **`@subscribe` / `@publish` / `@handle`** | Propriétés composant | **Oui** — `DataProviderKey<T, U>` avec `"base.${prop}"` |
+| **`@bind`** | Legacy / bidirectionnel | Éviter sur composants métier — préférer `@subscribe` |
+
+### `sub()` — dynamique OK (clés incluses), ne pas migrer vers `get()`
+
+`sub()` accepte `string | DataProviderKey`, résout les placeholders `${prop}` depuis le **composant hôte** du template (comme `@subscribe`), et se ré-abonne quand les props observées changent.
+
+```typescript
+const userKey = new DataProviderKey<User, { userIndex: number }>("users.${userIndex}");
+
+html`<p>${sub(userKey.name)}</p>`
+html`<p>${sub(counterKey.count)}</p>`
+html`<p>${sub(this.formDataProvider + ".email")}</p>`
+```
+
+Doc : `src/docs/_directives/sub.md`.
+
+**Anti-pattern** : remplacer `sub(…)` par `get(…)` dans un template → perte de réactivité (snapshot unique).
+
+### Clé dynamique Concorde → décorateur ou factory
+
+```typescript
+export const resourceKey = new DataProviderKey<ResourceData, { resourceId: string }>(
+  "${resourceId}",
+);
+
+// ❌ dp(resourceKey) ou dp(resourceKey.path) → throw
+export const resourceProvider = (id: string) => dp<ResourceData>(id);
+
+@handle(resourceKey.conf.mode)
+onMode(mode: Mode) { /* … */ }
+```
+
+## Patterns avant / après
+
+### Statique typé (nouveau code)
+
+```typescript
+const cartKey = new DataProviderKey<Cart>("cart");
+set(cartKey, { items: [] });
+dp(cartKey.items[0].qty).set(1);
+```
+
+### ID runtime (string pure, pas placeholder Concorde)
+
+```typescript
+dp(resolvedId); // ex. "resource-abc123"
+set(`forms/${formId}`, formData);
+```
+
+### Index ou segment dynamique via JS (compatible)
+
+**Avant** :
+
+```typescript
+set(`app.pages.${index}.isComplete`, isComplete);
+return get(`app.labels.${language}.${key}`);
+```
+
+**Après** (option typée, même runtime) :
+
+```typescript
+const pagesKey = new DataProviderKey<AppState["pages"]>("app.pages");
+set(pagesKey[index].isComplete, isComplete);
+
+const labelsKey = new DataProviderKey<AppState["labels"]>("app.labels");
+return get(labelsKey[language][key]);
+```
+
+**Helper générique** — conserver si le suffixe ne contient jamais `${` :
+
+```typescript
+export const appSet = <P extends string>(path: P, value: AppValue<P>) => {
+  set(`app.${path}`, value);
+};
+```
+
+### Chemins entièrement statiques
+
+**Avant** :
+
+```typescript
+set("app.widget.computed", value);
+const publisher = dp("app.widget.distance");
+```
+
+**Après** :
+
+```typescript
+const widgetKey = new DataProviderKey<AppState["widget"]>("app.widget");
+set(widgetKey.computed, value);
+const publisher = dp(widgetKey.distance);
+```
+
+## Profils de risque (générique)
+
+| Profil codebase | Risque | Indice |
+|-----------------|--------|--------|
+| Strings JS uniquement, pas de `DataProviderKey` | Très faible | Chemins déjà résolus avant `get/set/dp` |
+| Mix `DataProviderKey` statique + `.path` | Faible | Simplifier `dp(key)` progressivement |
+| Clés avec `"${prop}"` passées à `dp()` | **Élevé** | Remplacer par factory `dp(idRésolu)` ou décorateur |
+| Templates avec `sub()` | Aucun | Ne pas « migrer » vers `get()` |
+
+Migrations **distinctes** (hors scope) : `PublisherManager`, `@onAssign` → `@handle`.
+
+## Checklist migration (agent)
+
+1. [ ] Confirmer version Concorde avec `resolveStaticPublisherPath` dans `dataProviderKey.ts`.
+2. [ ] Chercher `DataProviderKey(` dont le constructeur contient `${` ou `{$`.
+3. [ ] Pour chaque hit : si `get` / `set` / `dp` reçoit la clé → factory `dp(idRésolu)` ou décorateur.
+4. [ ] Simplifier `dp(staticKey.path)` → `dp(staticKey)` sur clés statiques.
+5. [ ] **Ne pas** toucher `sub(...)` ni décorateurs dynamiques sans raison.
+6. [ ] Distinguer grep `${` (source) vs valeur runtime.
+7. [ ] Tests manuels sur les flux métier qui utilisent clés dynamiques et formulaires `sub()`.
+
+## Anti-patterns
+
+| Anti-pattern | Pourquoi |
+|--------------|----------|
+| `dp(key)` sur clé `"${resourceId}"` | Throw immédiat |
+| `sub()` → `get()` dans template | Perte réactivité |
+| Refactor global `.path` → clé sur toutes les clés sans tri statique/dynamique | Régressions |
+| Confondre migration get/set/dp et suppression `PublisherManager` | Périmètres différents |
+
+## Fichiers de référence (package Concorde)
+
+- `src/core/utils/dataProviderKey.ts` — `resolveStaticPublisherPath`
+- `src/core/utils/PublisherProxy.ts` — overloads `get` / `set` / `dp`
+- `src/core/utils/publisherPathKey.spec.ts` — tests
+- `src/core/directives/DataProvider.ts` — `sub()`
+- `src/docs/_misc/dataProviderKey.md`
+
+## Maintenance
+
+Mettre à jour quand l'API Concorde évolue ou que de nouveaux cas edge sont documentés dans les specs.

package/ai/skills/concorde-imports/SKILL.md

@@ -0,0 +1,78 @@
+# Imports Concorde — chemins courts
+
+Toujours préférer le **chemin export le plus court** documenté dans `package.json` de `@supersoniks/concorde` — **dans les projets consommateurs** (apps qui installent le package).
+
+Éviter les chemins `ui/…`, `functional/…`, `core/…` quand un alias racine existe **en dehors du monorepo Concorde**.
+
+## Dans le dépôt Concorde (lib + doc)
+
+Les exports courts (`@supersoniks/concorde/list`, `/menu`, `/queue`, …) **ne résolvent pas** ici : l’alias Vite `@supersoniks/concorde` pointe sur `src/`, pas sur les sous-chemins `package.json`.
+
+| Besoin | ✅ Dans ce repo | ❌ Ne pas utiliser ici |
+|--------|----------------|------------------------|
+| `sonic-list` | `import "../../core/components/functional/list/list"` ou `@supersoniks/concorde/core/components/functional/list/list` | `@supersoniks/concorde/list` |
+| `sonic-queue` | `…/core/components/functional/queue/queue` | `@supersoniks/concorde/queue` |
+| UI (button, input, …) | `…/core/components/ui/…` ou relatif depuis `src/docs` | `@supersoniks/concorde/button`, etc. |
+| `@subscribe`, `@ancestorAttribute` | `@supersoniks/concorde/core/decorators/Subscriber` | — |
+| `DataProviderKey` | `@supersoniks/concorde/core/utils/dataProviderKey` | `@supersoniks/concorde/dataProviderKey` (alias doc seulement si configuré) |
+
+`@supersoniks/concorde/decorators` peut fonctionner (fichier `src/decorators.ts`) ; préférer quand même les chemins `core/…` dans `src/docs/example/**` pour cohérence.
+
+## Composants UI
+
+| Composant | ✅ Préférer | ❌ Éviter |
+|-----------|------------|----------|
+| Menu | `@supersoniks/concorde/menu` | `…/ui/menu` |
+| Menu item | `@supersoniks/concorde/menu-item` | `…/ui/menu-item` |
+| Divider | `@supersoniks/concorde/divider` | `…/ui/divider` |
+| Button | `@supersoniks/concorde/button` | `…/ui/button` |
+| Theme | `@supersoniks/concorde/theme` | `…/ui/theme` |
+| Scope | `@supersoniks/concorde/sonic-scope` | `…/functional/sonic-scope` |
+| Input | `@supersoniks/concorde/input` | `…/ui/form/input` |
+| Select | `@supersoniks/concorde/select` | `…/ui/form/select` |
+| Checkbox | `@supersoniks/concorde/checkbox` | `…/ui/form/checkbox` |
+
+## Composants fonctionnels
+
+| Composant | ✅ Préférer | ❌ Éviter |
+|-----------|------------|----------|
+| List | `@supersoniks/concorde/list` | `…/functional/list` |
+| Queue | `@supersoniks/concorde/queue` | `…/functional/queue` |
+| Router | `@supersoniks/concorde/router` | `…/core/components/functional/router/router` |
+| Fetch | `@supersoniks/concorde/fetch` | `…/functional/fetch` |
+| Value | `@supersoniks/concorde/value` | `…/functional/value` |
+
+## Utilitaires & types
+
+| Besoin | ✅ Préférer | ❌ Éviter |
+|--------|------------|----------|
+| Décorateurs | `@supersoniks/concorde/decorators` | chemins `…/core/decorators/…` |
+| Directives (`sub`) | `@supersoniks/concorde/directives` | — |
+| `get` / `set` / `dp` | `@supersoniks/concorde/utils` | `PublisherManager` |
+| `DataProviderKey` | `@supersoniks/concorde/dataProviderKey` | `…/core/utils/dataProviderKey` |
+| `Endpoint` | `@supersoniks/concorde/utils/endpoint` | `…/core/utils/endpoint` |
+| `APIConfiguration` | `@supersoniks/concorde/utils/api` | `…/core/utils/api` |
+| Vite config | `@supersoniks/concorde/vite-config` | — |
+
+## Exemples
+
+```typescript
+import "@supersoniks/concorde/menu";
+import "@supersoniks/concorde/menu-item";
+import "@supersoniks/concorde/divider";
+import "@supersoniks/concorde/button";
+import "@supersoniks/concorde/theme";
+import "@supersoniks/concorde/input";
+import "@supersoniks/concorde/list";
+import "@supersoniks/concorde/queue";
+import "@supersoniks/concorde/router";
+
+import { subscribe, handle, get } from "@supersoniks/concorde/decorators";
+import { sub } from "@supersoniks/concorde/directives";
+import { get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+```
+
+Side-effect imports (enregistrement custom elements) : toujours le chemin **composant** court ci-dessus.

package/ai/skills/concorde-menu/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: concorde-menu
+description: >-
+  Menus et navigation Concorde : sonic-menu, sonic-menu-item, sonic-divider.
+  Sidebar, sections, routes pushstate.
+---
+
+# Concorde — menus et navigation
+
+Référence doc : `node_modules/@supersoniks/concorde/src/core/components/ui/menu/menu.md`
+
+## Imports
+
+```typescript
+import "@supersoniks/concorde/menu";
+import "@supersoniks/concorde/divider";
+```
+
+## Structure type (navigation latérale)
+
+```html
+<nav aria-label="Navigation latérale">
+  <sonic-menu direction="column" align="left" size="sm" class="w-full">
+    <sonic-menu-item pushstate href="/" autoActive="strict">Accueil</sonic-menu-item>
+
+    <sonic-divider label="Section A" align="left" size="sm"></sonic-divider>
+    <sonic-menu-item pushstate href="/a/page" autoActive="strict">Page A</sonic-menu-item>
+
+    <sonic-divider label="Section B" align="left" size="sm"></sonic-divider>
+    <sonic-menu-item pushstate href="/b/page" autoActive="strict">Page B</sonic-menu-item>
+  </sonic-menu>
+</nav>
+```
+
+## Règles
+
+| Contexte | Composants |
+|----------|------------|
+| Liste de liens / nav | **`sonic-menu`** + **`sonic-menu-item`** |
+| Séparation de sections | **`sonic-divider`** avec `label` |
+| Liens internes (router Concorde) | `pushstate` + `href` sur **`sonic-menu-item`** |
+| Item actif | `autoActive="strict"` sur chaque item de route |
+
+## Interdits pour la navigation
+
+- **Ne pas** empiler des **`sonic-button`** ghost pour simuler un menu latéral.
+- **Ne pas** inventer des séparateurs custom quand **`sonic-divider`** suffit.
+- **Ne pas** oublier `pushstate` sur les liens internes.
+- **Ne pas** mettre `autoActive` sur le **`sonic-menu`** — c’est sur chaque **`sonic-menu-item`**.
+
+## Attributs utiles
+
+### sonic-menu
+
+`direction="column"`, `align="left"`, `size="sm"` pour une sidebar.
+
+### sonic-menu-item
+
+Hérite de **`sonic-button`** : `pushstate`, `href`, `autoActive`, `variant`.
+
+### sonic-divider
+
+`label`, `align="left"`, `size="sm"`.
+
+## Routes fichier
+
+Pas de **tirets** dans les noms de dossiers sous `routes/` — le générateur Concorde produit des identifiants JS invalides (`dpkey-dynamic` → erreur).
+
+## Checklist
+
+- [ ] `sonic-menu` englobe tous les items
+- [ ] Sections séparées par `sonic-divider` avec `label`
+- [ ] Chaque route : `pushstate` + `href` + `autoActive="strict"`
+- [ ] Imports `@supersoniks/concorde/menu`, `/menu-item`, `/divider` (pas `ui/…`)

package/ai/skills/concorde-scope/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: concorde-scope
+description: >-
+  Scope (sonic-scope) — inherited API, form, and icon defaults. Not UI.
+  APIConfiguration via attributes or DataProvider.
+---
+
+# Scope — configuration héritée
+
+**Scope** = defaults app-wide via `<sonic-scope>` (light DOM). Les descendants lisent les attributs ancêtres — pas de shadow root.
+
+```typescript
+import "@supersoniks/concorde/sonic-scope";
+```
+
+## Attributs courants
+
+| Zone | Attributs | Consommé par |
+|------|-----------|--------------|
+| API | `serviceURL`, `token`, `credentials`, `userName`, `password` | `@get`, `sonic-list`, `sonic-queue`, `sonic-submit` |
+| Forms | `formDataProvider`, `dataProvider`, `submitResultDataProvider` | champs form, `sonic-submit` |
+| Icons | `customIconLibraryPath`, `customIconDefaultPrefix` | `sonic-icon` `library="custom"` |
+
+## APIConfiguration
+
+Type : `@supersoniks/concorde/utils/api`.
+
+| Champ | Rôle |
+|-------|------|
+| `serviceURL` | URL de base API |
+| `token` | Bearer |
+| `userName` / `password` | Basic auth (si pas de token) |
+| `credentials` | Mode `fetch` (`omit`, `same-origin`, `include`) |
+| `authToken` | Refresh token (attribut scope : `eventsApiToken`) |
+| `tokenProvider` | Chemin pour obtenir un nouveau bearer |
+| `cache`, `blockUntilDone`, `keepAlive`, `addHTTPResponse` | Options avancées fetch |
+
+## Deux façons de configurer l’API
+
+**1. Scope** — attributs sur `<sonic-scope>` ou `<sonic-theme>` (API seulement sur scope recommandé) :
+
+```html
+<sonic-scope serviceURL="https://api.example.com" token="…">
+  …
+</sonic-scope>
+```
+
+```typescript
+@get(usersEndpoint) // pas de 2ᵉ arg — hérite serviceURL
+@state() data: ApiGetResult<Users> | null = null;
+```
+
+**2. DataProvider** — objet typé :
+
+```typescript
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+
+const apiKey = new DataProviderKey<APIConfiguration>("myApi");
+set(apiKey, { serviceURL: "https://api.example.com", credentials: "same-origin" });
+
+@get(usersEndpoint, apiKey)
+@state() data: ApiGetResult<Users> | null = null;
+```
+
+Les deux patterns peuvent coexister (scope pour l’URL par défaut, clé explicite quand nécessaire).
+
+## Séparation theme / scope
+
+- **Scope** → API, forms, icônes app-wide
+- **Theme** → couleurs, typo (`concorde-theme`) — **pas** `serviceURL`