@supersoniks/concorde 4.9.9 → 4.9.91

package/docs/crawl/docs/_getting-started/ai-agents.html

@@ -6,7 +6,7 @@
   <title>AI agents (skills &amp; AGENTS.md) — Concorde</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) | , --merge-agents, --overlay , --cursor-only">
+| Concorde repo (contributors) | , --skip-agents, --merge-agents, --force-agents">
   <meta name="concorde-doc-id" content="docs/_getting-started/ai-agents">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html">
 </head>
@@ -17,7 +17,7 @@
   <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) | , --merge-agents, --overlay , --cursor-only. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html</a>.</span></p>
+| Concorde repo (contributors) | , --skip-agents, --merge-agents, --force-agents. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html">https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html</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="./concorde-outside.html#concorde-outside">starter</a> project, run <code>yarn ai:sync</code> after install. On a <a href="./concorde-manual-install.html#concorde-manual-install">manual / brownfield</a> project, install Concorde first, then use <code>ai-init</code> below.</p>
@@ -57,12 +57,20 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 </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>Append to an existing <code>AGENTS.md</code> instead of replacing it</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>Copy extra rules/skills from another layer (e.g. starter kit)</td>
+<td>Extra rules/skills + optional <code>AGENTS.concorde.md</code> for project-only Concorde agent notes</td>
 </tr>
 <tr>
 <td><code>--cursor-only</code></td>
@@ -73,6 +81,37 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 <td>Install only <code>.aiassistant/rules/</code></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>
+</tr>
+<tr>
+<td>File with <code>&lt;!-- concorde-ai --&gt;</code></td>
+<td>Refresh the managed zone only</td>
+</tr>
+<tr>
+<td>File <strong>without</strong> marker (project notes)</td>
+<td><strong>Left untouched</strong> — skills / rules are enough</td>
+</tr>
+<tr>
+<td><code>--merge-agents</code> / <code>--force-agents</code> / <code>--skip-agents</code></td>
+<td>See flags above</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>
@@ -83,7 +122,7 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 </thead>
 <tbody><tr>
 <td><code>AGENTS.md</code></td>
-<td>Project-level guide for agents (Concorde conventions)</td>
+<td>Created only if missing; existing project-owned files are left alone unless <code>--merge-agents</code> / <code>--force-agents</code></td>
 </tr>
 <tr>
 <td><code>.cursor/skills/concorde/</code></td>
@@ -122,7 +161,7 @@ node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
 <ol>
 <li><strong>Starter project:</strong> <a href="./concorde-outside.html#concorde-outside">Installation</a> — <code>yarn ai:sync</code> is wired in the kit.</li>
 <li><strong>Existing / manual Vite project:</strong> <a href="./concorde-manual-install.html#concorde-manual-install">Manual installation</a>, then <strong><code>ai-init</code></strong> after <code>yarn add @supersoniks/concorde</code>.</li>
-<li>Commit <code>AGENTS.md</code>, <code>.cursor/</code>, and <code>.aiassistant/</code> if your team shares agent settings.</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>

package/docs/crawl/hubs/decorators.html

