@supersoniks/concorde 5.1.2 → 5.1.3

package/docs/docs/decorators/bind.html

@@ -4,8 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>@bind — Concorde by Supersoniks</title>
-  <meta name="description" content="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; add { reflect: true } to push local writes back t">
-  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/bind, bind, @bind, decorator, { reflect: true }, passengers.0, @state(), DataProviderKey, reflect: false, reflect: true, set(), ${index}, null">
+  <meta name="description" content="@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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/bind, bind, @bind, decorator, @bind(key), { reflect: true }, @state(), reflect: true, set(), reflect, @subscribe, ${index}">
   <meta name="concorde-doc-id" content="docs/decorators/bind">
   <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/bind">
   <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/bind.md">
@@ -16,24 +16,12 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @bind</strong>. 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; add { reflect: true } to push local writes back t <span>Doc ID: <code>docs/decorators/bind</code>. Keywords: Concorde, supersoniks, docs/decorators/bind, bind, @bind, decorator, { reflect: true }, passengers.0, @state(), DataProviderKey, reflect: false, reflect: true, set(), ${index}, null. URL: <a href="https://concorde.supersoniks.org/docs/decorators/bind">https://concorde.supersoniks.org/docs/decorators/bind</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @bind</strong>. @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 <span>Doc ID: <code>docs/decorators/bind</code>. Keywords: Concorde, supersoniks, docs/decorators/bind, bind, @bind, decorator, @bind(key), { reflect: true }, @state(), reflect: true, set(), reflect, @subscribe, ${index}. URL: <a href="https://concorde.supersoniks.org/docs/decorators/bind">https://concorde.supersoniks.org/docs/decorators/bind</a>.</span></p>
       <h1 id="bind">@bind</h1>
-<p>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 <a href="/docs/misc/dataProviderKey">DataProviderKey</a>; add <code>{ reflect: true }</code> to push local writes back to the store. For read-only sync prefer <a href="/docs/decorators/subscribe">@subscribe</a>, and see <a href="/docs/getting-started/dataFlow">Data flow</a> for the overall model.</p>
+<p><code>@bind(key)</code> keeps a class property and one path of the DataProvider store in sync. With <code>{ reflect: true }</code> 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: <a href="/docs/decorators/subscribe">@subscribe</a> to read, <a href="/docs/decorators/publish">@publish</a> to write. See <a href="/docs/getting-started/dataFlow">Data flow</a> for the overall model.</p>
 <h2 id="import">Import</h2>
 <pre><code class="language-typescript">import { bind } from &quot;@supersoniks/concorde/decorators&quot;;
-
-@bind(&quot;flight.gate&quot;)
-@state()
-gate = &quot;&quot;;
-</code></pre>
-<h2 id="basic-usage">Basic usage</h2>
-<p>The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: <code>passengers.0</code>). The property updates each time the store value changes. Add <code>@state()</code> so Lit re-renders.</p>
-<pre><code>&lt;docs-demo-sources for=&quot;demo-bind&quot;&gt;&lt;/docs-demo-sources&gt;
-    &lt;demo-bind&gt;&lt;/demo-bind&gt;
-</code></pre>
-<h2 id="typed-key">Typed key</h2>
-<p>With a <code>DataProviderKey&lt;T&gt;</code>, TypeScript checks that the property type matches <code>T</code> at that path.</p>
-<pre><code class="language-typescript">import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
 
 type Flight = { flight: string; gate: string; boarded: number };
 const flightKey = new DataProviderKey&amp;lt;Flight&amp;gt;(&quot;flight&quot;);
@@ -42,13 +30,26 @@ const flightKey = new DataProviderKey&amp;lt;Flight&amp;gt;(&quot;flight&quot;);
 @state()
 boarded = 0;
 </code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>The key is a <a href="/docs/misc/dataProviderKey">DataProviderKey</a>: TypeScript checks that the property type matches <code>T</code> at that path. The property updates each time the store value changes. Add <code>@state()</code> so Lit re-renders.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-bind&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-bind&gt;&lt;/demo-bind&gt;
+</code></pre>
 <h2 id="reflect">Reflect</h2>
