@supersoniks/concorde 4.9.9 → 4.9.92

package/docs/llms-full.txt

@@ -3134,97 +3134,121 @@ Shared data: Sharing data.
 
 - URL: https://concorde.supersoniks.org/crawl/docs/_decorators/get.html
 - Doc ID: docs/_decorators/get
-- Keywords: Concorde, supersoniks, docs/_decorators/get, get, @get, decorator, API.getDetailed, ApiResult | null, request, response, null, dataProvider(...), result, Endpoint, ApiResult
+- Keywords: Concorde, supersoniks, docs/_decorators/get, get, @get, decorator, ApiResult, undefined, payload.result, payload.response, payload.request, 
 
-@get
+The first argument is always an
+[, serviceURL, refetch(component), 
 
-Loads data through API.getDetailed. The decorated property is ApiResult  | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.
 
-Pass an Endpoint  as the first argument. Import get and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.
 
-Configuration
+@get
 
-- 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.
+@get loads data and stores the result in an optional ApiResult  property.
+The property is undefined until a result is available.
 
-Dynamic path
+- payload.result: typed data;
+- payload.response: the HTTP response;
+- payload.request: the request that was sent.
 
-${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.
+Minimal usage
 
-Options (GetOptions)
+const usersEndpoint = new Endpoint ("users");
 
-Pass as the second argument (scoped config) or third (with a configuration key). Same shape as send decorators where applicable:
+@get(usersEndpoint)
+@state()
+payload?: ApiResult ;
 
-| Option | Description |
-|--------|-------------|
-| skipEmptyPlaceholder | Treat "" as not ready (see Dynamic path). |
-| refetchEveryMs | Automatic polling interval (ms). 0 or omitted = no polling. |
-| triggerKey | DataProviderKey — PublisherManager.get(...).invalidate() on that publisher re-runs the GET. |
+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.
 
-Manual refetch (triggerKey)
+Refetching a GET
 
-Same pattern as @post: a publisher acts as a signal, independent of the response payload.
+From the component
 
-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";
+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 geoCommunesEndpoint = new Endpoint (
-  "communes?limit=5&fields=nom,code",
-);
-const geoCommunesRefreshKey = new DataProviderKey (
-  "docsDemoGeoCommunesRefresh",
-);
+const usersGet = get(new Endpoint ("users"));
 
-@get(geoCommunesEndpoint, apiConfigurationKey, {
-  triggerKey: geoCommunesRefreshKey,
-})
+@usersGet
 @state()
-payload: ApiResult  | null = null;
+payload?: ApiResult ;
 
-// Same component or anywhere else:
-dp(geoCommunesRefreshKey).invalidate();
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
+}
 
-Prefer triggerKey over mutating the API configuration publisher when you only want to reload the same URL — no need to touch serviceURL, tokens, etc.
+refetch(component) returns a Promise  | undefined> that resolves
+after the GET has completed.
 
-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")).
+From a method decorator
 
-When the GET runs again
+The refetch can decorate a local method. The default is after; if the
+method returns a Promise, the GET waits for its resolution. The decorated method
+call also waits for the refetch to complete.
 
-- 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).
+import { refetch } from "@supersoniks/concorde/decorators";
 
-Import
+@refetch(usersGet)
+async reload() {
+  this.userId = "42";
+}
 
-import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+Use { when: "before" } when the GET must complete before the method runs:
 
-Minimal example
+@refetch(usersGet, { when: "before" })
+reloadBefore() {
+  // The refetch has completed before this method runs.
+}
 
-Same demo service as sonic-queue (/docs-mock-api/geo/). Publisher setup lives in decorators-demo-geo.ts and decorators-demo-subscribe-publish-get-demos.ts.
+The method decorator adds an explicit trigger; changes to dynamic endpoint
+properties and configuration publishers keep their existing automatic behavior.
 
-@get(new Endpoint ("users/${userId}"))
-@state()
-payload: ApiResult  | null = null;
+Options (GetOptions)
 
-Live demos
+Options are the second argument, or the third argument when an API
+configuration key is provided.
 