@@ -149,31 +149,56 @@ export class DemoBind extends LitElement {
 <section id="docs-_decorators-get" data-doc-id="docs/_decorators/get">
   <h2><a href="../docs/_decorators/get.html">@get</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/get</code> · <a href="../docs/_decorators/get.html">full page</a></p>
-  <p>Loads data through API.getDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.</p>
+  <p>@get loads data and stores the result in an ApiResult&lt;T&gt; | null property.</p>
   <pre class="doc-excerpt">@get
 
-Loads data through API.getDetailed. The decorated property is ApiResult  | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.
+@get loads data and stores the result in an ApiResult  | null property.
 
-Pass an 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  — config is read from the publisher at the resolved path; internal mutations trigger another GET. See API configuration for mock demos.
+const usersEndpoint = new Endpoint (&quot;users&quot;);
 
-Dynamic path
+@get(usersEndpoint)
+@state()
+payload: ApiResult  | null = null;
+
+The first argument is always an
+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.
+
+Refetching a GET
 
-${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 &quot;&quot; (empty string only). Details: Dynamic path placeholders.
+From the component
+
+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.
+
+const usersGet = get(new Endpoint (&quot;users&quot;));
+
+@usersGet
+@state()
+payload: ApiResult  | null = null;
+
+refresh() {
+  usersGet.refetch(this);
+}
 
 Options (GetOptions)
 
-Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:
+Options are the second argument, or the third argument when an API
+configuration key is provided.
 
-| Option | Description |
-|--------|-------------|
-| skipEmptyPlaceholder | Treat &quot;&quot; as not ready (see Dynamic path). |
-| refetchEveryMs | Automatic polling interval (ms). 0 or omitted = no polling. |
-| tri</pre>
+- skipEmptyPlaceholder: blocks the GET when ${prop} is &quot;&quot;.
+- refetchEveryMs: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use 0, to disable polling.
+
+With a configurat</pre>
 </section>
 <section id="docs-_decorators-handle" data-doc-id="docs/_decorators/handle">
   <h2><a href="../docs/_decorators/handle.html">@handle</a></h2>
@@ -253,71 +278,105 @@ export class DemoOnAssign extends LitElement {
 <section id="docs-_decorators-patch" data-doc-id="docs/_decorators/patch">
   <h2><a href="../docs/_decorators/patch.html">@patch</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/patch</code> · <a href="../docs/_decorators/patch.html">full page</a></p>
-  <p>Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).</p>
+  <p>@patch applies a partial update with the body from a publisher. It uses the</p>
   <pre class="doc-excerpt">@patch
 
-Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).
+@patch applies a partial update with the body from a publisher. It uses the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
+
+Minimal usage
 
-Pass an Endpoint  and a DataProviderKey for the request body. Import patch and ApiResult from @supersoniks/concorde/decorators.
+const bodyKey = new DataProviderKey &gt;(&quot;users.patch&quot;);
+const patchUser = patch(new Endpoint (&quot;users/42&quot;), bodyKey);
 
-Configuration
+@patchUser
+@state()
+payload: ApiResult  | null = null;
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+To run the operation again from the component:
 
-Options (PatchOptions)
+savePatch() {
+  patchUser.send(this);
+}
 
-Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.
+The PATCH is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. The available options are described in
+@post:
 
-Import
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
 
-import { patch, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
-import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+Pass explicit API configuration as the third argument:
 
-Example
+@patch(endpoint, bodyKey, apiConfigurationKey)
 
-const patchBodyKey = new DataProviderKey&amp;lt;Partial&amp;lt;Resource&amp;gt;&amp;gt;(&quot;resourcePatch&quot;);
+Import
 
-@patch(
-  new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;),
-  patchBodyKey,
-  { skipEmptyPlaceholder: true },
-)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
+import { patch, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 
 See also
 
-- @post — POST (live demos)
-- @put — full rep</pre>
+- @post — options and triggers
+- @put — full replacement
+- Dynamic path placeholders</pre>
 </section>
 <section id="docs-_decorators-post" data-doc-id="docs/_decorators/post">
   <h2><a href="../docs/_decorators/post.html">@post</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/post</code> · <a href="../docs/_decorators/post.html">full page</a></p>
-  <p>Sends data through API.postDetailed. The decorated property is ApiResult&lt;T&gt; | null: request, response, and typed result.</p>
+  <p>@post sends the contents of a publisher and stores the response in an</p>
   <pre class="doc-excerpt">@post
 
-Sends data through API.postDetailed. The decorated property is ApiResult  | null: request, response, and typed result.
+@post sends the contents of a publisher and stores the response in an
+ApiResult  | null property.
+
+Minimal usage
+
+Pass an Endpoint  and a DataProviderKey  for the request body.
 
-Pass an 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.
+const userBodyKey = new DataProviderKey (&quot;users.form&quot;);
+const createUser = post(new Endpoint (&quot;users&quot;), userBodyKey);
 
-Configuration
+@createUser
+@state()
+payload: ApiResult  | null = null;
+
+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.
 
-Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey  as third argument. See API configuration for mock demos.
+API configuration is read from the HTML scope, as with
+@get.
 
-Optional PostOptions (third or fourth argument)
+Sending the POST again
 
-| 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. |
-| triggerKey | DataProviderKey — invalidate() re-runs the POST with the current body. |
+From the component
 
-When the POST runs again
+Keep the decorator to access send(component). The body is read again when the
+operation runs.
 
-- Body publisher onInternalMutation when autoPostOnBodyMutation is true (defa</pre>
+saveAgain() {
+  createUser.send(this);
+}
+
+send() is useful for “Save” or “Retry” buttons. It can repeat an operation
+with side effects.
+
+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).
+- refetchE</pre>
 </section>
 <section id="docs-_decorators-publish" data-doc-id="docs/_decorators/publish">
   <h2><a href="../docs/_decorators/publish.html">@publish</a></h2>
@@ -365,40 +424,53 @@ Dynamic paths use the same placeholder rules as @bind / @subscribe. Resolution a
 <section id="docs-_decorators-put" data-doc-id="docs/_decorators/put">
   <h2><a href="../docs/_decorators/put.html">@put</a></h2>
   <p><strong>Doc ID:</strong> <code>docs/_decorators/put</code> · <a href="../docs/_decorators/put.html">full page</a></p>
-  <p>Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).</p>
+  <p>@put replaces a resource with the body from a publisher. It uses exactly the</p>
   <pre class="doc-excerpt">@put
 
-Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult  | null (request, response, result).
+@put replaces a resource with the body from a publisher. It uses exactly the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
 
-Pass an Endpoint  and a DataProviderKey for the request body. Import put and ApiResult from @supersoniks/concorde/decorators.
+Minimal usage
 
-Configuration
+const bodyKey = new DataProviderKey (&quot;users.form&quot;);
+const updateUser = put(new Endpoint (&quot;users/42&quot;), bodyKey);
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+@updateUser
+@state()
+payload: ApiResult  | null = null;
 
-Options (PutOptions)
+To run the operation again from the component:
 
-Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.
+update() {
+  updateUser.send(this);
+}
 
-Import
+The PUT is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. See
+@post for the option details:
 
-import { put, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
-import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
-import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
 
-Example
+Pass explicit API configuration as the third argument:
 
-const bodyKey = new DataProviderKey&amp;lt;UpdatePayload&amp;gt;(&quot;resourceBody&quot;);
+@put(endpoint, bodyKey, apiConfigurationKey)
 
-@put(new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;), bodyKey)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
+Import
 
-Changing resourceId on the host re-runs the PUT when the path becomes ready — see Dynamic path placeholders.
+import { put, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 
 See also
 
-- @post —</pre>
+- @post — options and triggers
+- @patch — partial update
+- Dynamic path placeholders</pre>
 </section>
 <section id="docs-_decorators-subscribe" data-doc-id="docs/_decorators/subscribe">
   <h2><a href="../docs/_decorators/subscribe.html">@subscribe</a></h2>