@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/src/docs/decorators/put.md

@@ -0,0 +1,51 @@
+# @put
+
+Sends the value of a publisher as the body of a `PUT` request, to replace a resource, and stores the response in an `ApiResult<T>` property. It takes the same arguments, options and `send(component)` handle as [@post](/docs/decorators/post); only the HTTP method differs.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { put, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The full passenger record is sent on connect and after each body mutation. Placeholders such as `${passengerId}` are resolved on the host component.
+
+<sonic-code language="typescript">
+  <template>
+type Passenger = { name: string; flight: string; seat: string };
+
+const passengerKey = new DataProviderKey&lt;Passenger&gt;("passengerForm");
+const savePassenger = put(
+  new Endpoint&lt;Passenger, { passengerId: string }&gt;("passengers/${passengerId}"),
+  passengerKey,
+  { autoPostOnBodyMutation: false },
+);
+
+@property() passengerId = "ada-lindqvist";
+
+@savePassenger
+@state()
+payload?: ApiResult&lt;Passenger&gt;;
+
+async save() {
+  await savePassenger.send(this);
+}
+  </template>
+</sonic-code>
+
+Triggers, the `send` method decorator and every option are described on [@post](/docs/decorators/post).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Resource path and response type |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as the full replacement body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options` | `PutOptions` | Same as [@post options](/docs/decorators/post) |

package/docs/src/docs/decorators/subscribe.md

@@ -0,0 +1,87 @@
+# @subscribe
+
+`@subscribe(key)` keeps a component property in sync with one path of the store: when a publisher assigns that path, the property updates and the component re-renders. It is read-only; use [@publish](/docs/decorators/publish) to write and [sub()](/docs/directives/sub) to read inside a template. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Cockpit = { altitude: number };
+const cockpitKey = new DataProviderKey&lt;Cockpit&gt;("cockpit");
+
+@subscribe(cockpitKey.altitude)
+@state()
+altitude = 0;
+  </template>
+</sonic-code>
+
+## Static path
+
+The key is a [DataProviderKey](/docs/misc/dataProviderKey): the property type must match `T` at that path. Add `@state()` so Lit re-renders. Until the publisher holds a value, the property keeps its initializer.
+
+<sonic-code language="typescript">
+  <template>
+type Flight = { code: string; gate: string; status: string };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
+
+@subscribe(flightKey)
+@state()
+flight: Flight | null = null;
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component. Declare them in the key's second generic so TypeScript requires them on the host. When `seatIndex` changes, the path is resolved again and `person` refreshes; while the placeholder is `null` or `undefined`, the subscription is inactive. Resolution rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+type OnBoard = { name: string; role: string; seat: string };
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@subscribe(personKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
+    <demo-subscribe-dynamic></demo-subscribe-dynamic>
+  </template>
+</sonic-code>
+
+## Ancestor scope
+
+Inside a list row or a `dataProvider` wrapper, read the path from the closest ancestor with [@ancestorAttribute](/docs/decorators/ancestor-attribute), then use it as the placeholder.
+
+<sonic-code language="typescript">
+  <template>
+const rowKey = new DataProviderKey&lt;OnBoard, { dataProvider: string | null }&gt;(
+  "${dataProvider}",
+);
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+
+@subscribe(rowKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` | `DataProviderKey<T, U>` | Path to read. `U` lists the host properties used by `${…}` placeholders |
+
+The decorated property is typed `T` (optionally `| null` or `| undefined`). The subscription starts when the component connects and stops when it disconnects.

package/docs/src/docs/decorators/wait-for-ancestors.md

@@ -0,0 +1,76 @@
+# @awaitConnectedAncestors
+
+Delays a component's `connectedCallback` until its matching ancestors are defined and connected, so context they set up (a `dataProvider`, a publisher, a fetched payload) is ready when the child starts. Pair it with `@dispatchConnectedEvent` on the ancestors, which signals readiness.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import {
+  awaitConnectedAncestors,
+  dispatchConnectedEvent,
+} from "@supersoniks/concorde/decorators";
+
+@customElement("flight-scope")
+@dispatchConnectedEvent()
+export class FlightScope extends LitElement {}
+
+@customElement("gate-panel")
+@awaitConnectedAncestors("flight-scope")
+export class GatePanel extends LitElement {}
+  </template>
+</sonic-code>
+
+## Wait for an ancestor
+
+Arguments are CSS selectors tested with `element.matches()` on each ancestor, across shadow roots. Here the parent element is not defined yet: the child stays uninitialized until you register it.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
+    <demo-wait-ancestors-section></demo-wait-ancestors-section>
+  </template>
+</sonic-code>
+
+## Several ancestors
+
+With several selectors, the child waits for every matching ancestor. Register both to initialize it, in any order.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-multi-section"></docs-demo-sources>
+    <demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
+  </template>
+</sonic-code>
+
+## Ancestor already connected
+
+When the ancestor is already connected, or no ancestor matches, the child initializes immediately.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
+    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+  </template>
+</sonic-code>
+
+## Signal readiness
+
+`@dispatchConnectedEvent()` dispatches a bubbling `sonic-connected` event (exported as `CONNECTED`) at the end of the ancestor's `connectedCallback`. You can listen to it anywhere:
+
+<sonic-code language="typescript">
+  <template>
+import { CONNECTED } from "@supersoniks/concorde/decorators";
+
+document.addEventListener(CONNECTED, (e) => console.log("ready:", e.target));
+  </template>
+</sonic-code>
+
+Elements without a hyphen in their tag name count as connected. A custom element ancestor that never dispatches the event releases the child after a **5 second** timeout, so decorate the ancestors you wait for.
+
+## API reference
+
+| Decorator | Argument | Description |
+|-----------|----------|-------------|
+| `@awaitConnectedAncestors` | `...selectors: string[]` | Class decorator. CSS selectors of the ancestors to wait for; with no selector, the class is left unchanged |
+| `@dispatchConnectedEvent` | none | Class decorator. Dispatches `CONNECTED` (`"sonic-connected"`, bubbles) after `connectedCallback` |

