@fias/create-fias-plugin 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "publishConfig": {
     "access": "public"
   },
@@ -8,6 +8,9 @@
   "bin": {
     "create-fias-plugin": "index.js"
   },
+  "scripts": {
+    "prepublishOnly": "node ../../scripts/check-plugin-sdk-docs-mirror.js"
+  },
   "files": [
     "index.js",
     "templates"

package/templates/default/AGENTS.md

@@ -2,8 +2,6 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `CLAUDE.md` (identical content).
-
 ## Project Structure
 
 ```
@@ -183,13 +181,17 @@ function AISummarizer() {
     });
   }
 
+  // `streamingText` accumulates tokens during the call AND continues to hold
+  // the full text after the call resolves — it is NOT cleared. `result.output`
+  // also contains the full text once `invoke()` resolves. Render ONE slot only
+  // — `streamingText` while loading, `result.output` afterwards — or the
+  // response appears twice.
   return (
     <div>
       <button onClick={() => summarize('...')} disabled={isLoading}>
         Summarize
       </button>
-      {isLoading && <p>{streamingText}</p>}
-      {result && <p>{result.output}</p>}
+      <p>{isLoading ? streamingText : result?.output}</p>
       {error && <p>Error: {error.message}</p>}
     </div>
   );
@@ -203,7 +205,43 @@ The `entityId` references a published model entity. Browse available models with
 **Permission:** `entities:image_generate`
 **Returns:** `ImageGenerationApi`
 
-Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned. Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned.
+
+#### Choosing an image model
+
+The `entityId` parameter accepts three forms. **Prefer the selector forms** (`platformRecommended` / `providerRecommended`) over hardcoded entity IDs: the platform's recommendations evolve, models get retired, and a selector lets your plugin pick up the current best automatically without a code edit. Hardcoded IDs are still supported for back-compat and for cases where you want a specific model — but if the platform retires that exact entity, your plugin breaks unless the platform has registered a successor.
+
+```tsx
+// 1. Platform's blessed pick for a workflow + optional style (RECOMMENDED).
+//    Asking for `image-to-image` will never return a model that can't do it.
+generate({
+  entityId: { platformRecommended: { mode: 'text-to-image', style: 'illustration' } },
+  prompt: "A child's storybook page of a fox in the forest",
+});
+
+// 2. A specific provider's blessed pick. Use when your plugin's value prop
+//    depends on a particular provider's quirks.
+generate({
+  entityId: { providerRecommended: { provider: 'openai', mode: 'image-to-image' } },
+  prompt: 'Make it look like an oil painting',
+  referenceImage: { fileId: previousImage.fileId },
+});
+
+// 3. Explicit entityId — back-compat path. Use only when you want a specific
+//    model. If the entity has been deprecated, the response includes
+//    `deprecation: { requestedEntityId, resolvedEntityId, deprecatedAt }` and
+//    you get the successor.
+generate({
+  entityId: 'ent_modeldef_gpt_image_1_5',
+  prompt: 'A serene mountain landscape at sunset',
+});
+```
+
+Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
+
+Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+
+#### Full example
 
 ```tsx
 import { useImageGeneration } from '@fias/arche-sdk';
@@ -216,23 +254,237 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_dalle3',
+            entityId: { platformRecommended: { mode: 'text-to-image' } },
             prompt: 'A serene mountain landscape at sunset',
-            size: '1024x1024',
-            quality: 'hd',
+            size: '16:9',
+            quality: 'high',
           })
         }
         disabled={isLoading}
       >
         {isLoading ? 'Generating...' : 'Generate Image'}
       </button>