-<p>By default (<code>reflect: false</code>) the binding is one-way: assigning the property does not touch the store. With <code>reflect: true</code>, each assignment calls <code>set()</code> on the publisher, so every other subscriber sees the new value. An internal guard prevents update loops.</p>
+<p>With <code>reflect: true</code>, each assignment to the property calls <code>set()</code> at the key path, so every other subscriber sees the new value. An internal guard prevents update loops. Without <code>reflect</code> (the default), assigning the property does not touch the store, and <code>@bind</code> behaves like <code>@subscribe</code>.</p>
 <pre><code>&lt;docs-demo-sources for=&quot;demo-bind-reflect&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-bind-reflect&gt;&lt;/demo-bind-reflect&gt;
 </code></pre>
 <h2 id="dynamic-path">Dynamic path</h2>
-<p>Placeholders such as <code>${index}</code> are resolved from properties of the same component, and <code>@bind</code> re-subscribes when they change. Write them in a plain string, not a backtick template literal. While a placeholder is <code>null</code> or <code>undefined</code> the binding is inactive; <code>{ skipEmptyPlaceholder: true }</code> also waits on <code>&quot;&quot;</code>. Full rules: <a href="/docs/misc/dynamic-path">Dynamic paths</a>.</p>
+<p>Placeholders such as <code>${index}</code> are resolved from properties of the same component, and <code>@bind</code> re-subscribes when they change. Declare them in the key&#39;s second generic and write them in a plain string, not a backtick template literal. While a placeholder is <code>null</code> or <code>undefined</code> the binding is inactive; <code>{ skipEmptyPlaceholder: true }</code> also waits on <code>&quot;&quot;</code>. Full rules: <a href="/docs/misc/dynamic-path">Dynamic paths</a>.</p>
+<pre><code class="language-typescript">const personKey = new DataProviderKey&amp;lt;Person, { dataProvider: string; index: number }&amp;gt;(
+  &quot;${dataProvider}.${index}&quot;,
+);
+
+@bind(personKey)
+@state()
+person: Person | null = null;
+</code></pre>
 <pre><code>&lt;docs-demo-sources for=&quot;demo-bind-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
     &lt;demo-bind-dynamic&gt;&lt;/demo-bind-dynamic&gt;
 </code></pre>
@@ -64,8 +65,8 @@ boarded = 0;
 </tr>
 </thead>
 <tbody><tr>
-<td><code>path</code></td>
-<td><code>string</code> or <code>DataProviderKey&lt;T&gt;</code></td>
+<td><code>key</code></td>
+<td><code>DataProviderKey&lt;T&gt;</code></td>
 <td>Store path to bind. Supports <code>${prop}</code> placeholders</td>
 </tr>
 <tr>

package/docs/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/docs/getting-started/ai-agents.html

@@ -3,10 +3,10 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>AI agents (skills &amp; AGENTS.md) — Concorde by Supersoniks</title>
-  <meta name="description" content="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, migratio">
-  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/ai-agents, ai-agents, AI agents (skills &amp; AGENTS.md), guide, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
-| Concorde repo (contributors) | , --skip-agents, --merge-agents, --force-agents">
+  <title>AI agents (skill) — Concorde by Supersoniks</title>
+  <meta name="description" content="Concorde ships one Agent Skill, 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; th">
+  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/ai-agents, ai-agents, AI agents (skill), guide, concorde, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
+| Concorde repo (contributors) | , SKILL.md, custom-elements.json, rules/">
   <meta name="concorde-doc-id" content="docs/getting-started/ai-agents">
   <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/ai-agents">
   <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/ai-agents.md">
@@ -17,12 +17,12 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — AI agents (skills &amp; AGENTS.md)</strong>. 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, migratio <span>Doc ID: <code>docs/getting-started/ai-agents</code>. Keywords: Concorde, supersoniks, docs/getting-started/ai-agents, ai-agents, AI agents (skills &amp; AGENTS.md), guide, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
-| Concorde repo (contributors) | , --skip-agents, --merge-agents, --force-agents. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/ai-agents">https://concorde.supersoniks.org/docs/getting-started/ai-agents</a>.</span></p>
-      <h1 id="ai-agents-skills--agentsmd">AI agents (skills &amp; AGENTS.md)</h1>
-<p>Concorde ships <strong>skills</strong>, <strong>rules</strong>, and a root <strong><code>AGENTS.md</code></strong> so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migrations).</p>
-<p>On a <a href="/docs/getting-started/installation">starter</a> project, run <code>yarn ai:sync</code> after install. On an existing project, install Concorde first, then use <code>ai-init</code> below.</p>
-<h2 id="dedicated-commands">Dedicated commands</h2>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — AI agents (skill)</strong>. Concorde ships one Agent Skill, 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; th <span>Doc ID: <code>docs/getting-started/ai-agents</code>. Keywords: Concorde, supersoniks, docs/getting-started/ai-agents, ai-agents, AI agents (skill), guide, concorde, AGENTS.md, yarn ai:sync, ai-init, yarn add @supersoniks/concorde,  |
+| Concorde repo (contributors) | , SKILL.md, custom-elements.json, rules/. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/ai-agents">https://concorde.supersoniks.org/docs/getting-started/ai-agents</a>.</span></p>
+      <h1 id="ai-agents-skill">AI agents (skill)</h1>
+<p>Concorde ships one <a href="https://agentskills.io">Agent Skill</a>, <code>concorde</code>, 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 <code>AGENTS.md</code>.</p>
+<p>On a <a href="/docs/getting-started/installation">starter</a> project, run <code>yarn ai:sync</code> after install. On an existing project, install Concorde first, then run <code>ai-init</code>.</p>
+<h2 id="commands">Commands</h2>
 <table>
 <thead>
 <tr>
