@supersoniks/concorde 4.9.9 → 4.9.91

package/docs/src/docs/_decorators/get.md

@@ -1,123 +1,97 @@
 # @get
 
-Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
+`@get` loads data and stores the result in an `ApiResult<T> | null` property.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+- `payload.result`: typed data;
+- `payload.response`: the HTTP response;
+- `payload.request`: the request that was sent.
 
-## Configuration
+## Minimal usage
 
-- **Default:** `HTML.getApiConfiguration(host)` (ancestor `serviceURL`, etc.).
-- **Second argument:** `DataProviderKey<APIConfiguration>` — config is read from the publisher at the resolved path; internal mutations trigger another GET. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
-
-## Dynamic path
-
-`${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+```typescript
+const usersEndpoint = new Endpoint<User[]>("users");
 
-## Options (`GetOptions`)
+@get(usersEndpoint)
+@state()
+payload: ApiResult<User[]> | null = null;
+```
 
-Pass as the **second** argument (scoped config) or **third** (with a configuration key). Same shape as send decorators where applicable:
+The first argument is always an
+[`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint). API configuration is read
+from the HTML scope (`serviceURL`, token, etc.), so the component is usually
+placed below an element that provides this configuration.
 
-| Option | Description |
-|--------|-------------|
-| `skipEmptyPlaceholder` | Treat `""` as not ready (see [Dynamic path](#docs/_misc/dynamic-path.md/dynamic-path)). |
-| `refetchEveryMs` | Automatic polling interval (ms). `0` or omitted = no polling. |
-| `triggerKey` | `DataProviderKey` — `PublisherManager.get(...).invalidate()` on that publisher re-runs the GET. |
+## Refetching a GET
 
-### Manual refetch (`triggerKey`)
+### From the component
 
-Same pattern as [@post](#docs/_decorators/post.md/post): a publisher acts as a **signal**, independent of the response payload.
+Keep the decorator in a constant to access `refetch(component)`. Refetch only
+targets the instance passed as the argument, even before it has received a
+result.
 
 ```typescript
-import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { dp } from "@supersoniks/concorde/core/utils/PublisherProxy";
-
-const geoCommunesEndpoint = new Endpoint<GeoCommuneRow[]>(
-  "communes?limit=5&fields=nom,code",
-);
-const geoCommunesRefreshKey = new DataProviderKey<void>(
-  "docsDemoGeoCommunesRefresh",
-);
-
-@get(geoCommunesEndpoint, apiConfigurationKey, {
-  triggerKey: geoCommunesRefreshKey,
-})
+const usersGet = get(new Endpoint<User[]>("users"));
+
+@usersGet
 @state()
-payload: ApiResult<GeoCommuneRow[]> | null = null;
+payload: ApiResult<User[]> | null = null;
 
-// Same component or anywhere else:
-dp(geoCommunesRefreshKey).invalidate();
+refresh() {
+  usersGet.refetch(this);
+}
 ```
 
-Prefer `triggerKey` over mutating the API configuration publisher when you only want to **reload the same URL** — no need to touch `serviceURL`, tokens, etc.
+## Options (`GetOptions`)
+
+Options are the second argument, or the third argument when an API
+configuration key is provided.
+
+- `skipEmptyPlaceholder`: blocks the GET when `${prop}` is `""`.
+- `refetchEveryMs`: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use `0`, to disable polling.
 
-The docs mock adds an **`X-Fetched-At`** response header on `/docs-mock-api/geo/communes` so live demos can show when the last fetch happened (`response.headers.get("X-Fetched-At")`).
+With a configuration key, use:
+
+```typescript
+@get(usersEndpoint, apiConfigurationKey)
+```
 
 ## When the GET runs again
 
-- A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
-- `set` on the active configuration publisher (`onInternalMutation`).
-- `triggerKey` publisher `invalidate()`.
-- `refetchEveryMs` polling (after each successful fetch).
+- when the component connects and configuration is available;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- after each response when `refetchEveryMs` is set.
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Minimal example
-
-Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`/docs-mock-api/geo/`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
-
-<sonic-code language="typescript">
-  <template>
-@get(new Endpoint<User>("users/${userId}"))
-@state()
-payload: ApiResult<User> | null = null;
-  </template>
-</sonic-code>
-
-## Live demos
-
-`@get` with **`triggerKey`** — refresh button + `X-Fetched-At` timestamp in the UI:
+## Demos
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get"></docs-demo-sources>
     <demo-api-get></demo-api-get>
-  </template>
-</sonic-code>
-
-Dynamic config and endpoint path. Manual refetch is triggered **from a separate component** (same `triggerKey` publisher):
-
-<sonic-code>
-  <template>
     <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
     <demo-api-get-configuration-key></demo-api-get-configuration-key>
-    <demo-api-get-refresh-remote></demo-api-get-refresh-remote>
-  </template>
-</sonic-code>
-
-Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="/docs-mock-api/geo/"`:
-
-<sonic-code>
-  <template>
-<div serviceURL="/docs-mock-api/geo/">
-  <docs-demo-sources for="demo-api-get-publish-subscribe"></docs-demo-sources>
-  <demo-api-get-publish-subscribe></demo-api-get-publish-subscribe>
-</div>
   </template>
 </sonic-code>
 
-Stale responses are ignored if the path or generation changed before the request finished.
+See [@post](#docs/_decorators/post.md/post),
+[@put](#docs/_decorators/put.md/put), and
+[@patch](#docs/_decorators/patch.md/patch) for write operations.
 
-## See also
+## Advanced
 
-- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)
-- [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — send decorators (same path rules)
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.

package/docs/src/docs/_decorators/patch.md

@@ -1,45 +1,56 @@
 # @patch
 
-Sends data through [`API.patchDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+`@patch` applies a partial update with the body from a publisher. It uses the
+same model as [@post](#docs/_decorators/post.md/post):
+`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
+`send(component)` handle.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `patch` and `ApiResult` from `@supersoniks/concorde/decorators`.
+## Minimal usage
 
-## Configuration
+```typescript
+const bodyKey = new DataProviderKey<Partial<User>>("users.patch");
+const patchUser = patch(new Endpoint<User>("users/42"), bodyKey);
 
-Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+@patchUser
+@state()
+payload: ApiResult<User> | null = null;
+```
+
+To run the operation again from the component:
+
+```typescript
+savePatch() {
+  patchUser.send(this);
+}
+```
+
+The PATCH is also sent automatically when the body mutates, unless
+`autoPostOnBodyMutation: false` is set. The available options are described in
+[@post](#docs/_decorators/post.md/post):
 
-## Options (`PatchOptions`)
+- `autoPostOnBodyMutation`
+- `skipIfBodyMissing`
+- `refetchEveryMs`
+- `skipEmptyPlaceholder`
 
-Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+Pass explicit API configuration as the third argument:
+
+```typescript
+@patch(endpoint, bodyKey, apiConfigurationKey)
+```
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
-
-## Example
-
-<sonic-code language="typescript">
-  <template>
-const patchBodyKey = new DataProviderKey&lt;Partial&lt;Resource&gt;&gt;("resourcePatch");
-
-@patch(
-  new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"),
-  patchBodyKey,
-  { skipEmptyPlaceholder: true },
-)
-@state()
-payload?: ApiResult&lt;Resource&gt; | null;
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
 ## See also
 
-- [@post](#docs/_decorators/post.md/post) — POST (live demos)
-- [@put](#docs/_decorators/put.md/put) — full replacement (PUT)
+- [@post](#docs/_decorators/post.md/post) — options and triggers
+- [@put](#docs/_decorators/put.md/put) — full replacement
 - [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/docs/src/docs/_decorators/post.md

@@ -1,93 +1,102 @@
 # @post
 
-Sends data through [`API.postDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response`, and typed `result`.
+`@post` sends the contents of a publisher and stores the response in an
+`ApiResult<T> | null` property.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument and a `DataProviderKey` for the **request body** as the second. Import `post` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+## Minimal usage
 
-## Configuration
+Pass an `Endpoint<T>` and a `DataProviderKey<B>` for the request body.
 
-Same as [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` by default, or `DataProviderKey<APIConfiguration>` as third argument. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+```typescript
+const userBodyKey = new DataProviderKey<CreateUser>("users.form");
+const createUser = post(new Endpoint<User>("users"), userBodyKey);
 
-## Optional `PostOptions` (third or fourth argument)
+@createUser
+@state()
+payload: ApiResult<User> | null = null;
+```
 
-| Option | Description |
-|--------|-------------|
-| `refetchEveryMs` | Re-post on an interval (ms). |
-| `skipIfBodyMissing` | Skip when body publisher is `null`/`undefined` (default: `true`). |
-| `autoPostOnBodyMutation` | Re-post when the body publisher mutates (default: `true`). `false` = manual via `triggerKey.invalidate()`. |
-| `skipEmptyPlaceholder` | If `true`, a placeholder resolved to `''` blocks the request (empty string only — not `0` or `false`). See [Dynamic paths](#docs/_misc/dynamic-path.md/dynamic-path). |
-| `triggerKey` | `DataProviderKey` — `invalidate()` re-runs the POST with the current body. |
+The current body is read from `userBodyKey`. By default, the POST is sent when
+the component connects and after each body mutation. Mutations in the same
+frame are coalesced into one request.
 
-## When the POST runs again
+API configuration is read from the HTML scope, as with
+[@get](#docs/_decorators/get.md/get).
 
-- Body publisher `onInternalMutation` when `autoPostOnBodyMutation` is `true` (default). Plusieurs mutations synchrones dans la même frame sont regroupées en **un seul POST** via `requestAnimationFrame`.
-- Endpoint path dependency changes (`${sessionId}` on the host).
-- Configuration publisher mutation.
-- `triggerKey` publisher `invalidate()`.
-- `refetchEveryMs` timer (if set).
+## Sending the POST again
 
-## Import
+### From the component
 
-<sonic-code language="typescript">
-  <template>
-import { post, publish, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
+Keep the decorator to access `send(component)`. The body is read again when the
+operation runs.
+
+```typescript
+saveAgain() {
+  createUser.send(this);
+}
+```
 
-## Minimal example
+`send()` is useful for “Save” or “Retry” buttons. It can repeat an operation
+with side effects.
 
-Mock service: `POST /docs-mock-api/api/register` (same route as [`sonic-submit`](#core/components/functional/submit/submit.md/submit) demos). Publisher setup lives in `decorators-demo-post.ts`.
+## Options (`PostOptions`)
+
+Options are the third argument, or the fourth argument when a configuration key
+is provided.
+
+- `autoPostOnBodyMutation`: send after a body mutation (default: `true`). Set
+  it to `false` to use `send()`.
+- `skipIfBodyMissing`: skip when the body is `null` or `undefined` (default:
+  `true`).
+- `refetchEveryMs`: repeat the POST at this interval. Use it only when
+  repeating the operation is intended.
+- `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
+  `""`.
+
+With a configuration key:
+
+```typescript
+@post(endpoint, userBodyKey, apiConfigurationKey)
+```
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
+
+## When the POST is sent
+
+- when the component connects and the body and configuration are available;
+- after a body mutation, unless `autoPostOnBodyMutation: false`;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- when `send()` is called;
+- after each response when `refetchEveryMs` is set.
+
+## Import
 
 <sonic-code language="typescript">
   <template>
-const syncRequest = new DataProviderKey&lt;SyncRequest&gt;("syncRequest");
-const syncTrigger = new DataProviderKey&lt;number&gt;("syncTrigger");
-
-@post(
-  new Endpoint&lt;SyncResponse, { sessionId: string }&gt;("sessions/${sessionId}/sync"),
-  syncRequest,
-  { triggerKey: syncTrigger },
-)
-@state()
-payload?: ApiResult&lt;SyncResponse&gt; | null;
+import { post, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Live demos
+## Demos
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-post"></docs-demo-sources>
     <demo-api-post></demo-api-post>
-  </template>
-</sonic-code>
-
-Dynamic endpoint path — changing `sessionId` on the host re-runs the POST (`POST /docs-mock-api/api/sessions/{id}/sync`):
-
-<sonic-code>
-  <template>
     <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
     <demo-api-post-dynamic></demo-api-post-dynamic>
   </template>
 </sonic-code>
 
-`@post` + `@publish` on the same property (see [@publish](#docs/_decorators/publish.md/publish)):
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-api-post-publish"></docs-demo-sources>
-    <demo-api-post-publish></demo-api-post-publish>
-  </template>
-</sonic-code>
-
-Stale responses are ignored if the path or generation changed before the request finished.
-
-**Note:** plusieurs composants `@post` sur la même page qui partagent le même `bodyKey` enverront chacun une requête à chaque mutation du body — utiliser une clé par composant (voir les deux démos live ci-dessus).
-
-Path placeholders (`${sessionId}`, …): [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+See [@put](#docs/_decorators/put.md/put) and
+[@patch](#docs/_decorators/patch.md/patch): they use the same model with a
+different HTTP method.
 
-## See also
+## Advanced
 
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — same decorator model, `PUT` / `PATCH` via `putDetailed` / `patchDetailed`
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.

package/docs/src/docs/_decorators/put.md

@@ -1,43 +1,56 @@
 # @put
 
-Sends data through [`API.putDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+`@put` replaces a resource with the body from a publisher. It uses exactly the
+same model as [@post](#docs/_decorators/post.md/post):
+`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
+`send(component)` handle.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `put` and `ApiResult` from `@supersoniks/concorde/decorators`.
+## Minimal usage
 
-## Configuration
+```typescript
+const bodyKey = new DataProviderKey<UpdateUser>("users.form");
+const updateUser = put(new Endpoint<User>("users/42"), bodyKey);
 
-Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+@updateUser
+@state()
+payload: ApiResult<User> | null = null;
+```
+
+To run the operation again from the component:
+
+```typescript
+update() {
+  updateUser.send(this);
+}
+```
+
+The PUT is also sent automatically when the body mutates, unless
+`autoPostOnBodyMutation: false` is set. See
+[@post](#docs/_decorators/post.md/post) for the option details:
 
-## Options (`PutOptions`)
+- `autoPostOnBodyMutation`
+- `skipIfBodyMissing`
+- `refetchEveryMs`
+- `skipEmptyPlaceholder`
 
-Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+Pass explicit API configuration as the third argument:
+
+```typescript
+@put(endpoint, bodyKey, apiConfigurationKey)
+```
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { put, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Example
-
-<sonic-code language="typescript">
-  <template>
-const bodyKey = new DataProviderKey&lt;UpdatePayload&gt;("resourceBody");
-
-@put(new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"), bodyKey)
-@state()
-payload?: ApiResult&lt;Resource&gt; | null;
-  </template>
-</sonic-code>
-
-Changing `resourceId` on the host re-runs the PUT when the path becomes ready — see [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
-
 ## See also
 
-- [@post](#docs/_decorators/post.md/post) — POST (live demos, polling, `@publish`)
-- [@patch](#docs/_decorators/patch.md/patch) — partial update (PATCH)
-- [Endpoint](#docs/_misc/endpoint.md/endpoint) · [API configuration](#docs/_misc/api-configuration.md/api-configuration)
+- [@post](#docs/_decorators/post.md/post) — options and triggers
+- [@patch](#docs/_decorators/patch.md/patch) — partial update
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/docs/src/docs/_getting-started/ai-agents.md

@@ -26,16 +26,36 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 
 | Flag | Effect |
 |------|--------|
-| `--merge-agents` | Append to an existing `AGENTS.md` instead of replacing it |
-| `--overlay <dir>` | Copy extra rules/skills from another layer (e.g. starter kit) |
+| `--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.
+
 ## What gets installed
 
 | Path | Role |
 |------|------|
-| `AGENTS.md` | Project-level guide for agents (Concorde conventions) |
+| `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 |
@@ -49,7 +69,7 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 
 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`.
-3. Commit `AGENTS.md`, `.cursor/`, and `.aiassistant/` if your team shares agent settings.
+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`).