@supersoniks/concorde 4.9.9 → 4.9.92

package/docs/crawl/docs/_decorators/put.html

@@ -4,8 +4,10 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>@put — Concorde</title>
-  <meta name="description" content="Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result).">
-  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, API.putDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators">
+  <meta name="description" content="@put replaces a resource with the body from a publisher. It uses exactly the">
+  <meta name="keywords" content="Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: &quot;before&quot;, autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing">
   <meta name="concorde-doc-id" content="docs/_decorators/put">
   <link rel="canonical" href="https://concorde.supersoniks.org/crawl/docs/_decorators/put.html">
 </head>
@@ -15,32 +17,53 @@
   </header>
   <main>
     <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @put</strong>. Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult&lt;T&gt; | null (request, response, result). <span>Doc ID: <code>docs/_decorators/put</code>. Keywords: Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, API.putDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/put.html">https://concorde.supersoniks.org/crawl/docs/_decorators/put.html</a>.</span></p>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @put</strong>. @put replaces a resource with the body from a publisher. It uses exactly the <span>Doc ID: <code>docs/_decorators/put</code>. Keywords: Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: &quot;before&quot;, autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing. URL: <a href="https://concorde.supersoniks.org/crawl/docs/_decorators/put.html">https://concorde.supersoniks.org/crawl/docs/_decorators/put.html</a>.</span></p>
       <h1 id="put">@put</h1>
-<p>Sends data through <a href="../../core/utils/api.ts"><code>API.putDetailed</code></a>. Same model as <a href="./post.html#post">@post</a>: decorated property is <strong><code>ApiResult&lt;T&gt; | null</code></strong> (<code>request</code>, <code>response</code>, <code>result</code>).</p>
-<p>Pass an <a href="../_misc/endpoint.html#endpoint"><code>Endpoint&lt;T&gt;</code></a> and a <code>DataProviderKey</code> for the <strong>request body</strong>. Import <code>put</code> and <code>ApiResult</code> from <code>@supersoniks/concorde/decorators</code>.</p>
-<h2 id="configuration">Configuration</h2>
-<p>Same as <a href="./post.html#post">@post</a> / <a href="./get.html#get">@get</a>: scoped <code>HTML.getApiConfiguration(host)</code> or <code>DataProviderKey&lt;APIConfiguration&gt;</code> as third argument.</p>
-<h2 id="options-putoptions">Options (<code>PutOptions</code>)</h2>
-<p>Same shape as <code>PostOptions</code> on <a href="./post.html#post">@post</a> (<code>ApiSendOptions</code>): <code>refetchEveryMs</code>, <code>skipIfBodyMissing</code>, <code>autoPostOnBodyMutation</code>, <code>triggerKey</code>, <code>skipEmptyPlaceholder</code>. See <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a> for <code>${sessionId}</code> and empty-string behaviour.</p>
+<p><code>@put</code> replaces a resource with the body from a publisher. It uses exactly the
+same model as <a href="./post.html#post">@post</a>:
+<code>Endpoint&lt;T&gt;</code>, <code>DataProviderKey&lt;B&gt;</code>, <code>ApiResult&lt;T&gt;</code>, options, and the
+<code>send(component)</code> handle.</p>
+<h2 id="minimal-usage">Minimal usage</h2>
+<pre><code class="language-typescript">const bodyKey = new DataProviderKey&lt;UpdateUser&gt;(&quot;users.form&quot;);
+const updateUser = put(new Endpoint&lt;User&gt;(&quot;users/42&quot;), bodyKey);
+
+@updateUser
+@state()
+payload?: ApiResult&lt;User&gt;;
+</code></pre>
+<p>To run the operation again from the component:</p>
+<pre><code class="language-typescript">async update() {
+  await updateUser.send(this);
+}
+</code></pre>
+<p><code>send(component)</code> returns a Promise resolved after the PUT completes. See
+<a href="./post.html#post">@post</a> for the method-decorator form and the
+<code>when: &quot;before&quot;</code> option.</p>
+<p>The PUT is also sent automatically when the body mutates, unless
+<code>autoPostOnBodyMutation: false</code> is set. See
+<a href="./post.html#post">@post</a> for the option details:</p>
+<ul>
+<li><code>autoPostOnBodyMutation</code></li>
+<li><code>skipIfBodyMissing</code></li>
+<li><code>refetchEveryMs</code></li>
+<li><code>skipEmptyPlaceholder</code></li>
+<li><code>triggerKey</code></li>
+</ul>
+<p>Pass explicit API configuration as the third argument:</p>
+<pre><code class="language-typescript">@put(endpoint, bodyKey, apiConfigurationKey)
+</code></pre>
 <h2 id="import">Import</h2>
 <pre><code class="language-typescript">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;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
 </code></pre>
-<h2 id="example">Example</h2>
-<pre><code class="language-typescript">const bodyKey = new DataProviderKey&amp;lt;UpdatePayload&amp;gt;(&quot;resourceBody&quot;);
-
-@put(new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;), bodyKey)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
-</code></pre>
-<p>Changing <code>resourceId</code> on the host re-runs the PUT when the path becomes ready — see <a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a>.</p>
 <h2 id="see-also">See also</h2>
 <ul>
