@fias/create-fias-plugin 1.4.3 → 1.6.0

package/package.json

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

package/templates/default/AGENTS.md

@@ -179,7 +179,9 @@ import { useFiasDataStore } from '@fias/arche-sdk';
 function MyComponent() {
   const dataStore = useFiasDataStore();
 
-  // Collection management
+  // Collection management. PREFER declaring collections in fias-plugin.json
+  // (see "Declaring your collections" below) — createCollection is capped at
+  // 10/minute, so scaffolding several at startup can silently lose the tail.
   await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
   const collections = await dataStore.listCollections();
   await dataStore.deleteCollection('scores');
@@ -236,6 +238,24 @@ await dataStore.batch([
 ]);
 ```
 
+### Declaring your collections (preferred)
+
+List the collections your plugin needs in `fias-plugin.json` and the platform creates them once at publish, before your plugin ever runs:
+
+```jsonc
+"collections": [
+  { "name": "scores", "scope": "user" },
+  { "name": "ledger", "scope": "workspace", "readMinRole": "member" },
+  { "name": "recipes", "scope": "shared", "writePolicy": "author", "searchable": { "field": "text" } }
+]
+```
+
+`scope` is `user` | `shared` | `workspace`. `readMinRole` / `writeMinRole` are workspace-only; `writePolicy` is shared-only; `searchable` names the text field to embed. Same options as `createCollection`, checked by `fias-dev validate` before you publish.
+
+Why this and not `createCollection` at startup: the runtime op is capped at **10 per minute** while an arche may hold **50** collections, so a plugin creating several on mount can exceed the cap and lose the rest **with no error** — surfacing later as `COLLECTION_NOT_FOUND` on an unrelated call. Declaring has no such window, and a mistake fails your publish instead of a user's session.
+
+Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
+
 **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`.
@@ -724,6 +744,7 @@ if ('canceled' in picked) {
 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)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -732,7 +753,55 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - 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.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
+- **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
+
+### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
+
+**Permission:** `ai:actions`
+
+The platform assistant (the Fias AI button in the host header) can perform actions inside your plugin — but only ones you declare. Declared actions become the assistant's tools while your plugin is open; a user can say "rotate the selected pages" and the assistant calls your handler.
+
+There are two declaration lanes, one shape:
+
+- **Manifest (static, every plugin):** a `fiasAI: { description, actions: [...] }` block in `fias-plugin.json`. Fixed at publish and reviewed with your submission.
+- **Runtime (this hook, trusted arches only):** declare/extend actions from code. The host silently ignores runtime declarations from non-trusted arches — manifest actions still work there, and this hook still handles their dispatches.
+
+```tsx
+import { useFiasAIActions } from '@fias/arche-sdk';
+
+useFiasAIActions({
+  description: 'Once a document is open, the assistant can rotate its pages.',
+  actions: [
+    {
+      id: 'rotate_pages', // lowercase snake_case — becomes the tool name
+      description: 'Rotate the selected pages 90° clockwise.',
+      parameterSchema: { type: 'object', properties: {} },
+      availableWhen: { documentOpen: true }, // hidden until the state says so
+    },
+  ],
+  state: { documentOpen: doc !== null }, // small, flag-shaped — NOT your data
+  onAction: async (actionId, params) => {
+    if (actionId === 'rotate_pages') {
+      if (!doc) throw new Error('No document is open.'); // ALWAYS re-check
+      await rotateSelected();
+      return;
+    }
+    throw new Error(`Unknown action ${actionId}`);
+  },
+});
+```
+
+Rules that matter:
+
+- **Throw to report failure.** The assistant awaits `onAction` before telling the model the action applied — a batch ("do this to each file") stops on the failing step only if you throw.
+- **Re-check preconditions in `onAction`.** `availableWhen` filtering is presentation; a stale turn can still dispatch a hidden verb.
+- **Keep `state` tiny** (`{documentOpen: true}`, `hasPages: true`) — it is embedded in the assistant's prompt every turn and oversized snapshots are dropped.
+- **UI state only.** Actions manipulate what the user could do in your interface; anything touching server state stays in your own code paths.
+- `requiresConfirmation: true` makes the assistant ask the user before dispatching. It escalates only — nothing can skip a confirmation the platform requires.
+- Manifest actions win id collisions with runtime ones; the merged list is capped at 50.
+- The assistant is not present in the builder preview or the dev harness — declarations are accepted but nothing dispatches until the published plugin runs with the Fias AI window.
 
 ### `useArcheAssets()` — Contributor-published asset library
 
@@ -756,6 +825,40 @@ const fresh = await getUrl(assetId);
 
 Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
 
+### `useCommunityAssets()` — User-published images, visible to this arche's users
+
+**Permissions:** `assets:community:read` (browse/view) · `assets:community:publish` (publish/unpublish/listMine)
+**Returns:** `CommunityAssetsApi`
+
+The only way one user's content reaches another user. A user publishes an image **they created here**, and after moderation every authenticated user of **this arche** (and no other) can see it. Free to publish.
+
+```tsx
+import { useCommunityAssets, useImageGeneration } from '@fias/arche-sdk';
+
+const { publish, publishMany, listCommunity, listMine, getUrls, unpublish } = useCommunityAssets();
+const { generate } = useImageGeneration();
+
+// 1. The user makes something, then shares it
+const image = await generate({ prompt: 'a sleepy blue whale' });
+const asset = await publish({ fileId: image.fileId, title: 'Sleepy whale', tags: ['page-art'] });
+// asset.status === 'pending_moderation'  ← NOT visible to others yet
+
+// 2. Browse what the community published
+const { assets, nextCursor } = await listCommunity({ limit: 30, tag: 'page-art' });
+
+// 3. Sign a whole gallery in ONE call (URLs last ~5 min; the hook refreshes them)
+const urls = await getUrls(assets.map((a) => a.assetId));
+// urls[i]: { assetId, url, expiresAt }  → drop straight into <img src={url} />
+```
+
+Three things to design around:
+
+1. **Publishing is not instant.** `publish()` returns `status: 'pending_moderation'`. It shows up in `listCommunity()` only once approved — so show the author their own pending item via `listMine()` instead of optimistically adding it to the community feed.
+2. **Batch your URLs.** Use `getUrls()` for a gallery or a multi-page book. Thirteen separate `getUrl()` calls against a ~5-minute TTL is the shape this exists to avoid. Ids that were taken down or aren't published yet are simply omitted — render around the gap.
+3. **Structure goes in the Data Store.** Which asset belongs on which page/level lives in a `shared`-scope Data Store collection holding `assetId`s. Community Assets stores the bytes and nothing queryable — `tags` plus cursor paging is the whole query surface, deliberately.
+
+Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -925,6 +1028,91 @@ await fias.dataStore.listCollections();
 await fias.dataStore.deleteCollection('scores');
 ```
 
+### Panels (dialogs, reward popups, empty states)
+
+A **panel** is a bounded block of declarative content — a title, an ordered list of leaf
+elements, some buttons. The platform ships a shared renderer, `@fias/panel-kit`, from its own
+CDN, so you get the same dialog/reward-popup look as first-party arches without writing modal,
+scrim or focus-trap code.
+
+**Opt in** with a permission and a dependency (the platform serves the module; do NOT install it
+from npm — it isn't there):
+
+```json
+// fias-plugin.json
+{
+  "permissions": ["sandbox:vendored-libraries"],
+  "dependencies": { "@fias/panel-kit": "0.3.0" }
+}
+```
+
+The build **pins the version from the platform registry and rejects a manifest that declares a
+different one**, with the exact string to write. When a new panel-kit ships, bump this on your
+next submission — already-published builds keep resolving the version they were built against.
+
+**Render one.** Inline is just a component; modal goes through the host:
+
+```tsx
+import { Panel, PanelHost, usePanel } from '@fias/panel-kit';
+
+// Inline — in the page's normal flow.
+<Panel definition={definition} context={{ values: { score }, items }} onAction={handleAction} />;
+
+// Modal — mount <PanelHost> once near your app root, then:
+const { showPanel } = usePanel();
+const outcome = await showPanel(definition, { context: { values, items } });
+if (outcome.type === 'emit' && outcome.token === 'restart') restart();
+```
+
+`onAction` / the resolved outcome hands you the parsed intent — the renderer never navigates. A
+button's `action` is a closed namespace: `close`, `emit:<token>` (your own verb, handed back to
+you), `open_arche:arc_<32 hex>`, `open_url:https://…`.
+
+**Elements** are leaf kinds only — no nesting, no layout algebra, no conditionals beyond one
+truthiness check:
+
+| Kind              | What it draws                                                                     |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `text`            | Plain text; `{placeholder}` tokens fill from `context.values`. Never HTML.        |
+| `conditionalText` | The same, only when `context.values[showIf]` is truthy. `showIf` is a value NAME. |
+| `image`           | A platform storage key the host resolves.                                         |
+| `assetImage`      | An arche asset-library id (`as_…`).                                               |
+| `items`           | `context.items` — the list you pass at render time.                               |
+| `slottedItems`    | `context.itemsBySlot[slot]` — several independent lists in one panel.             |
+| `button`          | Label + action.                                                                   |
+| `spacer`          | Vertical whitespace.                                                              |
+
+Both text kinds take `joinNext: true` to share a line with the element after them
+(`Base Reward: [icon] Fabricanse ×1`).
+
+**Theming.** A `theme` sets colours, font, radii, spacing and the quantity format. Pass it to the
+presenter — not to a wrapping element — because the modal portals out of your subtree:
+
+```tsx
+<PanelHost theme={{ bg: '#F6EAD2', accent: '#D8B24A', amountFormat: '×{n}' }} />
+```
+
+Values are grammars, not free CSS: hex or `rgb()/rgba()` colours, `px`/`rem`/`em` lengths, a font
+stack with no parentheses. Anything else is dropped (a `url()` in a custom property would make
+every panel you draw fetch a third-party asset).
+
+**Panels as DATA.** If your panels live in storage rather than in code — a `dataStore` document,
+an admin-edited blob — validate on the WRITE, using the same rules the platform enforces:
+
+```ts
+import { validatePanelCatalog } from '@fias/arche-sdk';
+
+const result = validatePanelCatalog(draft); // { panels: [...], theme?: {...} }
+if (!result.ok) return showErrors(result.issues); // one message per problem, path-prefixed
+await fias.dataStore.put('panels', 'catalog', draft);
+```
+
+That is the whole pattern for server-driven panel content: **your existing storage plus a shared
+validator** — no new permission, no platform call. Changing a panel's wording then means editing
+a document, not shipping a release. `validatePanelDefinition` and `validatePanelTheme` validate
+the parts individually; the types (`PanelDefinition`, `PanelElement`, `PanelTheme`, `PanelCatalog`)
+come from `@fias/arche-sdk` too, so the shape you store is the shape the renderer takes.
+
 ### Advanced exports (rarely needed)
 
 The SDK also exports the following for advanced use cases. Most plugins don't need them.

package/templates/default/CLAUDE.md

@@ -179,7 +179,9 @@ import { useFiasDataStore } from '@fias/arche-sdk';
 function MyComponent() {
   const dataStore = useFiasDataStore();
 
-  // Collection management
+  // Collection management. PREFER declaring collections in fias-plugin.json
+  // (see "Declaring your collections" below) — createCollection is capped at
+  // 10/minute, so scaffolding several at startup can silently lose the tail.
   await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
   const collections = await dataStore.listCollections();
   await dataStore.deleteCollection('scores');
@@ -236,6 +238,24 @@ await dataStore.batch([
 ]);
 ```
 
+### Declaring your collections (preferred)
+
+List the collections your plugin needs in `fias-plugin.json` and the platform creates them once at publish, before your plugin ever runs:
+
+```jsonc
+"collections": [
+  { "name": "scores", "scope": "user" },
+  { "name": "ledger", "scope": "workspace", "readMinRole": "member" },
+  { "name": "recipes", "scope": "shared", "writePolicy": "author", "searchable": { "field": "text" } }
+]
+```
+
+`scope` is `user` | `shared` | `workspace`. `readMinRole` / `writeMinRole` are workspace-only; `writePolicy` is shared-only; `searchable` names the text field to embed. Same options as `createCollection`, checked by `fias-dev validate` before you publish.
+
+Why this and not `createCollection` at startup: the runtime op is capped at **10 per minute** while an arche may hold **50** collections, so a plugin creating several on mount can exceed the cap and lose the rest **with no error** — surfacing later as `COLLECTION_NOT_FOUND` on an unrelated call. Declaring has no such window, and a mistake fails your publish instead of a user's session.
+
+Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
+
 **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`.
@@ -724,6 +744,7 @@ if ('canceled' in picked) {
 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)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -732,7 +753,55 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - 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.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
+- **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
+
+### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
+
+**Permission:** `ai:actions`
+
+The platform assistant (the Fias AI button in the host header) can perform actions inside your plugin — but only ones you declare. Declared actions become the assistant's tools while your plugin is open; a user can say "rotate the selected pages" and the assistant calls your handler.
+
+There are two declaration lanes, one shape:
+
+- **Manifest (static, every plugin):** a `fiasAI: { description, actions: [...] }` block in `fias-plugin.json`. Fixed at publish and reviewed with your submission.
+- **Runtime (this hook, trusted arches only):** declare/extend actions from code. The host silently ignores runtime declarations from non-trusted arches — manifest actions still work there, and this hook still handles their dispatches.
+
+```tsx
+import { useFiasAIActions } from '@fias/arche-sdk';
+
+useFiasAIActions({
+  description: 'Once a document is open, the assistant can rotate its pages.',
+  actions: [
+    {
+      id: 'rotate_pages', // lowercase snake_case — becomes the tool name
+      description: 'Rotate the selected pages 90° clockwise.',
+      parameterSchema: { type: 'object', properties: {} },
+      availableWhen: { documentOpen: true }, // hidden until the state says so
+    },
+  ],
+  state: { documentOpen: doc !== null }, // small, flag-shaped — NOT your data
+  onAction: async (actionId, params) => {
+    if (actionId === 'rotate_pages') {
+      if (!doc) throw new Error('No document is open.'); // ALWAYS re-check
+      await rotateSelected();
+      return;
+    }
+    throw new Error(`Unknown action ${actionId}`);
+  },
+});
+```
+
+Rules that matter:
+
+- **Throw to report failure.** The assistant awaits `onAction` before telling the model the action applied — a batch ("do this to each file") stops on the failing step only if you throw.
+- **Re-check preconditions in `onAction`.** `availableWhen` filtering is presentation; a stale turn can still dispatch a hidden verb.
+- **Keep `state` tiny** (`{documentOpen: true}`, `hasPages: true`) — it is embedded in the assistant's prompt every turn and oversized snapshots are dropped.
+- **UI state only.** Actions manipulate what the user could do in your interface; anything touching server state stays in your own code paths.
+- `requiresConfirmation: true` makes the assistant ask the user before dispatching. It escalates only — nothing can skip a confirmation the platform requires.
+- Manifest actions win id collisions with runtime ones; the merged list is capped at 50.
+- The assistant is not present in the builder preview or the dev harness — declarations are accepted but nothing dispatches until the published plugin runs with the Fias AI window.
 
 ### `useArcheAssets()` — Contributor-published asset library
 
@@ -756,6 +825,40 @@ const fresh = await getUrl(assetId);
 
 Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
 
+### `useCommunityAssets()` — User-published images, visible to this arche's users
+
+**Permissions:** `assets:community:read` (browse/view) · `assets:community:publish` (publish/unpublish/listMine)
+**Returns:** `CommunityAssetsApi`
+
+The only way one user's content reaches another user. A user publishes an image **they created here**, and after moderation every authenticated user of **this arche** (and no other) can see it. Free to publish.
+
+```tsx
+import { useCommunityAssets, useImageGeneration } from '@fias/arche-sdk';
+
+const { publish, publishMany, listCommunity, listMine, getUrls, unpublish } = useCommunityAssets();
+const { generate } = useImageGeneration();
+
+// 1. The user makes something, then shares it
+const image = await generate({ prompt: 'a sleepy blue whale' });
+const asset = await publish({ fileId: image.fileId, title: 'Sleepy whale', tags: ['page-art'] });
+// asset.status === 'pending_moderation'  ← NOT visible to others yet
+
+// 2. Browse what the community published
+const { assets, nextCursor } = await listCommunity({ limit: 30, tag: 'page-art' });
+
+// 3. Sign a whole gallery in ONE call (URLs last ~5 min; the hook refreshes them)
+const urls = await getUrls(assets.map((a) => a.assetId));
+// urls[i]: { assetId, url, expiresAt }  → drop straight into <img src={url} />
+```
+
+Three things to design around:
+
+1. **Publishing is not instant.** `publish()` returns `status: 'pending_moderation'`. It shows up in `listCommunity()` only once approved — so show the author their own pending item via `listMine()` instead of optimistically adding it to the community feed.
+2. **Batch your URLs.** Use `getUrls()` for a gallery or a multi-page book. Thirteen separate `getUrl()` calls against a ~5-minute TTL is the shape this exists to avoid. Ids that were taken down or aren't published yet are simply omitted — render around the gap.
+3. **Structure goes in the Data Store.** Which asset belongs on which page/level lives in a `shared`-scope Data Store collection holding `assetId`s. Community Assets stores the bytes and nothing queryable — `tags` plus cursor paging is the whole query surface, deliberately.
+
+Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -925,6 +1028,91 @@ await fias.dataStore.listCollections();
 await fias.dataStore.deleteCollection('scores');
 ```
 
+### Panels (dialogs, reward popups, empty states)
+
+A **panel** is a bounded block of declarative content — a title, an ordered list of leaf
+elements, some buttons. The platform ships a shared renderer, `@fias/panel-kit`, from its own
+CDN, so you get the same dialog/reward-popup look as first-party arches without writing modal,
+scrim or focus-trap code.
+
+**Opt in** with a permission and a dependency (the platform serves the module; do NOT install it
+from npm — it isn't there):
+
+```json
+// fias-plugin.json
+{
+  "permissions": ["sandbox:vendored-libraries"],
+  "dependencies": { "@fias/panel-kit": "0.3.0" }
+}
+```
+
+The build **pins the version from the platform registry and rejects a manifest that declares a
+different one**, with the exact string to write. When a new panel-kit ships, bump this on your
+next submission — already-published builds keep resolving the version they were built against.
+
+**Render one.** Inline is just a component; modal goes through the host:
+
+```tsx
+import { Panel, PanelHost, usePanel } from '@fias/panel-kit';
+
+// Inline — in the page's normal flow.
+<Panel definition={definition} context={{ values: { score }, items }} onAction={handleAction} />;
+
+// Modal — mount <PanelHost> once near your app root, then:
+const { showPanel } = usePanel();
+const outcome = await showPanel(definition, { context: { values, items } });
+if (outcome.type === 'emit' && outcome.token === 'restart') restart();
+```
+
+`onAction` / the resolved outcome hands you the parsed intent — the renderer never navigates. A
+button's `action` is a closed namespace: `close`, `emit:<token>` (your own verb, handed back to
+you), `open_arche:arc_<32 hex>`, `open_url:https://…`.
+
+**Elements** are leaf kinds only — no nesting, no layout algebra, no conditionals beyond one
+truthiness check:
+
+| Kind              | What it draws                                                                     |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `text`            | Plain text; `{placeholder}` tokens fill from `context.values`. Never HTML.        |
+| `conditionalText` | The same, only when `context.values[showIf]` is truthy. `showIf` is a value NAME. |
+| `image`           | A platform storage key the host resolves.                                         |
+| `assetImage`      | An arche asset-library id (`as_…`).                                               |
+| `items`           | `context.items` — the list you pass at render time.                               |
+| `slottedItems`    | `context.itemsBySlot[slot]` — several independent lists in one panel.             |
+| `button`          | Label + action.                                                                   |
+| `spacer`          | Vertical whitespace.                                                              |
+
+Both text kinds take `joinNext: true` to share a line with the element after them
+(`Base Reward: [icon] Fabricanse ×1`).
+
+**Theming.** A `theme` sets colours, font, radii, spacing and the quantity format. Pass it to the
+presenter — not to a wrapping element — because the modal portals out of your subtree:
+
+```tsx
+<PanelHost theme={{ bg: '#F6EAD2', accent: '#D8B24A', amountFormat: '×{n}' }} />
+```
+
+Values are grammars, not free CSS: hex or `rgb()/rgba()` colours, `px`/`rem`/`em` lengths, a font
+stack with no parentheses. Anything else is dropped (a `url()` in a custom property would make
+every panel you draw fetch a third-party asset).
+
+**Panels as DATA.** If your panels live in storage rather than in code — a `dataStore` document,
+an admin-edited blob — validate on the WRITE, using the same rules the platform enforces:
+
+```ts
+import { validatePanelCatalog } from '@fias/arche-sdk';
+
+const result = validatePanelCatalog(draft); // { panels: [...], theme?: {...} }
+if (!result.ok) return showErrors(result.issues); // one message per problem, path-prefixed
+await fias.dataStore.put('panels', 'catalog', draft);
+```
+
+That is the whole pattern for server-driven panel content: **your existing storage plus a shared
+validator** — no new permission, no platform call. Changing a panel's wording then means editing
+a document, not shipping a release. `validatePanelDefinition` and `validatePanelTheme` validate
+the parts individually; the types (`PanelDefinition`, `PanelElement`, `PanelTheme`, `PanelCatalog`)
+come from `@fias/arche-sdk` too, so the shape you store is the shape the renderer takes.
+
 ### Advanced exports (rarely needed)
 
 The SDK also exports the following for advanced use cases. Most plugins don't need them.