@purveyors/sdk 0.52.0 → 0.54.0

package/dist/index.d.ts

@@ -1159,7 +1159,10 @@ interface paths {
         };
         get?: never;
         put?: never;
-        /** Snapshot an executed roast as a reference profile */
+        /**
+         * Save an executed roast as a reference profile
+         * @description Save one of the caller's executed roasts as a reference profile. The default `chart_snapshot` basis stores the roast's chart for comparison only. The `artisan_source` basis copies the Artisan file the roast was imported from, so the reference can be the base for a planned profile and its export; it requires a roast with an Artisan file on record, returns 400 `roast_artisan_source_unavailable` with a `reason` otherwise, and returns the reference already saved from that roast's file instead of creating a duplicate. The roast is never modified. Requires Mallard Studio, and for API keys the exact roast:read and roast:write scopes.
+         */
         post: {
             parameters: {
                 query?: never;
@@ -1175,7 +1178,22 @@ interface paths {
                 };
             };
             responses: {
-                /** @description Created immutable roast snapshot */
+                /** @description The reference already saved from this roast's Artisan file */
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileResponse"];
+                    };
+                };
+                /** @description Created reference profile */
                 201: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
@@ -1190,8 +1208,144 @@ interface paths {
                         "application/json": components["schemas"]["ReferenceProfileResponse"];
                     };
                 };
-                /** @description Invalid request */
+                /** @description Invalid request, or the roast has no usable Artisan file on record */
                 400: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Reference profile or source roast not found */
