@supersoniks/concorde 5.1.2 → 5.1.3

package/docs/sitemap.xml

@@ -9,6 +9,12 @@
   <url>
     <loc>https://concorde.supersoniks.org/docs/index.html</loc>
   </url>
+  <url>
+    <loc>https://concorde.supersoniks.org/about</loc>
+  </url>
+  <url>
+    <loc>https://concorde.supersoniks.org/privacy</loc>
+  </url>
   <url>
     <loc>https://concorde.supersoniks.org/hubs/decorators.html</loc>
   </url>

package/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/docs/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/`.

package/docs/src/docs/getting-started/dataFlow.md

@@ -19,7 +19,7 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 | Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](/core/components/functional/jsonata) |
 | Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](/docs/misc/docs-mock-api) |
 
-Skill: `concorde-get-set-dp` in the package `ai/` folder.
+Agent skill: `concorde` (`rules/data.md`), see [AI agents](/docs/getting-started/ai-agents).
 
 ## DataProviderKey