@fias/arche-sdk 1.12.0 → 1.13.1

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,11 +181,11 @@ function AISummarizer() {
     });
   }
 
-  // streamingText holds the accumulated tokens during the call AND continues to
-  // hold the full text after the call completes — it is NOT cleared. result.output
-  // also contains the full text once invoke() resolves. Render ONE slot only —
-  // streamingText while loading, result.output afterwards. Showing both renders
-  // the response twice.
+  // `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}>
@@ -207,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';
@@ -220,9 +254,9 @@ function ImageMaker() {
       <button
         onClick={() =>
           generate({
-            entityId: 'ent_modeldef_gpt_image_1_5',
+            entityId: { platformRecommended: { mode: 'text-to-image' } },
             prompt: 'A serene mountain landscape at sunset',
-            size: '1024x1024',
+            size: '16:9',
             quality: 'high',
           })
         }
@@ -230,63 +264,227 @@ function ImageMaker() {
       >
         {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>
   );
 }
 ```
 
-### `useFiasFiles()` — User-files filesystem (SDK ≥ 1.9.0)
+### `useImageEntities()` — Discover image-generation entities
+
+**Permission:** `entities:image_generate`
+**Returns:** `{ entities, isLoading, error, refetch }`
 
-**Permissions:** `files:read` for `list`/`read`/`getDownloadUrl`; add `files:write` for `write`/`update`/`delete`
-**Returns:** `FiasFilesApi`
+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`:
 
-Access the user's Fias filesystem, scoped to files this arche owns. Files written through this hook (and images created via `useImageGeneration()`) appear in MyData under `/My-Fias/{ArcheName}/`. Listing is by ownership — moving a file in MyData doesn't hide it from the arche.
+```tsx
+await generate({
+  entityId: { platformRecommended: { mode: 'text-to-image' } },
+  prompt: '...',
+});
+```
 
-The most common use is `getDownloadUrl(fileId)` to refresh the presigned URL on a generated image after the original (~1h) expires:
+Discovery hook usage:
 
 ```tsx
-import { useFiasFiles, useImageGeneration } from '@fias/arche-sdk';
+import { useImageEntities } from '@fias/arche-sdk';
 
-function PortraitGallery({ savedFileId }: { savedFileId: string }) {
-  const { getDownloadUrl } = useFiasFiles();
-  const [url, setUrl] = useState<string | null>(null);
+const { entities, isLoading } = useImageEntities({
+  modes: ['image-to-image'],
+  supportsReferenceImage: true,
+});
+// entities[i]: { entityId, displayName, provider, modes, supportedSizes,
+//                supportsReferenceImage, isPlatformRecommended, ... }
+```
 
-  useEffect(() => {
-    let cancelled = false;
-    getDownloadUrl(savedFileId).then((r) => {
-      if (!cancelled) setUrl(r.url);
-    });
-    return () => {
-      cancelled = true;
-    };
-  }, [savedFileId, getDownloadUrl]);
+Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-  return url ? <img src={url} alt="" /> : null;
-}
+### `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');
 ```
 
-**Store the `fileId`, not the `imageUrl`.** Image-generation results include both, but `imageUrl` is a short-lived presigned link. Persist `fileId` in your data store and resolve to a fresh URL on render via `getDownloadUrl`.
+Default per-request timeout is 180 s (covers TTS for long text and Lyria multi-clip generation).
+
+### `useVaultDocuments()` — User-owned Vault documents
 
-**Same-name writes overwrite.** Calling `write({ name: 'save.json', content })` twice with the same name reuses the existing `fileId` and replaces the content — useful for periodic snapshots.
+**Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
+**Returns:** `VaultDocumentsApi`
 
-**`read()` is text-only.** It rejects binary content types with HTTP 415. Use `getDownloadUrl(fileId)` and pass the URL to `<img>`, `fetch`, etc. for binaries.
+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
-const files = useFiasFiles();
+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);
 
-await files.write({
-  name: 'save.json',
-  content: JSON.stringify(state),
+// 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',
 });
-const { content } = await files.read(fileId);
-const { files: page, nextCursor } = await files.list({ limit: 20 });
-await files.update(fileId, { tags: ['draft'] });
-await files.delete(fileId);
+// 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
@@ -303,21 +501,18 @@ navigateTo('/settings');
 
 **Returns:** `StepNavigationApi`
 
-Call **once** in the top-level App component. Share `currentStep` and `setCurrentStep` with step components via React context — do not call `useStepNavigation` from step components (each call creates an independent state).
-
 ```tsx
 import { useStepNavigation } from '@fias/arche-sdk';
 
