@fias/arche-sdk 2.19.0 → 2.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/arche-sdk",
-  "version": "2.19.0",
+  "version": "2.19.1",
   "description": "SDK for building FIAS platform plugin arches",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.18.0 -->
+<!-- fias-sdk-guide-version: 2.19.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -545,11 +545,34 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended, ... }
+//                supportsReferenceImage, isPlatformRecommended,
+//                creditsPerImage, estimatedDurationMs, company, strengths,
+//                providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+
+**Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
+
+```tsx
+// param: { key, label, description, controlType, defaultValue,
+//          min?, max?, step?, options?, category? }
+// controlType: 'slider' | 'number' | 'select' | 'checkbox' | 'textarea'
+const seed = entity.providerParams?.find((p) => p.key === 'seed');
+await generate({ entityId, prompt, providerParams: { seed: 42 } });
+```
+
+**The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
+
+```tsx
+generate({ entityId, prompt, quality: 'high' }); // honoured
+generate({ entityId, prompt, providerParams: { gpt_quality: 'high' } }); // SILENTLY IGNORED
+```
+
+Its `options` are still how you build the control — only the destination differs.
+
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.18.0 -->
+<!-- fias-sdk-guide-version: 2.19.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -545,11 +545,34 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended, ... }
+//                supportsReferenceImage, isPlatformRecommended,
+//                creditsPerImage, estimatedDurationMs, company, strengths,
+//                providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+
+**Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
+
+```tsx
+// param: { key, label, description, controlType, defaultValue,
+//          min?, max?, step?, options?, category? }
+// controlType: 'slider' | 'number' | 'select' | 'checkbox' | 'textarea'
+const seed = entity.providerParams?.find((p) => p.key === 'seed');
+await generate({ entityId, prompt, providerParams: { seed: 42 } });
+```
+
+**The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
+
+```tsx
+generate({ entityId, prompt, quality: 'high' }); // honoured
+generate({ entityId, prompt, providerParams: { gpt_quality: 'high' } }); // SILENTLY IGNORED
+```
+
+Its `options` are still how you build the control — only the destination differs.
+
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`