@fias/create-fias-plugin 1.4.0 → 1.4.2

package/package.json

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

package/templates/default/AGENTS.md

@@ -63,6 +63,28 @@ function MyComponent() {
 - `fonts`: `{ body, heading, mono }` (font-family strings)
 - `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
 
+### `useFiasVendoredAssets(importSpecifier)` — Self-hosted vendored-library asset URLs
+
+**Permission:** `sandbox:vendored-libraries`
+**Returns:** `Record<string, string> | null` (null when the host CDN is unconfigured or the library isn't vendored)
+
+Some heavy libraries (pdf.js today; WASM runtimes later) need a Web Worker and large asset files that a sandboxed plugin can't bundle or self-host. The platform vendors a curated set of these — version-pinned, served from its trusted CDN. A plugin opts in by (1) listing the library in its `dependencies` and (2) declaring the `sandbox:vendored-libraries` permission. The platform then widens the plugin CSP for exactly that library (e.g. pdf.js → `worker-src blob:`+CDN, `script-src`/`connect-src` CDN), pins the import specifier to the self-hosted build via the host importmap (so `import * as pdfjsLib from 'pdfjs-dist'` resolves to it), and delivers the library's asset URLs here. For `pdfjs-dist` you typically only need `worker` (feed it to `@fias/pdf-core`'s loader `workerModuleUrl`) plus `cMapUrl` / `standardFontDataUrl` for CID / non-embedded fonts.
+
+```tsx
+import { useFiasVendoredAssets } from '@fias/arche-sdk';
+import { loadPdfJs, configurePdfAssets } from '@fias/pdf-core/loader';
+
+function PdfViewer() {
+  const assets = useFiasVendoredAssets('pdfjs-dist');
+  if (!assets) return <div>PDF rendering unavailable</div>;
+  configurePdfAssets({ cMapUrl: assets.cMapUrl, standardFontDataUrl: assets.standardFontDataUrl });
+  const pdfjs = await loadPdfJs({ workerModuleUrl: assets.worker }); // off-thread worker
+  // ...render with pdfjs
+}
+```
+
+**`pdfjs-dist` asset keys:** `{ mainModule, worker, cMapUrl, standardFontDataUrl }` — all absolute CDN URLs.
+
 ### `useFiasFonts()` — Platform font catalog
 
 **Permission:** none
@@ -205,10 +227,120 @@ const doc = await fias.dataStore.get('scores', 'key');
 - 100 MB total storage per plugin
 - Max 100 results per query, max 10 filters, max field path depth 5
 
-**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
+**Atomic batch writes:** `batch(operations)` applies up to 25 put/delete ops in a **single transaction** — all-or-nothing. Use it when several writes must stay consistent (e.g. append a ledger entry AND update a running total); a sequence of separate `put`/`delete` calls can leave a half-applied state. A batch may span collections and scopes (pass `workspaceId` per op); any failure (bad key, role denial, quota) rolls the whole batch back.
+
+```tsx
+await dataStore.batch([
+  { op: 'put', collection: 'ledger', key: 'tx-42', data: { delta: 100 } },
+  { op: 'put', collection: 'totals', key: 'balance', data: { value: newBalance } },
+]);
+```
+
+**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
 
+**Semantic search (`data:search`):** Make a collection searchable to do vector search over a text field. Declare it at creation with `searchable: { field }`, then call `search()`. Embeddings are managed by the platform — you never handle vectors or pick a model. Documents are embedded asynchronously, so a freshly-written doc becomes searchable a moment later (it's always immediately visible to `query`). The query embedding charges the caller's credits. Requires the `data:search` permission (distinct from `data:store`).
+
+```tsx
+// Create a searchable collection (embedding the `text` field) and publish docs.
+await dataStore.createCollection('recipes', { userScope: 'shared', searchable: { field: 'text' } });
+await dataStore.put('recipes', recipeId, { text: `${title} ${description}`, title, cuisine });
+
+// Semantic search (charges the caller's credits for the query embedding).
+const matches = await dataStore.search('recipes', 'quick vegetarian weeknight dinner', {
+  topK: 10,
+  filters: [{ field: 'cuisine', op: 'eq', value: 'italian' }], // vector + JSONB facet, ANDed
+});
+// matches: Array<{ key, data, similarity }>, best first
+```
+
+**Search limits:** `topK` ≤ 50, query ≤ 1024 chars, 50,000 embedded documents per arche; `search` is rate-limited to 20/min (each call embeds the query). Documents in non-searchable collections — and not-yet-embedded docs — are invisible to `search` but always returned by `query`.
+
+### `useDataSubscription()` — Realtime collection change events
+
+**Permission:** `data:store` (same as reading — live updates grant nothing polling couldn't)
+**Returns:** `DataSubscriptionState` — `{ status: 'subscribing' | 'active' | 'ended', endedReason? }`
+
+Get notified when a datastore collection changes, instead of manually refreshing. **Notify-then-refetch:** the platform pushes a minimal "this collection changed" signal and your `onInvalidate` callback re-runs whatever query your component renders from. Perfect for shared-scope collections where other users' writes should appear live (leaderboards, live scores, registrations).
+
+```tsx
+import { useFiasDataStore, useDataSubscription } from '@fias/arche-sdk';
+
+function Leaderboard() {
+  const dataStore = useFiasDataStore();
+  const [rows, setRows] = useState<ScoreRow[]>([]);
+
+  const refresh = useCallback(async () => {
+    const res = await dataStore.query<ScoreRow>('scores', {
+      orderBy: { field: 'score', direction: 'desc' },
+      limit: 20,
+    });
+    setRows(res.documents.map((d) => d.data));
+  }, [dataStore]);
+
+  // Refetches automatically whenever ANY user writes to `scores`.
+  const { status } = useDataSubscription('scores', refresh);
+  // status: 'subscribing' → 'active'; 'ended' + endedReason on teardown
+}
+```
+
+**Semantics you can rely on:**
+
+- The initial refetch fires after the subscription is live, so a write racing your mount is never missed.
+- `onInvalidate` runs single-flight with one trailing call — event bursts coalesce, never parallel refetches.
+- Delivery is best-effort (events can drop or duplicate) — always treat it as "time to refetch", never as data.
+- Scope-aware: `shared` collections notify on any user's writes; `user`-scoped only on yours; `workspace`-scoped need `{ workspaceId }` and an active membership.
+- When the subscription ends (`status: 'ended'`), `endedReason` tells you why: `collection_deleted` and `authorization_revoked` are terminal; `limit`, `transport_error`, and `lease_expired` may be worth resubscribing (remount or toggle the `enabled` option).
+
+**Options:** `useDataSubscription(collection, onInvalidate, { workspaceId?, enabled? })`.
+
+**Rate limit:** subscribe handshakes 60/min (renewals are automatic and budgeted within this). Up to 32 live subscriptions per tab.
+
+### `useFiasWorkspaces()` — Team/org workspaces with roles
+
+**Permission:** `data:workspace`
+**Returns:** `FiasWorkspacesApi`
+
+Model **multi-tenant data with roles**: a _workspace_ is a tenant (team/org space) inside your arche, with role-on-edge membership. A collection created with `userScope: 'workspace'` holds documents owned by a workspace and visible to its members, gated by role. Roles are `owner` > `admin` > `member` > `viewer`:
+
+- **owner** — manage the workspace + members, read/write docs
+- **admin** — manage non-owner members, read/write docs
+- **member** — read/write docs
+- **viewer** — read docs only
+
+The creating user becomes the founding owner, and a workspace always keeps at least one owner (`MUST_KEEP_ONE_OWNER`). To read/write a workspace's documents, use `useFiasDataStore()` with the `{ workspaceId }` option (that still needs `data:store`, plus the server-side role gate).
+
+```tsx
+import { useFiasWorkspaces, useFiasDataStore } from '@fias/arche-sdk';
+
+function Team() {
+  const workspaces = useFiasWorkspaces();
+  const dataStore = useFiasDataStore();
+
+  async function setup() {
+    const ws = await workspaces.create('Acme Corp'); // caller becomes owner
+    await workspaces.addMember(ws.workspaceId, 'alice', 'member'); // members are addressed by username
+
+    // Workspace-scoped collection + document (role-gated server-side).
+    await dataStore.createCollection('ledger', { userScope: 'workspace' });
+    await dataStore.put('ledger', 'tx-1', { amount: 100 }, { workspaceId: ws.workspaceId });
+
+    // Read the workspace's ledger back: data store query with the workspace scope.
+    const securities = await dataStore.query(
+      'ledger',
+      { orderBy: { field: 'shares', direction: 'desc' } },
+      { workspaceId: ws.workspaceId },
+    );
+
+    const mine = await workspaces.list(); // workspaces I belong to
+    const members = await workspaces.listMembers(ws.workspaceId);
+  }
+}
+```
+
+**Methods:** `create`, `list`, `get`, `archive` (owner only), `listMembers`, `addMember`, `updateMember`, `removeMember`. `addMember(workspaceId, username, role, expiresAt?)` accepts an optional ISO-8601 `expiresAt` to grant **time-bounded** access (e.g. a contractor seat) — owners cannot expire; an expired member is treated as no longer a member. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -412,6 +544,73 @@ 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.
 
+### Image-editing capability hooks (auto-generated)
+
+**Permission:** `entities:image_edit`
+**Returns (per hook):** `{ invoke, isLoading, result, error }`
+
+Mask-aware AI image-editing surfaces, generated from the platform's surface registry (same typed-hook pattern as audio). The source image and mask are passed **by handle** — `{ fileId }` (a Vault Document this arche owns), `{ archeAssetId }` (a published asset), or `{ dataUrl }` (inline base64; keep it small — use a handle for large source images). The edited result is saved to the user's Vault and returned as a presigned `imageUrl` you load onto your canvas.
+
+```tsx
+import { useSmartInpaint } from '@fias/arche-sdk';
+
+const { invoke } = useSmartInpaint();
+const result = await invoke({
+  image: { fileId: sourceDocId }, // or { dataUrl } / { archeAssetId }
+  mask: { dataUrl: maskPngDataUrl }, // alpha=255 = region to replace
+  prompt: 'a field of sunflowers',
+  engine: 'stability', // 'stability' | 'recraft' | 'openai'
+});
+// result: { imageUrl, imageRef, fileId, mimeType, costCredits }
+```
+
+Long-running edits complete over WebSocket transparently — `await invoke(...)` resolves with the final result just like any other hook. Browse the full surface list with `npx fias-dev entities`.
+
+Currently shipped image-edit hooks: `useSmartInpaint` (mask replace), `useSmartErase` (mask remove + fill), `useSmartOutpaint` (extend canvas), `useSmartSearchReplace` (prompt-targeted replace, no mask), `useSmartSearchRecolor` (prompt-targeted recolor), `useSmartVectorize` (raster → SVG), `useSmartRemoveBackground` (server-side bg removal), `useSmartImageToImage` (guided regenerate), `useSmartUpscale` (resolution increase), `useSmartControl` (sketch/structure/style control), `useSmartReplaceBackground` (swap + relight background). Mask-based hooks take an `image` + `mask`; search/recolor take an `image` + a text selector; outpaint takes an `image` + edge pixels; vectorize/remove-background/upscale take an `image` (+ mode/engine); control and replace-background accept additional reference images by handle.
+
+### `useClientEntity()` — Invoke client-side (on-device) entities
+
+**Permission:** `entities:client_invoke`
+**Returns:** `ClientEntityApi`
+
+The generic surface for any client-side entity — capabilities the host runs entirely in the browser (dictionary/WASM engines). Input never leaves the device and there is no per-call cost. The on-device counterpart to `useEntityInvocation()`. Target the entity by ID and supply its documented input/output types:
+
+```tsx
+import {
+  useClientEntity,
+  GRAMMAR_CHECK_ENTITY_ID,
+  NLLB_TRANSLATION_ENTITY_ID,
+  NLLB_LANGUAGES,
+} from '@fias/arche-sdk';
+import type {
+  GrammarCheckInput,
+  GrammarCheckResult,
+  TranslateParams,
+  TranslationResult,
+} from '@fias/arche-sdk';
+
+const { invoke, isLoading, error } = useClientEntity();
+
+// Grammar & spell check (non-AI nspell + retext engine):
+const { issues } = await invoke<GrammarCheckInput, GrammarCheckResult>(GRAMMAR_CHECK_ENTITY_ID, {
+  text: 'teh quick brown fox',
+  categories: ['spelling', 'grammar', 'style', 'readability'], // optional; default = all
+  customDictionary: ['Fias'], // optional; words never flagged as misspelled
+});
+// issues: Array<{ start, end, message, category, ruleId, suggestions[] }>
+
+// On-device translation (Meta NLLB-200 via transformers.js, free; the source
+// language is auto-detected when omitted, target is a FLORES-200 code — pick
+// from the exported NLLB_LANGUAGES label/code list):
+const { translation, detectedSourceLang } = await invoke<TranslateParams, TranslationResult>(
+  NLLB_TRANSLATION_ENTITY_ID,
+  { text: 'Hello', targetLang: 'spa_Latn' }, // pass sourceLang to skip detection
+);
+```
+
+**Grammar limits:** text ≤ 100,000 characters, rate-limited to 30/min per arche per user.
+**Translation limits:** text ≤ 2,000 characters, rate-limited to 20/min per arche per user. The first call downloads the model (~600 MB, then browser-cached) and needs a reasonably capable device (~1–2 GB of browser memory); on constrained/mobile devices the load can fail — catch the error and offer `useEntityInvocation` (the AI engine) as a fallback.
+
 ### Audio capability hooks (auto-generated)
 
 **Permission:** `entities:audio_generate`
@@ -441,6 +640,23 @@ 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).
 
+### `useIntegrationWebSearch()` — Live web search
+
+**Permission:** `entities:web_search`
+**Returns:** `{ invoke, isLoading, result, error }`
+
+Search the live web and get a concise, cited summary. Backed by the swappable
+`web-search` entity (the search provider can change without your code changing). The signed-in user is charged the standard 20% markup over the raw
+search cost. Rate-limited to 10/min per arche per user.
+
+```tsx
+import { useIntegrationWebSearch } from '@fias/arche-sdk';
+
+const { invoke, isLoading, result } = useIntegrationWebSearch();
+await invoke({ query: 'latest EU AI Act enforcement dates' });
+// result: { summary, sources: [{ url, title }], searchCount, costCredits }
+```
+
 ### `useVaultDocuments()` — User-owned Vault documents
 
 **Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
@@ -499,6 +715,41 @@ await vault.detach(documentId, referenceId);
 
 **`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.
 
+### `useVaultUserDocuments()` — User-granted access to the user's own documents
+
+**Permission:** `vault:user-documents:read`
+
+The only SDK surface that reaches data your plugin did NOT create: documents the user already owns in their Vault, shared with your plugin through an explicit, per-document consent flow. `useVaultDocuments` (above) is for documents your plugin creates; this hook is for documents the _user_ brings.
+
+```tsx
+import { useVaultUserDocuments } from '@fias/arche-sdk';
+
+const userDocs = useVaultUserDocuments();
+
+// 1. Ask the user to share documents. The HOST renders its own Vault picker
+//    + consent sheet — your plugin never sees the user's vault listing, only
+//    what they hand-pick and explicitly approve. Call from a button click.
+const picked = await userDocs.pick({ maxDocuments: 5 });
+if ('canceled' in picked) {
+  // A normal outcome — the user changed their mind. Never treat as an error.
+} else {
+  // picked.documents: [{ documentId, name, mimeType, sizeBytes }]
+}
+
+// 2. Later (any session): read what was granted.
+const granted = await userDocs.list(); // all granted docs
+const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
+const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+```
+
+**The consent model (what to tell your users):**
+
+- Grants are **per-document** and **standing**: the plugin can re-read granted documents in later sessions until the user removes access in **Vault → App Access**.
+- After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
+- `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
+- Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
+- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+
 ### `useArcheAssets()` — Contributor-published asset library
 
 **Permission:** `assets:read`
@@ -579,10 +830,40 @@ function UnlockButton() {
 ```tsx
 import { useFiasNavigation } from '@fias/arche-sdk';
 
-const { navigateTo, currentPath } = useFiasNavigation();
-navigateTo('/settings');
+const { navigateTo, openArche, currentPath } = useFiasNavigation();
+navigateTo('/settings'); // within THIS arche's route space
+
+// Open ANOTHER arche's page. Requires the `navigation:open_arche` permission.
+// Pass a stable arche id (`arc_…` / `arche_…`), not a slug. `newTab` is
+// best-effort — the browser may block the popup, in which case the host
+// navigates in the same tab instead.
+openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
 ```
 
+### Opening external links
+
+To send the user to an external website (a YouTube video, docs, your homepage),
+open it in a **new tab** with the standard web API — no SDK hook or permission
+is needed:
+
+```tsx
+<button
+  onClick={() => window.open('https://youtube.com/watch?v=…', '_blank', 'noopener,noreferrer')}
+>
+  Watch the video
+</button>
+```
+
+Notes:
+
+- The plugin iframe grants `allow-popups`, so `window.open(url, '_blank')`
+  works. Opening in the **same** tab (or an `<a>` without `target="_blank"`)
+  does **not** — that would try to navigate the sandbox itself.
+- There is **no** "leaving Fias" confirmation dialog — the tab opens directly.
+  Only send users to URLs you trust, and always pass `'noopener,noreferrer'`.
+- Only `http(s)` URLs make sense here; `javascript:`/`data:` URLs are blocked
+  by the sandbox.
+
 ### `useStepNavigation()` — Multi-step workflows
 
 **Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
@@ -616,6 +897,26 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 
 **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.
 
+### `useFiasPreviewState()` — Survive builder-preview rebuilds
+
+**Permission:** none.
+
+In the arche builder, editing code (or a background cross-device sync) rebuilds the preview, which reloads the iframe and wipes the plugin's in-memory state — losing, for example, a report the user just generated. Opt that state into host-side preservation: just before the reload the host snapshots `getState()`, and after the reload it hands the value back to `onRestore`.
+
+```tsx
+import { useFiasPreviewState } from '@fias/arche-sdk';
+
+const [report, setReport] = useState<Report | null>(null);
+// `key` namespaces this slice; `getState` must return JSON-safe state.
+useFiasPreviewState(
+  'report',
+  () => report,
+  (saved) => setReport(saved as Report),
+);
+```
+
+**Inert outside the builder preview** (the host never requests a capture), so it's safe to leave in production plugin code. Use it only for expensive-to-recreate transient state — not as a substitute for `usePersistentState` (which persists across full reloads and sessions).
+
 ### `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).