-@get with triggerKey — refresh button + X-Fetched-At timestamp in the UI:
+- 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.
+- triggerKey: a publisher whose invalidate() runs the GET again.
 
-Dynamic config and endpoint path. Manual refetch is triggered from a separate component (same triggerKey publisher):
+With a configuration key, use:
 
-Scoped @get with @publish / @subscribe on the payload (see @publish and @subscribe) — wrap under an ancestor with serviceURL="/docs-mock-api/geo/":
+@get(usersEndpoint, apiConfigurationKey)
 
-Stale responses are ignored if the path or generation changed before the request finished.
+When the GET runs again
 
-See also
+- when the component connects and configuration is available;
+- when a property used in ${...} changes;
+- when a configuration publisher changes;
+- when the triggerKey publisher is invalidated;
+- after each response when refetchEveryMs is set.
 
-- Dynamic path placeholders
-- @post · @put · @patch — send decorators (same path rules)
+See Dynamic path placeholders for
+dynamic path details.
+
+Import
+
+import { get, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+
+Demos
+
+See @post,
+@put, and
+@patch for write operations.
+
+Advanced
+
+External invalidation is currently available through triggerKey; it is kept
+out of the main usage examples.
 
 ---
 
@@ -3731,44 +3755,60 @@ Notes
 
 - URL: https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html
 - Doc ID: docs/_decorators/patch
-- Keywords: Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, API.patchDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators
+- Keywords: Concorde, supersoniks, docs/_decorators/patch, patch, @patch, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: "before", autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing
 
 @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 >("users.patch");
+const patchUser = patch(new Endpoint ("users/42"), bodyKey);
 
-Configuration
+@patchUser
+@state()
+payload?: ApiResult ;
 
-Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey  as third argument.
+To run the operation again from the component:
 
-Options (PatchOptions)
+async savePatch() {
+  await 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.
+send(component) returns a Promise resolved after the PATCH completes. See
+@post for the method-decorator form and the
+when: "before" option.
 
-Import
+The PATCH is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. The available options are described in
+@post:
 
-import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
+- triggerKey
 
-Example
+Pass explicit API configuration as the third argument:
 
-const patchBodyKey = new DataProviderKey<Partial<Resource>>("resourcePatch");
+@patch(endpoint, bodyKey, apiConfigurationKey)
 
-@patch(
-  new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"),
-  patchBodyKey,
-  { skipEmptyPlaceholder: true },
-)
-@state()
-payload?: ApiResult<Resource> | null;
+Import
+
+import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 
 See also
 
-- @post — POST (live demos)
-- @put — full replacement (PUT)
+- @post — options and triggers
+- @put — full replacement
 - Dynamic path placeholders
 
 ---
@@ -3777,72 +3817,126 @@ See also
 
 - URL: https://concorde.supersoniks.org/crawl/docs/_decorators/post.html
 - Doc ID: docs/_decorators/post
-- Keywords: Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, API.postDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators
+- Keywords: Concorde, supersoniks, docs/_decorators/post, post, @post, decorator, ApiResult, undefined, Endpoint, DataProviderKey, 
+
+The current body is read from , send(component), 
+
+,  returns a , 
+
+Use 
 
 @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.
 
-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.
+Minimal usage
 
-Configuration
+Pass an Endpoint  and a DataProviderKey  for the request body.
 
-Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey  as third argument. See API configuration for mock demos.
+const userBodyKey = new DataProviderKey ("users.form");
+const createUser = post(new Endpoint ("users"), userBodyKey);
 
-Optional PostOptions (third or fourth argument)
+@createUser
+@state()
+payload?: ApiResult ;
 
-| 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. |
+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.
 
-- 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
 
-import { post, publish, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+Keep the decorator to access send(component). The body is read again when the
+operation runs.
+
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
 
-Minimal example
+send() returns a Promise  | undefined> that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
 
-Mock service: POST /docs-mock-api/api/register (same route as sonic-submit demos). Publisher setup lives in decorators-demo-post.ts.
+From a method decorator
 
-const syncRequest = new DataProviderKey<SyncRequest>("syncRequest");
-const syncTrigger = new DataProviderKey<number>("syncTrigger");
+The send action can decorate a local method. It runs after the method by
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:
 
-@post(
-  new Endpoint<SyncResponse, { sessionId: string }>("sessions/${sessionId}/sync"),
-  syncRequest,
-  { triggerKey: syncTrigger },
-)
-@state()
-payload?: ApiResult<SyncResponse> | null;
+import { send } from "@supersoniks/concorde/decorators";
+
+@send(createUser)
+async save() {
+  // Prepare local state or validate the form.
+}
 
-Live demos
+Use { when: "before" } when the send must complete before the method runs:
 
-Dynamic endpoint path — changing sessionId on the host re-runs the POST (POST /docs-mock-api/api/sessions/{id}/sync):
+@send(createUser, { when: "before" })
+saveBefore() {
+  // The POST has completed before this method runs.
+}
 
-@post + @publish on the same property (see @publish):
+The method decorator adds an explicit send. If the method also mutates the body
+publisher, set autoPostOnBodyMutation: false when the decorated method must
+be the only trigger.
 
-Stale responses are ignored if the path or generation changed before the request finished.
+Options (PostOptions)
 
-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).
+Options are the third argument, or the fourth argument when a configuration key
+is provided.
 
-Path placeholders (${sessionId}, …): Dynamic path placeholders.
+- 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
+  "".
+- triggerKey: a publisher whose invalidate() sends the POST again.
 
-See also
+With a configuration key:
+
+@post(endpoint, userBodyKey, apiConfigurationKey)
+
+See Dynamic path placeholders 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 the triggerKey publisher is invalidated;
+- when send() is called;
+- after each response when refetchEveryMs is set.
+
+Import
+
+import { post, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 
-- @put · @patch — same decorator model, PUT / PATCH via putDetailed / patchDetailed
+Demos
+
+See @put and
+@patch: they use the same model with a
+different HTTP method.
+
+Advanced
+
+External invalidation is currently available through triggerKey; it is kept
+out of the main usage examples.
 
 ---
 
@@ -3897,43 +3991,61 @@ Dynamic paths use the same placeholder rules as @bind / @subscribe. Resolution a
 
 - URL: https://concorde.supersoniks.org/crawl/docs/_decorators/put.html
 - Doc ID: docs/_decorators/put
-- Keywords: Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, API.putDetailed, ApiResult | null, request, response, result, Endpoint, DataProviderKey, ApiResult, @supersoniks/concorde/decorators
+- Keywords: Concorde, supersoniks, docs/_decorators/put, put, @put, decorator, Endpoint, DataProviderKey, ApiResult, send(component), 
+
+, when: "before", autoPostOnBodyMutation: false, autoPostOnBodyMutation, skipIfBodyMissing
 
 @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 ("users.form");
+const updateUser = put(new Endpoint ("users/42"), 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: "before" option.
 
-import { put, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+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<UpdatePayload>("resourceBody");
+Pass explicit API configuration as the third argument:
 
-@put(new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"), bodyKey)
-@state()
-payload?: ApiResult<Resource> | 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 "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 
 See also
 
-- @post — POST (live demos, polling, @publish)
-- @patch — partial update (PATCH)
-- Endpoint · API configuration
+- @post — options and triggers
+- @patch — partial update
+- Dynamic path placeholders
 
 ---
 
@@ -4233,7 +4345,7 @@ See DataProviderKey, @subscribe, and the concorde-get-set-dp migration skill.
 - URL: https://concorde.supersoniks.org/crawl/docs/_getting-started/ai-agents.html
 - Doc ID: docs/_getting-started/ai-agents
 - Keywords: Concorde, supersoniks, docs/_getting-started/ai-agents, ai-agents, AI agents (skills & 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
 
 AI agents (skills & AGENTS.md)
 
@@ -4259,16 +4371,33 @@ Useful flags
 
 | Flag | Effect |
 |------|--------|
-| --merge-agents | Append to an existing AGENTS.md instead of replacing it |
-| --overlay   | 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   | 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   | 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 |
+
+[optional project preamble — short, project-only]
+
+[--- + overlay AGENTS.concorde.md]
+
+Everything after   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 |
@@ -4282,7 +4411,7 @@ Workflow
 
 1. Starter project: Installation — yarn ai:sync is wired in the kit.
 2. Existing / manual Vite project: Manual installation, 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 nodemodules/@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/llms.txt

@@ -71,13 +71,13 @@ Custom
 - [@ancestorAttribute](https://concorde.supersoniks.org/crawl/docs/_decorators/ancestor-attribute.html) (docs/_decorators/ancestor-attribute): The @ancestorAttribute decorator automatically injects the value of an ancestor's attribute into a class property at the time of connectedCallback.
 - [@autoSubscribe](https://concorde.supersoniks.org/crawl/docs/_decorators/auto-subscribe.html) (docs/_decorators/auto-subscribe): > Legacy: prefer @subscribe + DataProviderKey. Examples below may still show PublisherManager for existing codebases.
 - [@bind](https://concorde.supersoniks.org/crawl/docs/_decorators/bind.html) (docs/_decorators/bind): Binds a class property to a path in a publisher. The property updates when publisher data changes.
-- [@get](https://concorde.supersoniks.org/crawl/docs/_decorators/get.html) (docs/_decorators/get): Loads data through API.getDetailed. The decorated property is ApiResult<T> | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.
+- [@get](https://concorde.supersoniks.org/crawl/docs/_decorators/get.html) (docs/_decorators/get): @get loads data and stores the result in an optional ApiResult<T> property.
 - [@handle](https://concorde.supersoniks.org/crawl/docs/_decorators/handle.html) (docs/_decorators/handle): Typed callback on one or more DataProviderKey<T> paths: invokes the decorated method when a publisher assigns a value (calculations, side effects, updating other @state properties, etc.).
 - [@onAssign](https://concorde.supersoniks.org/crawl/docs/_decorators/on-assign.html) (docs/_decorators/on-assign): > New apps: use @handle with DataProviderKey (Data flow). @onAssign uses untyped string paths; it remains documented for existing codebases — see Migrating to @handle below.
-- [@patch](https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html) (docs/_decorators/patch): Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult<T> | null (request, response, result).
-- [@post](https://concorde.supersoniks.org/crawl/docs/_decorators/post.html) (docs/_decorators/post): Sends data through API.postDetailed. The decorated property is ApiResult<T> | null: request, response, and typed result.
+- [@patch](https://concorde.supersoniks.org/crawl/docs/_decorators/patch.html) (docs/_decorators/patch): @patch applies a partial update with the body from a publisher. It uses the
+- [@post](https://concorde.supersoniks.org/crawl/docs/_decorators/post.html) (docs/_decorators/post): @post sends the contents of a publisher and stores the response in an
 - [@publish](https://concorde.supersoniks.org/crawl/docs/_decorators/publish.html) (docs/_decorators/publish): Write-only binding: assigning to the property publishes to the DataProviderKey path. No read subscription (inverse of @subscribe).
-- [@put](https://concorde.supersoniks.org/crawl/docs/_decorators/put.html) (docs/_decorators/put): Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult<T> | null (request, response, result).
+- [@put](https://concorde.supersoniks.org/crawl/docs/_decorators/put.html) (docs/_decorators/put): @put replaces a resource with the body from a publisher. It uses exactly the
 - [@subscribe](https://concorde.supersoniks.org/crawl/docs/_decorators/subscribe.html) (docs/_decorators/subscribe): Keeps a Lit property in sync with a read-only slice of the DataProvider store. You pass a DataProviderKey; when that path changes, the property updates and the component re-renders.
 - [@awaitConnectedAncestors and @dispatchConnectedEvent](https://concorde.supersoniks.org/crawl/docs/_decorators/wait-for-ancestors.html) (docs/_decorators/wait-for-ancestors): The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual e
 - [sub()](https://concorde.supersoniks.org/crawl/docs/_directives/sub.html) (docs/_directives/sub): Read-only Lit directive: displays the current DataProvider value and updates whenever it is assigned.