@@ -43,76 +43,45 @@
 <td><code>yarn ai-init</code></td>
 </tr>
 </tbody></table>
-<pre><code class="language-shell"># Starter (from project root)
-yarn ai:sync
-
-# Manual / existing project
-node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
-</code></pre>
-<h2 id="useful-flags">Useful flags</h2>
+<p>Re-run the same command after each Concorde upgrade to refresh the skill.</p>
+<h2 id="the-skill">The skill</h2>
+<p><code>SKILL.md</code> is the entry point: where to find the truth (the project, these docs, <code>custom-elements.json</code>), the critical rules and the imports. Details live in <code>rules/</code> files that the agent reads only for the topic at hand.</p>
 <table>
 <thead>
 <tr>
-<th>Flag</th>
-<th>Effect</th>
+<th>File</th>
+<th>Topic</th>
 </tr>
 </thead>
 <tbody><tr>
-<td><code>--skip-agents</code></td>
-<td>Never write <code>AGENTS.md</code> (skills / rules only)</td>
-</tr>
-<tr>
-<td><code>--merge-agents</code></td>
-<td>Opt-in: keep the project preamble and append / refresh the Concorde block</td>
-</tr>
-<tr>
-<td><code>--force-agents</code></td>
-<td>Opt-in: <strong>replace</strong> the whole <code>AGENTS.md</code> (destructive)</td>
-</tr>
-<tr>
-<td><code>--overlay &lt;dir&gt;</code></td>
-<td>Extra rules/skills + optional <code>AGENTS.concorde.md</code> for project-only Concorde agent notes</td>
+<td><code>SKILL.md</code></td>
+<td>Sources, critical rules, component shape, imports</td>
 </tr>
 <tr>
-<td><code>--cursor-only</code></td>
-<td>Install only <code>.cursor/skills</code> and <code>.cursor/rules</code></td>
+<td><code>rules/data.md</code></td>
+<td>Store, <code>DataProviderKey</code>, <code>@subscribe</code> / <code>@publish</code> / <code>@bind</code> / <code>@handle</code>, <code>sub()</code>, <code>get</code> / <code>set</code> / <code>dp</code></td>
 </tr>
 <tr>
-<td><code>--jetbrains-only</code></td>
-<td>Install only <code>.aiassistant/rules/</code></td>
+<td><code>rules/http.md</code></td>
+<td><code>Endpoint</code>, <code>@get</code> / <code>@post</code>, API configuration</td>
 </tr>
-</tbody></table>
-<h2 id="agentsmd-policy-non-invasive"><code>AGENTS.md</code> policy (non-invasive)</h2>
-<table>
-<thead>
 <tr>
-<th>Situation</th>
-<th>Default</th>
-</tr>
-</thead>
-<tbody><tr>
-<td>No <code>AGENTS.md</code></td>
-<td>Create the Concorde guide</td>
+<td><code>rules/lists-forms.md</code></td>
+<td><code>sonic-list</code> / <code>sonic-queue</code>, form fields</td>
 </tr>
 <tr>
-<td>File with <code>&lt;!-- concorde-ai --&gt;</code></td>
-<td>Refresh the managed zone only</td>
+<td><code>rules/styling.md</code></td>
+<td>Theme, tokens, classes, styling rules</td>
 </tr>
 <tr>
-<td>File <strong>without</strong> marker (project notes)</td>
-<td><strong>Left untouched</strong> — skills / rules are enough</td>
+<td><code>rules/composition.md</code></td>
+<td>Parts of compound components, built-in states</td>
 </tr>
 <tr>