-<li><a href="./post.html#post">@post</a> — POST (live demos, polling, <code>@publish</code>)</li>
-<li><a href="./patch.html#patch">@patch</a> — partial update (PATCH)</li>
-<li><a href="../_misc/endpoint.html#endpoint">Endpoint</a> · <a href="../_misc/api-configuration.html#api-configuration">API configuration</a></li>
+<li><a href="./post.html#post">@post</a> — options and triggers</li>
+<li><a href="./patch.html#patch">@patch</a> — partial update</li>
+<li><a href="../_misc/dynamic-path.html#dynamic-path">Dynamic path placeholders</a></li>
 </ul>
 
     </article>

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,55 @@ 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 optional ApiResult&lt;T&gt; 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 optional ApiResult  property.
+The property is undefined until a result is available.
 
-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 ;
+
+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
+
+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;));
 
-${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.
+@usersGet
+@state()
+payload?: ApiResult ;
+
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
+}
 
-Options (GetOptions)
+refetch(component) returns a Promise  | undefined&gt; that resolves
+after the GET has completed.
 
-Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:
+From a method decorator
 
-| Option | Description |
-|--------|-------------|
-| skipEmptyPlaceholder | Treat &quot;&quot; as not ready (see Dynamic path). |
-| refetchEveryMs | Automatic polling interval (ms). 0 or omitted = no polling. |
-| tri</pre>
+The refetch can decorate a local method. The default is after; if the
+method returns a Promise, the GET waits for its resol</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 +277,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.
 
-Pass an Endpoint  and a DataProviderKey for the request body. Import patch and ApiResult from @supersoniks/concorde/decorators.
+Minimal usage
 
-Configuration
+const bodyKey = new DataProviderKey &gt;(&quot;users.patch&quot;);
+const patchUser = patch(new Endpoint (&quot;users/42&quot;), bodyKey);
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+@patchUser
+@state()
+payload?: ApiResult ;
 
-Options (PatchOptions)
+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.
+async savePatch() {
+  await patchUser.send(this);
+}
 
-Import
+send(component) returns a Promise resolved after the PATCH completes. See
+@post for the method-decorator form and the
+when: &quot;before&quot; option.
 
-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;;
+The PATCH is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. The available options are described in
+@post:
 
-Example
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
+- triggerKey
 
-const patchBodyKey = new DataProviderKey&amp;lt;Partial&amp;lt;Resource&amp;gt;&amp;gt;(&quot;resourcePatch&quot;);
+Pass explicit API configuration as the third argument:
 
-@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;
+@patch(endpoint, bodyKey, apiConfigurationKey)
+
+Import
+
+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 —</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
+optional ApiResult  property. The property is undefined until a result
+is available.
+
+Minimal usage
+
+Pass an Endpoint  and a DataProviderKey  for the request body.
+
+const userBodyKey = new DataProviderKey (&quot;users.form&quot;);
+const createUser = post(new Endpoint (&quot;users&quot;), userBodyKey);
+
+@createUser
+@state()
+payload?: ApiResult ;
+
+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.
+
+API configuration is read from the HTML scope, as with
+@get.
 
-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.
+Sending the POST again
 
-Configuration
+From the component
 
-Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey  as third argument. See API configuration for mock demos.
+Keep the decorator to access send(component). The body is read again when the
+operation runs.
 
-Optional PostOptions (third or fourth argument)
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
 
-| 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. |
+send() returns a Promise  | undefined&gt; that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
 
-When the POST runs again
+From a method decorator
 
-- Body publisher onInternalMutation when autoPostOnBodyMutation is true (defa</pre>
+The send action can decorate a local method. It runs after the method by
+default, waits for an eventu</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 +423,57 @@ 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 ;
 
-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.
+async update() {
+  await updateUser.send(this);
+}
 
-Import
+send(component) returns a Promise resolved after the PUT completes. See
+@post for the method-decorator form and the
+when: &quot;before&quot; option.
 
-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;;
+The PUT is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. See
+@post for the option details:
 
-Example
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
+- triggerKey
 
-const bodyKey = new DataProviderKey&amp;lt;UpdatePayload&amp;gt;(&quot;resourceBody&quot;);
+Pass explicit API configuration as the third argument:
 
-@put(new Endpoint&amp;lt;Resource, { resourceId: string }&amp;gt;(&quot;resources/${resourceId}&quot;), bodyKey)
-@state()
-payload?: ApiResult&amp;lt;Resource&amp;gt; | null;
+@put(endpoint, bodyKey, apiConfigurationKey)
 
-Changing resourceId on the host re-runs the PUT when the path becomes ready — see Dynamic path placeholders.
+Import
+
+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
+- @</pre>
 </section>
 <section id="docs-_decorators-subscribe" data-doc-id="docs/_decorators/subscribe">
   <h2><a href="../docs/_decorators/subscribe.html">@subscribe</a></h2>