@fias/create-fias-plugin 1.10.1 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "publishConfig": {
     "access": "public"
   },

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`
@@ -665,7 +688,7 @@ await invoke({ query: 'latest EU AI Act enforcement dates' });
 
 ### `useVaultDocuments()` — User-owned Vault documents
 
-**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
+**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / saveContent / update / delete / attach / detach / upload)
 **Returns:** `VaultDocumentsApi`
 
 The Vault is the platform's persistent document store for the signed-in user. Distinct from `useFiasStorage` (per-plugin sandbox): Vault docs live in the user's My Data, survive plugin uninstall, and can be cross-referenced from other arches. Documents this arche creates are scoped to it (`source_arche_id`) and surfaced to the user under `/My-Fias/Arches/<archeId>/`.
@@ -709,6 +732,15 @@ const result = await vault.upload(bytes, {
 // but still appears in list() — don't assume every listed doc has bytes.
 const { bytes: saved } = await vault.readBytes(documentId);
 
+// Overwrite a document THIS arche created IN PLACE — same documentId, bytes
+// replaced, no version history. The autosave path (a spreadsheet saving as
+// the user works); to publish a distinct new version use write({
+// replacesDocumentId }) instead. UTF-8 text, ≤ 200 KB (OWN_DOCUMENT_SAVE_TOO_LARGE
+// names the cap). Debounce: a few seconds of idle plus blur/close — never per
+// keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
+// drops the document's search index and does not re-run extraction.
+await vault.saveContent({ documentId, content: JSON.stringify(sheet) });
+
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
 const { matches } = await vault.search('quarterly revenue', { topK: 5 });

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`
@@ -665,7 +688,7 @@ await invoke({ query: 'latest EU AI Act enforcement dates' });
 
 ### `useVaultDocuments()` — User-owned Vault documents
 
-**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
+**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / saveContent / update / delete / attach / detach / upload)
 **Returns:** `VaultDocumentsApi`
 
 The Vault is the platform's persistent document store for the signed-in user. Distinct from `useFiasStorage` (per-plugin sandbox): Vault docs live in the user's My Data, survive plugin uninstall, and can be cross-referenced from other arches. Documents this arche creates are scoped to it (`source_arche_id`) and surfaced to the user under `/My-Fias/Arches/<archeId>/`.
@@ -709,6 +732,15 @@ const result = await vault.upload(bytes, {
 // but still appears in list() — don't assume every listed doc has bytes.
 const { bytes: saved } = await vault.readBytes(documentId);
 
+// Overwrite a document THIS arche created IN PLACE — same documentId, bytes
+// replaced, no version history. The autosave path (a spreadsheet saving as
+// the user works); to publish a distinct new version use write({
+// replacesDocumentId }) instead. UTF-8 text, ≤ 200 KB (OWN_DOCUMENT_SAVE_TOO_LARGE
+// names the cap). Debounce: a few seconds of idle plus blur/close — never per
+// keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
+// drops the document's search index and does not re-run extraction.
+await vault.saveContent({ documentId, content: JSON.stringify(sheet) });
+
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
 const { matches } = await vault.search('quarterly revenue', { topK: 5 });