-<td><code>--merge-agents</code> / <code>--force-agents</code> / <code>--skip-agents</code></td>
-<td>See flags above</td>
+<td><code>rules/troubleshooting.md</code></td>
+<td>Symptom → cause → fix: values not updating, requests not sent, empty lists</td>
 </tr>
 </tbody></table>
-<pre><code class="language-text">[optional project preamble — short, project-only]
-&lt;!-- concorde-ai --&gt;
-&lt;package ai/AGENTS.md&gt;
-[--- + overlay AGENTS.concorde.md]
-</code></pre>
-<p>Everything <strong>after</strong> <code>&lt;!-- concorde-ai --&gt;</code> is replaced on each <code>ai-init</code> run (idempotent). Do not paste a full copy of the Concorde guide above the marker — put project-specific notes in <code>AGENTS.concorde.md</code> (overlay). If the preamble duplicates package <code>AGENTS.md</code>, <code>ai-init</code> slims or drops it and prints a warning. Legacy filenames <code>AGENTS.overlay.md</code> / <code>AGENTS.starter.md</code> are still accepted with a deprecation warning.</p>
 <h2 id="what-gets-installed">What gets installed</h2>
 <table>
 <thead>
@@ -122,51 +91,38 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 </tr>
 </thead>
 <tbody><tr>
-<td><code>AGENTS.md</code></td>
-<td>Created only if missing; existing project-owned files are left alone unless <code>--merge-agents</code> / <code>--force-agents</code></td>
+<td><code>.agents/skills/concorde/</code></td>
+<td>The skill (read directly by Cursor)</td>
 </tr>
 <tr>
-<td><code>.cursor/skills/concorde/</code></td>
-<td>Core Lit + DataProvider patterns</td>
+<td><code>.claude/skills/concorde</code></td>
+<td>Symlink for Claude Code</td>
 </tr>
 <tr>
-<td><code>.cursor/skills/concorde-imports/</code></td>
-<td>Short <code>@supersoniks/concorde/…</code> import paths</td>
-</tr>
-<tr>
-<td><code>.cursor/skills/concorde-scope/</code></td>
-<td><code>serviceURL</code>, <code>formDataProvider</code>, API configuration</td>
-</tr>
-<tr>
-<td><code>.cursor/skills/concorde-theme/</code></td>
-<td><code>sonic-theme</code> and <code>--sc-*</code> tokens</td>
-</tr>
-<tr>
-<td><code>.cursor/skills/concorde-menu/</code></td>
-<td><code>sonic-menu</code> navigation</td>
+<td><code>.junie/skills/concorde</code></td>
+<td>Symlink for JetBrains Junie</td>
 </tr>
+</tbody></table>
+<p>Where symlinks are not allowed (some Windows setups), the skill is copied instead. Your own skills in these folders are never touched. Commit <code>.agents/</code> and the links if your team shares agent settings.</p>
+<p><strong><code>AGENTS.md</code> stays yours:</strong> <code>ai-init</code> never reads or writes it.</p>
+<h2 id="flags">Flags</h2>
+<table>
+<thead>
 <tr>
-<td><code>.cursor/skills/concorde-get-set-dp/</code></td>
-<td><code>get</code> / <code>set</code> / <code>dp</code> and <code>DataProviderKey</code> migration</td>
+<th>Flag</th>
+<th>Effect</th>
 </tr>
-<tr>
-<td><code>.cursor/rules/concorde.mdc</code></td>
-<td>Cursor rules (always-on patterns)</td>
+</thead>
+<tbody><tr>
+<td><code>--no-links</code></td>
+<td>Install <code>.agents/skills</code> only, without the <code>.claude</code> / <code>.junie</code> links</td>
 </tr>
 <tr>
-<td><code>.aiassistant/rules/concorde.md</code></td>
-<td>JetBrains AI Assistant rules</td>
+<td><code>--overlay &lt;dir&gt;</code></td>
+<td>Also install the skills found in <code>&lt;dir&gt;/skills/</code> (project kit)</td>
 </tr>
 </tbody></table>