-      {result && <img src={result.imageUrl} alt="Generated" />}
+      {result && (
+        <>
+          <img src={result.imageUrl} alt="Generated" />
+          {result.deprecation && (
+            <p style={{ color: 'orange' }}>
+              Note: requested entity "{result.deprecation.requestedEntityId}" is deprecated;
+              auto-substituted "{result.deprecation.resolvedEntityId}". Update your code.
+            </p>
+          )}
+        </>
+      )}
       {error && <p>Error: {error.message}</p>}
     </div>
   );
 }
 ```
 
+### `useImageEntities()` — Discover image-generation entities
+
+**Permission:** `entities:image_generate`
+**Returns:** `{ entities, isLoading, error, refetch }`
+
+Use to render a "let the user pick a model" picker. For the common case of "just give me something good," skip discovery and pass a selector directly to `useImageGeneration`:
+
+```tsx
+await generate({
+  entityId: { platformRecommended: { mode: 'text-to-image' } },
+  prompt: '...',
+});
+```
+
+Discovery hook usage:
+
+```tsx
+import { useImageEntities } from '@fias/arche-sdk';
+
+const { entities, isLoading } = useImageEntities({
+  modes: ['image-to-image'],
+  supportsReferenceImage: true,
+});
+// entities[i]: { entityId, displayName, provider, modes, supportedSizes,
+//                supportsReferenceImage, isPlatformRecommended, ... }
+```
+
+Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
+
+### `useBackgroundRemoval()` — Client-side background removal
+
+**Permission:** `entities:image_remove_background`
+**Returns:** `BackgroundRemovalApi`
+
+Runs the imgly WASM model inside the host page — bytes never leave the user's device. Returns a transparent PNG.
+
+```tsx
+import { useBackgroundRemoval } from '@fias/arche-sdk';
+
+const { removeBackground, isLoading } = useBackgroundRemoval();
+const transparentPng = await removeBackground(jpegBlob);
+```
+
+**Limits:** input ≤ 25 MiB, PNG/JPEG only, rate-limited to 10/min per arche per user. Throws on size violation rather than returning a result.
+
+### Audio capability hooks (auto-generated)
+
+**Permission:** `entities:audio_generate`
+**Returns (per hook):** `{ invoke, isLoading, result, error }`
+
+Specialty capabilities expose **typed convenience hooks** generated from the platform's surface registry. Each hook bakes in a `surfaceKey` and infers params/result types from the surface's schemas.
+
+Currently shipped audio hooks: `useLyriaMusic`, `useElevenLabsTts`, `useElevenLabsMusic`, `useElevenLabsSfx`, `useElevenLabsStt`, `useElevenLabsAudioIsolation`, `useElevenLabsForcedAlignment`, `useElevenLabsVoiceChanger`, `useElevenLabsVoiceDesign`. Browse the full surface list with `npx fias-dev entities`.
+
+A legacy `useAudioGeneration()` hook still ships for back-compat with code written before the typed-surface migration. New plugins should use the typed hooks above — the legacy hook will be removed in a future major version.
+
+```tsx
+import { useElevenLabsTts } from '@fias/arche-sdk';
+
+const { invoke, isLoading, result } = useElevenLabsTts();
+await invoke({ text: 'Hello world', voiceId: '...' });
+// result: { audioUrl, audioRef, durationMinutes, costCredits, ... }
+```
+
+For surfaces without a typed wrapper yet, the generic substrate:
+
+```tsx
+import { useSurface } from '@fias/arche-sdk';
+
+const { invoke } = useSurface<MyParams, MyResult>('my.surface-key');
+```
+
+Default per-request timeout is 180 s (covers TTS for long text and Lyria multi-clip generation).
+
+### `useVaultDocuments()` — User-owned Vault documents
+
+**Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / 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>/`.
+
+**Most common use:** images returned from `useImageGeneration()` are auto-saved here. The result includes a `documentId` — pass it to `getDownloadUrl()` later to refresh the presigned URL after the original ~1h TTL expires.
+
+```tsx
+import { useVaultDocuments } from '@fias/arche-sdk';
+
+const vault = useVaultDocuments();
+
+// Refresh a presigned URL (cached client-side, auto-refreshed before expiry)
+const { url, expiresAt, contentType } = await vault.getDownloadUrl(documentId);
+
+// List documents this arche owns
+const { documents, nextCursor } = await vault.list({ search: 'invoice', limit: 50 });
+
+// Write a small text/JSON document (UTF-8, ≤ 1 MB)
+const { documentId } = await vault.write({
+  name: 'settings.json',
+  content: JSON.stringify(settings),
+  contentType: 'application/json',
+  tags: ['config'],
+});
+
+// Upload a binary or larger document — wraps the two-step presigned-PUT flow
+const result = await vault.upload(bytes, {
+  name: 'photo.jpg',
+  mimeType: 'image/jpeg',
+});
+// result.status transitions 'uploaded' → 'available' once indexed for search
+
+// 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 });
+
+// Update / delete
+await vault.update(documentId, { name: 'new-name.json', tags: ['archived'] });
+await vault.delete(documentId); // soft-delete, recoverable from My Data Trash
+```
+
+**Cross-arche attachment.** A document can be referenced from another arche's record (Business Contact, Company, Fias 360 Renewal in V-1). The reference points at the document but does NOT expose its contents to the target arche.
+
+```tsx
+const { referenceId } = await vault.attach(documentId, {
+  regardingType: 'vault_business_contact',
+  regardingId: contactId,
+});
+await vault.detach(documentId, referenceId);
+```
+
+**Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
+
+**`fetchVaultDocumentDownloadUrl(documentId)`** — non-React function that shares the hook's client-side URL cache. Use from PDF exporters, image preloaders, or other non-component code paths.
+
+### `useArcheAssets()` — Contributor-published asset library
+
+**Permission:** `assets:read`
+**Returns:** `ArcheAssetsApi`
+
+A frozen set of images the arche's contributor uploaded and pinned to the published version — logos, brand images, hole maps, reference photos. Each entry has an immutable `assetId` and a short-lived `signedUrl` (~5 min) suitable for `<img src>`.
+
+```tsx
+import { useArcheAssets } from '@fias/arche-sdk';
+
+const { list, getUrl } = useArcheAssets();
+
+const { entries, nextCursor } = await list({ limit: 50 });
+// entries[i]: { assetId, signedUrl, expiresAt, contentType, width, height,
+//               sizeBytes, name, altText, tags }
+
+// Refresh a signed URL when it's about to expire
+const fresh = await getUrl(assetId);
+```
+
+Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
+
+### `useFiasStore()` — In-app purchases (IAP)
+
+**Permission:** `store:purchase`
+**Returns:** `FiasStoreApi`
+
+How a plugin charges the signed-in user for anything inside the arche — one-time unlocks, consumables, subscriptions, paid sign-ups, donations. **All in-arche payments go through this hook.** The arche never handles payment directly: the platform shows a confirmation overlay, debits the user's Fias credit balance, and returns a result. Do not import Stripe or any external payment SDK — they are sandboxed out and not needed.
+
+Products are declared in `fias-plugin.json` under a `products` array (see Manifest Reference below). Each product has a stable `identifier` your code passes to `purchase()`. Prices are denominated in **Fias credits**, not USD.
+
+```tsx
+import { useFiasStore } from '@fias/arche-sdk';
+
+function UnlockButton() {
+  const { products, purchase, hasEntitlement, isLoading } = useFiasStore();
+  const product = products.find((p) => p.productIdentifier === 'pro_unlock');
+
+  if (isLoading || !product) return null;
+  if (hasEntitlement('pro_unlock')) return <p>Pro features unlocked.</p>;
+
+  async function buy() {
+    const result = await purchase('pro_unlock');
+    if (!result.success) {
+      // Common codes: INSUFFICIENT_CREDITS, USER_CANCELLED, PRODUCT_NOT_FOUND
+      console.error(result.error);
+    }
+    // On success, `entitlements` updates automatically.
+  }
+
+  return <button onClick={buy}>Unlock for {product.priceCredits} credits</button>;
+}
+```
+
+**Product types:**
+
+- `consumable` — buyable repeatedly (tokens, energy, single donations, sign-up entries). Does NOT create an entitlement; track usage in `useFiasDataStore`.
+- `non_consumable` — one-time purchase, permanent entitlement.
+- `auto_renewable` — subscription that renews automatically. Requires `subscriptionPeriod`: `weekly` | `monthly` | `quarterly` | `yearly`.
+- `non_renewing` — time-limited access that does NOT renew (season pass).
+
+**API surface:**
+
+- `products: StoreProduct[]` — loaded on mount.
+- `purchase(productIdentifier, { quantity? }) → StorePurchaseResult` — triggers the platform confirmation overlay. `quantity` only applies to consumables.
+- `entitlements: StoreEntitlement[]` — current non-consumable + subscription entitlements; updated automatically after a successful purchase.
+- `hasEntitlement(productIdentifier) → boolean` — convenience check.
+- `getPurchaseHistory() → Promise<StorePurchase[]>` — full log including consumables.
+- `restorePurchases() → Promise<StoreEntitlement[]>` — re-sync entitlements from the platform.
+
+**Error handling:** `purchase()` returns `{ success: false, error, code }` rather than throwing — always branch on `result.success`. The user must be signed in to a Fias account; IAP is not available to anonymous visitors on public arches.
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -252,9 +504,16 @@ navigateTo('/settings');
 ```tsx
 import { useStepNavigation } from '@fias/arche-sdk';
 
-const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+// Pass `persistKey` to survive preview rebuilds (do NOT additionally wrap
+// currentStep in usePersistentState — that creates two state sources and
+// a bidirectional sync loop).
+const { currentStep, setCurrentStep } = useStepNavigation('step-1', {
+  persistKey: 'workflow-step',
+});
 ```
 