+                404: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Revision, idempotency, or concurrency conflict */
+                409: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                429: components["responses"]["ApiRateLimitExceeded"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/reference-profiles/from-roast/candidates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List executed roasts that can be the base for a planned profile
+         * @description List the caller's executed roasts whose Artisan file is on record, newest first, each with its current revision token and the reference it is or would be saved under. `ineligibleRoastCount` counts the caller's other roasts, which have no usable Artisan file on record (entered manually, logged live, imported before files were kept, or holding a file larger than a reference profile allows). Requires Mallard Studio, and for API keys the exact roast:read scope.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    limit?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Roasts with an Artisan file on record */
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileRoastCandidatesResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
                         "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
@@ -1205,6 +1359,73 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                429: components["responses"]["ApiRateLimitExceeded"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/reference-profiles/from-roast/preview": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Preview a planned profile based on an executed roast
+         * @description Preview a constrained planned profile built on the Artisan file one of the caller's executed roasts was imported from. Read-only: nothing is saved and the roast is not modified. Returns the same measured preview as a saved reference, plus the reference identity a later save would use. Roasts without a usable Artisan file on record return 400 `roast_artisan_source_unavailable` with a `reason`. Requires Mallard Studio, and for API keys the exact roast:read scope.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["ReferenceProfileRoastGenerationRequest"];
+                };
+            };
+            responses: {
+                /** @description Deterministic preview without persistence */
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileRoastGenerationPreviewResponse"];
+                    };
+                };
+                /** @description Invalid request, or the roast has no usable Artisan file on record */
+                400: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
+                    };
+                };
                 /** @description Authentication required */
                 401: {
                     headers: {
@@ -4128,6 +4349,7 @@ interface paths {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -4251,6 +4473,7 @@ interface paths {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -4377,6 +4600,7 @@ interface paths {
         get: {
             parameters: {
                 query?: {
+                    include?: "grading";
                     stocked?: "true" | "false" | "all";
                     showWholesale?: "true" | "false";
                     wholesaleOnly?: "true" | "false";
@@ -4409,6 +4633,7 @@ interface paths {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -6003,7 +6228,7 @@ interface paths {
         };
         /**
          * Find catalog coffees similar to a target coffee
-         * @description Vector-similarity matches between public supplier catalog coffees, with deterministic identity gating, supplier-diversity re-ranking, and a canonical/similar split. User-owned coffees are excluded. Available to member sessions and customer API keys; API keys also require catalog:read. Green responses return at most 25 matches.
+         * @description Vector-similarity matches between public supplier catalog coffees, with deterministic identity gating, supplier-diversity re-ranking, and a canonical/similar split. User-owned coffees are excluded. Available to member sessions, or any customer API key with catalog:read (all API plans, within plan quota). Responses return at most 25 matches.
          */
         get: {
             parameters: {
@@ -7130,7 +7355,7 @@ interface paths {
         put?: never;
         /**
          * Execute a user-confirmed product action
-         * @description Execute one of the closed product actions for the authenticated session owner. The stable executionId provides payload-bound replay, and owner plus entitlement checks run again inside the same database transaction as the mutation. Generated reference saves require explicit user confirmation and remain planned profiles. API keys are not accepted.
+         * @description Execute one of the closed product actions for the authenticated session owner. The stable executionId provides payload-bound replay, and owner plus entitlement checks run again inside the same database transaction as the mutation. Generated reference saves require explicit user confirmation and remain planned profiles; one based on an executed roast also saves that roast's stored Artisan file as its parent reference and never modifies the roast. API keys are not accepted.
          */
         post: {
             parameters: {
@@ -7160,7 +7385,7 @@ interface paths {
                         "application/json": components["schemas"]["ConfirmedActionExecuteResponse"];
                     };
                 };
-                /** @description Invalid or unsupported confirmed-action payload */
+                /** @description Invalid or unsupported confirmed-action payload, or a roast-based plan whose roast has no usable Artisan file on record */
                 400: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
@@ -7172,7 +7397,7 @@ interface paths {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -10242,7 +10467,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/roasts/{id}/artisan-import": {
+    "/v1/roasts/imports/from-reference": {
         parameters: {
             query?: never;
             header?: never;
@@ -10250,29 +10475,28 @@ interface paths {
             cookie?: never;
         };
         get?: never;
+        put?: never;
         /**
-         * Replace a roast's Artisan import
-         * @description Re-derive one of the caller's existing roasts from an Artisan `.alog` file: replace its temperature curve, event markers, milestones, chart bounds, and computed metrics, and write an artisan_import_log entry atomically. The roast's identity (coffee, batch name, roast date, weights, and user notes) is preserved. Optional `If-Match: <last_updated>` enables optimistic concurrency (409 on mismatch). Requires an authenticated session, or an owner-bound API key carrying the exact roast:write scope.
+         * Create a roast from a saved Artisan reference
+         * @description Create a roast profile owned by the caller from the Artisan file stored with one of their uploaded reference profiles, against one of their green-coffee lots. The curve, events, and import log are written atomically, exactly as a direct Artisan import. Only uploaded Artisan references qualify: a planned (generated) profile is never recorded as a roast, and a reference saved from an existing roast is refused because that roast is already in history. Requires Mallard Studio, and for API keys the exact roast:read and roast:write scopes.
          */
-        put: {
+        post: {
             parameters: {
                 query?: never;
                 header?: {
-                    "if-match"?: string;
-                };
-                path: {
-                    id: number;
+                    "idempotency-key"?: string;
                 };
+                path?: never;
                 cookie?: never;
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["RoastArtisanImportReplaceRequest"];
+                    "application/json": components["schemas"]["RoastImportFromReferenceRequest"];
                 };
             };
             responses: {
-                /** @description The updated roast profile plus import summary */
-                200: {
+                /** @description The created roast profile plus import summary */
+                201: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
                         "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
@@ -10283,7 +10507,7 @@ interface paths {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["RoastImportResponse"];
+                        "application/json": components["schemas"]["RoastImportFromReferenceResponse"];
                     };
                 };
                 /** @description Invalid query parameter */
@@ -10331,7 +10555,7 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description No such roast profile owned by the caller */
+                /** @description No such coffee lot owned by the caller */
                 404: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
@@ -10395,22 +10619,181 @@ interface paths {
                 };
             };
         };
-        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/roasts/{id}/artisan-import": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
         /**
-         * Clear a roast's Artisan import
-         * @description Remove import-derived temperature samples, event markers, and artisan_import_log rows from one of the caller's existing roasts without deleting the roast profile. Import-derived profile metrics are reset to manual/null values. Requires an authenticated session, or an owner-bound API key carrying the exact roast:write scope.
+         * Replace a roast's Artisan import
+         * @description Re-derive one of the caller's existing roasts from an Artisan `.alog` file: replace its temperature curve, event markers, milestones, chart bounds, and computed metrics, and write an artisan_import_log entry atomically. The roast's identity (coffee, batch name, roast date, weights, and user notes) is preserved. Optional `If-Match: <last_updated>` enables optimistic concurrency (409 on mismatch). Requires an authenticated session, or an owner-bound API key carrying the exact roast:write scope.
          */
-        delete: {
+        put: {
             parameters: {
                 query?: never;
-                header?: never;
+                header?: {
+                    "if-match"?: string;
+                };
                 path: {
                     id: number;
                 };
                 cookie?: never;
             };
-            requestBody?: never;
-            responses: {
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["RoastArtisanImportReplaceRequest"];
+                };
+            };
+            responses: {
+                /** @description The updated roast profile plus import summary */
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RoastImportResponse"];
+                    };
+                };
+                /** @description Invalid query parameter */
+                400: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description No such roast profile owned by the caller */
+                404: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Write conflict: an If-Match precondition failed */
+                409: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Per-user mutation throttle exceeded; retry after a short wait Customer API keys may also receive an account monthly or machine burst quota rejection. */
+                429: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        "Retry-After": components["headers"]["Retry-After"];
+                        "X-RateLimit-Blocked-By": components["headers"]["X-RateLimit-Blocked-By"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Roast writes are not enabled in this environment */
+                503: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        post?: never;
+        /**
+         * Clear a roast's Artisan import
+         * @description Remove import-derived temperature samples, event markers, and artisan_import_log rows from one of the caller's existing roasts without deleting the roast profile. Import-derived profile metrics are reset to manual/null values. Requires an authenticated session, or an owner-bound API key carrying the exact roast:write scope.
+         */
+        delete: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: number;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
                 /** @description The cleared roast id plus deleted row counts */
                 200: {
                     headers: {
@@ -13794,7 +14177,13 @@ interface components {
             updatedAt: string;
         };
         ReferenceProfileListResponse: {
-            data: components["schemas"]["ReferenceProfileSummary"][];
+            data: (components["schemas"]["ReferenceProfileSummary"] & {
+                /** @description The executed roast the current revision was saved from, or null for an uploaded or planned profile. */
+                sourceRoast: {
+                    id: number;
+                    revision: string;
+                } | null;
+            })[];
             meta: {
                 /** @enum {string} */
                 resource: "reference-profiles";
@@ -13996,110 +14385,248 @@ interface components {
             fileContent: string;
             fileSize?: number;
         };
+        RoastSourceErrorResponse: {
+            error: {
+                code: string;
+                message: string;
+                /**
+                 * @description Present when code is `roast_artisan_source_unavailable`. `no_artisan_import`: the roast was entered manually or logged live. `artisan_file_not_retained`: it was imported before Artisan files were kept. `artisan_file_too_large`: its file is larger than a reference profile can hold.
+                 * @enum {string}
+                 */
+                reason?: "no_artisan_import" | "artisan_file_not_retained" | "artisan_file_too_large";
+            };
+        };
         ReferenceProfileFromRoastRequest: {
             roastId: number;
+            /** @description The roast's current revision token (its last_updated value). */
             roastRevision: string;
+            /**
+             * @description chart_snapshot keeps a comparison-only chart. artisan_source copies the roast's stored Artisan file so a planned profile can be built from it.
+             * @default chart_snapshot
+             * @enum {string}
+             */
+            basis: "chart_snapshot" | "artisan_source";
             title?: string;
             notes?: string;
         };
-        ProfileComparisonResponse: {
+        ReferenceProfileRoastCandidatesResponse: {
             data: {
-                /** @enum {string} */
-                alignment: "charge";
-                /** @enum {string} */
-                targetUnit: "F" | "C";
-                left: {
-                    type: string;
-                    id: string;
-                    revision: string;
-                };
-                right: {
-                    type: string;
-                    id: string;
-                    revision: string;
-                };
-                series: {
-                    id: string;
-                    name: string;
-                    /** @enum {string} */
-                    kind: "bean_temperature" | "environmental_temperature" | "auxiliary";
-                    unit: string;
-                    points: {
-                        timeMilliseconds: number;
-                        left: number;
-                        right: number;
-                        delta: number;
-                    }[];
-                }[];
-                milestones: {
-                    name: string;
-                    leftMilliseconds: number;
-                    rightMilliseconds: number;
-                    deltaMilliseconds: number;
+                roasts: {
+                    roastId: number;
+                    roastRevision: string;
+                    label: string;
+                    batchName: string | null;
+                    coffeeName: string | null;
+                    roastDate: string | null;
+                    reference: {
+                        /** Format: uuid */
+                        profileId: string;
+                        /** Format: uuid */
+                        revisionId: string;
+                        saved: boolean;
+                    };
                 }[];
+                eligibleCount: number;
+                totalRoastCount: number;
+                ineligibleRoastCount: number;
             };
             meta: {
                 /** @enum {string} */
-                resource: "profile-comparisons";
+                resource: "reference-profile-roast-candidates";
                 /** @enum {string} */
-                namespace: "/v1/profile-comparisons";
+                namespace: "/v1/reference-profiles";
                 /** @enum {string} */
                 version: "v1";
             };
         };
-        ProfileComparisonRequest: {
-            left: {
-                /** @enum {string} */
-                type: "reference_revision";
-                /** Format: uuid */
-                revisionId: string;
-            } | {
-                /** @enum {string} */
-                type: "executed_roast";
-                roastId: number;
-                roastRevision: string;
-            };
-            right: {
-                /** @enum {string} */
-                type: "reference_revision";
+        ReferenceProfileRoastGenerationPreviewResponse: {
+            data: {
                 /** Format: uuid */
-                revisionId: string;
-            } | {
-                /** @enum {string} */
-                type: "executed_roast";
-                roastId: number;
-                roastRevision: string;
-            };
-            /**
-             * @default charge
-             * @enum {string}
-             */
-            alignment: "charge";
-            /** @enum {string} */
-            targetUnit: "F" | "C";
-            /** @default 400 */
-            targetPoints: number;
-        };
-        AccountDeletionOperation: {
-            /** Format: uuid */
-            operationId: string;
-            /** @enum {string} */
-            status: "accepted" | "provider_deleting" | "local_cleaning" | "auth_deleting" | "post_auth_cleanup" | "retryable" | "conflict" | "completed";
-        };
-        BillingCheckoutSession: {
-            /** Format: uuid */
-            admissionId: string;
-            /** @enum {string} */
-            status: "accepted" | "attempting" | "published" | "settled" | "closed" | "conflict";
-            clientSecret: string | null;
-        };
-        MarketBriefDraftState: {
-            /** Format: uuid */
-            draftId: string;
-            edition: number;
-            productionCommit: string;
-            /** @enum {string} */
-            status: "creating" | "uncertain" | "created" | "conflict";
+                parentRevisionId: string;
+                title: string;
+                userGoal: string | null;
+                modelRecommendation: string | null;
+                userEdits: string | null;
+                changes: {
+                    temperatureAdjustments: {
+                        /** @enum {string} */
+                        kind: "bean_temperature" | "environmental_temperature";
+                        startMilliseconds: number;
+                        endMilliseconds: number;
+                        delta: number;
+                    }[];
+                };
+                measuredFacts: {
+                    /** @enum {string} */
+                    temperatureUnit: "F" | "C";
+                    adjustments: {
+                        /** @enum {string} */
+                        kind: "bean_temperature" | "environmental_temperature";
+                        startMilliseconds: number;
+                        endMilliseconds: number;
+                        requestedDelta: number;
+                        /** @enum {string} */
+                        unit: "F" | "C";
+                        changedSampleCount: number;
+                        unchangedZeroSampleCount: number;
+                        parent: {
+                            first: {
+                                timeMilliseconds: number;
+                                value: number;
+                            } | null;
+                            last: {
+                                timeMilliseconds: number;
+                                value: number;
+                            } | null;
+                            minimum: number | null;
+                            maximum: number | null;
+                        };
+                        planned: {
+                            first: {
+                                timeMilliseconds: number;
+                                value: number;
+                            } | null;
+                            last: {
+                                timeMilliseconds: number;
+                                value: number;
+                            } | null;
+                            minimum: number | null;
+                            maximum: number | null;
+                        };
+                    }[];
+                    /** @enum {boolean} */
+                    eventsUnchanged: true;
+                };
+                chart: components["schemas"]["ReferenceProfileChart"];
+                /** @enum {boolean} */
+                exportEligible: true;
+                /**
+                 * Format: uuid
+                 * @description The reference this roast's Artisan file is, or will be, saved under.
+                 */
+                parentProfileId: string;
+                /** @description Whether that reference already exists. A preview never creates it. */
+                parentSaved: boolean;
+                sourceRoast: {
+                    id: number;
+                    revision: string;
+                    label: string;
+                    batchName: string | null;
+                    coffeeName: string | null;
+                    roastDate: string | null;
+                };
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "reference-profile-previews";
+                /** @enum {string} */
+                namespace: "/v1/reference-profiles";
+                /** @enum {string} */
+                version: "v1";
+            };
+        };
+        ReferenceProfileRoastGenerationRequest: components["schemas"]["ReferenceProfileGenerationRequest"] & {
+            roastId: number;
+            roastRevision: string;
+        };
+        ProfileComparisonResponse: {
+            data: {
+                /** @enum {string} */
+                alignment: "charge";
+                /** @enum {string} */
+                targetUnit: "F" | "C";
+                left: {
+                    type: string;
+                    id: string;
+                    revision: string;
+                };
+                right: {
+                    type: string;
+                    id: string;
+                    revision: string;
+                };
+                series: {
+                    id: string;
+                    name: string;
+                    /** @enum {string} */
+                    kind: "bean_temperature" | "environmental_temperature" | "auxiliary";
+                    unit: string;
+                    points: {
+                        timeMilliseconds: number;
+                        left: number;
+                        right: number;
+                        delta: number;
+                    }[];
+                }[];
+                milestones: {
+                    name: string;
+                    leftMilliseconds: number;
+                    rightMilliseconds: number;
+                    deltaMilliseconds: number;
+                }[];
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "profile-comparisons";
+                /** @enum {string} */
+                namespace: "/v1/profile-comparisons";
+                /** @enum {string} */
+                version: "v1";
+            };
+        };
+        ProfileComparisonRequest: {
+            left: {
+                /** @enum {string} */
+                type: "reference_revision";
+                /** Format: uuid */
+                revisionId: string;
+            } | {
+                /** @enum {string} */
+                type: "executed_roast";
+                roastId: number;
+                roastRevision: string;
+            };
+            right: {
+                /** @enum {string} */
+                type: "reference_revision";
+                /** Format: uuid */
+                revisionId: string;
+            } | {
+                /** @enum {string} */
+                type: "executed_roast";
+                roastId: number;
+                roastRevision: string;
+            };
+            /**
+             * @default charge
+             * @enum {string}
+             */
+            alignment: "charge";
+            /** @enum {string} */
+            targetUnit: "F" | "C";
+            /** @default 400 */
+            targetPoints: number;
+        };
+        AccountDeletionOperation: {
+            /** Format: uuid */
+            operationId: string;
+            /** @enum {string} */
+            status: "accepted" | "provider_deleting" | "local_cleaning" | "auth_deleting" | "post_auth_cleanup" | "retryable" | "conflict" | "completed";
+        };
+        BillingCheckoutSession: {
+            /** Format: uuid */
+            admissionId: string;
+            /** @enum {string} */
+            status: "accepted" | "attempting" | "published" | "settled" | "closed" | "conflict";
+            clientSecret: string | null;
+        };
+        MarketBriefDraftState: {
+            /** Format: uuid */
+            draftId: string;
+            edition: number;
+            productionCommit: string;
+            /** @enum {string} */
+            status: "creating" | "uncertain" | "created" | "conflict";
         };
         MarketBriefDraftResponse: {
             data: components["schemas"]["MarketBriefDraftState"];
@@ -14690,6 +15217,13 @@ interface components {
                 fermentation_type?: string[];
                 process_additives?: string[];
                 processing_disclosure_level?: string[];
+                grade_size?: string[];
+                grade_altitude?: string[];
+                grade_defects?: string[];
+                grade_cup?: string[];
+                grade_preparation?: string[];
+                screen_size_min?: string[];
+                elevation_band?: string[];
             };
             /** @description Counted facet values for CLI/agent use. Counts are computed after visibility and entitled query filters are applied. */
             facets: {
@@ -14757,6 +15291,34 @@ interface components {
                     value: string;
                     count: number;
                 }[];
+                grade_size?: {
+                    value: string;
+                    count: number;
+                }[];
+                grade_altitude?: {
+                    value: string;
+                    count: number;
+                }[];
+                grade_defects?: {
+                    value: string;
+                    count: number;
+                }[];
+                grade_cup?: {
+                    value: string;
+                    count: number;
+                }[];
+                grade_preparation?: {
+                    value: string;
+                    count: number;
+                }[];
+                screen_size_min?: {
+                    value: string;
+                    count: number;
+                }[];
+                elevation_band?: {
+                    value: string;
+                    count: number;
+                }[];
             };
             meta: {
                 /** @enum {string} */
@@ -16516,6 +17078,8 @@ interface components {
                     }[];
                 };
                 change_set_summary: string;
+                source_roast_id?: number | string;
+                source_roast_revision?: string;
             };
         } | {
             /** @description Stable operation id. Repeating it with the same action payload replays the stored result; changing the payload returns 409. */
@@ -17354,6 +17918,61 @@ interface components {
             /** @description Reported source size in bytes for import-log metadata; defaults to the content length. */
             fileSize?: number;
         };
+        RoastImportFromReferenceResponse: {
+            data: {
+                roast: components["schemas"]["RoastDetailResource"];
+                import: components["schemas"]["ArtisanImportSummary"];
+                reference: {
+                    /** Format: uuid */
+                    profileId: string;
+                    /** Format: uuid */
+                    revisionId: string;
+                    /** @description Whether the reference now lists the new roast as a linked roast. */
+                    linked: boolean;
+                };
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "roasts";
+                /** @enum {string} */
+                namespace: "/v1/roasts";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "session" | "api-key";
+                    /** @enum {string|null} */
+                    role: "admin" | "member" | "viewer" | null;
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                };
+            };
+        };
+        RoastImportFromReferenceRequest: {
+            /**
+             * Format: uuid
+             * @description A saved Artisan reference profile owned by the caller.
+             */
+            referenceProfileId: string;
+            /**
+             * Format: uuid
+             * @description That reference's current revision.
+             */
+            referenceRevisionId: string;
+            /** @description green_coffee_inv.id owned by the caller to roast against. */
+            coffeeId: number;
+            /** @description Batch name; defaults to '<coffee> - <roast date>'. */
+            batchName?: string;
+            /** @description Roast date (YYYY-MM-DD); defaults to the file's date. */
+            roastDate?: string;
+            /** @description Input weight in oz; defaults to the file's weight if present. */
+            ozIn?: number;
+            /** @description Output weight in oz; defaults to the file's weight if present. */
+            ozOut?: number;
+            /** @description Roast notes; overrides the generated import summary note. */
+            roastNotes?: string;
+            roastTargets?: string;
+        };
         RoastArtisanImportReplaceRequest: {
             /** @description Source file name. Must end in .alog, .alog.json, or .json (Artisan export). */
             fileName: string;
@@ -18263,6 +18882,10 @@ type RoastChartSeries = components["schemas"]["RoastChartSeries"];
 type RoastChartEvent = components["schemas"]["RoastChartEvent"];
 type ReferenceProfileImportRequest = NonNullable<paths["/v1/reference-profiles/imports"]["post"]["requestBody"]>["content"]["application/json"];
 type ReferenceProfileFromRoastRequest = NonNullable<paths["/v1/reference-profiles/from-roast"]["post"]["requestBody"]>["content"]["application/json"];
+/** Request body for {@link ParchmentClient.referenceProfiles.previewFromRoast}. */
+type ReferenceProfileRoastGenerationRequest = NonNullable<paths["/v1/reference-profiles/from-roast/preview"]["post"]["requestBody"]>["content"]["application/json"];
+/** Query parameters for {@link ParchmentClient.referenceProfiles.roastCandidates}. */
+type ReferenceProfileRoastCandidatesQuery = NonNullable<paths["/v1/reference-profiles/from-roast/candidates"]["get"]["parameters"]["query"]>;
 type ReferenceProfileUpdateRequest = NonNullable<paths["/v1/reference-profiles/{id}"]["patch"]["requestBody"]>["content"]["application/json"];
 type ReferenceProfileGenerationRequest = NonNullable<paths["/v1/reference-profiles/{id}/revisions/{revisionId}/preview"]["post"]["requestBody"]>["content"]["application/json"];
 type ProfileComparisonRequest = NonNullable<paths["/v1/profile-comparisons"]["post"]["requestBody"]>["content"]["application/json"];
@@ -18278,6 +18901,8 @@ type RoastUpdateRequest = NonNullable<paths["/v1/roasts/{id}"]["patch"]["request
 type RoastLiveCurveRequest = NonNullable<paths["/v1/roasts/{id}/live-curve"]["put"]["requestBody"]>["content"]["application/json"];
 /** Request body for {@link ParchmentClient.roasts.import}. */
 type RoastImportRequest = NonNullable<paths["/v1/roasts/imports"]["post"]["requestBody"]>["content"]["application/json"];
+/** Request body for {@link ParchmentClient.roasts.importFromReference}. */
+type RoastImportFromReferenceRequest = NonNullable<paths["/v1/roasts/imports/from-reference"]["post"]["requestBody"]>["content"]["application/json"];
 /** Request body for {@link ParchmentClient.roasts.replaceArtisanImport}. */
 type RoastArtisanImportReplaceRequest = NonNullable<paths["/v1/roasts/{id}/artisan-import"]["put"]["requestBody"]>["content"]["application/json"];
 /** Query parameters for {@link ParchmentClient.sales.list}. */
@@ -20780,6 +21405,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -20886,6 +21512,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -20940,6 +21567,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -21073,6 +21701,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -21103,6 +21732,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
         facets: (query?: CatalogFacetsQuery, headers?: CatalogFacetsHeaders) => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: {
+                    include?: "grading";
                     stocked?: "true" | "false" | "all";
                     showWholesale?: "true" | "false";
                     wholesaleOnly?: "true" | "false";
@@ -21135,6 +21765,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -21203,6 +21834,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
         }, {
             params: {
                 query: {
+                    include?: "grading";
                     stocked?: "true" | "false" | "all";
                     showWholesale?: "true" | "false";
                     wholesaleOnly?: "true" | "false";
@@ -21235,6 +21867,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     screenMax?: number | null;
                     includeUnknownScreen?: "true" | "false";
                     gradeCode?: string | string[];
+                    gradeDimension?: "size" | "altitude" | "defects" | "cup" | "preparation";
                     peaberry?: "true" | "false";
                     labAnalyzed?: "true" | "false";
                     moistureMax?: number | null;
@@ -23874,7 +24507,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
                     };
                 };
                 401: {
@@ -24043,6 +24676,8 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         }[];
                     };
                     change_set_summary: string;
+                    source_roast_id?: number | string;
+                    source_roast_revision?: string;
                 };
             } | {
                 executionId: string;
@@ -29284,31 +29919,190 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
             } | undefined;
         }, `${string}/${string}`>>;
         /**
-         * Replace the Artisan import data on one of the caller's existing roasts,
-         * re-deriving its curve, events, and computed metrics while preserving the
-         * roast's identity. Pass `ifMatch` (the roast's `last_updated`) to enable
-         * optimistic concurrency (409 on mismatch).
+         * Create a roast profile from the Artisan file stored with one of the
+         * caller's uploaded reference profiles. Only uploaded Artisan references
+         * qualify: planned (generated) profiles are never recorded as roasts,
+         * and a reference saved from an existing roast is refused. Requires
+         * Mallard Studio plus a session, or an owner-bound API key carrying the
+         * exact `roast:read` and `roast:write` scopes. The optional
+         * `idempotencyKey` is payload-bound.
          */
-        replaceArtisanImport: (id: number, body: RoastArtisanImportReplaceRequest, options?: {
-            ifMatch?: string;
+        importFromReference: (body: RoastImportFromReferenceRequest, options?: {
+            idempotencyKey?: string;
         }) => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: never;
                 header?: {
-                    "if-match"?: string;
-                };
-                path: {
-                    id: number;
+                    "idempotency-key"?: string;
                 };
+                path?: never;
                 cookie?: never;
             };
             requestBody: {
                 content: {
-                    "application/json": components["schemas"]["RoastArtisanImportReplaceRequest"];
+                    "application/json": components["schemas"]["RoastImportFromReferenceRequest"];
                 };
             };
             responses: {
-                200: {
+                201: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RoastImportFromReferenceResponse"];
+                    };
+                };
+                400: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                404: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                409: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                429: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        "Retry-After": components["headers"]["Retry-After"];
+                        "X-RateLimit-Blocked-By": components["headers"]["X-RateLimit-Blocked-By"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                503: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        }, {
+            body: {
+                referenceProfileId: string;
+                referenceRevisionId: string;
+                coffeeId: number;
+                batchName?: string;
+                roastDate?: string;
+                ozIn?: number;
+                ozOut?: number;
+                roastNotes?: string;
+                roastTargets?: string;
+            };
+            params: {
+                header: {
+                    "idempotency-key": string;
+                };
+            } | undefined;
+        }, `${string}/${string}`>>;
+        /**
+         * Replace the Artisan import data on one of the caller's existing roasts,
+         * re-deriving its curve, events, and computed metrics while preserving the
+         * roast's identity. Pass `ifMatch` (the roast's `last_updated`) to enable
+         * optimistic concurrency (409 on mismatch).
+         */
+        replaceArtisanImport: (id: number, body: RoastArtisanImportReplaceRequest, options?: {
+            ifMatch?: string;
+        }) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: {
+                    "if-match"?: string;
+                };
+                path: {
+                    id: number;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["RoastArtisanImportReplaceRequest"];
+                };
+            };
+            responses: {
+                200: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
                         "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
@@ -29803,7 +30597,9 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                 409: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
-                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Remaining": 
+                        /** Available exact 30-day comparisons, with no empty-origin search. */
+                        components["headers"]["X-RateLimit-Remaining"];
                         "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
                         "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
                         "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
@@ -29833,7 +30629,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     id: string;
                     revisionId: string;
                 };
-                cookie?: never;
+                cookie? /** Metadata-trend index (process/disclosure/Purveyor Score over time). */: never;
             };
             requestBody: {
                 content: {
@@ -30303,6 +31099,13 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                 };
             };
         }, `${string}/${string}`>>;
+        /**
+         * Save an executed roast as a reference. `basis: "artisan_source"`
+         * copies the roast's stored Artisan file so a planned profile can be
+         * built from it, and returns the reference already saved from that
+         * roast's file instead of a duplicate; the default
+         * `"chart_snapshot"` keeps a comparison-only chart.
+         */
         fromRoast: (body: ReferenceProfileFromRoastRequest, idempotencyKey: string) => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: never;
@@ -30318,6 +31121,20 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                 };
             };
             responses: {
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileResponse"];
+                    };
+                };
                 201: {
                     headers: {
                         "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
@@ -30343,7 +31160,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
                     };
                 };
                 401: {
@@ -30408,6 +31225,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
             body: {
                 roastId: number;
                 roastRevision: string;
+                basis: "chart_snapshot" | "artisan_source";
                 title?: string;
                 notes?: string;
             };
@@ -30417,6 +31235,195 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                 };
             };
         }, `${string}/${string}`>>;
+        /**
+         * List the caller's executed roasts whose Artisan file is on record and
+         * can therefore be the base for a planned profile, newest first.
+         */
+        roastCandidates: (query?: ReferenceProfileRoastCandidatesQuery) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: {
+                    limit?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileRoastCandidatesResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                429: components["responses"]["ApiRateLimitExceeded"];
+            };
+        }, {
+            params: {
+                query: {
+                    limit?: number;
+                } | undefined;
+            };
+        }, `${string}/${string}`>>;
+        /**
+         * Preview a planned profile built directly on an executed roast's stored
+         * Artisan file. Read-only: nothing is saved and the roast is unchanged.
+         */
+        previewFromRoast: (body: ReferenceProfileRoastGenerationRequest) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["ReferenceProfileRoastGenerationRequest"];
+                };
+            };
+            responses: {
+                200: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ReferenceProfileRoastGenerationPreviewResponse"];
+                    };
+                };
+                400: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RoastSourceErrorResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                404: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                409: {
+                    headers: {
+                        "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                        "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                        "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                        "X-RateLimit-Burst-Limit": components["headers"]["X-RateLimit-Burst-Limit"];
+                        "X-RateLimit-Burst-Remaining": components["headers"]["X-RateLimit-Burst-Remaining"];
+                        "X-RateLimit-Burst-Reset": components["headers"]["X-RateLimit-Burst-Reset"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                429: components["responses"]["ApiRateLimitExceeded"];
+            };
+        }, {
+            body: {
+                title: string;
+                notes?: string;
+                userGoal?: string;
+                modelRecommendation?: string;
+                userEdits?: string;
+                changes: {
+                    temperatureAdjustments: {
+                        kind: "bean_temperature" | "environmental_temperature";
+                        startMilliseconds: number;
+                        endMilliseconds: number;
+                        delta: number;
+                    }[];
+                };
+            } & {
+                roastId: number;
+                roastRevision: string;
+            };
+        }, `${string}/${string}`>>;
         update: (id: string, body: ReferenceProfileUpdateRequest) => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: never;
@@ -30582,9 +31589,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": 
-                        /** Request body for {@link ParchmentClient.apiKeys.create}. */
-                        components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 403: {
@@ -31788,7 +32793,7 @@ type ParchmentClientMethod = MethodPaths<Omit<ParchmentClient, "raw">>;
  * SDK (such as the CLI) can import this list to prove they cover everything
  * the web agent can do.
  */
-declare const CHAT_AGENT_CAPABILITIES: readonly ["me", "catalog.list", "catalog.facets", "catalog.rank", "catalog.suppliers", "catalog.similar", "catalog.compare", "catalog.grades", "catalog.priceHistory", "inventory.list", "roasts.list", "roasts.get", "roasts.chartData", "referenceProfiles.list", "referenceProfiles.get", "referenceProfiles.chart", "referenceProfiles.compare", "referenceProfiles.preview", "tasting.get", "priceIndex.list", "priceIndex.stats", "priceIndex.comparisons", "priceIndex.comparison", "priceIndex.history", "market.signals", "market.metadataIndex", "market.overview", "market.evidence"];
+declare const CHAT_AGENT_CAPABILITIES: readonly ["me", "catalog.list", "catalog.facets", "catalog.rank", "catalog.suppliers", "catalog.similar", "catalog.compare", "catalog.grades", "catalog.priceHistory", "inventory.list", "roasts.list", "roasts.get", "roasts.chartData", "referenceProfiles.list", "referenceProfiles.get", "referenceProfiles.chart", "referenceProfiles.compare", "referenceProfiles.preview", "referenceProfiles.roastCandidates", "referenceProfiles.previewFromRoast", "tasting.get", "priceIndex.list", "priceIndex.stats", "priceIndex.comparisons", "priceIndex.comparison", "priceIndex.history", "market.signals", "market.metadataIndex", "market.overview", "market.evidence"];
 type ChatAgentCapability = (typeof CHAT_AGENT_CAPABILITIES)[number];
 /**
  * Writes the web agent can propose. The agent never writes directly: it