-<h2 id="workflow">Workflow</h2>
-<ol>
-<li><strong>Starter project:</strong> <a href="/docs/getting-started/installation">Installation</a> — <code>yarn ai:sync</code> is wired in the kit.</li>
-<li><strong>Existing project:</strong> run <strong><code>ai-init</code></strong> after <code>yarn add @supersoniks/concorde</code>.</li>
-<li>Commit <code>.cursor/</code> and <code>.aiassistant/</code> (and <code>AGENTS.md</code> only if you opted in / it was created) if your team shares agent settings.</li>
-<li>Re-run the same command when you bump <code>@supersoniks/concorde</code> to refresh skills from <code>node_modules/@supersoniks/concorde/ai/</code>.</li>
-<li>In Cursor, skills under <code>.cursor/skills/</code> are picked up automatically; mention a skill in chat for focused tasks (e.g. migration → <code>concorde-get-set-dp</code>).</li>
-</ol>
-<p>Source files in the npm package: <code>node_modules/@supersoniks/concorde/ai/</code> (see also <code>ai/README.md</code> in the <a href="https://github.com/supersoniks/concorde">Concorde repository</a>).</p>
+<p>Source files in the npm package: <code>node_modules/@supersoniks/concorde/ai/skills/concorde/</code>.</p>
 
     </article>
   </main>

package/docs/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/docs/getting-started/dataFlow.html

@@ -76,7 +76,7 @@
 <td><code>serviceURL=&quot;/docs-mock-api&quot;</code> — <a href="/docs/misc/docs-mock-api">Local API demos</a></td>
 </tr>
 </tbody></table>
-<p>Skill: <code>concorde-get-set-dp</code> in the package <code>ai/</code> folder.</p>
+<p>Agent skill: <code>concorde</code> (<code>rules/data.md</code>), see <a href="/docs/getting-started/ai-agents">AI agents</a>.</p>
 <h2 id="dataproviderkey">DataProviderKey</h2>
 <pre><code class="language-typescript">import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
 import { dp, get, set } from &quot;@supersoniks/concorde/utils&quot;;

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

package/docs/docs/index.html

@@ -79,7 +79,7 @@
     <li><a href="/docs/decorators/wait-for-ancestors">@awaitConnectedAncestors</a> <small>(docs/decorators/wait-for-ancestors)</small></li>
     <li><a href="/docs/directives/sub">sub()</a> <small>(docs/directives/sub)</small></li>
     <li><a href="/docs/directives/t">t()</a> <small>(docs/directives/t)</small></li>
-    <li><a href="/docs/getting-started/ai-agents">AI agents (skills &amp; AGENTS.md)</a> <small>(docs/getting-started/ai-agents)</small></li>
+    <li><a href="/docs/getting-started/ai-agents">AI agents (skill)</a> <small>(docs/getting-started/ai-agents)</small></li>
     <li><a href="/docs/getting-started/components">Components</a> <small>(docs/getting-started/components)</small></li>
     <li><a href="/docs/getting-started/create-a-component">Creating components</a> <small>(docs/getting-started/create-a-component)</small></li>
     <li><a href="/docs/getting-started/dataFlow">Data flow</a> <small>(docs/getting-started/dataFlow)</small></li>

package/docs/hubs/decorators.html

@@ -80,27 +80,14 @@ API reference
 <section id="docs-decorators-bind" data-doc-id="docs/decorators/bind">
   <h2><a href="/docs/decorators/bind">@bind</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/decorators/bind</code> · <a href="/docs/decorators/bind">full page</a></p>
-  <p>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; add { reflect: true } to push local writes back t</p>
+  <p>@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</p>
   <pre class="doc-excerpt">@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; add { reflect: true } to push local writes back to the store. For read-only sync prefer @subscribe, and see Data flow 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 to read, @publish to write. See Data flow for the overall model.
 
 Import
 
 import { bind } from &quot;@supersoniks/concorde/decorators&quot;;
-
-@bind(&quot;flight.gate&quot;)
-@state()
-gate = &quot;&quot;;
-
-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.
-
-Typed key
-
-With a DataProviderKey , TypeScript checks that the property type matches T at that path.
-
 import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
 
 type Flight = { flight: string; gate: string; boarded: number };
@@ -110,9 +97,17 @@ const flightKey = new DataProviderKey&amp;lt;Flight&amp;gt;(&quot;flight&quot;);
 @state()
 boarded = 0;
 
+Basic usage
+
+The key is a 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.
+
 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 subsc</pre>
+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.
+
+Dynamic path
+
+Placeholders s</pre>
 </section>
 <section id="docs-decorators-get" data-doc-id="docs/decorators/get">
   <h2><a href="/docs/decorators/get">@get</a></h2>