+The host can also drive step changes from outside the iframe — for example, when the user clicks a node in an external graph view. The hook listens for those `step_navigate` messages and updates `currentStep` automatically, so unexpected step transitions aren't a bug to chase.
+
 ### `usePersistentState()` — Auto-saving state
 
 **Permission:** `storage:sandbox`
@@ -272,13 +531,36 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 
 ### `fias` — Imperative utilities
 
+Use the `fias` namespace when you need bridge operations from outside a React component (event handlers attached imperatively, utility modules, non-React entry points).
+
 ```tsx
 import { fias } from '@fias/arche-sdk';
 
+fias.ready(); // Manual ready signal (FiasProvider does this automatically)
 fias.resize(800); // Resize iframe height
 fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' | 'error'
+
+// fias.dataStore mirrors useFiasDataStore() — same operations, same limits.
+// Requires the `data:store` permission.
+await fias.dataStore.createCollection('scores', { userScope: 'user' });
+await fias.dataStore.put('scores', 'doc-key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'doc-key');
+await fias.dataStore.query('scores', {
+  filters: [{ field: 'score', op: 'gte', value: 50 }],
+});
+await fias.dataStore.delete('scores', 'doc-key');
+await fias.dataStore.listCollections();
+await fias.dataStore.deleteCollection('scores');
 ```
 
