@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/ai/README.md

@@ -1,58 +1,46 @@
 # Agent IA — Concorde
 
-Fichiers installables pour **Cursor** et **JetBrains AI Assistant**.
+Une skill unique, `concorde` (format [Agent Skills](https://agentskills.io)), installable dans un projet : Cursor, Claude Code, JetBrains Junie et tout agent qui lit `.agents/skills`.
 
-## Installation dans un projet
-
-```bash
-node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
-```
-
-Options :
+## Structure
 
-- `--overlay <dir>` — couche projet ; lit `AGENTS.concorde.md` (legacy : `AGENTS.overlay.md`, `AGENTS.starter.md`)
-- `--skip-agents` — n’écrit jamais `AGENTS.md` (skills / rules seulement)
-- `--merge-agents` — opt-in : conserve le préambule projet et ajoute / rafraîchit le bloc Concorde
-- `--force-agents` — opt-in : **remplace** tout `AGENTS.md` (destructif)
-- `--cursor-only` / `--jetbrains-only`
+Sur le modèle de la skill shadcn : un point d’entrée court, des fichiers de règles lus à la demande.
 
-Depuis le dépôt Concorde (dev) : `yarn ai-init`
+```text
+skills/concorde/
+  SKILL.md            point d’entrée : sources (projet, doc, custom-elements.json), règles critiques, imports
+  rules/data.md       store, DataProviderKey, décorateurs, sub(), get / set / dp
+  rules/http.md       Endpoint, @get / @post, configuration API
+  rules/lists-forms.md
+  rules/styling.md    thème, tokens, règles de style
+  rules/composition.md  parties des composants composés, états intégrés
+  rules/troubleshooting.md  symptôme → cause → correction
+```
 
-## Politique `AGENTS.md` (non invasive)
+Ajouter un sujet = un fichier dans `rules/` + une ligne dans le tableau « Rules files » de `SKILL.md`. Pas de nouvelle skill sauf besoin vraiment distinct.
 
-| Situation | Comportement par défaut |
-|-----------|-------------------------|
-| Pas de `AGENTS.md` | Création du guide Concorde |
-| Fichier avec `<!-- concorde-ai -->` | Rafraîchit la zone gérée seulement |
-| Fichier **sans** marker (notes projet) | **Laissé intact** — skills / rules suffisent |
-| `--merge-agents` | Préambule projet + bloc Concorde après le marker |
-| `--force-agents` | Remplacement complet |
-| `--skip-agents` | Jamais d’écriture `AGENTS.md` |
+## Installation dans un projet
 
-```text
-[optional project preamble — short, project-only]
-<!-- concorde-ai -->
-<package ai/AGENTS.md>
-[--- + overlay AGENTS.concorde.md]
+```bash
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 ```
 
-- Tout **après** `<!-- concorde-ai -->` est **régénéré** à chaque run (pas d’empilement).
-- Ne pas recopier le guide Concorde dans le préambule : notes projet → `overlay/AGENTS.concorde.md`.
-- Si le préambule duplique `ai/AGENTS.md`, `ai-init` le **allège / drop** et affiche un warning.
-- Legacy : `AGENTS.overlay.md` / `AGENTS.starter.md` encore lus si `AGENTS.concorde.md` est absent (warning de dépréciation).
+Depuis le dépôt Concorde : `yarn ai-init`.
+
+| Source | Cible dans le projet |
+|--------|---------------------|
+| `skills/<nom>/` | `.agents/skills/<nom>/` (copie ; lue directement par Cursor) |
+| — | `.claude/skills/<nom>` et `.junie/skills/<nom>` : liens symboliques (copie si les liens sont interdits) |
 
-## Contenu
+Options :
 
-| Dossier | Cible |
-|---------|--------|
-| `skills/` | `.cursor/skills/` (concorde, imports, scope, theme, menu) |
-| `cursor/rules/` | `.cursor/rules/` |
-| `jetbrains/rules/` | `.aiassistant/rules/` |
-| `AGENTS.md` | racine du projet **seulement** si absent, déjà marqué, ou via `--merge-agents` / `--force-agents` |
+- `--overlay <dir>` — skills supplémentaires d’un kit projet (`<dir>/skills/<nom>/`)
+- `--no-links` — `.agents/skills` seulement
+- `--project-root <dir>`, `--concorde-ai <dir>`
 
-## Template starter
+**`AGENTS.md` appartient au projet** : `ai-init` ne le lit ni ne l’écrit. Les agents trouvent la skill seuls, par sa description.
 
-Le package `create-concorde-ts-starter` ajoute un overlay via `yarn ai:sync`.
+Seules les skills du package sont remplacées ; une skill du projet portant le même nom n’est jamais écrasée. Si `.claude/skills` pointe déjà vers `.agents/skills`, aucun lien par skill n’est créé.
 
 ## Tests
 

package/ai/skills/concorde/SKILL.md

@@ -1,348 +1,78 @@
 ---
 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…).
+  Entry point for any work in a project that uses Concorde
+  (@supersoniks/concorde), the Lit web components library: writing components,
+  reading or writing the DataProvider store, calling APIs, lists, forms,
+  styling with sonic-* components and theme tokens, imports. Use whenever code
+  imports @supersoniks/concorde or uses sonic-* elements.
 ---
 
-# Concorde — patterns et migrations
+# Concorde
 
-Source de vérité : fichiers `.md` dans `node_modules/@supersoniks/concorde/src/` (composants, décorateurs, docs).
+Lit + TypeScript web components (`sonic-*`) with a shared data store, the **DataProvider**. This file holds the critical rules; read the matching file in `rules/` before working on that topic.
 
-**Imports** : toujours les chemins **les plus courts** — voir skill `concorde-imports` et section ci-dessous.
+## Rules files
 
-**Vocabulaire** : toujours **DataProvider**. Accès programmatique : **`get(chemin)`** (alias Concorde `dp`), **`set(chemin, valeur)`**. **Pas** `PublisherManager` ni `getDataProvider`.
+| Topic | Read |
+|-------|------|
+| Store, `DataProviderKey`, `@subscribe` / `@publish` / `@bind` / `@handle`, `sub()`, `get` / `set` / `dp` | [rules/data.md](rules/data.md) |
+| HTTP: `Endpoint`, `@get` / `@post`, API configuration | [rules/http.md](rules/http.md) |
+| `sonic-list` / `sonic-queue`, forms | [rules/lists-forms.md](rules/lists-forms.md) |
+| Theme, tokens, classes, styling rules | [rules/styling.md](rules/styling.md) |
+| Which parts go in which component, built-in states | [rules/composition.md](rules/composition.md) |
+| Something does not update, render or send | [rules/troubleshooting.md](rules/troubleshooting.md) |
 
-## Imports (règle prioritaire)
+## Sources of truth
 
-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 »).
+1. **The project.** Check the installed version (`npm ls @supersoniks/concorde`); an API missing from it is not available. Reuse the project's `DataProviderKey`s, `Endpoint`s, API configuration and components before creating new ones.
+2. **The docs.** Every page is Markdown when you append `.md` to its URL. Index: https://concorde.supersoniks.org/llms.txt · offline: `node_modules/@supersoniks/concorde/src/**/*.md`.
+3. **The element API.** Attributes with allowed values, properties, events and slots are in `node_modules/@supersoniks/concorde/custom-elements.json`. It is large: query one element.
 
-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`.
-- Les décorateurs API **`@get`**, **`@post`**, **`@put`** et **`@patch`**
-  s'adaptent aux propriétés et aux méthodes ; la méthode reçoit le
-  `ApiResult` complet.
-- **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.
-
-### Décorateurs API sur une méthode
-
-`@get`, `@post`, `@put` et `@patch` peuvent décorer une propriété ou une
-méthode. En mode méthode, le callback reçoit le `ApiResult` complet :
-
-```typescript
-@get(endpoints.ticket)
-handleTicket(payload: ApiResult<PurchaseItem> | undefined) {
-  if (!payload?.result || !payload.response?.ok) return;
-  dp<PurchaseItem>(this.dataProvider).set(payload.result);
-}
-```
-
-La méthode reçoit le payload complet (`result`, `response`, `request`).
-`undefined` représente un appel terminé sans payload, par exemple une erreur
-réseau. Si un refetch nommé est nécessaire, conserver le handle et décorer la
-méthode avec lui :
-
-```typescript
-const ticketGet = get(endpoints.ticket);
-
-@ticketGet
-handleTicket(payload: ApiResult<PurchaseItem> | undefined) {}
-
-@refetch(ticketGet)
-reloadTicket() {}
-```
-
-`@send(handle)` reste le décorateur de méthode qui déclenche explicitement une
-écriture ; les mutations du body, triggers et polling conservent leur
-comportement.
-
-Exemple écriture :
-
-```typescript
-@post(endpoints.ticket, ticketBodyKey)
-handleTicketCreation(payload: ApiResult<PurchaseItem> | undefined) {
-  if (payload?.response?.ok) console.log(payload.result);
-}
-```
-
-## 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 color font class="block bg-base">` + 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;
+```bash
+node -e 'const t=process.argv[1];for(const m of require("@supersoniks/concorde/custom-elements.json").modules)for(const d of m.declarations)if(d.tagName===t)console.log(JSON.stringify({attributes:d.attributes?.map(a=>[a.name,a.type?.text,a.default]),properties:d.members?.filter(p=>p.kind==="field"&&!p.attribute).map(p=>p.name),events:d.events?.map(e=>e.name),slots:d.slots?.map(s=>s.name)},null,1))' sonic-select
 ```
 
-**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`).
+## Critical rules
 
-**Templates** : même règle avec `sub(dpKeys.currentSession.edito.title)` plutôt que `sub(dpKeys.currentSession)` + accès JS.
+- `LitElement` + decorators. In new code, and when touching old code: `Subscriber` mixin → decorators · `sonic-fetch` → `@get`, or `sonic-list` with `fetch` · `@onAssign` → `@handle` · `PublisherManager` → `get` / `set` / `dp` · `data-bind` → `sub()`.
+- Store access through a typed `DataProviderKey`, never a string path.
+- Display store values with `sub(key.leaf)`; subscribe to the leaf you render, not to its parent object.
+- Lists render rows with `.items` / `.noItems` / `.skeleton` (Lit properties, with the dot).
+- Form fields write to the store by themselves: `formDataProvider` + `name`, no `@input` wiring.
+- `@post` sends on every body mutation by default: forms use `autoPostOnBodyMutation: false` + `send()`.
+- Use `sonic-*` components and their attributes before custom markup; semantic tokens only, no raw colors, no `dark:`.
 
-### Cas hybride — hôte `Subscriber` + enfants sonic
+## Component shape
 
-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.
+```ts
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { subscribe, DataProviderKey } from "@supersoniks/concorde/decorators";
 
-| 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 |
+type Flight = { code: string; gate: string };
+const flightKey = new DataProviderKey<Flight>("flight");
 
-**`dataProvider` imbriqué** (éviter la clé plate `"app.currentSession"`) :
+@customElement("app-flight")
+export class AppFlight extends LitElement {
+  @subscribe(flightKey.gate)
+  @state()
+  gate = "";
 
-```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.
-
-### Piège migration `Subscriber` → `LitElement` (checklist)
-
-Lors du remplacement de `sonic-fetch` ou du retrait du mixin `Subscriber` sur un composant **métier** :
-
-| Étape | Vérification |
-|-------|----------------|
-| Champs affichés dans `render()` | Chaque `@property` autrefois remplie par template filling → **`@subscribe(dpKey.feuille)` + `@state()`** (pas laisser des `@property` orphelins) |
-| Enfant d’un `@get` | `@get` + `@publish`/`@handle` vers le DataProvider cible ; l’UI lit ce DP via `@subscribe`, pas via des props vides |
-| Placeholders `Endpoint` | Les noms `${prop}` doivent exister sur l’hôte (`@property` ou copie dans `willUpdate` si le scan utilise un autre nom, ex. `checkCode` → `code`) |
-| Modale / portal | `@get(endpoint, apiConfigKey)` si pas de `serviceURL` ascendant fiable (`Modal` → `Theme.getPopContainer()`) |
-| Remplacement `sonic-fetch` | Expliciter `dataProvider` + `subDataProvider` sur les hôtes `Subscriber` enfants (ex. `app` + `currentScanTicket`) |
-
-```typescript
-// ❌ — Subscriber retiré, props jamais alimentées
-export class TicketInfos extends LitElement {
-  @property({ type: Object }) owner = {};
-  render() { return html`${this.owner?.firstName}`; }
+  render() {
+    return html`Gate ${this.gate}`;
+  }
 }
-
-// ✅ — une souscription par champ affiché
-@subscribe(dpKeys.currentScanTicket.owner)
-@state() owner: Contact = {};
-```
-
-**`@subscribe` + décorateur Lit** : préférer **`@state()`** (pas `@property`) pour les champs purement lus depuis le DataProvider.
-
-## 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)` |
-| Effet après GET | `@get(endpoint)` sur une méthode |
-| Effet après écriture | `@post` / `@put` / `@patch` sur une méthode |
-| É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` + `@publish`/`@handle` + `@subscribe` / hôte `Subscriber` |
-| `extends Subscriber(LitElement)` (métier seul) | `LitElement` + `@subscribe` feuille par feuille / `sub()` — **ne pas oublier** les champs template-filled |
-| `extends Subscriber` (hôte d’enfants sonic) | Conserver `Subscriber` + `dataProvider` / `subDataProvider` corrects |
-| `@get` dans modale | `@get(endpoint, apiConfigKey)` si config API hors scope DOM |
-| `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) |
+## Imports
 
-## Recettes
+| What | From |
+|------|------|
+| Components (side-effect import) | `@supersoniks/concorde/button` · `/input` · `/list` · `/queue` · `/sonic-scope` · `/theme` … |
+| Decorators, `DataProviderKey`, `Endpoint`, `ApiResult` | `@supersoniks/concorde/decorators` |
+| `sub()` | `@supersoniks/concorde/directives` |
+| `get` / `set` / `dp`, `derive` | `@supersoniks/concorde/utils` |
+| `APIConfiguration` type | `@supersoniks/concorde/utils/api` |
 
-- **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: … }>`.
-- **GET avec effet de bord** : `@get(endpoint)` sur une méthode ; conserver
-  `const request = get(endpoint)` si un refetch nommé est nécessaire.
+`get` exists twice: the HTTP decorator (`/decorators`) and the store read (`/utils`). Alias one when a file needs both: `import { get as getRequest } from "@supersoniks/concorde/decorators"`. Inside the Concorde repository itself, short entry points do not resolve: import `@supersoniks/concorde/core/…` or relative paths.

package/ai/skills/concorde/rules/composition.md

@@ -0,0 +1,32 @@
+# Composition and states
+
+Docs: [Components](https://concorde.supersoniks.org/docs/getting-started/components). Exact attributes: query `custom-elements.json` (see `SKILL.md`).
+
+## Parts
+
+Compound components keep their parts inside them; do not rebuild a part with a `div`. A nav is `sonic-menu` + `sonic-menu-item`, not a stack of ghost buttons.
+
+| Component | Parts |
+|-----------|-------|
+| `sonic-card` | `sonic-card-header` (+ `sonic-card-header-description`) · `sonic-card-main` · `sonic-card-footer` |
+| `sonic-modal` | `sonic-modal-title` (always) · `sonic-modal-subtitle` · `sonic-modal-content` · `sonic-modal-actions`; inside the actions, a `sonic-button` with `hideModal` closes it |
+| `sonic-menu` | `sonic-menu-item` only; sections with `sonic-divider label="…"` |
+| `sonic-fieldset` | `sonic-legend` (or `label` / `description`), then `sonic-form-layout` |
+| Form body | `sonic-form-layout` for fields, `sonic-form-actions` last for the buttons |
+| `sonic-table` | `sonic-thead` · `sonic-tbody` · `sonic-tfoot` → `sonic-tr` → `sonic-th` / `sonic-td`; rows from `sonic-list` |
+
+Icons go in a button's `prefix` / `suffix` slot as `sonic-icon`, not as inline SVG.
+
+## States
+
+Use the state a component already has before adding `@state` flags and `if` branches.
+
+| State | Use |
+|-------|-----|
+| Action running | `loading` on `sonic-button` (spinner, blocks clicks) |
+| List loading / empty | `.skeleton` / `.noItems` on `sonic-list` / `sonic-queue`, or their `loader` attribute |
+| Other content loading | `sonic-loader mode="inline"`; without `mode` it covers the viewport |
+| Field validation | `required` / `pattern` / `min` / `max`; `status="error"` and `description` for the message |
+| Inline message | `sonic-alert status="…"` |
+| Short feedback | `SonicToast.add({ text, status })` from `@supersoniks/concorde/toast` |
+| Disabled | `disabled` on the button or field, not a class |

package/ai/skills/concorde/rules/data.md

@@ -0,0 +1,47 @@
+# Data: store and keys
+
+Docs: [Data flow](https://concorde.supersoniks.org/docs/getting-started/dataFlow) · [DataProviderKey](https://concorde.supersoniks.org/docs/misc/dataProviderKey) · [Dynamic paths](https://concorde.supersoniks.org/docs/misc/dynamic-path) · [@subscribe](https://concorde.supersoniks.org/docs/decorators/subscribe) · [@bind](https://concorde.supersoniks.org/docs/decorators/bind) · [@handle](https://concorde.supersoniks.org/docs/decorators/handle) · [sub()](https://concorde.supersoniks.org/docs/directives/sub)
+
+The app state is one store, the **DataProvider**, addressed by dot paths. Always go through a typed `DataProviderKey<T>`: `cartKey.items[0].qty` builds the path and checks the type.
+
+| Need | Use |
+|------|-----|
+| Display a value in a template | `sub(key.field)` |
+| Value used in logic / `willUpdate` | `@subscribe(key.field)` + `@state()` (read only) |
+| Write a property to the store | `@publish(key.field)` |
+| Read **and** write the same path | `@bind(key.field, { reflect: true })` |
+| Side effect on change | `@handle(keyA, keyB)` method |
+| Imperative read / write | `get(key)` · `set(key, value)` · `dp(key)` |
+| Inherit an ancestor attribute | `@ancestorAttribute("dataProvider")` |
+
+## Subscribe to the leaf you render
+
+A `set` on a child mutates the parent object in place and does not notify subscribers of the parent. `@subscribe(sessionKey)` + `this.session.title` misses title changes: use `sub(sessionKey.title)` or `@subscribe(sessionKey.title)`.
+
+`sub()` in templates, `get()` in code: `get()` in a template renders once and never updates.
+
+## Dynamic paths
+
+Placeholders go in a plain string (not a template literal) and are declared in the key's second generic. They resolve from properties of the host component, in decorators and in `sub()`:
+
+```ts
+const userKey = new DataProviderKey<User, { userId: string }>("users.${userId}");
+
+@property() userId = "";
+@subscribe(userKey.name) @state() name = "";
+```
+
+`get`, `set` and `dp` **throw** if the path they receive still contains `${…}` or `{$…}`. In imperative code, build the resolved key instead:
+
+```ts
+const usersKey = new DataProviderKey<Record<string, User>>("users");
+set(usersKey[userId], user);
+set(`app.pages.${index}.done`, true); // fine too: JS resolves it before the call
+```
+
+## Moving old code to keys
+
+- `get("app.widget.distance")` → `get(widgetKey.distance)`.
+- `dp(key.path)` / `set(key.path, v)` → `dp(key)` / `set(key, v)`.
+- A key with placeholders passed to `get` / `set` / `dp` → a decorator, or the resolved key above.
+- Leave `sub()` and decorators with placeholders as they are. Grepping `${` is not enough: what matters is the string received at runtime.

package/ai/skills/concorde/rules/http.md

@@ -0,0 +1,25 @@
+# HTTP
+
+Docs: [@get](https://concorde.supersoniks.org/docs/decorators/get) · [@post](https://concorde.supersoniks.org/docs/decorators/post) · [Endpoint](https://concorde.supersoniks.org/docs/misc/endpoint) · [API configuration](https://concorde.supersoniks.org/docs/misc/api-configuration)
+
+```ts
+const boardEndpoint = new Endpoint<FlightBoard, { direction: string }>(
+  "flights?direction=${direction}",
+);
+
+@property() direction = "departures";
+
+@get(boardEndpoint)
+@state()
+board?: ApiResult<FlightBoard>; // { result, response, request } | undefined
+```
+
+- `@get` on a property stores the `ApiResult<T>`; on a method, the method receives it. A change of a placeholder property runs the request again; while a placeholder is `null` / `undefined`, nothing is sent.
+- To reload: keep the handle (`const load = get(endpoint)`, then `@load` on the property) and call `load.refetch(this)`, or decorate a method with `@refetch(load)`.
+- `@post(endpoint, bodyKey)` (and `@put` / `@patch`) send the store value at `bodyKey`, **on every body mutation by default**. For a form submitted by a button: `post(endpoint, bodyKey, { autoPostOnBodyMutation: false })` kept in a constant, then `save.send(this)` or `@send(save)` on a method.
+
+## API configuration
+
+`serviceURL`, `token`, `credentials`… are read from ancestor attributes by default, usually `<sonic-scope serviceURL="…">` at the app root. A component rendered outside that DOM (modal, portal) gets them from the store instead: pass a `DataProviderKey<APIConfiguration>` as second argument, `@get(endpoint, apiKey)`.
+
+Do not put API settings on `sonic-theme`: it is for styling only.

package/ai/skills/concorde/rules/lists-forms.md

@@ -0,0 +1,35 @@
+# Lists and forms
+
+Docs: [List](https://concorde.supersoniks.org/core/components/functional/list) · [Queue](https://concorde.supersoniks.org/core/components/functional/queue) · [Input](https://concorde.supersoniks.org/core/components/ui/form/input) · [Submit](https://concorde.supersoniks.org/core/components/functional/submit)
+
+## Lists
+
+`sonic-list` renders one array; `sonic-queue` loads a paginated API in batches (lazy scroll, filters). Render rows with Lit properties: `.items=${(item) => html`…`}`, plus `.noItems` · `.skeleton` · `.separator`. The `.` is required: functions only pass as properties. (`<template>` children exist for plain-HTML hosts only.)
+
+```ts
+html`<sonic-queue
+  serviceURL="/api"
+  dataProviderExpression="flights?offset=$offset&limit=$limit"
+  key="flights"
+  dataFilterProvider=${flightSearchKey.path}
+  .items=${(f: Flight) => html`<app-flight-row .flight=${f}></app-flight-row>`}
+  .noItems=${() => html`No flights`}
+></sonic-queue>`;
+```
+
+## Forms
+
+Fields write into the store by themselves: `formDataProvider` on a container (or on the field) + `name` on each field. No `@input` / `.value` wiring.
+
+```ts
+html`<div formDataProvider=${checkInKey.path}>
+  <sonic-form-layout>
+    <sonic-input name="passenger" label="Passenger" required></sonic-input>
+    <sonic-select name="cabin" label="Cabin" .options=${cabins}></sonic-select>
+  </sonic-form-layout>
+</div>`;
+```
+
+- Read values with `sub()` / `@subscribe` on the form key.
+- Submit with `@post` + `send()` (see [http.md](http.md)), or `sonic-submit`.
+- A `sonic-queue` filters on a form store through `dataFilterProvider`: each non-empty field becomes a query parameter.