@@ -667,26 +968,26 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 **Fields:**
 
-| 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                            |
+| 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   | Path to an icon image **under `public/`** (e.g. `public/icon.png`) — only `src/` and `public/` are packaged. Applied on local-dev submissions only; on staging/prod set the icon via the admin console. |
+| `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:**
 
@@ -701,7 +1002,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 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`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:image_remove_background`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
 
 **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`.
 
@@ -737,7 +1038,7 @@ Add a `products` array to declare what users can buy inside the arche. Each entr
 
 **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.
+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 read-only catalog viewers — not for collecting registrations or payments from anonymous users.
 
 ## Plugin Constraints
 
@@ -751,8 +1052,9 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 
 ### Sandboxing
 
-- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-downloads allow-popups allow-popups-to-escape-sandbox"` (note: **no** `allow-same-origin` — the plugin has an opaque origin)
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **You _can_ open external links in a new tab** (e.g. `window.open('https://…', '_blank')`) — see "Opening external links" above
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
 - All platform communication goes through the bridge (SDK hooks)
@@ -832,8 +1134,8 @@ You can choose between **Staging** and **Production** environments using the dro
 You can also authenticate via the command line:
 
 ```bash
-npx fias-dev login                    # Authenticate with staging (default)
-npx fias-dev login --env production   # Authenticate with production
+npx fias-dev login                    # Authenticate with prod (default)
+npx fias-dev login --env staging      # Authenticate with staging (internal)
 ```
 
 ### Browsing Available Entities