+### Advanced exports (rarely needed)
+
+The SDK also exports the following for advanced use cases. Most plugins don't need them.
+
+- `VALID_PLUGIN_PERMISSIONS`, `isValidPluginPermission(perm)` — runtime permission validation.
+- Theme catalog: `DARK_THEME`, `LIGHT_THEME`, `getDefaultTheme()`, `THEME_CATALOG`, `getThemeById()`, `FONT_PAIRINGS`, `getFontPairingById()` — useful when the plugin lets the user pick from preset themes/fonts.
+- Bridge introspection: `FiasBridge`, `getBridge()`, `resetBridge()`, `SDK_BRIDGE_PROTOCOL_VERSION`, `SDK_REQUIRES_HOST_PROTOCOL_VERSION` — testing and advanced cases that need direct bridge control.
+
 ## Manifest Reference (`fias-plugin.json`)
 
 ```json
@@ -298,23 +580,78 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 **Fields:**
 
-| Field          | Required | Description                                               |
-| -------------- | -------- | --------------------------------------------------------- |
-| `name`         | Yes      | Plugin identifier (lowercase, hyphens)                    |
-| `version`      | Yes      | Semver (e.g., `"1.0.0"`)                                  |
-| `description`  | Yes      | Short marketplace description                             |
-| `main`         | Yes      | Entry point source file                                   |
-| `archeType`    | Yes      | `"tool"` or `"site"`                                      |
-| `tags`         | No       | Discovery tags                                            |
-| `pricing`      | Yes      | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
-| `permissions`  | Yes      | Array of permission scopes                                |
-| `sdk`          | Yes      | SDK version range                                         |
-| `dependencies` | No       | npm packages with **exact** versions (max 20)             |
-
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
+| Field                 | Req  | Description                                                                                             |
+| --------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
+| `name`                | Yes  | Plugin identifier (lowercase, hyphens)                                                                  |
+| `version`             | Yes  | Semver (e.g., `"1.0.0"`)                                                                                |
+| `description`         | Yes  | Short marketplace description                                                                           |
+| `expandedDescription` | No   | Long-form marketplace copy                                                                              |
+| `main`                | Yes  | Entry point source file                                                                                 |
+| `archeType`           | Yes  | `"tool"` or `"site"`                                                                                    |
+| `categorySlug`        | No   | Marketplace category for discovery                                                                      |
+| `icon`                | No   | Relative path to icon asset (shown in marketplace + arche header)                                       |
+| `tags`                | No   | Discovery tags                                                                                          |
+| `pricing`             | Yes  | Marketplace **listing** pricing (see "Pricing detail" below). NOT for in-arche charges — use `products` |
+| `permissions`         | Yes  | Array of permission scopes (see below)                                                                  |
+| `products`            | No   | IAP product catalog for `useFiasStore()` (see "Defining IAP products" below)                            |
+| `isPublic`            | No   | Default `false`. Anonymous visitors can view (see "Public arches" below)                                |
+| `isFullScreen`        | No   | Default `false`. Renders without platform chrome — implies `archeType: "site"`                          |
+| `isListed`            | No   | Default `true`. Visible in marketplace store                                                            |
+| `sdk`                 | Yes  | SDK version range                                                                                       |
+| `dependencies`        | No   | npm packages with **exact** versions (max 20)                                                           |
+| `archeIds`            | Auto | Per-environment IDs written by the CLI after first publish — don't hand-edit                            |
+
+**Pricing detail:**
+
+`pricing` is the marketplace **listing** model — controls what the platform charges users to access the arche itself. It does NOT cover charges the plugin makes from inside (entry fees, unlocks, donations) — for those, use IAP via `products`.
+
+| `pricing.model` | Required sub-fields             |
+| --------------- | ------------------------------- |
+| `"free"`        | none                            |
+| `"fixed"`       | `priceCents`                    |
+| `"per_use"`     | `baseFeeCents`                  |
+| `"tiered"`      | `tiers: [{ upTo, priceCents }]` |
+
+Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`, `entities:image_remove_background`, `entities:audio_generate`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
+**Defining IAP products (for `useFiasStore`):**
+
+Add a `products` array to declare what users can buy inside the arche. Each entry needs a stable `identifier` your code passes to `purchase()`. Prices are in Fias credits.
+
+```json
+{
+  "products": [
+    {
+      "identifier": "pro_unlock",
+      "type": "non_consumable",
+      "name": "Pro features",
+      "description": "Permanent unlock for advanced features.",
+      "priceCredits": 500
+    },
+    {
+      "identifier": "monthly_sub",
+      "type": "auto_renewable",
+      "name": "Monthly subscription",
+      "description": "Renewing access.",
+      "priceCredits": 200,
+      "subscriptionPeriod": "monthly",
+      "subscriptionGroup": "pro"
+    }
+  ],
+  "permissions": ["store:purchase"]
+}
+```
+
+`store:purchase` must be in `permissions` whenever `products` is non-empty. Use `consumable` for things bought repeatedly (single donations, sign-up entries), `non_consumable` for one-time unlocks, `auto_renewable` / `non_renewing` for time-bounded access.
+
+**Public arches (`isPublic: true`):**
+
+Setting `isPublic: true` lets anonymous visitors (no Fias account) view the arche at `/a/<archeId>`. The UI renders without the platform sidebar. **Bridge operations still require auth** — `useFiasDataStore` writes, `useFiasStore.purchase()`, `useFiasStorage` reads, vault operations, etc. all require the visitor to be signed in. Public mode is for read-only landing pages, marketing pages, and shared-content viewers — not for collecting registrations or payments from anonymous users.
+
 ## Plugin Constraints
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
@@ -418,7 +755,7 @@ npx fias-dev login --env production   # Authenticate with production
 npx fias-dev entities                              # List all
 npx fias-dev entities --search "image"             # Search by keyword
 npx fias-dev entities --type "model-definition"    # Filter by type
-npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
+npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
 ### Validating the Manifest

package/templates/default/CLAUDE.md

@@ -2,8 +2,6 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `AGENTS.md` (identical content).
-
 ## Project Structure
 
 ```
@@ -183,13 +181,17 @@ function AISummarizer() {
     });
   }
 
+  // `streamingText` accumulates tokens during the call AND continues to hold
+  // the full text after the call resolves — it is NOT cleared. `result.output`
+  // also contains the full text once `invoke()` resolves. Render ONE slot only
+  // — `streamingText` while loading, `result.output` afterwards — or the
+  // response appears twice.
   return (
     <div>
       <button onClick={() => summarize('...')} disabled={isLoading}>
         Summarize
       </button>
-      {isLoading && <p>{streamingText}</p>}
-      {result && <p>{result.output}</p>}
+      <p>{isLoading ? streamingText : result?.output}</p>
       {error && <p>Error: {error.message}</p>}
     </div>
   );
@@ -203,7 +205,43 @@ The `entityId` references a published model entity. Browse available models with
 **Permission:** `entities:image_generate`
 **Returns:** `ImageGenerationApi`
 
-Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned. Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned.
+
+#### Choosing an image model
+
+The `entityId` parameter accepts three forms. **Prefer the selector forms** (`platformRecommended` / `providerRecommended`) over hardcoded entity IDs: the platform's recommendations evolve, models get retired, and a selector lets your plugin pick up the current best automatically without a code edit. Hardcoded IDs are still supported for back-compat and for cases where you want a specific model — but if the platform retires that exact entity, your plugin breaks unless the platform has registered a successor.
+
+```tsx
+// 1. Platform's blessed pick for a workflow + optional style (RECOMMENDED).
+//    Asking for `image-to-image` will never return a model that can't do it.
+generate({
+  entityId: { platformRecommended: { mode: 'text-to-image', style: 'illustration' } },
+  prompt: "A child's storybook page of a fox in the forest",
+});
+
+// 2. A specific provider's blessed pick. Use when your plugin's value prop
+//    depends on a particular provider's quirks.
+generate({
+  entityId: { providerRecommended: { provider: 'openai', mode: 'image-to-image' } },
+  prompt: 'Make it look like an oil painting',
+  referenceImage: { fileId: previousImage.fileId },
+});
+
+// 3. Explicit entityId — back-compat path. Use only when you want a specific
+//    model. If the entity has been deprecated, the response includes
+//    `deprecation: { requestedEntityId, resolvedEntityId, deprecatedAt }` and
+//    you get the successor.
+generate({
+  entityId: 'ent_modeldef_gpt_image_1_5',
+  prompt: 'A serene mountain landscape at sunset',
+});
+```
+
+Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
+
+Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+
+#### Full example
 
 ```tsx
 import { useImageGeneration } from '@fias/arche-sdk';
@@ -216,23 +254,237 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_dalle3',
+            entityId: { platformRecommended: { mode: 'text-to-image' } },
             prompt: 'A serene mountain landscape at sunset',
-            size: '1024x1024',
-            quality: 'hd',
+            size: '16:9',
+            quality: 'high',
           })
         }
         disabled={isLoading}
       >
         {isLoading ? 'Generating...' : 'Generate Image'}
       </button>