-// Without persistence — currentStep resets on preview rebuild
-const { currentStep, setCurrentStep } = useStepNavigation('step-1');
-
-// With persistence — currentStep survives preview rebuilds (SDK ≥ 1.7.0)
+// 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: 'currentStep',
+  persistKey: 'workflow-step',
 });
 ```
 
-**Do NOT wrap `currentStep` in `usePersistentState`.** Two independent step-state sources create a bidirectional `useEffect` sync loop that spams `storage_write` and flashes the UI between steps. `persistKey` is the only correct way to persist the current 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
 
@@ -332,21 +527,40 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 // Automatically persists to storage on change
 ```
 
-Use for domain data (form inputs, selections, AI results). **Do not use for `currentStep`** — use `useStepNavigation({ persistKey })` instead.
-
-**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously on every setter call, but the underlying `storage_write` is coalesced with a 250 ms trailing-edge debounce and a 1 s max-wait, and flushed on unmount. This makes the hook safe to call from `requestAnimationFrame`, `mousemove`, and other high-frequency handlers — bursts no longer trip the `storage_write` rate limit.
-
-Trade-off: reading the same key via `useFiasStorage().readFile('__state/foo')` immediately after a `setValue` can see a stale value for up to ~250 ms. Read through the hook instead of bypassing it.
+**Writes are debounced (SDK ≥ 1.8.0).** The in-memory value updates synchronously, but the underlying `storage_write` is coalesced (250 ms trailing-edge debounce, 1 s max-wait, flushed on unmount). Safe to call from `requestAnimationFrame` and other high-frequency handlers. For state that updates every frame (game positions, drag coordinates), still prefer plain `useState` — persisting transient state is wasteful and not useful on reload.
 
 ### `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
@@ -366,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.
@@ -414,7 +683,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
 
-A separate **runaway-loop detector** also fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target for diagnostics, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) called 51 times in 5s.` — if you see this, look at the identified path and debounce the updates at the source.
+A separate **runaway-loop detector** fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) …` — the path tells you where to debounce at the source.
 
 ### Security Rules (enforced during review)
 
@@ -435,9 +704,16 @@ A separate **runaway-loop detector** also fires if any method is called >50 time
 
 ### Check for Updates (DO THIS FIRST)
 
-**At the start of every new session**, check if the FIAS packages and tooling are up to date:
+**At the start of every new session**, install dependencies if they aren't already, then check if the FIAS packages and tooling are up to date:
 
 ```bash
+# 1. Install deps first if node_modules/ is missing.
+#    fias-dev is a binary inside @fias/plugin-dev-harness, not a standalone
+#    npm package — `npx fias-dev …` before `npm install` falls through to
+#    the registry and prints a misleading "404 Not Found" for fias-dev.
+[ -d node_modules ] || npm install
+
+# 2. Then check for updates.
 npm outdated @fias/arche-sdk @fias/plugin-dev-harness
 npx fias-dev sync --dry-run
 ```
@@ -446,18 +722,6 @@ If newer package versions are available, tell the user and ask if they want to u
 
 If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
 