@@ -869,7 +1171,7 @@ happened either way).
 
 ### Managing the asset library (for `useArcheAssets`)
 
-`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <prod|staging|local>` (default `prod`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
 
 ```bash
 npx fias-dev assets enable                  # Turn on the asset library for this arche
@@ -897,7 +1199,7 @@ npx fias-dev collaborators set <identifier> \              # Change role and/or
 npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
 ```
 
-All commands accept `--env <staging|production|local>` (default `staging`).
+All commands accept `--env <prod|staging|local>` (default `prod`).
 
 ### Other CLI diagnostics
 

package/templates/default/CLAUDE.md

@@ -63,6 +63,28 @@ function MyComponent() {
 - `fonts`: `{ body, heading, mono }` (font-family strings)
 - `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
 
+### `useFiasVendoredAssets(importSpecifier)` — Self-hosted vendored-library asset URLs
+
+**Permission:** `sandbox:vendored-libraries`
+**Returns:** `Record<string, string> | null` (null when the host CDN is unconfigured or the library isn't vendored)
+
+Some heavy libraries (pdf.js today; WASM runtimes later) need a Web Worker and large asset files that a sandboxed plugin can't bundle or self-host. The platform vendors a curated set of these — version-pinned, served from its trusted CDN. A plugin opts in by (1) listing the library in its `dependencies` and (2) declaring the `sandbox:vendored-libraries` permission. The platform then widens the plugin CSP for exactly that library (e.g. pdf.js → `worker-src blob:`+CDN, `script-src`/`connect-src` CDN), pins the import specifier to the self-hosted build via the host importmap (so `import * as pdfjsLib from 'pdfjs-dist'` resolves to it), and delivers the library's asset URLs here. For `pdfjs-dist` you typically only need `worker` (feed it to `@fias/pdf-core`'s loader `workerModuleUrl`) plus `cMapUrl` / `standardFontDataUrl` for CID / non-embedded fonts.
+
+```tsx
+import { useFiasVendoredAssets } from '@fias/arche-sdk';
+import { loadPdfJs, configurePdfAssets } from '@fias/pdf-core/loader';
+
+function PdfViewer() {
+  const assets = useFiasVendoredAssets('pdfjs-dist');
+  if (!assets) return <div>PDF rendering unavailable</div>;
+  configurePdfAssets({ cMapUrl: assets.cMapUrl, standardFontDataUrl: assets.standardFontDataUrl });
+  const pdfjs = await loadPdfJs({ workerModuleUrl: assets.worker }); // off-thread worker
+  // ...render with pdfjs
+}
+```
+
+**`pdfjs-dist` asset keys:** `{ mainModule, worker, cMapUrl, standardFontDataUrl }` — all absolute CDN URLs.
+
 ### `useFiasFonts()` — Platform font catalog
 
 **Permission:** none
@@ -205,10 +227,120 @@ const doc = await fias.dataStore.get('scores', 'key');
 - 100 MB total storage per plugin
 - Max 100 results per query, max 10 filters, max field path depth 5
 
-**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `createCollection` 10
+**Atomic batch writes:** `batch(operations)` applies up to 25 put/delete ops in a **single transaction** — all-or-nothing. Use it when several writes must stay consistent (e.g. append a ledger entry AND update a running total); a sequence of separate `put`/`delete` calls can leave a half-applied state. A batch may span collections and scopes (pass `workspaceId` per op); any failure (bad key, role denial, quota) rolls the whole batch back.
+
+```tsx
+await dataStore.batch([
+  { op: 'put', collection: 'ledger', key: 'tx-42', data: { delta: 100 } },
+  { op: 'put', collection: 'totals', key: 'balance', data: { value: newBalance } },
+]);
+```
+
+**Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
 
+**Semantic search (`data:search`):** Make a collection searchable to do vector search over a text field. Declare it at creation with `searchable: { field }`, then call `search()`. Embeddings are managed by the platform — you never handle vectors or pick a model. Documents are embedded asynchronously, so a freshly-written doc becomes searchable a moment later (it's always immediately visible to `query`). The query embedding charges the caller's credits. Requires the `data:search` permission (distinct from `data:store`).
+
+```tsx
+// Create a searchable collection (embedding the `text` field) and publish docs.
+await dataStore.createCollection('recipes', { userScope: 'shared', searchable: { field: 'text' } });
+await dataStore.put('recipes', recipeId, { text: `${title} ${description}`, title, cuisine });
+
+// Semantic search (charges the caller's credits for the query embedding).
+const matches = await dataStore.search('recipes', 'quick vegetarian weeknight dinner', {
+  topK: 10,
+  filters: [{ field: 'cuisine', op: 'eq', value: 'italian' }], // vector + JSONB facet, ANDed
+});
+// matches: Array<{ key, data, similarity }>, best first
+```
+
+**Search limits:** `topK` ≤ 50, query ≤ 1024 chars, 50,000 embedded documents per arche; `search` is rate-limited to 20/min (each call embeds the query). Documents in non-searchable collections — and not-yet-embedded docs — are invisible to `search` but always returned by `query`.
+
+### `useDataSubscription()` — Realtime collection change events
+
+**Permission:** `data:store` (same as reading — live updates grant nothing polling couldn't)
+**Returns:** `DataSubscriptionState` — `{ status: 'subscribing' | 'active' | 'ended', endedReason? }`
+
+Get notified when a datastore collection changes, instead of manually refreshing. **Notify-then-refetch:** the platform pushes a minimal "this collection changed" signal and your `onInvalidate` callback re-runs whatever query your component renders from. Perfect for shared-scope collections where other users' writes should appear live (leaderboards, live scores, registrations).
+
+```tsx
+import { useFiasDataStore, useDataSubscription } from '@fias/arche-sdk';
+
+function Leaderboard() {
+  const dataStore = useFiasDataStore();
+  const [rows, setRows] = useState<ScoreRow[]>([]);
+
+  const refresh = useCallback(async () => {
+    const res = await dataStore.query<ScoreRow>('scores', {
+      orderBy: { field: 'score', direction: 'desc' },
+      limit: 20,
+    });
+    setRows(res.documents.map((d) => d.data));
+  }, [dataStore]);
+
+  // Refetches automatically whenever ANY user writes to `scores`.
+  const { status } = useDataSubscription('scores', refresh);
+  // status: 'subscribing' → 'active'; 'ended' + endedReason on teardown
+}
+```
+
+**Semantics you can rely on:**
+
+- The initial refetch fires after the subscription is live, so a write racing your mount is never missed.
+- `onInvalidate` runs single-flight with one trailing call — event bursts coalesce, never parallel refetches.
+- Delivery is best-effort (events can drop or duplicate) — always treat it as "time to refetch", never as data.
+- Scope-aware: `shared` collections notify on any user's writes; `user`-scoped only on yours; `workspace`-scoped need `{ workspaceId }` and an active membership.
+- When the subscription ends (`status: 'ended'`), `endedReason` tells you why: `collection_deleted` and `authorization_revoked` are terminal; `limit`, `transport_error`, and `lease_expired` may be worth resubscribing (remount or toggle the `enabled` option).
+
+**Options:** `useDataSubscription(collection, onInvalidate, { workspaceId?, enabled? })`.
+
+**Rate limit:** subscribe handshakes 60/min (renewals are automatic and budgeted within this). Up to 32 live subscriptions per tab.
+
+### `useFiasWorkspaces()` — Team/org workspaces with roles
+
+**Permission:** `data:workspace`
+**Returns:** `FiasWorkspacesApi`
+
+Model **multi-tenant data with roles**: a _workspace_ is a tenant (team/org space) inside your arche, with role-on-edge membership. A collection created with `userScope: 'workspace'` holds documents owned by a workspace and visible to its members, gated by role. Roles are `owner` > `admin` > `member` > `viewer`:
+
+- **owner** — manage the workspace + members, read/write docs
+- **admin** — manage non-owner members, read/write docs
+- **member** — read/write docs
+- **viewer** — read docs only
+
+The creating user becomes the founding owner, and a workspace always keeps at least one owner (`MUST_KEEP_ONE_OWNER`). To read/write a workspace's documents, use `useFiasDataStore()` with the `{ workspaceId }` option (that still needs `data:store`, plus the server-side role gate).
+
+```tsx
+import { useFiasWorkspaces, useFiasDataStore } from '@fias/arche-sdk';
+
+function Team() {
+  const workspaces = useFiasWorkspaces();
+  const dataStore = useFiasDataStore();
+
+  async function setup() {
+    const ws = await workspaces.create('Acme Corp'); // caller becomes owner
+    await workspaces.addMember(ws.workspaceId, 'alice', 'member'); // members are addressed by username
+
+    // Workspace-scoped collection + document (role-gated server-side).
+    await dataStore.createCollection('ledger', { userScope: 'workspace' });
+    await dataStore.put('ledger', 'tx-1', { amount: 100 }, { workspaceId: ws.workspaceId });
+
+    // Read the workspace's ledger back: data store query with the workspace scope.
+    const securities = await dataStore.query(
+      'ledger',
+      { orderBy: { field: 'shares', direction: 'desc' } },
+      { workspaceId: ws.workspaceId },
+    );
+
+    const mine = await workspaces.list(); // workspaces I belong to
+    const members = await workspaces.listMembers(ws.workspaceId);
+  }
+}
+```
+
+**Methods:** `create`, `list`, `get`, `archive` (owner only), `listMembers`, `addMember`, `updateMember`, `removeMember`. `addMember(workspaceId, username, role, expiresAt?)` accepts an optional ISO-8601 `expiresAt` to grant **time-bounded** access (e.g. a contractor seat) — owners cannot expire; an expired member is treated as no longer a member. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -412,6 +544,73 @@ 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.
 
+### Image-editing capability hooks (auto-generated)
+
+**Permission:** `entities:image_edit`
+**Returns (per hook):** `{ invoke, isLoading, result, error }`
+
+Mask-aware AI image-editing surfaces, generated from the platform's surface registry (same typed-hook pattern as audio). The source image and mask are passed **by handle** — `{ fileId }` (a Vault Document this arche owns), `{ archeAssetId }` (a published asset), or `{ dataUrl }` (inline base64; keep it small — use a handle for large source images). The edited result is saved to the user's Vault and returned as a presigned `imageUrl` you load onto your canvas.
+
+```tsx
+import { useSmartInpaint } from '@fias/arche-sdk';
+
+const { invoke } = useSmartInpaint();
+const result = await invoke({
+  image: { fileId: sourceDocId }, // or { dataUrl } / { archeAssetId }
+  mask: { dataUrl: maskPngDataUrl }, // alpha=255 = region to replace
+  prompt: 'a field of sunflowers',
+  engine: 'stability', // 'stability' | 'recraft' | 'openai'
+});
+// result: { imageUrl, imageRef, fileId, mimeType, costCredits }
+```
+
+Long-running edits complete over WebSocket transparently — `await invoke(...)` resolves with the final result just like any other hook. Browse the full surface list with `npx fias-dev entities`.
+
+Currently shipped image-edit hooks: `useSmartInpaint` (mask replace), `useSmartErase` (mask remove + fill), `useSmartOutpaint` (extend canvas), `useSmartSearchReplace` (prompt-targeted replace, no mask), `useSmartSearchRecolor` (prompt-targeted recolor), `useSmartVectorize` (raster → SVG), `useSmartRemoveBackground` (server-side bg removal), `useSmartImageToImage` (guided regenerate), `useSmartUpscale` (resolution increase), `useSmartControl` (sketch/structure/style control), `useSmartReplaceBackground` (swap + relight background). Mask-based hooks take an `image` + `mask`; search/recolor take an `image` + a text selector; outpaint takes an `image` + edge pixels; vectorize/remove-background/upscale take an `image` (+ mode/engine); control and replace-background accept additional reference images by handle.
+
+### `useClientEntity()` — Invoke client-side (on-device) entities
+
+**Permission:** `entities:client_invoke`
+**Returns:** `ClientEntityApi`
+
+The generic surface for any client-side entity — capabilities the host runs entirely in the browser (dictionary/WASM engines). Input never leaves the device and there is no per-call cost. The on-device counterpart to `useEntityInvocation()`. Target the entity by ID and supply its documented input/output types:
+
+```tsx
+import {
+  useClientEntity,
+  GRAMMAR_CHECK_ENTITY_ID,
+  NLLB_TRANSLATION_ENTITY_ID,
+  NLLB_LANGUAGES,
+} from '@fias/arche-sdk';
+import type {
+  GrammarCheckInput,
+  GrammarCheckResult,
+  TranslateParams,
+  TranslationResult,
+} from '@fias/arche-sdk';
+
+const { invoke, isLoading, error } = useClientEntity();
+
+// Grammar & spell check (non-AI nspell + retext engine):
+const { issues } = await invoke<GrammarCheckInput, GrammarCheckResult>(GRAMMAR_CHECK_ENTITY_ID, {
+  text: 'teh quick brown fox',
+  categories: ['spelling', 'grammar', 'style', 'readability'], // optional; default = all
+  customDictionary: ['Fias'], // optional; words never flagged as misspelled
+});
+// issues: Array<{ start, end, message, category, ruleId, suggestions[] }>
+
+// On-device translation (Meta NLLB-200 via transformers.js, free; the source
+// language is auto-detected when omitted, target is a FLORES-200 code — pick
+// from the exported NLLB_LANGUAGES label/code list):
+const { translation, detectedSourceLang } = await invoke<TranslateParams, TranslationResult>(
+  NLLB_TRANSLATION_ENTITY_ID,
+  { text: 'Hello', targetLang: 'spa_Latn' }, // pass sourceLang to skip detection
+);
+```
+
+**Grammar limits:** text ≤ 100,000 characters, rate-limited to 30/min per arche per user.
+**Translation limits:** text ≤ 2,000 characters, rate-limited to 20/min per arche per user. The first call downloads the model (~600 MB, then browser-cached) and needs a reasonably capable device (~1–2 GB of browser memory); on constrained/mobile devices the load can fail — catch the error and offer `useEntityInvocation` (the AI engine) as a fallback.
+
 ### Audio capability hooks (auto-generated)
 
 **Permission:** `entities:audio_generate`
@@ -441,6 +640,23 @@ 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).
 
+### `useIntegrationWebSearch()` — Live web search
+
+**Permission:** `entities:web_search`
+**Returns:** `{ invoke, isLoading, result, error }`
+
+Search the live web and get a concise, cited summary. Backed by the swappable
+`web-search` entity (the search provider can change without your code changing). The signed-in user is charged the standard 20% markup over the raw
+search cost. Rate-limited to 10/min per arche per user.
+
+```tsx
+import { useIntegrationWebSearch } from '@fias/arche-sdk';
+
+const { invoke, isLoading, result } = useIntegrationWebSearch();
+await invoke({ query: 'latest EU AI Act enforcement dates' });
+// result: { summary, sources: [{ url, title }], searchCount, costCredits }
+```
+
 ### `useVaultDocuments()` — User-owned Vault documents
 
 **Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
@@ -499,6 +715,41 @@ await vault.detach(documentId, referenceId);
 
 **`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.
 
+### `useVaultUserDocuments()` — User-granted access to the user's own documents
+
+**Permission:** `vault:user-documents:read`
+
+The only SDK surface that reaches data your plugin did NOT create: documents the user already owns in their Vault, shared with your plugin through an explicit, per-document consent flow. `useVaultDocuments` (above) is for documents your plugin creates; this hook is for documents the _user_ brings.
+
+```tsx
+import { useVaultUserDocuments } from '@fias/arche-sdk';
+
+const userDocs = useVaultUserDocuments();
+
+// 1. Ask the user to share documents. The HOST renders its own Vault picker
+//    + consent sheet — your plugin never sees the user's vault listing, only
+//    what they hand-pick and explicitly approve. Call from a button click.
+const picked = await userDocs.pick({ maxDocuments: 5 });
+if ('canceled' in picked) {
+  // A normal outcome — the user changed their mind. Never treat as an error.
+} else {
+  // picked.documents: [{ documentId, name, mimeType, sizeBytes }]
+}
+
+// 2. Later (any session): read what was granted.
+const granted = await userDocs.list(); // all granted docs
+const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
+const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+```
+
+**The consent model (what to tell your users):**
+
+- Grants are **per-document** and **standing**: the plugin can re-read granted documents in later sessions until the user removes access in **Vault → App Access**.
+- After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
+- `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
+- Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
+- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+
 ### `useArcheAssets()` — Contributor-published asset library
 
 **Permission:** `assets:read`
@@ -579,10 +830,40 @@ function UnlockButton() {
 ```tsx
 import { useFiasNavigation } from '@fias/arche-sdk';
 
-const { navigateTo, currentPath } = useFiasNavigation();
-navigateTo('/settings');
+const { navigateTo, openArche, currentPath } = useFiasNavigation();
+navigateTo('/settings'); // within THIS arche's route space
+
+// Open ANOTHER arche's page. Requires the `navigation:open_arche` permission.
+// Pass a stable arche id (`arc_…` / `arche_…`), not a slug. `newTab` is
+// best-effort — the browser may block the popup, in which case the host
+// navigates in the same tab instead.
+openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
 ```
 
+### Opening external links
+
+To send the user to an external website (a YouTube video, docs, your homepage),
+open it in a **new tab** with the standard web API — no SDK hook or permission
+is needed:
+
+```tsx
+<button
+  onClick={() => window.open('https://youtube.com/watch?v=…', '_blank', 'noopener,noreferrer')}
+>
+  Watch the video
+</button>
+```
+
+Notes:
+
+- The plugin iframe grants `allow-popups`, so `window.open(url, '_blank')`
+  works. Opening in the **same** tab (or an `<a>` without `target="_blank"`)
+  does **not** — that would try to navigate the sandbox itself.
+- There is **no** "leaving Fias" confirmation dialog — the tab opens directly.
+  Only send users to URLs you trust, and always pass `'noopener,noreferrer'`.
+- Only `http(s)` URLs make sense here; `javascript:`/`data:` URLs are blocked
+  by the sandbox.
+
 ### `useStepNavigation()` — Multi-step workflows
 
 **Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
@@ -616,6 +897,26 @@ const [count, setCount] = usePersistentState<number>('counter', 0);
 
 **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.
 
+### `useFiasPreviewState()` — Survive builder-preview rebuilds
+
+**Permission:** none.
+
+In the arche builder, editing code (or a background cross-device sync) rebuilds the preview, which reloads the iframe and wipes the plugin's in-memory state — losing, for example, a report the user just generated. Opt that state into host-side preservation: just before the reload the host snapshots `getState()`, and after the reload it hands the value back to `onRestore`.
+
+```tsx
+import { useFiasPreviewState } from '@fias/arche-sdk';
+
+const [report, setReport] = useState<Report | null>(null);
+// `key` namespaces this slice; `getState` must return JSON-safe state.
+useFiasPreviewState(
+  'report',
+  () => report,
+  (saved) => setReport(saved as Report),
+);
+```
+
+**Inert outside the builder preview** (the host never requests a capture), so it's safe to leave in production plugin code. Use it only for expensive-to-recreate transient state — not as a substitute for `usePersistentState` (which persists across full reloads and sessions).
+
 ### `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).
@@ -667,26 +968,26 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 **Fields:**
 
-| 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                            |
+| 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   | Path to an icon image **under `public/`** (e.g. `public/icon.png`) — only `src/` and `public/` are packaged. Applied on local-dev submissions only; on staging/prod set the icon via the admin console. |
+| `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:**
 
@@ -701,7 +1002,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 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`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:image_remove_background`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
 
 **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`.
 
@@ -737,7 +1038,7 @@ Add a `products` array to declare what users can buy inside the arche. Each entr
 
 **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.
+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 read-only catalog viewers — not for collecting registrations or payments from anonymous users.
 
 ## Plugin Constraints
 
@@ -751,8 +1052,9 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 
 ### Sandboxing
 
-- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-same-origin allow-downloads"`
+- Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-downloads allow-popups allow-popups-to-escape-sandbox"` (note: **no** `allow-same-origin` — the plugin has an opaque origin)
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
+- **You _can_ open external links in a new tab** (e.g. `window.open('https://…', '_blank')`) — see "Opening external links" above
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
 - All platform communication goes through the bridge (SDK hooks)
@@ -832,8 +1134,8 @@ You can choose between **Staging** and **Production** environments using the dro
 You can also authenticate via the command line:
 
 ```bash
-npx fias-dev login                    # Authenticate with staging (default)
-npx fias-dev login --env production   # Authenticate with production
+npx fias-dev login                    # Authenticate with prod (default)
+npx fias-dev login --env staging      # Authenticate with staging (internal)
 ```
 
 ### Browsing Available Entities
@@ -869,7 +1171,7 @@ happened either way).
 
 ### Managing the asset library (for `useArcheAssets`)
 
-`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <staging|prod|local>` (default `staging`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
+`useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <prod|staging|local>` (default `prod`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
 
 ```bash
 npx fias-dev assets enable                  # Turn on the asset library for this arche
@@ -897,7 +1199,7 @@ npx fias-dev collaborators set <identifier> \              # Change role and/or
 npx fias-dev collaborators remove <identifier>             # Revoke a collaborator
 ```
 
-All commands accept `--env <staging|production|local>` (default `staging`).
+All commands accept `--env <prod|staging|local>` (default `prod`).
 
 ### Other CLI diagnostics