-      {result && <img src={result.imageUrl} alt="Generated" />}
+      {result && (
+        <>
+          <img src={result.imageUrl} alt="Generated" />
+          {result.deprecation && (
+            <p style={{ color: 'orange' }}>
+              Note: requested entity "{result.deprecation.requestedEntityId}" is deprecated;
+              auto-substituted "{result.deprecation.resolvedEntityId}". Update your code.
+            </p>
+          )}
+        </>
+      )}
       {error && <p>Error: {error.message}</p>}
     </div>
   );
 }
 ```
 
+### `useImageEntities()` — Discover image-generation entities
+
+**Permission:** `entities:image_generate`
+**Returns:** `{ entities, isLoading, error, refetch }`
+
+Use to render a "let the user pick a model" picker. For the common case of "just give me something good," skip discovery and pass a selector directly to `useImageGeneration`:
+
+```tsx
+await generate({
+  entityId: { platformRecommended: { mode: 'text-to-image' } },
+  prompt: '...',
+});
+```
+
+Discovery hook usage:
+
+```tsx
+import { useImageEntities } from '@fias/arche-sdk';
+
+const { entities, isLoading } = useImageEntities({
+  modes: ['image-to-image'],
+  supportsReferenceImage: true,
+});
+// entities[i]: { entityId, displayName, provider, modes, supportedSizes,
+//                supportsReferenceImage, isPlatformRecommended, ... }
+```
+
+Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
+
+### `useBackgroundRemoval()` — Client-side background removal
+
+**Permission:** `entities:image_remove_background`
+**Returns:** `BackgroundRemovalApi`
+
+Runs the imgly WASM model inside the host page — bytes never leave the user's device. Returns a transparent PNG.
+
+```tsx
+import { useBackgroundRemoval } from '@fias/arche-sdk';
+
+const { removeBackground, isLoading } = useBackgroundRemoval();
+const transparentPng = await removeBackground(jpegBlob);
+```
+
+**Limits:** input ≤ 25 MiB, PNG/JPEG only, rate-limited to 10/min per arche per user. Throws on size violation rather than returning a result.
+
+### Audio capability hooks (auto-generated)
+
+**Permission:** `entities:audio_generate`
+**Returns (per hook):** `{ invoke, isLoading, result, error }`
+
+Specialty capabilities expose **typed convenience hooks** generated from the platform's surface registry. Each hook bakes in a `surfaceKey` and infers params/result types from the surface's schemas.
+
+Currently shipped audio hooks: `useLyriaMusic`, `useElevenLabsTts`, `useElevenLabsMusic`, `useElevenLabsSfx`, `useElevenLabsStt`, `useElevenLabsAudioIsolation`, `useElevenLabsForcedAlignment`, `useElevenLabsVoiceChanger`, `useElevenLabsVoiceDesign`. Browse the full surface list with `npx fias-dev entities`.
+
+A legacy `useAudioGeneration()` hook still ships for back-compat with code written before the typed-surface migration. New plugins should use the typed hooks above — the legacy hook will be removed in a future major version.
+
+```tsx
+import { useElevenLabsTts } from '@fias/arche-sdk';
+
+const { invoke, isLoading, result } = useElevenLabsTts();
+await invoke({ text: 'Hello world', voiceId: '...' });
+// result: { audioUrl, audioRef, durationMinutes, costCredits, ... }
+```
+
+For surfaces without a typed wrapper yet, the generic substrate:
+
+```tsx
+import { useSurface } from '@fias/arche-sdk';
+
+const { invoke } = useSurface<MyParams, MyResult>('my.surface-key');
+```
+
+Default per-request timeout is 180 s (covers TTS for long text and Lyria multi-clip generation).
+
+### `useVaultDocuments()` — User-owned Vault documents
+
+**Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / 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>/`.
+
+**Most common use:** images returned from `useImageGeneration()` are auto-saved here. The result includes a `documentId` — pass it to `getDownloadUrl()` later to refresh the presigned URL after the original ~1h TTL expires.
+
+```tsx
+import { useVaultDocuments } from '@fias/arche-sdk';
+
+const vault = useVaultDocuments();
+
+// Refresh a presigned URL (cached client-side, auto-refreshed before expiry)
+const { url, expiresAt, contentType } = await vault.getDownloadUrl(documentId);
+
+// List documents this arche owns
+const { documents, nextCursor } = await vault.list({ search: 'invoice', limit: 50 });
+
+// Write a small text/JSON document (UTF-8, ≤ 1 MB)
+const { documentId } = await vault.write({
+  name: 'settings.json',
+  content: JSON.stringify(settings),
+  contentType: 'application/json',
+  tags: ['config'],
+});
+
+// Upload a binary or larger document — wraps the two-step presigned-PUT flow
+const result = await vault.upload(bytes, {
+  name: 'photo.jpg',
+  mimeType: 'image/jpeg',
+});
+// result.status transitions 'uploaded' → 'available' once indexed for search
+
+// 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 });
+
+// Update / delete
+await vault.update(documentId, { name: 'new-name.json', tags: ['archived'] });
+await vault.delete(documentId); // soft-delete, recoverable from My Data Trash
+```
+
+**Cross-arche attachment.** A document can be referenced from another arche's record (Business Contact, Company, Fias 360 Renewal in V-1). The reference points at the document but does NOT expose its contents to the target arche.
+
+```tsx
+const { referenceId } = await vault.attach(documentId, {
+  regardingType: 'vault_business_contact',
+  regardingId: contactId,
+});
+await vault.detach(documentId, referenceId);
+```
+
+**Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
+
+**`fetchVaultDocumentDownloadUrl(documentId)`** — non-React function that shares the hook's client-side URL cache. Use from PDF exporters, image preloaders, or other non-component code paths.
+
+### `useArcheAssets()` — Contributor-published asset library
+
+**Permission:** `assets:read`
+**Returns:** `ArcheAssetsApi`
+
+A frozen set of images the arche's contributor uploaded and pinned to the published version — logos, brand images, hole maps, reference photos. Each entry has an immutable `assetId` and a short-lived `signedUrl` (~5 min) suitable for `<img src>`.
+
+```tsx
+import { useArcheAssets } from '@fias/arche-sdk';
+
+const { list, getUrl } = useArcheAssets();
+
+const { entries, nextCursor } = await list({ limit: 50 });
+// entries[i]: { assetId, signedUrl, expiresAt, contentType, width, height,
+//               sizeBytes, name, altText, tags }
+
+// Refresh a signed URL when it's about to expire
+const fresh = await getUrl(assetId);
+```
+
+Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
+
+### `useFiasStore()` — In-app purchases (IAP)
+
+**Permission:** `store:purchase`
+**Returns:** `FiasStoreApi`
+
+How a plugin charges the signed-in user for anything inside the arche — one-time unlocks, consumables, subscriptions, paid sign-ups, donations. **All in-arche payments go through this hook.** The arche never handles payment directly: the platform shows a confirmation overlay, debits the user's Fias credit balance, and returns a result. Do not import Stripe or any external payment SDK — they are sandboxed out and not needed.
+
+Products are declared in `fias-plugin.json` under a `products` array (see Manifest Reference below). Each product has a stable `identifier` your code passes to `purchase()`. Prices are denominated in **Fias credits**, not USD.
+
+```tsx
+import { useFiasStore } from '@fias/arche-sdk';
+
+function UnlockButton() {
+  const { products, purchase, hasEntitlement, isLoading } = useFiasStore();
+  const product = products.find((p) => p.productIdentifier === 'pro_unlock');
+
+  if (isLoading || !product) return null;
+  if (hasEntitlement('pro_unlock')) return <p>Pro features unlocked.</p>;
+
+  async function buy() {
+    const result = await purchase('pro_unlock');
+    if (!result.success) {
+      // Common codes: INSUFFICIENT_CREDITS, USER_CANCELLED, PRODUCT_NOT_FOUND
+      console.error(result.error);
+    }
+    // On success, `entitlements` updates automatically.
+  }
+
+  return <button onClick={buy}>Unlock for {product.priceCredits} credits</button>;
+}
+```
+
+**Product types:**
+
+- `consumable` — buyable repeatedly (tokens, energy, single donations, sign-up entries). Does NOT create an entitlement; track usage in `useFiasDataStore`.
+- `non_consumable` — one-time purchase, permanent entitlement.
+- `auto_renewable` — subscription that renews automatically. Requires `subscriptionPeriod`: `weekly` | `monthly` | `quarterly` | `yearly`.
+- `non_renewing` — time-limited access that does NOT renew (season pass).
+
+**API surface:**
+
+- `products: StoreProduct[]` — loaded on mount.
+- `purchase(productIdentifier, { quantity? }) → StorePurchaseResult` — triggers the platform confirmation overlay. `quantity` only applies to consumables.
+- `entitlements: StoreEntitlement[]` — current non-consumable + subscription entitlements; updated automatically after a successful purchase.
+- `hasEntitlement(productIdentifier) → boolean` — convenience check.
+- `getPurchaseHistory() → Promise<StorePurchase[]>` — full log including consumables.
+- `restorePurchases() → Promise<StoreEntitlement[]>` — re-sync entitlements from the platform.
+
+**Error handling:** `purchase()` returns `{ success: false, error, code }` rather than throwing — always branch on `result.success`. The user must be signed in to a Fias account; IAP is not available to anonymous visitors on public arches.
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -252,9 +504,16 @@ navigateTo('/settings');
 ```tsx
 import { useStepNavigation } from '@fias/arche-sdk';
 
-const { currentStep, setCurrentStep } = useStepNavigation('step-1');
+// Pass `persistKey` to survive preview rebuilds (do NOT additionally wrap
+// currentStep in usePersistentState — that creates two state sources and
+// a bidirectional sync loop).
+const { currentStep, setCurrentStep } = useStepNavigation('step-1', {
+  persistKey: 'workflow-step',
+});
 ```
 
