@supersoniks/concorde 5.1.2 → 5.1.3

package/site-pages/privacy.md

@@ -0,0 +1,32 @@
+# Privacy notice
+
+This notice covers the Concorde documentation site, https://concorde.supersoniks.org, published by [Supersoniks](https://supersoniks.com/), 22 rue du Docteur Bretonneau, 37000 Tours, France.
+
+## What this site does not do
+
+- It has no user accounts, sign-up or login.
+- It sets no cookies and runs no analytics, advertising or tracking scripts.
+- It has no forms that send personal data to Supersoniks.
+
+## What is stored in your browser
+
+- `sonicTheme` in localStorage remembers your light or dark theme choice. It never leaves your browser.
+- A service worker serves the mock API used by live examples (`/docs-mock-api/…`). It runs locally in your browser.
+- Some examples demonstrate features that store values in localStorage (for example dismissed alerts or cached labels). They only run when you open those pages.
+
+## Third-party services
+
+To display pages, your browser loads files from these providers, which receive your IP address and browser details as part of any web request:
+
+- Google Fonts (fonts.googleapis.com, fonts.gstatic.com) for the Schibsted Grotesk font.
+- jsDelivr (cdn.jsdelivr.net) for the search and Markdown libraries.
+- cdn.supersoniks.com for icons.
+- A few live examples call public demo APIs (geo.api.gouv.fr, reqres.in, i.pravatar.cc) when you open them.
+
+## Server logs
+
+Like any web server, the host records technical request data (IP address, URL, date, user agent) to operate and secure the site.
+
+## Your rights
+
+Under the GDPR you can ask for access to, correction or deletion of data about you. Contact Supersoniks through [supersoniks.com/un-projet](https://supersoniks.com/un-projet), by phone at +33 2 47 68 93 25, or by mail at 22 rue du Docteur Bretonneau, 37000 Tours, France. See also the [Supersoniks privacy policy](https://supersoniks.com/politique-de-confidentialite) and [legal notice](https://supersoniks.com/mentions-legales).

package/src/core/components/functional/date/date.md

@@ -116,7 +116,7 @@ A child `<template data-value="<part>">` wraps a part in your own markup: `weekd
         <template data-value="year"><span class="block text-lg font-bold leading-tight"></span></template>
         <template data-value="to"><span class="block my-1 text-3xl leading-none">↓</span></template>
       </sonic-date>
-      <sonic-image src="img/concorde/plane_03.jpg" alt="Concorde specifications board" ratio="1/1" cover></sonic-image>
+      <sonic-image src="/img/concorde/plane_03.jpg" alt="Concorde specifications board" ratio="1/1" cover></sonic-image>
     </div>
   </template>
 </sonic-code>

package/src/core/components/functional/list/list.md

@@ -1,6 +1,6 @@
 # List
 
-**`sonic-list`** renders one row per entry of its `props` array, either set directly or loaded with `fetch`. From Lit, pass a row renderer on the `items` property; in plain HTML, declare `<template>` children. Each row gets its own data provider at `<dataProvider>/list-item/<index>`.
+**`sonic-list`** renders one row per entry of its `props` array, either set directly or loaded with `fetch`. In TypeScript, prefer the `.items` row renderer (with `.separator` · `.noItems` · `.skeleton`); `<template>` children are for plain HTML hosts without Lit. Each row gets its own data provider at `<dataProvider>/list-item/<index>`.
 
 ## Basic example
 
@@ -16,7 +16,7 @@ Add `fetch` to load `props` from `serviceURL` + `endPoint` (or `dataProvider` wh
   </template>
 </sonic-code>
 
-Fetch attributes (`lazyload` · `refetchEveryMs` · headers · authentication) are shared with [Fetch](/core/components/functional/fetch).
+This example uses HTML templates; from Lit, use the [row renderer](#row-renderer) instead. Fetch attributes (`lazyload` · `refetchEveryMs` · headers · authentication) are shared with [Fetch](/core/components/functional/fetch).
 
 ## Row renderer
 
@@ -98,6 +98,8 @@ With no `loader`, nothing is shown while fetching. Set `loader` (`fixed`) or `lo
 | `loader` | `fixed` (when empty) · `inline` | Loader shown while fetching. None by default |
 | `debug` | boolean | Shows each row's data on hover |
 
+Properties (TypeScript / Lit, preferred):
+
 | Property | Type | Description |
 |----------|------|-------------|
 | `props` | array · object | Rows to render |
@@ -107,6 +109,8 @@ With no `loader`, nothing is shown while fetching. Set `loader` (`fixed`) or `lo
 | `skeleton` | `() => TemplateResult` | Rendered while fetching |
 | `itemPropertyMap` | object | `propertyMap` passed to each row subscriber |
 
+Templates (plain HTML hosts):
+
 | Template | Description |
 |----------|-------------|
 | `<template>` | Row markup; several are used in turn |

package/src/core/components/functional/sdui/component-catalog.gaps.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:58:38.625Z",
+  "generatedAt": "2026-10-27T09:09:14.532Z",
   "count": 66,
   "items": [
     {

package/src/core/components/functional/sdui/component-catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:58:38.625Z",
+  "generatedAt": "2026-10-27T09:09:14.532Z",
   "componentCount": 67,
   "components": [
     {

package/src/core/components/ui/card/card.md

@@ -160,7 +160,7 @@ Header, media, body, and footer together.
         <sonic-image
           rounded
           ratio="16/9"
-          src="img/concorde/plane_04.jpg"
+          src="/img/concorde/plane_04.jpg"
           alt="Concorde on the apron under a blue sky"
         ></sonic-image>
         <p class="mb-0">

package/src/core/components/ui/image/image.md

@@ -10,31 +10,31 @@ With no `rounded`, corners are square. Boolean `rounded` uses the theme token `-
   <template>
     <div class="grid gap-6 grid-cols-3 lg:grid-cols-4 items-end text-center text-xs">
       <div>
-        <sonic-image ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">default</p>
       </div>
       <div>
-        <sonic-image rounded="sm" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded="sm" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">sm</p>
       </div>
       <div>
-        <sonic-image rounded ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">rounded</p>
       </div>
       <div>
-        <sonic-image rounded="md" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded="md" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">md</p>
       </div>
       <div>
-        <sonic-image rounded="lg" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded="lg" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">lg</p>
       </div>
       <div>
-        <sonic-image rounded="xl" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded="xl" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">xl</p>
       </div>
       <div>
-        <sonic-image rounded="full" ratio="1/1" src="img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <sonic-image rounded="full" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
         <p class="mt-2">full</p>
       </div>
     </div>
@@ -48,10 +48,10 @@ With no `rounded`, corners are square. Boolean `rounded` uses the theme token `-
 <sonic-code>
   <template>
     <div class="grid gap-8 grid-cols-2 items-center">
-      <sonic-image src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
-      <sonic-image ratio="16/9" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
-      <sonic-image ratio="1/1" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
-      <sonic-image ratio="2/3" src="img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="16/9" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="1/1" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="2/3" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
     </div>
   </template>
 </sonic-code>
@@ -63,8 +63,8 @@ With no `rounded`, corners are square. Boolean `rounded` uses the theme token `-
 <sonic-code>
   <template>
     <div class="grid gap-8 grid-cols-2 items-center">
-      <sonic-image ratio="11/4" src="img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
-      <sonic-image objectPosition="center top" ratio="11/4" src="img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
+      <sonic-image ratio="11/4" src="/img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
+      <sonic-image objectPosition="center top" ratio="11/4" src="/img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
     </div>
   </template>
 </sonic-code>
@@ -76,7 +76,7 @@ With no `rounded`, corners are square. Boolean `rounded` uses the theme token `-
 <sonic-code>
   <template>
     <div class="h-96 relative rounded-lg overflow-hidden">
-      <sonic-image cover src="img/concorde/plane_10.jpg" alt="Concorde fleet parked in a star"></sonic-image>
+      <sonic-image cover src="/img/concorde/plane_10.jpg" alt="Concorde fleet parked in a star"></sonic-image>
     </div>
   </template>
 </sonic-code>
@@ -99,7 +99,7 @@ Set `transition` to `fade` or `fade-scale-out`. The image stays transparent unti
           img.loading = 'eager';
           img.style.width = '8rem';
           var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
-          img.src = 'img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
+          img.src = '/img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
           host.appendChild(img);
         })()"
       >
@@ -117,7 +117,7 @@ Set `transition` to `fade` or `fade-scale-out`. The image stays transparent unti
           img.loading = 'eager';
           img.style.width = '8rem';
           var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
-          img.src = 'img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
+          img.src = '/img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
           host.appendChild(img);
         })()"
       >
@@ -145,7 +145,7 @@ Always set a meaningful `alt`. Use `alt=""` only for decorative images.
       rounded="md"
       ratio="16/9"
       alt="Crowd gathered around Concorde at night"
-      src="img/concorde/plane_07.jpg"
+      src="/img/concorde/plane_07.jpg"
     ></sonic-image>
   </template>
 </sonic-code>

package/src/core/components/ui/modal/modal.md

@@ -88,7 +88,7 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
     >
       <sonic-image
         cover
-        src="img/concorde/plane_12.jpg"
+        src="/img/concorde/plane_12.jpg"
         alt="Concorde at the gate with boarding stairs"
       ></sonic-image>
     </sonic-modal>
@@ -105,7 +105,7 @@ Set **`width`** · **`height`** · **`maxWidth`** · **`maxHeight`** with CSS le
     <sonic-modal fullscreen id="Fullscreen">
       <sonic-image
         cover
-        src="img/concorde/plane_10.jpg"
+        src="/img/concorde/plane_10.jpg"
         alt="Concorde fleet parked in a star"
       ></sonic-image>
     </sonic-modal>

package/src/core/decorators/subscriber/bind.ts

@@ -189,28 +189,23 @@ function bindImpl(
   };
 }
 
+/** @deprecated Pass a `DataProviderKey<T>` instead of a string path (typed, refactor-safe). */
+export function bind(
+  path: string,
+  options?: BindOptions,
+): (target: unknown, propertyKey: string) => void;
 /**
- * Bidirectional binding to a publisher path. Subscribes to changes and optionally reflects writes back.
- * Accepts either a string path (legacy) or DataProviderKey&lt;T&gt; for type-safe binding.
- * Supports dynamic paths: use placeholders like "users.${userIndex}" in the path or DataProviderKey.
+ * Bidirectional binding to a publisher path: subscribes to changes and, with
+ * `reflect: true`, writes local assignments back. For one direction only, use
+ * `@subscribe` (read) or `@publish` (write).
+ * Supports dynamic paths: use placeholders like "users.${userIndex}" in the DataProviderKey.
  *
  * @example
- * // String path (legacy):
- * @bind("demoData.firstName")
- * @state()
- * firstName = "";
- *
- * @example
- * // DataProviderKey with type validation:
  * const dataKey = new DataProviderKey<Data>("data");
  * @bind(dataKey.count, { reflect: true })
  * @state()
  * count: number = 0;
  */
-export function bind(
-  path: string,
-  options?: BindOptions,
-): (target: unknown, propertyKey: string) => void;
 export function bind<T, U = any>(
   key: DataProviderKey<T, U>,
   options?: BindOptions,

package/src/docs/components/docs-demo-sources.ts

@@ -342,12 +342,12 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
   ],
   "demo-bind": [
-    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 32, label: "demo-bind" },
+    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 36, label: "demo-bind" },
   ],
   "demo-bind-reflect": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 70,
+      line: 74,
       label: "demo-bind-reflect",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -355,7 +355,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-bind-dynamic": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 130,
+      line: 113,
       label: "demo-bind-dynamic",
     },
   ],

package/src/docs/decorators/bind.md

@@ -1,22 +1,26 @@
 # @bind
 
-Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a [DataProviderKey](/docs/misc/dataProviderKey); add `{ reflect: true }` to push local writes back to the store. For read-only sync prefer [@subscribe](/docs/decorators/subscribe), and see [Data flow](/docs/getting-started/dataFlow) for the overall model.
+`@bind(key)` keeps a class property and one path of the DataProvider store in sync. With `{ reflect: true }` the sync goes both ways: the property follows the store, and each assignment is written back to it. For one direction only, use the complementary decorators: [@subscribe](/docs/decorators/subscribe) to read, [@publish](/docs/decorators/publish) to write. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { bind } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Flight = { flight: string; gate: string; boarded: number };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
 
-@bind("flight.gate")
+@bind(flightKey.boarded, { reflect: true })
 @state()
-gate = "";
+boarded = 0;
   </template>
 </sonic-code>
 
 ## Basic usage
 
-The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: `passengers.0`). The property updates each time the store value changes. Add `@state()` so Lit re-renders.
+The key is a [DataProviderKey](/docs/misc/dataProviderKey): TypeScript checks that the property type matches `T` at that path. The property updates each time the store value changes. Add `@state()` so Lit re-renders.
 
 <sonic-code>
   <template>
@@ -25,26 +29,9 @@ The first path segment is the data provider id, the rest is dot notation (array
   </template>
 </sonic-code>
 
-## Typed key
-
-With a `DataProviderKey<T>`, TypeScript checks that the property type matches `T` at that path.
-
-<sonic-code language="typescript">
-  <template>
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-
-type Flight = { flight: string; gate: string; boarded: number };
-const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
-
-@bind(flightKey.boarded, { reflect: true })
-@state()
-boarded = 0;
-  </template>
-</sonic-code>
-
 ## Reflect
 
-By default (`reflect: false`) the binding is one-way: assigning the property does not touch the store. With `reflect: true`, each assignment calls `set()` on the publisher, so every other subscriber sees the new value. An internal guard prevents update loops.
+With `reflect: true`, each assignment to the property calls `set()` at the key path, so every other subscriber sees the new value. An internal guard prevents update loops. Without `reflect` (the default), assigning the property does not touch the store, and `@bind` behaves like `@subscribe`.
 
 <sonic-code>
   <template>
@@ -55,7 +42,19 @@ By default (`reflect: false`) the binding is one-way: assigning the property doe
 
 ## Dynamic path
 
-Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Declare them in the key's second generic and write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;Person, { dataProvider: string; index: number }&gt;(
+  "${dataProvider}.${index}",
+);
+
+@bind(personKey)
+@state()
+person: Person | null = null;
+  </template>
+</sonic-code>
 
 <sonic-code>
   <template>
@@ -72,6 +71,6 @@ The decorator subscribes in `connectedCallback` and unsubscribes in `disconnecte
 
 | Argument | Type | Description |
 |----------|------|-------------|
-| `path` | `string` or `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
+| `key` | `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
 | `options.reflect` | `boolean` (default `false`) | Write local assignments back to the store |
 | `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |

package/src/docs/docs-location.spec.ts

@@ -19,6 +19,16 @@ describe("docsPagePath / docsPageHref", () => {
 });
 
 describe("parseDocsLocation", () => {
+  it("maps root site pages to their markdown", () => {
+    const r = parseDocsLocation("/about");
+    expect(r.url).toBe("about.md");
+    expect(r.pagePath).toBe("/about");
+    expect(parseDocsLocation("/privacy#your-rights").anchor).toBe("your-rights");
+    expect(parseDocsLocation("/about/").url).toBe("about.md");
+    expect(parseDocsLocation("/developers").url).toBe("");
+    expect(parseDocsLocation("/unknown").url).toBe("");
+  });
+
   it("parses pretty pathname doc URLs", () => {
     const r = parseDocsLocation("/docs/getting-started/start");
     expect(r.url).toBe("docs/getting-started/start.md");

package/src/docs/docs-location.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+  SITE_PAGE_SLUGS,
   toPublicMdRel,
   toPublicPath,
   toSourceId,
@@ -107,6 +108,15 @@ export function parseDocsLocation(location: string): {
   }
 
   const rel = pathname.replace(/^\//, "");
+  if (SITE_PAGE_SLUGS.includes(rel)) {
+    return {
+      url: `${rel}.md`,
+      anchor: hash,
+      demoSubHash: hash,
+      pagePath: pathname,
+      pageHash: pathname,
+    };
+  }
   if (!rel || !isDocsContentPath(rel)) {
     return empty;
   }

package/src/docs/example/decorators-demo-bind-demos.ts

@@ -14,6 +14,10 @@ type Person = { firstName: string; lastName: string; role: string };
 const bindFlightKey = new DataProviderKey<Flight>("bindFlight");
 const bindPassengersKey = new DataProviderKey<Person[]>("bindPassengers");
 const bindCrewKey = new DataProviderKey<Person[]>("bindCrew");
+const bindPersonKey = new DataProviderKey<
+  Person,
+  { dataProvider: string; index: number }
+>("${dataProvider}.${index}");
 
 const GATES = ["B12", "B14", "C2", "D7", "E31"];
 
@@ -33,15 +37,15 @@ set(bindCrewKey, [
 export class DemoBind extends LitElement {
   static styles = [tailwind];
 
-  @bind("bindFlight.flight")
+  @bind(bindFlightKey.flight)
   @state()
   flight = "";
 
-  @bind("bindFlight.gate")
+  @bind(bindFlightKey.gate)
   @state()
   gate = "";
 
-  @bind("bindFlight.updates")
+  @bind(bindFlightKey.updates)
   @state()
   updates = 0;
 
@@ -71,11 +75,11 @@ export class DemoBind extends LitElement {
 export class DemoBindReflect extends LitElement {
   static styles = [tailwind];
 
-  @bind("bindReflectDemo.count", { reflect: true })
+  @bind(bindReflectDemoKey.count, { reflect: true })
   @state()
   withReflect = 0;
 
-  @bind("bindReflectDemo.count")
+  @bind(bindReflectDemoKey.count)
   @state()
   withoutReflect = 0;
 
@@ -91,7 +95,7 @@ export class DemoBindReflect extends LitElement {
   render() {
     return html`
       <div class="mb-3">
-        Boarded passengers in the store: ${sub("bindReflectDemo.count")}<br />
+        Boarded passengers in the store: ${sub(bindReflectDemoKey.count)}<br />
         Property with reflect: ${this.withReflect}<br />
         Property without reflect: ${this.withoutReflect}
       </div>
@@ -106,27 +110,6 @@ export class DemoBindReflect extends LitElement {
   }
 }
 