package/docs/src/docs/directives/sub.md

@@ -0,0 +1,75 @@
+# sub()
+
+`sub(path)` is a Lit directive that renders the current value of a store path and updates in place on every assignment. Use it inside `html` templates for read-only display; in a decorator, the same path goes to [@subscribe](/docs/decorators/subscribe). See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { sub } from "@supersoniks/concorde/directives";
+
+render() {
+  return html`&lt;p&gt;Altitude: ${sub("cockpit.altitude")} ft&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## DataProviderKey
+
+Pass a [DataProviderKey](/docs/misc/dataProviderKey) instead of a string to get a typo-safe path. Until the publisher holds a value, nothing is rendered.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const flightKey = new DataProviderKey&lt;{ code: string; gate: string }&gt;("flight");
+
+render() {
+  return html`&lt;p&gt;${sub(flightKey.code)} · gate ${sub(flightKey.gate)}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the component that renders the template; the directive re-subscribes when they change. While a placeholder is `null` or `undefined`, nothing is rendered. Rules: [Dynamic paths](/docs/misc/dynamic-path). `skipEmptyPlaceholder` is not available on `sub()`.
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+render() {
+  return html`&lt;strong&gt;${sub(personKey.name)}&lt;/strong&gt; · ${sub(personKey.role)}`;
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
+    <demo-sub-template></demo-sub-template>
+  </template>
+</sonic-code>
+
+## sub() or get()
+
+`get(path)` from `@supersoniks/concorde/utils` returns a one-time snapshot: in a template it never updates. Use `sub()` in templates and `get` / `set` / `dp` in imperative code.
+
+<sonic-code language="typescript">
+  <template>
+html`${sub(flightKey.gate)}`; // updates on gate change
+html`${get(flightKey.gate)}`; // frozen at first render
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `DataProviderKey<T, U>` | Path to read. Placeholders resolve on the template host |
+
+The directive subscribes when its part connects and unsubscribes when it disconnects.

package/docs/src/docs/directives/t.md

@@ -0,0 +1,73 @@
+# t()
+
+Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest `wordingProvider` ancestor attribute, and results are cached in `localStorage`.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { t } from "@supersoniks/concorde/directives/Wording";
+  </template>
+</sonic-code>
+
+`wording` and `w` are aliases of `t`. In plain HTML, use the [`sonic-t`](/core/components/functional/translation) element.
+
+## Usage
+
+Set `serviceURL` and `wordingProvider` on the host component or one of its ancestors, then call `t(key)` in a template. Attributes on elements **inside** the component's own template are not read. Click the button to bump the version and reload the labels.
+
+<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
+
+## Endpoint contract
+
+All keys requested in the same tick are sent in one request, appended to `wordingProvider` as `labels[]`:
+
+<sonic-code language="shell">
+  <template>
+GET {serviceURL}/wording/labels?lang=fr&labels[]=greeting&labels[]=farewell
+  </template>
+</sonic-code>
+
+The response is a flat map of key to label:
+
+<sonic-code language="json">
+  <template>
+{ "greeting": "Bonjour", "farewell": "Au revoir" }
+  </template>
+</sonic-code>
+
+Until the label arrives, `t()` renders an empty string.
+
+## HTML labels
+
+`t()` escapes the label. Use `unsafeWording(key)` for labels that contain trusted HTML.
+
+<sonic-code language="typescript">
+  <template>
+import { unsafeWording } from "@supersoniks/concorde/directives/Wording";
+
+html`&lt;p&gt;${unsafeWording("terms.notice")}&lt;/p&gt;`;
+  </template>
+</sonic-code>
+
+## Reloading labels
+
+Labels are fetched again when:
+
+- the `lang` attribute of `<html>` changes
+- the number stored at `wordingVersionProvider` changes — bump it after publishing new labels to invalidate the `localStorage` cache
+
+## API reference
+
+| Function | Description |
+|----------|-------------|
+| `t(key)` · `wording(key)` · `w(key)` | Renders the escaped label for `key` |
+| `unsafeWording(key)` | Renders the label as HTML |
+| `isWordingReady(key)` | `true` once the label for `key` is loaded |
+
+| Ancestor attribute | Description |
+|--------------------|-------------|
+| `wordingProvider` | Endpoint path and query, relative to `serviceURL` |
+| `wordingVersionProvider` | DataProvider path holding a version number |
+
+Other ancestor attributes (`serviceURL`, `token`, …) apply as for any request: see [API configuration](/docs/misc/api-configuration).

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

@@ -2,7 +2,7 @@
 
 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).
 
-On a [starter](#docs/_getting-started/concorde-outside.md/concorde-outside) project, run `yarn ai:sync` after install. On a [manual / brownfield](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install) 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 use `ai-init` below.
 
 ## Dedicated commands
 
@@ -67,8 +67,8 @@ Everything **after** `<!-- concorde-ai -->` is replaced on each `ai-init` run (i
 
 ## Workflow
 
-1. **Starter project:** [Installation](#docs/_getting-started/concorde-outside.md/concorde-outside) — `yarn ai:sync` is wired in the kit.
-2. **Existing / manual Vite project:** [Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install), then **`ai-init`** after `yarn add @supersoniks/concorde`.
+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`).

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

@@ -0,0 +1,5 @@
+# Components
+
+Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.
+
+<docs-components-index></docs-components-index>

package/{src/docs/_getting-started → docs/src/docs/getting-started}/create-a-component.md

@@ -1,6 +1,6 @@
 # Creating components
 
-> **New app components:** start with [My first component](#docs/_getting-started/my-first-component.md/my-first-component) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). The `Subscriber` mixin below is [legacy](#docs/_core-concept/subscriber.md/subscriber).
+> **New app components:** start with [My first component](/docs/getting-started/my-first-component) and [Data flow](/docs/getting-started/dataFlow). The `Subscriber` mixin below is legacy.
 
 ## Where to put it?
 
@@ -63,10 +63,7 @@ export class SonicComponent extends LitElement {
   </template>
 </sonic-code>
 
-Regarding `Subscriber`, see:
-
-- [🔔 Subscriber](#docs/_core-concept/subscriber.md/subscriber)
-- [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)
+Regarding data sharing, see [Data flow](/docs/getting-started/dataFlow).
 
 ### Naming the Component
 
@@ -94,7 +91,7 @@ For example, for a "title" component in the "event" destination, the name would
 
 #### Creating Reactive Properties and Modifying the Render Function
 
-To do this, study the functioning of https://lit.dev and also refer to [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
+To do this, study the functioning of https://lit.dev and also refer to [Data flow](/docs/getting-started/dataFlow).
 
 #### HTML Structure of a Component
 

package/{src/docs/_core-concept → docs/src/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,8 +16,8 @@ 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.
 
@@ -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/src/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/{src/docs/_getting-started → docs/src/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/src/docs/getting-started/start.md

@@ -0,0 +1,35 @@
+# Introduction
+
+## What is Concorde?
+
+Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of web components for shared apps and websites.  
+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.
+
+## Why and use case
+
+In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.  
+One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.
+
+### Stack
+
+* Lit
+* TypeScript
+* Vite
+* Tailwind (starter kit, not required in the core package)
+
+### Functional features
+
+* **DataProvider** store (decorators, `get` / `set`)
+* Forms (`formDataProvider`)
+* Lists, queues, lazy loading
+* Router, states, UI kit with status variants
+
+## Start a new project
+
+<sonic-code language="bash">
+  <template>
+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).