+The host can also drive step changes from outside the iframe — for example, when the user clicks a node in an external graph view. The hook listens for those `step_navigate` messages and updates `currentStep` automatically, so unexpected step transitions aren't a bug to chase.
+
 ### `usePersistentState()` — Auto-saving state
 
 **Permission:** `storage:sandbox`
@@ -272,13 +531,36 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 
 ### `fias` — Imperative utilities
 
+Use the `fias` namespace when you need bridge operations from outside a React component (event handlers attached imperatively, utility modules, non-React entry points).
+
 ```tsx
 import { fias } from '@fias/arche-sdk';
 
+fias.ready(); // Manual ready signal (FiasProvider does this automatically)
 fias.resize(800); // Resize iframe height
 fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' | 'error'
+
+// fias.dataStore mirrors useFiasDataStore() — same operations, same limits.
+// Requires the `data:store` permission.
+await fias.dataStore.createCollection('scores', { userScope: 'user' });
+await fias.dataStore.put('scores', 'doc-key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'doc-key');
+await fias.dataStore.query('scores', {
+  filters: [{ field: 'score', op: 'gte', value: 50 }],
+});
+await fias.dataStore.delete('scores', 'doc-key');
+await fias.dataStore.listCollections();
+await fias.dataStore.deleteCollection('scores');
 ```
 