-@customElement("demo-bind-key")
-export class DemoBindKey extends LitElement {
-  static styles = [tailwind];
-
-  @bind(bindReflectDemoKey.count, { reflect: true })
-  @state()
-  count = 0;
-
-  connectedCallback() {
-    super.connectedCallback();
-    set(bindReflectDemoKey, { count: 0 });
-  }
-
-  render() {
-    return html`
-      <p class="mb-3">Boarded passengers: ${this.count}</p>
-      <sonic-button @click=${() => this.count++}>Board one passenger</sonic-button>
-    `;
-  }
-}
-
 @customElement("demo-bind-dynamic")
 export class DemoBindDynamic extends LitElement {
   static styles = [tailwind];
@@ -137,7 +120,7 @@ export class DemoBindDynamic extends LitElement {
   @property({ type: Number })
   index = 0;
 
-  @bind("${dataProvider}.${index}")
+  @bind(bindPersonKey)
   @state()
   person: Person | null = null;
 

package/src/docs/example/docs-toggle-demos.ts

@@ -36,7 +36,7 @@ export class DocsToggleIfDemo extends LitElement {
         ></sonic-checkbox>
         <sonic-if .condition=${show} class="mt-4 block">
           <sonic-image
-            src="img/concorde/plane_07.jpg"
+            src="/img/concorde/plane_07.jpg"
             alt="Crowd gathered around Concorde at night"
             rounded="md"
             ratio="3/2"

package/src/docs/getting-started/ai-agents.md

@@ -1,10 +1,10 @@
-# AI agents (skills & AGENTS.md)
+# AI agents (skill)
 
-Concorde ships **skills**, **rules**, and a root **`AGENTS.md`** so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migrations).
+Concorde ships one [Agent Skill](https://agentskills.io), `concorde`, so coding agents follow the framework patterns. Cursor, Claude Code, JetBrains Junie and other agents load it on their own when they work on Concorde code; there is nothing to add to your `AGENTS.md`.
 
-On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` after install. On an existing project, install Concorde first, then use `ai-init` below.
+On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` after install. On an existing project, install Concorde first, then run `ai-init`.
 
-## Dedicated commands
+## Commands
 
 | Context | Command |
 |---------|---------|
@@ -12,65 +12,39 @@ On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` a
 | Any consumer app (after `yarn add @supersoniks/concorde`) | `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` |
 | Concorde repo (contributors) | `yarn ai-init` |
 
-<sonic-code language="shell">
-  <template>
-# Starter (from project root)
-yarn ai:sync
+Re-run the same command after each Concorde upgrade to refresh the skill.
 
-# Manual / existing project
-node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
-  </template>
-</sonic-code>
+## The skill
 
-## Useful flags
+`SKILL.md` is the entry point: where to find the truth (the project, these docs, `custom-elements.json`), the critical rules and the imports. Details live in `rules/` files that the agent reads only for the topic at hand.
 
-| Flag | Effect |
-|------|--------|
-| `--skip-agents` | Never write `AGENTS.md` (skills / rules only) |
-| `--merge-agents` | Opt-in: keep the project preamble and append / refresh the Concorde block |
-| `--force-agents` | Opt-in: **replace** the whole `AGENTS.md` (destructive) |
-| `--overlay <dir>` | Extra rules/skills + optional `AGENTS.concorde.md` for project-only Concorde agent notes |
-| `--cursor-only` | Install only `.cursor/skills` and `.cursor/rules` |
-| `--jetbrains-only` | Install only `.aiassistant/rules/` |
-
-## `AGENTS.md` policy (non-invasive)
-
-| Situation | Default |
-|-----------|---------|
-| No `AGENTS.md` | Create the Concorde guide |
-| File with `<!-- concorde-ai -->` | Refresh the managed zone only |
-| File **without** marker (project notes) | **Left untouched** — skills / rules are enough |
-| `--merge-agents` / `--force-agents` / `--skip-agents` | See flags above |
-
-```text
-[optional project preamble — short, project-only]
-<!-- concorde-ai -->
-<package ai/AGENTS.md>
-[--- + overlay AGENTS.concorde.md]
-```
-
-Everything **after** `<!-- concorde-ai -->` is replaced on each `ai-init` run (idempotent). Do not paste a full copy of the Concorde guide above the marker — put project-specific notes in `AGENTS.concorde.md` (overlay). If the preamble duplicates package `AGENTS.md`, `ai-init` slims or drops it and prints a warning. Legacy filenames `AGENTS.overlay.md` / `AGENTS.starter.md` are still accepted with a deprecation warning.
+| File | Topic |
+|------|-------|
+| `SKILL.md` | Sources, critical rules, component shape, imports |
+| `rules/data.md` | Store, `DataProviderKey`, `@subscribe` / `@publish` / `@bind` / `@handle`, `sub()`, `get` / `set` / `dp` |
+| `rules/http.md` | `Endpoint`, `@get` / `@post`, API configuration |
+| `rules/lists-forms.md` | `sonic-list` / `sonic-queue`, form fields |
+| `rules/styling.md` | Theme, tokens, classes, styling rules |
+| `rules/composition.md` | Parts of compound components, built-in states |
+| `rules/troubleshooting.md` | Symptom → cause → fix: values not updating, requests not sent, empty lists |
 
 ## What gets installed
 
 | Path | Role |
 |------|------|
-| `AGENTS.md` | Created only if missing; existing project-owned files are left alone unless `--merge-agents` / `--force-agents` |
-| `.cursor/skills/concorde/` | Core Lit + DataProvider patterns |
-| `.cursor/skills/concorde-imports/` | Short `@supersoniks/concorde/…` import paths |
-| `.cursor/skills/concorde-scope/` | `serviceURL`, `formDataProvider`, API configuration |
-| `.cursor/skills/concorde-theme/` | `sonic-theme` and `--sc-*` tokens |
-| `.cursor/skills/concorde-menu/` | `sonic-menu` navigation |
-| `.cursor/skills/concorde-get-set-dp/` | `get` / `set` / `dp` and `DataProviderKey` migration |
-| `.cursor/rules/concorde.mdc` | Cursor rules (always-on patterns) |
-| `.aiassistant/rules/concorde.md` | JetBrains AI Assistant rules |
+| `.agents/skills/concorde/` | The skill (read directly by Cursor) |
+| `.claude/skills/concorde` | Symlink for Claude Code |
+| `.junie/skills/concorde` | Symlink for JetBrains Junie |
+
+Where symlinks are not allowed (some Windows setups), the skill is copied instead. Your own skills in these folders are never touched. Commit `.agents/` and the links if your team shares agent settings.
+
+**`AGENTS.md` stays yours:** `ai-init` never reads or writes it.
 
-## Workflow
+## Flags
 
-1. **Starter project:** [Installation](/docs/getting-started/installation) — `yarn ai:sync` is wired in the kit.
-2. **Existing project:** run **`ai-init`** after `yarn add @supersoniks/concorde`.
-3. Commit `.cursor/` and `.aiassistant/` (and `AGENTS.md` only if you opted in / it was created) if your team shares agent settings.
-4. Re-run the same command when you bump `@supersoniks/concorde` to refresh skills from `node_modules/@supersoniks/concorde/ai/`.
-5. In Cursor, skills under `.cursor/skills/` are picked up automatically; mention a skill in chat for focused tasks (e.g. migration → `concorde-get-set-dp`).
+| Flag | Effect |
+|------|--------|
+| `--no-links` | Install `.agents/skills` only, without the `.claude` / `.junie` links |
+| `--overlay <dir>` | Also install the skills found in `<dir>/skills/` (project kit) |
 
-Source files in the npm package: `node_modules/@supersoniks/concorde/ai/` (see also `ai/README.md` in the [Concorde repository](https://github.com/supersoniks/concorde)).
+Source files in the npm package: `node_modules/@supersoniks/concorde/ai/skills/concorde/`.