@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

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.

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

@@ -0,0 +1,46 @@
+# Styling
+
+Docs: [Theming](https://concorde.supersoniks.org/docs/getting-started/theming). Which parts and states components offer: [composition.md](composition.md).
+
+## Theme
+
+One `<sonic-theme>` at the app root sets the tokens; popovers, modals and toasts mount under it.
+
+```ts
+html`<sonic-theme theme="auto" color font class="block bg-base min-h-screen">…</sonic-theme>`;
+```
+
+`theme="light" | "dark" | "auto"` picks a palette; without it, only your `--sc-*` overrides apply. To brand, override the **essential tokens** only (fills, `-content` pairs, `--sc-base-*`, `--sc-rounded`, fonts) on `sonic-theme` or `:root`. Never copy derived variables (`--sc-rounded-sm`, `--sc-btn-*`, …).
+
+## Rules
+
+1. **Compose components first.** `sonic-button`, `sonic-badge`, `sonic-alert`, `sonic-card`, `sonic-divider`, `sonic-menu`, `sonic-icon`, form fields… before hand-made markup ([composition.md](composition.md)).
+2. **Configure components with attributes, not CSS.** `type` (`primary` · `neutral` · `success` · `warning` · `danger` · `info`), `variant` (`outline` · `ghost` · `link`), `size` (`2xs` … `2xl`), `shape`, `status`. `class` on a `sonic-*` element is for layout only (width, margin, grid placement). No `::part()`, no private `--sc_*` variables.
+3. **Semantic tokens only.** Fills and their text go in pairs: `bg-primary text-primary-content`, `bg-danger text-danger-content`. Surfaces: `bg-base text-content`. Borders and muted UI: the neutral scale (`border-neutral-200`, `bg-neutral-50`, `text-neutral-600`). Never raw colors: no hex / rgb, no Tailwind palette (`blue-500`). A missing color becomes a theme token.
+4. **No `dark:` overrides.** Dark mode comes from `sonic-theme`; tokens switch by themselves.
+5. **Shape from tokens.** `rounded` / `rounded-lg`, `shadow` / `shadow-md` and `border` map to `--sc-rounded*`, `--sc-shadow*`, `--sc-border-width`. Avoid arbitrary values when they could be replaced easily (`rounded-[6px]`, `p-[13px]`).
+6. **Layout with `flex` / `grid` + `gap`.** Not `space-x-*` / `space-y-*` or margins between siblings. `size-10` instead of `w-10 h-10`.
+7. **Conditional classes with `classMap`** (`lit/directives/class-map.js`), dynamic values with `styleMap`. No template-literal ternaries inside `class="…"`.
+8. **Accessible by default.** Every field has a `label`. An icon-only button (`shape="circle"` / `"square"`) gets an `aria-label`; `sonic-icon` is `aria-hidden`.
+
+## In a component
+
+Tailwind classes apply inside a shadow root only if the component includes the project's Tailwind styles in `static styles`. Otherwise, write `css` with the tokens:
+
+```ts
+static styles = css`
+  :host { display: flex; gap: 0.5rem; }
+  .panel {
+    background: var(--sc-base);
+    color: var(--sc-base-content);
+    border: var(--sc-border-width) solid var(--sc-base-200);
+    border-radius: var(--sc-rounded);
+  }
+`;
+```
+
+```ts
+html`<div class=${classMap({ "bg-warning text-warning-content": delayed, "bg-base": !delayed })}>
+  <sonic-badge type=${delayed ? "warning" : "success"} size="sm">${status}</sonic-badge>
+</div>`;
+```

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

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+Symptom → usual cause → fix. Check these before reading framework source.
+
+## Data
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Value never updates in the view | Subscribed to a parent object; a child `set` mutates it in place without notifying | `sub(key.leaf)` or `@subscribe(key.leaf)` |
+| Same, with a leaf key | `@subscribe` without `@state()` | Add `@state()` |
+| Value frozen in a template | `get(key)` in `html` (one-time snapshot) | `sub(key)` |
+| `sub()` renders nothing | The store has no value yet, or a placeholder is `null` / `undefined` | Set an initial value; check the host property |
+| Store value overwritten when the component connects | `@publish` publishes a defined initializer on connect | Leave the property `undefined` to keep the store value |
+| `@handle` method crashes on start | It runs on connect and on every assignment, `null` included | Guard nullish values, or `{ waitForAllDefined: true }` / `Skip.Nullish` |
+| `get` / `set` / `dp` throw about a placeholder | A key with `${…}` reached imperative code | Decorator, or build the resolved key (`usersKey[id]`) |
+| Decorator with a dynamic path does nothing | A placeholder property is `null` / `undefined` (or `""` with `skipEmptyPlaceholder`) | Set the host property |
+
+## HTTP
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `@get` never sends | No `serviceURL` on an ancestor (the GET waits for it); common in modals and portals | `<sonic-scope serviceURL>` around it, or `@get(endpoint, apiConfigKey)` |
+| POST sent on every keystroke | `@post` sends on each body mutation by default | `{ autoPostOnBodyMutation: false }` + `send()` |
+| Property `undefined` after the request | Read `this.board.flights` instead of the `ApiResult` | `this.board?.result?.flights` |
+
+## Lists and forms
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| List renders nothing | `items=${fn}` without the dot, so the function is lost | `.items=${fn}` (same for `.noItems` / `.skeleton` / `.separator`) |
+| `sonic-list` never requests | No `fetch` attribute | Add `fetch` |
+| List empty although the response has data | `key` does not name the array in the response | Set `key` to the array property |
+| `sonic-queue` loads one batch only | No `$offset` in `dataProviderExpression` | `…?offset=$offset&limit=$limit` |
+| Queue ignores the filter form | `dataFilterProvider` is not the form's store, or fields lack `name` | Same key path on both; reload follows after a 400 ms debounce |
+| Field value not in the store | Missing `name`, or no `formDataProvider` on the field or an ancestor (`dataProvider` does not count) | Add both; pass `key.path`, not the key |
+
+## Rendering and styling
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| A `sonic-*` tag shows nothing | Its module was never imported | `import "@supersoniks/concorde/<name>"` |
+| Tailwind classes ignored inside a component | The shadow root does not include the Tailwind styles | Add them to `static styles`, or use `css` with `var(--sc-*)` |
+| Modal, popover or toast unstyled | No `sonic-theme` ancestor: they mount under the nearest one | Wrap the app in `sonic-theme` |
+| `hideModal` button does not close the modal | The button is not inside `sonic-modal-actions` | Move it there |
+| `get` is not a function / wrong `get` | Decorator `get` (`/decorators`) and store `get` (`/utils`) collide | Alias one: `get as getRequest` |

package/build-infos.json

@@ -1 +1 @@
-{"date":1793021294}
+{"date":1793309731}