+### Advanced exports (rarely needed)
+
+The SDK also exports the following for advanced use cases. Most plugins don't need them.
+
+- `VALID_PLUGIN_PERMISSIONS`, `isValidPluginPermission(perm)` — runtime permission validation.
+- Theme catalog: `DARK_THEME`, `LIGHT_THEME`, `getDefaultTheme()`, `THEME_CATALOG`, `getThemeById()`, `FONT_PAIRINGS`, `getFontPairingById()` — useful when the plugin lets the user pick from preset themes/fonts.
+- Bridge introspection: `FiasBridge`, `getBridge()`, `resetBridge()`, `SDK_BRIDGE_PROTOCOL_VERSION`, `SDK_REQUIRES_HOST_PROTOCOL_VERSION` — testing and advanced cases that need direct bridge control.
+
 ## Manifest Reference (`fias-plugin.json`)
 
 ```json
@@ -298,23 +580,78 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 
 **Fields:**
 
-| Field          | Required | Description                                               |
-| -------------- | -------- | --------------------------------------------------------- |
-| `name`         | Yes      | Plugin identifier (lowercase, hyphens)                    |
-| `version`      | Yes      | Semver (e.g., `"1.0.0"`)                                  |
-| `description`  | Yes      | Short marketplace description                             |
-| `main`         | Yes      | Entry point source file                                   |
-| `archeType`    | Yes      | `"tool"` or `"site"`                                      |
-| `tags`         | No       | Discovery tags                                            |
-| `pricing`      | Yes      | `{ model: "free" }` or `"fixed"`, `"per_use"`, `"tiered"` |
-| `permissions`  | Yes      | Array of permission scopes                                |
-| `sdk`          | Yes      | SDK version range                                         |
-| `dependencies` | No       | npm packages with **exact** versions (max 20)             |
-
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
+| Field                 | Req  | Description                                                                                             |
+| --------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
+| `name`                | Yes  | Plugin identifier (lowercase, hyphens)                                                                  |
+| `version`             | Yes  | Semver (e.g., `"1.0.0"`)                                                                                |
+| `description`         | Yes  | Short marketplace description                                                                           |
+| `expandedDescription` | No   | Long-form marketplace copy                                                                              |
+| `main`                | Yes  | Entry point source file                                                                                 |
+| `archeType`           | Yes  | `"tool"` or `"site"`                                                                                    |
+| `categorySlug`        | No   | Marketplace category for discovery                                                                      |
+| `icon`                | No   | Relative path to icon asset (shown in marketplace + arche header)                                       |
+| `tags`                | No   | Discovery tags                                                                                          |
+| `pricing`             | Yes  | Marketplace **listing** pricing (see "Pricing detail" below). NOT for in-arche charges — use `products` |
+| `permissions`         | Yes  | Array of permission scopes (see below)                                                                  |
+| `products`            | No   | IAP product catalog for `useFiasStore()` (see "Defining IAP products" below)                            |
+| `isPublic`            | No   | Default `false`. Anonymous visitors can view (see "Public arches" below)                                |
+| `isFullScreen`        | No   | Default `false`. Renders without platform chrome — implies `archeType: "site"`                          |
+| `isListed`            | No   | Default `true`. Visible in marketplace store                                                            |
+| `sdk`                 | Yes  | SDK version range                                                                                       |
+| `dependencies`        | No   | npm packages with **exact** versions (max 20)                                                           |
+| `archeIds`            | Auto | Per-environment IDs written by the CLI after first publish — don't hand-edit                            |
+
+**Pricing detail:**
+
+`pricing` is the marketplace **listing** model — controls what the platform charges users to access the arche itself. It does NOT cover charges the plugin makes from inside (entry fees, unlocks, donations) — for those, use IAP via `products`.
+
+| `pricing.model` | Required sub-fields             |
+| --------------- | ------------------------------- |
+| `"free"`        | none                            |
+| `"fixed"`       | `priceCents`                    |
+| `"per_use"`     | `baseFeeCents`                  |
+| `"tiered"`      | `tiers: [{ upTo, priceCents }]` |
+
+Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
+
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`, `entities:image_remove_background`, `entities:audio_generate`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
+**Defining IAP products (for `useFiasStore`):**
+
+Add a `products` array to declare what users can buy inside the arche. Each entry needs a stable `identifier` your code passes to `purchase()`. Prices are in Fias credits.
+
+```json
+{
+  "products": [
+    {
+      "identifier": "pro_unlock",
+      "type": "non_consumable",
+      "name": "Pro features",
+      "description": "Permanent unlock for advanced features.",
+      "priceCredits": 500
+    },
+    {
+      "identifier": "monthly_sub",
+      "type": "auto_renewable",
+      "name": "Monthly subscription",
+      "description": "Renewing access.",
+      "priceCredits": 200,
+      "subscriptionPeriod": "monthly",
+      "subscriptionGroup": "pro"
+    }
+  ],
+  "permissions": ["store:purchase"]
+}
+```
+
+`store:purchase` must be in `permissions` whenever `products` is non-empty. Use `consumable` for things bought repeatedly (single donations, sign-up entries), `non_consumable` for one-time unlocks, `auto_renewable` / `non_renewing` for time-bounded access.
+
+**Public arches (`isPublic: true`):**
+
+Setting `isPublic: true` lets anonymous visitors (no Fias account) view the arche at `/a/<archeId>`. The UI renders without the platform sidebar. **Bridge operations still require auth** — `useFiasDataStore` writes, `useFiasStore.purchase()`, `useFiasStorage` reads, vault operations, etc. all require the visitor to be signed in. Public mode is for read-only landing pages, marketing pages, and shared-content viewers — not for collecting registrations or payments from anonymous users.
+
 ## Plugin Constraints
 
 These are hard limits enforced by the platform. Code that violates these will fail review or be blocked at runtime.
@@ -418,7 +755,7 @@ npx fias-dev login --env production   # Authenticate with production
 npx fias-dev entities                              # List all
 npx fias-dev entities --search "image"             # Search by keyword
 npx fias-dev entities --type "model-definition"    # Filter by type
-npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
+npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
 ### Validating the Manifest