-#### UI cache after a harness upgrade
-
-The harness pulls its host-page UI (toolbar, mode toggle, sign-in modal) from a CDN and caches it in `~/.fias/harness-cache/`. The cached UI takes priority over the bundled copy that ships in the npm package.
-
-When you upgrade `@fias/plugin-dev-harness` but the CDN hasn't been redeployed yet, the cached UI can be older than the CLI. fias-dev now detects this case automatically and falls back to the bundled UI — look for this line in the startup log:
-
-```
-ℹ Cached harness UI v1.14.3 is older than CLI v1.18.0 — using bundled UI.
-```
-
-That message means everything is fine; the bundled UI exactly matches your CLI version. If you ever see stale behavior persist across an upgrade (and the line above didn't appear), delete `~/.fias/harness-cache/` and restart.
-
 ### Starting Development
 
 ```bash
@@ -494,39 +758,6 @@ npx fias-dev entities --type "model-definition"    # Filter by type
 npx fias-dev entities --detail ent_modeldef_gpt_image_1_5 # Full entity details (capabilities, sizes, pricing)
 ```
 
-### Debugging — Read the Browser's View Directly
-
-The harness mirrors every browser-side event to a per-port log file at `/tmp/fias-dev-<port>.log` (so usually `/tmp/fias-dev-3200.log`). The file path is also printed at startup:
-
-```
-Browser dev-log mirror: /tmp/fias-dev-3200.log
-```
-
-What's captured:
-
-- Every Dev Console entry (`send` / `recv` / `info` / `error` / `toast` / `cost` / `nav`)
-- Every uncaught JS error (`window.error`)
-- Every unhandled promise rejection (`unhandledrejection`)
-- Bridge requests + responses with payload previews
-
-Format is one line per event:
-
-```
-2026-05-24T07:14:33.123Z [ERROR] window.error {"message":"...","file":"...","line":42}
-2026-05-24T07:14:35.456Z [SEND]  image_generate {"entityId":"ent_modeldef_..."}
-2026-05-24T07:14:36.789Z [RECV]  response       {...}
-```
-
-**For AI agents pair-debugging with a developer:** tail this file instead of asking the developer to open DevTools and copy-paste output. Reproduce the failing action in the browser, then read the file — you'll see exactly what the iframe and harness exchanged.
-
-```bash
-tail -f /tmp/fias-dev-3200.log
-```
-
-The file is truncated on every `fias-dev` start, so it always reflects the current session.
-
-The mirror uses `navigator.sendBeacon` (with a `fetch` fallback) so there's a sub-second delay before the most recent events land in the file. If you're chasing a race, give it a beat before reading.
-
 ### Validating the Manifest
 
 ```bash
@@ -549,84 +780,6 @@ If the AI review rejects your submission, the listing-fee portion is
 refunded automatically (the per-review portion is not, since review work
 happened either way).
 
-## Common Pitfalls
-
-These are real bugs that have shipped from AI-generated plugins. Avoid them.
-
-### Don't navigate from a `useEffect` that watches derived state
-
-If a step component derives a value from context state and uses `useEffect` to redirect when that derived value is missing, the redirect can fire mid-update and yank the user away from a working screen. Common shape:
-
-```tsx
-// ❌ BUG: redirects whenever conversations changes between renders
-const currentConversation = conversations.find((c) => c.id === currentConversationId);
-
-useEffect(() => {
-  if (!currentConversation) {
-    setCurrentStep('list');
-  }
-}, [currentConversation, setCurrentStep]); // fires on every conversations change
-```
-
-`currentConversation` is a _derived_ value — its reference changes every time `conversations` changes. The effect re-runs and may redirect during a state transition (e.g., right after the user sends a message and the component is mid-update). The user reports "I sent a message and got bounced back" or "the response never showed up".
-
-```tsx
-// ✅ FIX: gate on the *id* (which is durable) and render a loading state when
-// the conversation can't be found yet — let the user navigate back manually
-// instead of forcing it.
-useEffect(() => {
-  if (!currentConversationId) setCurrentStep('list');
-}, [currentConversationId, setCurrentStep]);
-
-if (!currentConversation) return <div>Loading conversation…</div>;
-```
-
-### Use functional updaters when an `await` sits between reads and writes
-
-When you read state, `await` something, then write back, the closure captures the _stale_ state. Use the functional form so the setter receives the latest value at the time of the update:
-
-```tsx
-// ❌ BUG: `messages` here is the snapshot from before await
-const messages = currentConversation.messages;
-const response = await invoke({ entityId, input });
-setConversations(
-  conversations.map((c) => (c.id === id ? { ...c, messages: [...messages, response] } : c)),
-);
-
-// ✅ FIX: functional updater reads fresh state at update time
-await invoke({ entityId, input });
-setConversations((prev) =>
-  prev.map((c) => (c.id === id ? { ...c, messages: [...c.messages, response] } : c)),
-);
-```
-
-This matters most for `usePersistentState` on lists: the user can fire many updates quickly, and lost-update bugs are common with snapshot-style updates.
-
-### Render `streamingText` OR `result.output` — never both
-
-Already covered in the `useEntityInvocation` section above, but worth repeating: `streamingText` is _not_ cleared after the call completes — it keeps holding the full final text. Showing `{streamingText && ...}` AND `{result && ...}` in separate JSX nodes prints the response twice as soon as `result` arrives. Use one slot: `{isLoading ? streamingText : result?.output}`.
-
-### Verify visually when the user reports a UI bug
-
-If a user says "I don't see the response" or "the layout's broken", don't rely solely on `console.log` and `useFiasStorage` reads. Inspect the actual rendered output. The platform exposes `get_preview_screenshot` to AI builders for exactly this reason.
-
-### Don't persist per-frame state
-
-For state that updates every frame (game position, drag coordinates, animated values), use plain `useState` — not `usePersistentState`. Persisting every ball-position tick writes unbounded data to durable storage and doesn't survive reloads in any useful way anyway (the ball will be somewhere different when the player resumes).
-
-Hook-level debouncing (SDK ≥ 1.8.0) makes `usePersistentState` safe under bursts, but you still shouldn't persist what you'll discard on reload. Keep ephemeral state in `useState` and persist only meaningful checkpoints (final score, selected difficulty, high-score list).
-
-```tsx
-// ❌ Persisting ball position every frame — meaningless on reload
-const [gameState, setGameState] = usePersistentState<GameState>('gameState', initial);
-requestAnimationFrame(() => setGameState(advance(gameState)));
-
-// ✅ Ephemeral for live gameplay, persisted for results
-const [gameState, setGameState] = useState<GameState>(initial);
-const [highScores, setHighScores] = usePersistentState<Score[]>('highScores', []);
-// persist highScores only when a run completes
-```
-
 ## Common Patterns
 
 ### Theme-Aware Card Component