@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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 |
 |---------|---------|
@@ -17,60 +17,60 @@ On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` a
 # Starter (from project root)
 yarn ai:sync
 
-# Manual / existing project
+# Existing project
 node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
   </template>
 </sonic-code>
 
-## Useful flags
+Re-run the same command after each Concorde upgrade to refresh the skill.
 
-| 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.
+## The skill
+
+`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.
+
+| 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 |
+
+### Sources of truth
+
+The skill tells the agent to check, in this order:
+
+1. **The project** — the installed Concorde version (`npm ls @supersoniks/concorde`) and its existing `DataProviderKey`s, `Endpoint`s and components.
+2. **These docs** — index at [llms.txt](https://concorde.supersoniks.org/llms.txt); every page is served as Markdown when `.md` is appended to its URL. Offline: `node_modules/@supersoniks/concorde/src/**/*.md`.
+3. **The element API** — attributes, properties, events and slots in `node_modules/@supersoniks/concorde/custom-elements.json`. The file is large, so the agent queries one element:
+
+<sonic-code language="shell">
+  <template>
+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
+  </template>
+</sonic-code>
 
 ## 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 |
-
-## Workflow
-
-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`).
-
-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)).
+| `.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. Only Concorde's own skill is replaced on each run: a project skill with another name is left alone, and one with the same name in `.claude/skills` or `.junie/skills` is never overwritten. If `.claude/skills` already points to `.agents/skills`, no per-skill link is created. Commit `.agents/` and the links if your team shares agent settings.
+
+**`AGENTS.md` stays yours:** `ai-init` never reads or writes it.
+
+## Flags
+
+| 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) |
+| `--project-root <dir>` | Project to install into (default: current directory) |
+| `--concorde-ai <dir>` | Concorde `ai/` folder to install from (default: the package's own) |
+
+Source files in the npm package: `node_modules/@supersoniks/concorde/ai/skills/concorde/`.

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

@@ -6,7 +6,7 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 
 | Need | Use |
 |------|-----|
-| Read/write in code | `get` / `set` / `dp` + `DataProviderKey` (static paths only) |
+| Read/write in code | `get` / `set` / `dp` + `DataProviderKey` (static paths only). **Store immutable** : `set` takes ownership (clone + freeze); `get` / `@subscribe` typed `Frozen<T>` — mutate via `set` only ([study / ADR](/docs/misc/publisher-get-immutability-study)) |
 | Reactive Lit template | `sub(key)` or `@subscribe` |
 | Read component state from store | `@subscribe` + `DataProviderKey<T, U>` + `@state` |
 | Inherit ancestor attributes | `@ancestorAttribute` |
@@ -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
 

package/src/docs/home/home.ts

@@ -131,7 +131,7 @@ const COMPONENT_COUNT = INDEX_TABS.reduce(
   0,
 );
 
-const ARCHIVE = "./img/archive/";
+const ARCHIVE = "/img/archive/";
 
 /** Credit lines for the archive pictures (CC BY / CC BY-SA, from assets.mjs --credits). */
 const CREDITS = `Film: <a href="https://commons.wikimedia.org/wiki/File:Concorde_%26_Red_Arrows_2002.webm">“Concorde &amp; Red Arrows 2002”</a> by Steve Elliott, <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC BY-SA 2.0</a>, via Wikimedia Commons.`;
@@ -501,6 +501,8 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
           <sonic-link href="https://www.npmjs.com/package/@supersoniks/concorde" target="_blank"
             >npm</sonic-link
           >
+          <sonic-link href="/about">About</sonic-link>
+          <sonic-link href="/privacy">Privacy</sonic-link>
         </nav>
         <span class="footer-end">MIT licence · ${new Date().getFullYear()}</span>
       </div>