@supersoniks/concorde 5.1.1 → 5.1.3

package/{src/docs/_core-concept → docs/docs/getting-started}/dataFlow.md

@@ -1,6 +1,6 @@
 # Data flow
 
-Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a **DataProvider** store (legacy **Publisher** API: [Legacy: Sharing data](#docs/_getting-started/pubsub.md/pubsub)).
+Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a **DataProvider** store.
 
 ## Quick map
 
@@ -16,10 +16,10 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 | HTTP POST (body from store) | `@post` + `Endpoint` + body `DataProviderKey` |
 | HTTP PUT / PATCH (body from store) | `@put` / `@patch` — same model as `@post` |
 | Forms | `formDataProvider` + `name` on fields (no Subscriber on form elements) |
-| Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](#core/components/functional/jsonata/jsonata.md/jsonata) |
-| Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) |
+| 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
 
@@ -36,15 +36,15 @@ get(cartKey);
   </template>
 </sonic-code>
 
-Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
 
-[DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)
+[DataProviderKey](/docs/misc/dataProviderKey)
 
 ## Decorators
 
 | Decorator | Role |
 |-----------|------|
-| `@subscribe` | Read-only property from store — [data configuration](#docs/_getting-started/my-first-component.md/my-first-component) (type + key + scope) |
+| `@subscribe` | Read-only property from store — [data configuration](/docs/getting-started/my-first-component) (type + key + scope) |
 | `@publish` | Push property writes to store |
 | `@handle` | Method called on assignment |
 | `@ancestorAttribute` | Copy ancestor HTML attribute onto property |
@@ -52,15 +52,15 @@ Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.
 | `@post` | HTTP POST into `ApiResult&lt;T&gt;` (body from a publisher) |
 | `@put` / `@patch` | HTTP PUT / PATCH into `ApiResult&lt;T&gt;` |
 
-Walkthrough: [My first component](#docs/_getting-started/my-first-component.md/my-first-component)
+Walkthrough: [My first component](/docs/getting-started/my-first-component)
 
 ## HTTP and lists
 
-- [@get](#docs/_decorators/get.md/get) — single GET on a component
-- [@post](#docs/_decorators/post.md/post) — POST with body read from a `DataProviderKey`
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH (same options as `@post`)
-- [List](#core/components/functional/list/list.md/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
-- [Queue](#core/components/functional/queue/queue.md/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
+- [@get](/docs/decorators/get) — single GET on a component
+- [@post](/docs/decorators/post) — POST with body read from a `DataProviderKey`
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH (same options as `@post`)
+- [List](/core/components/functional/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
+- [Queue](/core/components/functional/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
 
 ## Starter kit
 
@@ -75,14 +75,13 @@ Interactive routes mirror these patterns (`/concepts/*`, `/demo/*`).
 Use when you need **client-side aggregations** (groupby, top N, chart shapes) from existing DataProviders — without inline app JS in SDUI.
 
 - Primitive: `derive({ inputs, compute, output, variables? })` from `@supersoniks/concorde/utils` (read-only output, debounce, generation, cycle detection, `{output}/_state_`).
-- SDUI adapter: [`sonic-jsonata`](#core/components/functional/jsonata/jsonata.md/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
-- vs [`sonic-mix`](#core/components/functional/mix/mix.md/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
+- SDUI adapter: [`sonic-jsonata`](/core/components/functional/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
+- vs [`sonic-mix`](/core/components/functional/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
 
 ## Legacy integration
 
 | Topic | Page |
 |-------|------|
-| `Subscriber` / `Fetcher` mixins on app code | [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber), [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber) |
-| `data-bind` HTML (plain HTML hosts) | [HTML integration](#docs/_misc/html-integration.md/html-integration) — doc demos use Lit in `src/docs/example/` |
-| `@onAssign` | [@onAssign](#docs/_decorators/on-assign.md/on-assign) (prefer `@handle`) |
-| `sonic-fetch` alone | [Fetch](#core/components/functional/fetch/fetch.md/fetch) |
+| `data-bind` HTML (plain HTML hosts) | [HTML integration](/docs/misc/html-integration) — doc demos use Lit in `src/docs/example/` |
+| `@onAssign` | [@onAssign](/docs/decorators/on-assign) (prefer `@handle`) |
+| `sonic-fetch` alone | [Fetch](/core/components/functional/fetch) |

package/docs/docs/getting-started/installation.html

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/installation" data-doc-id="docs/getting-started/installation">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Installation — Concorde by Supersoniks</title>
+  <meta name="description" content="Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/installation, installation, Installation, guide, npx concorde enable-short-paths, yarn ai:sync, yarn dev, tsc --noEmit, document.querySelector, renderRoot">
+  <meta name="concorde-doc-id" content="docs/getting-started/installation">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/installation">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/installation.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/installation">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Installation</strong>. Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command. <span>Doc ID: <code>docs/getting-started/installation</code>. Keywords: Concorde, supersoniks, docs/getting-started/installation, installation, Installation, guide, npx concorde enable-short-paths, yarn ai:sync, yarn dev, tsc --noEmit, document.querySelector, renderRoot. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/installation">https://concorde.supersoniks.org/docs/getting-started/installation</a>.</span></p>
+      <h1 id="installation">Installation</h1>
+<p>Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.</p>
+<h2 id="use-the-starter">Use the starter</h2>
+<pre><code class="language-shell">npx @supersoniks/create-concorde-ts-starter my-app
+cd my-app
+yarn install
+yarn dev --host
+</code></pre>
+<p>The project includes:</p>
+<ul>
+<li>an example component to copy from</li>
+<li><code>npx concorde enable-short-paths</code> for short import paths</li>
+<li><code>yarn ai:sync</code> for <a href="/docs/getting-started/ai-agents">AI agent skills</a></li>
+</ul>
+<p>Package: <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a>.</p>
+<h2 id="stack">Stack</h2>
+<table>
+<thead>
+<tr>
+<th>Tool</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><a href="https://lit.dev">Lit</a></td>
+<td>Base class, templates and reactive properties for web components</td>
+</tr>
+<tr>
+<td><a href="https://www.typescriptlang.org">TypeScript</a></td>
+<td>Decorators and typed store paths</td>
+</tr>
+<tr>
+<td><a href="https://vite.dev">Vite</a></td>
+<td>Dev server and build</td>
+</tr>
+<tr>
+<td><a href="https://tailwindcss.com">Tailwind</a></td>
+<td>Optional, layout in your components. Concorde components ship their own styles, driven by <a href="/docs/getting-started/theming">theme</a> variables</td>
+</tr>
+</tbody></table>
+<h2 id="gotchas">Gotchas</h2>
+<ul>
+<li><code>yarn dev</code> does not type-check. Run <code>tsc --noEmit</code> or a production build to catch type errors.</li>
+<li>Scripts that query the global document (<code>document.querySelector</code>, jQuery plugins, icon replacers) cannot see inside a shadow root. Query from the component&#39;s <code>renderRoot</code>, or pass the element as slotted content.</li>
+</ul>
+
+    </article>
+  </main>
+</body>
+</html>

package/docs/docs/getting-started/installation.md

@@ -0,0 +1,36 @@
+# Installation
+
+Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.
+
+## Use the starter
+
+<sonic-code language="shell">
+  <template>
+npx @supersoniks/create-concorde-ts-starter my-app
+cd my-app
+yarn install
+yarn dev --host
+  </template>
+</sonic-code>
+
+The project includes:
+
+- an example component to copy from
+- `npx concorde enable-short-paths` for short import paths
+- `yarn ai:sync` for [AI agent skills](/docs/getting-started/ai-agents)
+
+Package: [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter).
+
+## Stack
+
+| Tool | Role |
+|------|------|
+| [Lit](https://lit.dev) | Base class, templates and reactive properties for web components |
+| [TypeScript](https://www.typescriptlang.org) | Decorators and typed store paths |
+| [Vite](https://vite.dev) | Dev server and build |
+| [Tailwind](https://tailwindcss.com) | Optional, layout in your components. Concorde components ship their own styles, driven by [theme](/docs/getting-started/theming) variables |
+
+## Gotchas
+
+- `yarn dev` does not type-check. Run `tsc --noEmit` or a production build to catch type errors.
+- Scripts that query the global document (`document.querySelector`, jQuery plugins, icon replacers) cannot see inside a shadow root. Query from the component's `renderRoot`, or pass the element as slotted content.

package/docs/docs/getting-started/my-first-component.html

@@ -0,0 +1,180 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/my-first-component" data-doc-id="docs/getting-started/my-first-component">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My first component — Concorde by Supersoniks</title>
+  <meta name="description" content="Build a Lit user card with Tailwind and Concorde UI, then connect it to the DataProvider store: declare the data configuration (type, key, scope), and let @subscribe keep the card in sync.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/my-first-component, my-first-component, My first component, guide, @subscribe, src/docs/tailwind.ts, ${unsafeCSS(tailwindImport)}, DocsUserData, user, docsUserRowKey, &quot;${dataProvider}&quot;, { dataProvider: string | null }">
+  <meta name="concorde-doc-id" content="docs/getting-started/my-first-component">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/my-first-component">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/my-first-component.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/my-first-component">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — My first component</strong>. Build a Lit user card with Tailwind and Concorde UI, then connect it to the DataProvider store: declare the data configuration (type, key, scope), and let @subscribe keep the card in sync. <span>Doc ID: <code>docs/getting-started/my-first-component</code>. Keywords: Concorde, supersoniks, docs/getting-started/my-first-component, my-first-component, My first component, guide, @subscribe, src/docs/tailwind.ts, ${unsafeCSS(tailwindImport)}, DocsUserData, user, docsUserRowKey, &quot;${dataProvider}&quot;, { dataProvider: string | null }. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/my-first-component">https://concorde.supersoniks.org/docs/getting-started/my-first-component</a>.</span></p>
+      <h1 id="my-first-component">My first component</h1>
+<p>Build a <strong>Lit</strong> user card with Tailwind and Concorde UI, then connect it to the <strong>DataProvider</strong> store: declare the <strong>data configuration</strong> (type, key, scope), and let <strong><code>@subscribe</code></strong> keep the card in sync.</p>
+<h2 id="1-lit-component--tailwind">1. Lit component + Tailwind</h2>
+<p>Export Tailwind once (e.g. <code>src/docs/tailwind.ts</code> in this repo):</p>
+<pre><code class="language-typescript">import { css, unsafeCSS } from &quot;lit&quot;;
+import tailwindImport from &quot;./css/tailwind.css?inline&quot;;
+
+export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+</code></pre>
+<p>User card — plain Lit properties and UI components (no store yet):</p>
+<pre><code class="language-typescript">import { html, LitElement } from &quot;lit&quot;;
+import { customElement, property } from &quot;lit/decorators.js&quot;;
+import { tailwind } from &quot;../tailwind&quot;;
+
+@customElement(&quot;docs-user&quot;)
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String }) first_name = &quot;&quot;;
+  @property({ type: String }) last_name = &quot;&quot;;
+  @property({ type: String }) email = &quot;&quot;;
+  @property({ type: String }) avatar = &quot;&quot;;
+
+  render() {
+    return html`&amp;lt;div class=&quot;flex items-center gap-3 rounded-md p-2&quot;&amp;gt;
+      &amp;lt;sonic-image src=${this.avatar} rounded=&quot;md&quot; ratio=&quot;1/1&quot; class=&quot;w-16&quot;&amp;gt;&amp;lt;/sonic-image&amp;gt;
+      &amp;lt;div&amp;gt;
+        &amp;lt;div&amp;gt;${this.first_name} &amp;lt;span class=&quot;font-bold&quot;&amp;gt;${this.last_name}&amp;lt;/span&amp;gt;&amp;lt;/div&amp;gt;
+        &amp;lt;div class=&quot;text-sm text-neutral-400&quot;&amp;gt;${this.email}&amp;lt;/div&amp;gt;
+      &amp;lt;/div&amp;gt;
+    &amp;lt;/div&amp;gt;`;
+  }
+}
+</code></pre>
+<h2 id="2-data-configuration">2. Data configuration</h2>
+<p>The card does not hard-code user fields anymore. You declare <strong>what</strong> is stored, <strong>where</strong> it lives, and <strong>which ancestor scope</strong> applies — then <code>@subscribe</code> mirrors that object on the component.</p>
+<h3 id="type--shape-of-the-data">Type — shape of the data</h3>
+<p><code>DocsUserData</code> documents the fields you expect at this scope (first name, email, avatar, …). TypeScript checks that <code>user</code> matches that shape.</p>
+<pre><code class="language-typescript">export type DocsUserData = {
+  first_name: string;
+  last_name: string;
+  email: string;
+  avatar: string;
+};
+</code></pre>
+<h3 id="key--path-in-the-dataprovider">Key — path in the DataProvider</h3>
+<p><code>docsUserRowKey</code> points at the store segment to read. The path <code>&quot;${dataProvider}&quot;</code> is resolved at runtime from a property on the component (see scope below).</p>
+<pre><code class="language-typescript">import { DataProviderKey } from &quot;@supersoniks/concorde/core/utils/dataProviderKey&quot;;
+
+export const docsUserRowKey = new DataProviderKey&amp;lt;
+  DocsUserData,
+  { dataProvider: string | null }
+&amp;gt;(&quot;${dataProvider}&quot;);
+</code></pre>
+<p>The second generic (<code>{ dataProvider: string | null }</code>) lists what the host must expose so <code>&quot;${dataProvider}&quot;</code> can be resolved. See <a href="/docs/misc/dataProviderKey">DataProviderKey</a> and <a href="/docs/misc/dynamic-path">Dynamic path placeholders</a>.</p>
+<h3 id="scope--which-store-segment-applies">Scope — which store segment applies</h3>
+<p>A parent sets <code>dataProvider=${docsUserScopeAKey.path}</code> (or a list row sets <code>…/list-item/0</code>). <a href="/docs/decorators/ancestor-attribute"><code>@ancestorAttribute</code></a> copies that attribute onto <code>this.dataProvider</code>, so the key resolves to the correct branch.</p>
+<pre><code class="language-typescript">@ancestorAttribute(&quot;dataProvider&quot;)
+dataProvider: string | null = null;
+</code></pre>
+<h3 id="subscribe--keep-the-card-in-sync">Subscribe — keep the card in sync</h3>
+<p><a href="/docs/decorators/subscribe"><code>@subscribe</code></a> watches <code>docsUserRowKey</code> and updates <code>user</code> when the store changes. Use <code>@state()</code> so Lit re-renders. The template reads <code>this.user</code> like any other property.</p>
+<pre><code class="language-typescript">import { html, LitElement, nothing } from &quot;lit&quot;;
+import { customElement, state } from &quot;lit/decorators.js&quot;;
+import {
+  ancestorAttribute,
+  subscribe,
+} from &quot;@supersoniks/concorde/core/decorators/Subscriber&quot;;
+import { docsUserRowKey, type DocsUserData } from &quot;./users&quot;;
+import { tailwind } from &quot;../tailwind&quot;;
+
+@customElement(&quot;docs-user&quot;)
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @ancestorAttribute(&quot;dataProvider&quot;)
+  dataProvider: string | null = null;
+
+  @subscribe(docsUserRowKey)
+  @state()
+  user: DocsUserData | null = null;
+
+  render() {
+    const u = this.user;
+    if (!u) return nothing;
+    return html`&amp;lt;div class=&quot;flex items-center gap-3 rounded-md p-2&quot;&amp;gt;
+      &amp;lt;sonic-image src=${u.avatar} rounded=&quot;md&quot; ratio=&quot;1/1&quot; class=&quot;w-16&quot;&amp;gt;&amp;lt;/sonic-image&amp;gt;
+      &amp;lt;div&amp;gt;
+        &amp;lt;div&amp;gt;${u.first_name} &amp;lt;span class=&quot;font-bold&quot;&amp;gt;${u.last_name}&amp;lt;/span&amp;gt;&amp;lt;/div&amp;gt;
+        &amp;lt;div class=&quot;text-sm text-neutral-400&quot;&amp;gt;${u.email}&amp;lt;/div&amp;gt;
+      &amp;lt;/div&amp;gt;
+    &amp;lt;/div&amp;gt;`;
+  }
+}
+</code></pre>
+<p>Live code: <code>src/docs/example/users.ts</code>. In this repo, imports use <strong><code>core/…</code> paths</strong> (short <code>@supersoniks/concorde/…</code> exports apply in <strong>consumer apps</strong> only).</p>
+<h3 id="two-scopes-one-component">Two scopes, one component</h3>
+<p>The same <code>docs-user</code> is mounted twice. Each copy inherits a <strong>different</strong> nearest <code>dataProvider</code> — that is the row/list <strong>scope</strong>:</p>
+<pre><code>&lt;docs-demo-sources for=&quot;docs-user-two-scopes&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;docs-user-two-scopes&gt;&lt;/docs-user-two-scopes&gt;
+</code></pre>
+<p>Markup (two isolated stores; keys from <code>docs-provider-keys.ts</code>):</p>
+<pre><code class="language-markup">&amp;lt;div class=&quot;grid md:grid-cols-2 gap-6&quot;&amp;gt;
+      &amp;lt;div dataProvider=&quot;${docsUserScopeAKey.path}&quot;&amp;gt;
+        &amp;lt;docs-user&amp;gt;&amp;lt;/docs-user&amp;gt;
+      &amp;lt;/div&amp;gt;
+      &amp;lt;div dataProvider=&quot;${docsUserScopeBKey.path}&quot;&amp;gt;
+        &amp;lt;docs-user&amp;gt;&amp;lt;/docs-user&amp;gt;
+      &amp;lt;/div&amp;gt;
+    &amp;lt;/div&amp;gt;
+</code></pre>
+<p>Seeded in <code>docs-provider-keys.ts</code> (<code>set(docsUserScopeAKey, …)</code>): <strong>Paul</strong> / <strong>Marie</strong>. Without <code>@ancestorAttribute</code>, both cards would not know which store to read.</p>
+<h2 id="3-fetch-users--sonic-list-with-items">3. Fetch users — <code>sonic-list</code> with <code>.items</code></h2>
+<p>Use a Lit parent and the <strong><code>items</code></strong> renderer (not HTML <code>&lt;template&gt;</code> children). The callback receives each row object from fetch — render fields directly (<code>${item.first_name}</code>, …), like porting a template that used <code>data-bind</code> / <code>&lt;sonic-value&gt;</code>.</p>
+<pre><code>&lt;docs-lit-demo for=&quot;docs-users-list&quot;&gt;&lt;/docs-lit-demo&gt;
+</code></pre>
+<p>Wrapper (<code>docs-users-list.ts</code>):</p>
+<pre><code class="language-typescript">import { html, LitElement } from &quot;lit&quot;;
+import { customElement } from &quot;lit/decorators.js&quot;;
+import &quot;../../core/components/functional/list/list&quot;;
+import &quot;./users&quot;;
+
+@customElement(&quot;docs-users-list&quot;)
+export class DocsUsersList extends LitElement {
+  private items = ({ first_name, last_name, email, avatar }) =&gt; html`
+    &amp;lt;div class=&quot;flex gap-3&quot;&amp;gt;
+      &amp;lt;sonic-image src=${avatar} ...&amp;gt;&amp;lt;/sonic-image&amp;gt;
+      &amp;lt;div&amp;gt;${first_name} &amp;lt;b&amp;gt;${last_name}&amp;lt;/b&amp;gt;&amp;lt;/div&amp;gt;
+      &amp;lt;div class=&quot;text-sm text-neutral-400&quot;&amp;gt;${email}&amp;lt;/div&amp;gt;
+    &amp;lt;/div&amp;gt;
+  `;
+
+  render() {
+    return html`
+      &amp;lt;sonic-list fetch dataProvider=${usersListEndpoint.path} key=&quot;data&quot; .items=${this.items}&amp;gt;&amp;lt;/sonic-list&amp;gt;
+    `;
+  }
+}
+</code></pre>
+<p>See <a href="/docs/misc/docs-mock-api">Local API demos</a> for <code>serviceURL=&quot;/docs-mock-api&quot;</code>.</p>
+<h2 id="4-form-preview-with-formdataprovider">4. Form preview with <code>formDataProvider</code></h2>
+<p>Edit fields in a form; the card follows the same <code>docsUserRowKey</code> when the preview host sets <code>dataProvider=&quot;userPreview&quot;</code>.</p>
+<pre><code>&lt;div class=&quot;grid grid-cols-1 gap-4 max-w-xl&quot;&gt;
+      &lt;form formDataProvider=&quot;${docsUserPreviewKey.path}&quot; class=&quot;grid grid-cols-2 gap-3&quot;&gt;
+        &lt;sonic-input label=&quot;First name&quot; name=&quot;first_name&quot; value=&quot;Paul&quot; size=&quot;sm&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-input label=&quot;Last name&quot; name=&quot;last_name&quot; value=&quot;Metrand&quot; size=&quot;sm&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-input class=&quot;col-span-2&quot; label=&quot;Email&quot; name=&quot;email&quot; value=&quot;paul@example.com&quot; size=&quot;sm&quot;&gt;&lt;/sonic-input&gt;
+        &lt;sonic-input class=&quot;col-span-2&quot; label=&quot;Avatar URL&quot; name=&quot;avatar&quot; value=&quot;https://i.pravatar.cc/150?u=paul&quot; size=&quot;sm&quot;&gt;&lt;/sonic-input&gt;
+      &lt;/form&gt;
+      &lt;sonic-divider align=&quot;left&quot;&gt;Preview&lt;/sonic-divider&gt;
+      &lt;div dataProvider=&quot;${docsUserPreviewKey.path}&quot;&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+</code></pre>
+<p>Use <code>formDataProvider</code> + <code>name</code> on inputs — no manual <code>@input</code> handlers (<a href="/docs/getting-started/dataFlow">Data flow</a>).</p>
+
+    </article>
+  </main>
+</body>
+</html>

package/{src/docs/_getting-started → docs/docs/getting-started}/my-first-component.md

@@ -2,8 +2,6 @@
 
 Build a **Lit** user card with Tailwind and Concorde UI, then connect it to the **DataProvider** store: declare the **data configuration** (type, key, scope), and let **`@subscribe`** keep the card in sync.
 
-> Legacy approach with the **Subscriber mixin**: [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber).
-
 ## 1. Lit component + Tailwind
 
 Export Tailwind once (e.g. `src/docs/tailwind.ts` in this repo):
@@ -81,11 +79,11 @@ export const docsUserRowKey = new DataProviderKey<
   </template>
 </sonic-code>
 
-The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](/docs/misc/dataProviderKey) and [Dynamic path placeholders](/docs/misc/dynamic-path).
 
 ### Scope — which store segment applies
 
-A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
+A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](/docs/decorators/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
 
 <sonic-code language="typescript">
   <template>
@@ -96,7 +94,7 @@ dataProvider: string | null = null;
 
 ### Subscribe — keep the card in sync
 
-[`@subscribe`](#docs/_decorators/subscribe.md/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
+[`@subscribe`](/docs/decorators/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
 
 <sonic-code language="typescript">
   <template>
@@ -203,7 +201,7 @@ export class DocsUsersList extends LitElement {
   </template>
 </sonic-code>
 
-See [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) for `serviceURL="/docs-mock-api"`.
+See [Local API demos](/docs/misc/docs-mock-api) for `serviceURL="/docs-mock-api"`.
 
 ## 4. Form preview with `formDataProvider`
 
@@ -226,11 +224,4 @@ Edit fields in a form; the card follows the same `docsUserRowKey` when the previ
   </template>
 </sonic-code>
 
-Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)).
-
-## Next steps
-
-- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — full map
-- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed paths and host constraints
-- [@subscribe](#docs/_decorators/subscribe.md/subscribe) / [sub()](#docs/_directives/sub.md/sub) — read-only in templates
-- [List](#core/components/functional/list/list.md/list) — `.items`, `.noItems`, `.skeleton`
+Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](/docs/getting-started/dataFlow)).

package/docs/docs/getting-started/start.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/start" data-doc-id="docs/getting-started/start">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Introduction — Concorde by Supersoniks</title>
+  <meta name="description" content="Based on lit.dev, Concorde is a collection of web components for shared apps and websites.">
+  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/start, start, Introduction, guide, get, set, formDataProvider, yarn ai:sync">
+  <meta name="concorde-doc-id" content="docs/getting-started/start">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/start">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/start.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/start">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Introduction</strong>. Based on lit.dev, Concorde is a collection of web components for shared apps and websites. <span>Doc ID: <code>docs/getting-started/start</code>. Keywords: Concorde, supersoniks, docs/getting-started/start, start, Introduction, guide, get, set, formDataProvider, yarn ai:sync. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/start">https://concorde.supersoniks.org/docs/getting-started/start</a>.</span></p>
+      <h1 id="introduction">Introduction</h1>
+<h2 id="what-is-concorde">What is Concorde?</h2>
+<p>Based on <strong><a href="https://lit.dev">lit.dev</a></strong>, Concorde is a collection of web components for shared apps and websites.<br>Build UIs without tying components to a specific host stack, while keeping visual consistency through the smallest set of CSS variables needed to define a theme.</p>
+<h2 id="why-and-use-case">Why and use case</h2>
+<p>In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.<br>One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.</p>
+<h3 id="stack">Stack</h3>
+<ul>
+<li>Lit</li>
+<li>TypeScript</li>
+<li>Vite</li>
+<li>Tailwind (starter kit, not required in the core package)</li>
+</ul>
+<h3 id="functional-features">Functional features</h3>
+<ul>
+<li><strong>DataProvider</strong> store (decorators, <code>get</code> / <code>set</code>)</li>
+<li>Forms (<code>formDataProvider</code>)</li>
+<li>Lists, queues, lazy loading</li>
+<li>Router, states, UI kit with status variants</li>
+</ul>
+<h2 id="start-a-new-project">Start a new project</h2>
+<pre><code class="language-bash">npx @supersoniks/create-concorde-ts-starter &quot;project_name&quot;
+</code></pre>
+<p>The starter runs <strong><code>yarn ai:sync</code></strong> for you. Details: <a href="/docs/getting-started/ai-agents">AI agents (skills)</a>.</p>
+
+    </article>
+  </main>
+</body>
+</html>

package/{src/docs/_getting-started → docs/docs/getting-started}/start.md

@@ -24,18 +24,6 @@ One composable web-component library replaced many one-off apps. Lit was chosen
 * Lists, queues, lazy loading
 * Router, states, UI kit with status variants
 
-## Learn Concorde
-
-| Step | Page |
-|------|------|
-| 1 | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — Lit card, `@ancestorAttribute`, `@bind`, mock API |
-| 2 | [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — Core concepts: decorators and APIs |
-| 3 | [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL` for this site (Misc) |
-| 4 | [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) — **recommended** project kit (Vite, Tailwind, `yarn ai:sync`) |
-| 5 | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `AGENTS.md`, Cursor / JetBrains rules |
-
-Legacy (Subscriber mixin, Publisher API): **Legacy** section at the bottom of the sidebar.
-
 ## Start a new project
 
 <sonic-code language="bash">
@@ -44,4 +32,4 @@ npx @supersoniks/create-concorde-ts-starter "project_name"
   </template>
 </sonic-code>
 
-The starter runs **`yarn ai:sync`** for you. Details: [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents). Manual Vite setup: [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install).
+The starter runs **`yarn ai:sync`** for you. Details: [AI agents (skills)](/docs/getting-started/ai-agents).