@fias/arche-sdk 2.26.0 → 2.27.0

package/dist/generated/permissions.d.ts

@@ -9,7 +9,7 @@
  * `tests/architecture/sdk-permissions-match-db-types.test.ts` ensures
  * this file stays in lockstep with the canonical source.
  */
-export type PluginPermission = 'ai:actions' | 'assets:community:publish' | 'assets:community:read' | 'assets:read' | 'data:search' | 'data:store' | 'data:workspace' | 'docsign:envelopes:read' | 'email:company:send' | 'entities:audio_generate' | 'entities:client_invoke' | 'entities:image_edit' | 'entities:image_generate' | 'entities:invoke' | 'entities:web_search' | 'navigation:open_arche' | 'sandbox:vendored-libraries' | 'storage:sandbox' | 'store:purchase' | 'theme:read' | 'user:profile:read' | 'vault:arche-saves:write' | 'vault:documents:read' | 'vault:documents:write' | 'vault:user-documents:edit' | 'vault:user-documents:read' | 'vault:user-documents:write' | 'vault:workspace-documents:read';
+export type PluginPermission = 'ai:actions' | 'assets:community:publish' | 'assets:community:read' | 'assets:read' | 'data:agents' | 'data:search' | 'data:store' | 'data:workspace' | 'docsign:envelopes:read' | 'email:company:send' | 'entities:audio_generate' | 'entities:client_invoke' | 'entities:image_edit' | 'entities:image_generate' | 'entities:invoke' | 'entities:web_search' | 'navigation:open_arche' | 'sandbox:vendored-libraries' | 'storage:sandbox' | 'store:purchase' | 'theme:read' | 'user:profile:read' | 'vault:arche-saves:write' | 'vault:documents:read' | 'vault:documents:write' | 'vault:user-documents:edit' | 'vault:user-documents:read' | 'vault:user-documents:write' | 'vault:workspace-documents:read';
 export declare const VALID_PLUGIN_PERMISSIONS: readonly PluginPermission[];
 export declare function isValidPluginPermission(perm: string): perm is PluginPermission;
 /**

package/dist/generated/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,0BAA0B,GAC1B,uBAAuB,GACvB,aAAa,GACb,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,wBAAwB,GACxB,oBAAoB,GACpB,yBAAyB,GACzB,wBAAwB,GACxB,qBAAqB,GACrB,yBAAyB,GACzB,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,4BAA4B,GAC5B,iBAAiB,GACjB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,yBAAyB,GACzB,sBAAsB,GACtB,uBAAuB,GACvB,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,GAC5B,gCAAgC,CAAC;AAErC,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EA6BtD,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAE9E;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAwCrF,CAAC"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,0BAA0B,GAC1B,uBAAuB,GACvB,aAAa,GACb,aAAa,GACb,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,wBAAwB,GACxB,oBAAoB,GACpB,yBAAyB,GACzB,wBAAwB,GACxB,qBAAqB,GACrB,yBAAyB,GACzB,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,4BAA4B,GAC5B,iBAAiB,GACjB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,yBAAyB,GACzB,sBAAsB,GACtB,uBAAuB,GACvB,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,GAC5B,gCAAgC,CAAC;AAErC,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EA8BtD,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAE9E;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CA0CrF,CAAC"}

package/dist/generated/permissions.js

@@ -18,6 +18,7 @@ exports.VALID_PLUGIN_PERMISSIONS = [
     'assets:community:publish',
     'assets:community:read',
     'assets:read',
+    'data:agents',
     'data:search',
     'data:store',
     'data:workspace',
@@ -56,6 +57,7 @@ exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
     'assets:community:publish': 'Share images you made here so other people using this arche can see them, and manage what you have shared.',
     'assets:community:read': 'Show you images that other people using this arche have shared. Everything shared is checked before anyone can see it.',
     'assets:read': "Show images from this arche's published asset library.",
+    'data:agents': "Let Fias AI, and assistants you connect with an API key and allow here, read this arche's data — and change it where it says so — even while it is closed.",
     'data:search': "Search this arche's own data semantically — costs credits per search.",
     'data:store': "Save structured data in this arche's own private database.",
     'data:workspace': 'Create team workspaces and manage their members.',

package/dist/generated/permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AA+DH,0DAEC;AAjCY,QAAA,wBAAwB,GAAgC;IACnE,YAAY;IACZ,0BAA0B;IAC1B,uBAAuB;IACvB,aAAa;IACb,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,wBAAwB;IACxB,oBAAoB;IACpB,yBAAyB;IACzB,wBAAwB;IACxB,qBAAqB;IACrB,yBAAyB;IACzB,iBAAiB;IACjB,qBAAqB;IACrB,uBAAuB;IACvB,4BAA4B;IAC5B,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;IACZ,mBAAmB;IACnB,yBAAyB;IACzB,sBAAsB;IACtB,uBAAuB;IACvB,2BAA2B;IAC3B,2BAA2B;IAC3B,4BAA4B;IAC5B,gCAAgC;CACxB,CAAC;AAEX,SAAgB,uBAAuB,CAAC,IAAY;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACU,QAAA,8BAA8B,GAA+C;IACxF,YAAY,EACV,6HAA6H;IAC/H,0BAA0B,EACxB,4GAA4G;IAC9G,uBAAuB,EACrB,wHAAwH;IAC1H,aAAa,EAAE,wDAAwD;IACvE,aAAa,EAAE,uEAAuE;IACtF,YAAY,EAAE,4DAA4D;IAC1E,gBAAgB,EAAE,kDAAkD;IACpE,wBAAwB,EACtB,iGAAiG;IACnG,oBAAoB,EAClB,yNAAyN;IAC3N,yBAAyB,EAAE,kDAAkD;IAC7E,wBAAwB,EACtB,wEAAwE;IAC1E,qBAAqB,EAAE,+CAA+C;IACtE,yBAAyB,EAAE,mDAAmD;IAC9E,iBAAiB,EAAE,wDAAwD;IAC3E,qBAAqB,EAAE,qDAAqD;IAC5E,uBAAuB,EAAE,8CAA8C;IACvE,4BAA4B,EAC1B,8EAA8E;IAChF,iBAAiB,EAAE,iDAAiD;IACpE,gBAAgB,EAAE,+DAA+D;IACjF,YAAY,EAAE,4BAA4B;IAC1C,mBAAmB,EAAE,mCAAmC;IACxD,yBAAyB,EAAE,gDAAgD;IAC3E,sBAAsB,EAAE,yEAAyE;IACjG,uBAAuB,EAAE,mEAAmE;IAC5F,2BAA2B,EACzB,0MAA0M;IAC5M,2BAA2B,EACzB,kJAAkJ;IACpJ,4BAA4B,EAC1B,iFAAiF;IACnF,gCAAgC,EAC9B,yJAAyJ;CAC5J,CAAC"}
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAiEH,0DAEC;AAlCY,QAAA,wBAAwB,GAAgC;IACnE,YAAY;IACZ,0BAA0B;IAC1B,uBAAuB;IACvB,aAAa;IACb,aAAa;IACb,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,wBAAwB;IACxB,oBAAoB;IACpB,yBAAyB;IACzB,wBAAwB;IACxB,qBAAqB;IACrB,yBAAyB;IACzB,iBAAiB;IACjB,qBAAqB;IACrB,uBAAuB;IACvB,4BAA4B;IAC5B,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;IACZ,mBAAmB;IACnB,yBAAyB;IACzB,sBAAsB;IACtB,uBAAuB;IACvB,2BAA2B;IAC3B,2BAA2B;IAC3B,4BAA4B;IAC5B,gCAAgC;CACxB,CAAC;AAEX,SAAgB,uBAAuB,CAAC,IAAY;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACU,QAAA,8BAA8B,GAA+C;IACxF,YAAY,EACV,6HAA6H;IAC/H,0BAA0B,EACxB,4GAA4G;IAC9G,uBAAuB,EACrB,wHAAwH;IAC1H,aAAa,EAAE,wDAAwD;IACvE,aAAa,EACX,4JAA4J;IAC9J,aAAa,EAAE,uEAAuE;IACtF,YAAY,EAAE,4DAA4D;IAC1E,gBAAgB,EAAE,kDAAkD;IACpE,wBAAwB,EACtB,iGAAiG;IACnG,oBAAoB,EAClB,yNAAyN;IAC3N,yBAAyB,EAAE,kDAAkD;IAC7E,wBAAwB,EACtB,wEAAwE;IAC1E,qBAAqB,EAAE,+CAA+C;IACtE,yBAAyB,EAAE,mDAAmD;IAC9E,iBAAiB,EAAE,wDAAwD;IAC3E,qBAAqB,EAAE,qDAAqD;IAC5E,uBAAuB,EAAE,8CAA8C;IACvE,4BAA4B,EAC1B,8EAA8E;IAChF,iBAAiB,EAAE,iDAAiD;IACpE,gBAAgB,EAAE,+DAA+D;IACjF,YAAY,EAAE,4BAA4B;IAC1C,mBAAmB,EAAE,mCAAmC;IACxD,yBAAyB,EAAE,gDAAgD;IAC3E,sBAAsB,EAAE,yEAAyE;IACjG,uBAAuB,EAAE,mEAAmE;IAC5F,2BAA2B,EACzB,0MAA0M;IAC5M,2BAA2B,EACzB,kJAAkJ;IACpJ,4BAA4B,EAC1B,iFAAiF;IACnF,gCAAgC,EAC9B,yJAAyJ;CAC5J,CAAC"}

package/dist/index.mjs

@@ -2948,6 +2948,7 @@ var VALID_PLUGIN_PERMISSIONS = [
   "assets:community:publish",
   "assets:community:read",
   "assets:read",
+  "data:agents",
   "data:search",
   "data:store",
   "data:workspace",
@@ -2981,6 +2982,7 @@ var PLUGIN_PERMISSION_DESCRIPTIONS = {
   "assets:community:publish": "Share images you made here so other people using this arche can see them, and manage what you have shared.",
   "assets:community:read": "Show you images that other people using this arche have shared. Everything shared is checked before anyone can see it.",
   "assets:read": "Show images from this arche's published asset library.",
+  "data:agents": "Let Fias AI, and assistants you connect with an API key and allow here, read this arche's data \u2014 and change it where it says so \u2014 even while it is closed.",
   "data:search": "Search this arche's own data semantically \u2014 costs credits per search.",
   "data:store": "Save structured data in this arche's own private database.",
   "data:workspace": "Create team workspaces and manage their members.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/arche-sdk",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "description": "SDK for building FIAS platform plugin arches",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.26.0 -->
+<!-- fias-sdk-guide-version: 2.27.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -283,6 +283,121 @@ Why this and not `createCollection` at startup: the runtime op is capped at **10
 
 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.
 
+### Letting agents use your data (`agentAccess`)
+
+**Permission:** `data:agents` (requires `data:store`)
+
+Your plugin can share some of its collections with AI agents — the platform's Fias AI assistant, and agents a user connects over MCP (Claude Code and others) — **while your plugin is closed**. Agents never run your code: they read and change documents through a fixed set of platform tools (`plugin_apps_list`, `plugin_app_describe`, `plugin_data_query`, `plugin_data_get`, `plugin_data_put`, `plugin_data_patch`, `plugin_data_delete`). Declare what you share in `fias-plugin.json`:
+
+```jsonc
+"permissions": ["data:store", "data:agents"],
+"collections": [
+  { "name": "scenes", "scope": "user" },
+  { "name": "render_requests", "scope": "user" },
+  { "name": "previews", "scope": "user" }
+],
+"agentAccess": {
+  "description": "Puppet cut scenes: a cast, scene-frames and spoken lines.",
+  "collections": {
+    "scenes": {
+      "access": "read_write",
+      "description": "One cut scene per document, keyed by scene id.",
+      "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
+    },
+    "render_requests": {
+      "access": "read_write",
+      "description": "Ask the open app for stills of a scene at chosen times.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "scene": { "type": "string", "maxLength": 100 },
+          "times": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 1, "maxItems": 12 },
+          "width": { "type": "integer", "minimum": 64, "maximum": 800 },
+          "status": { "enum": ["pending", "working", "done", "failed"] },
+          "error": { "type": "string", "maxLength": 2000 },
+          "previews": { "type": "integer", "minimum": 0, "maximum": 12 }
+        },
+        "required": ["scene", "times", "status"],
+        "additionalProperties": false
+      }
+    },
+    "previews": { "access": "read", "description": "Stills the open app rendered.", "images": ["/image"] }
+  }
+}
+```
+
+Rules (checked by `fias-dev validate` and at publish):
+
+- `data:agents` and the `agentAccess` block go together: declaring the permission without a block is an error.
+- Only collections you declare in `collections`, with `user` or `shared` scope. `read_write` only on `user` scope (a write to a `shared` collection would land in every user's copy), and it needs a `schema` — every agent write is validated against it. `workspace` collections can't be shared with agents yet.
+- Schemas use a restricted JSON Schema 2020-12: `type`, `properties`, `required`, `additionalProperties`, `items`, `prefixItems`, `enum`, `const`, min/max bounds, `anyOf`/`oneOf`/`allOf`/`not`, `title`, `description`, `default`, `examples`, `format` (annotation only), and `$ref` to your own `#/$defs/…`. **No `pattern`** (regular expressions), no `propertyNames`, and no remote `$ref`. `uniqueItems` only on arrays whose `items` have a scalar `type`. A `$ref` may recurse only through `properties` / `items` / `additionalProperties` (a tree), never straight back to itself. ≤ 16 KB per schema, depth ≤ 12. If you generate schemas with Zod, note that `z.record()` emits `propertyNames` and `z.email()` / `z.uuid()` / `z.regex()` emit `pattern` — neither is accepted.
+- Descriptions describe your data — they are not instructions to an AI. The publish review flags text that tells an agent what to do, links, and mentions of other apps.
+- `images` names fields holding `{ "mimeType": "image/png" | "image/jpeg" | "image/webp", "data": "<base64>" }` (≤ 96 KB, ≤ 2000 px a side; every image is fully decoded before an agent sees it, and one that doesn't decode is replaced by an error). Agents receive them as pictures and can never write them — so in a `read_write` collection an image field must be optional, never `required`.
+
+What agents can do: **Fias AI** acts as the signed-in user on what you declare. An **external agent** reaches your app only through an API key the user allowed to use it, collection by collection, read or read and change — and if you later share more, nothing new is reachable until the user allows it again. Every agent write is conditional on the version it read, so it can't silently overwrite a change made in your open UI; deletes always need the user's confirmation in Fias.
+
+**Your obligation for `read_write` collections: validate what you load.** An agent — or text an agent was shown — may have written it. Treat those documents like any untrusted input; never evaluate or render a field as code or HTML.
+
+**Answering an agent while open (previews).** Agents can't run your code, but your open plugin can do work for them through data. Watch a requests collection, do the work, and write the answer back:
+
+```tsx
+const dataStore = useFiasDataStore();
+const answerPending = useCallback(async () => {
+  const { documents } = await dataStore.query<RenderRequest>('render_requests', {
+    filters: [{ field: 'status', op: 'eq', value: 'pending' }],
+    limit: 5,
+  });
+  for (const req of documents) {
+    // Claim it first, so two open tabs never both do it.
+    const claimed = await dataStore
+      .batch(
+        [
+          {
+            op: 'put',
+            collection: 'render_requests',
+            key: req.key,
+            data: { ...req.data, status: 'working' },
+          },
+        ],
+        {
+          preconditions: [
+            { kind: 'version', collection: 'render_requests', key: req.key, version: req.version },
+          ],
+        },
+      )
+      .then(
+        () => true,
+        () => false,
+      );
+    if (!claimed) continue;
+    const stills = await renderStills(req.data); // your own code, bounded by your schema
+    for (const [i, image] of stills.entries()) {
+      await dataStore.put('previews', `${req.key}-${i}`, {
+        request: req.key,
+        t: req.data.times[i],
+        image,
+      });
+    }
+    await dataStore.put('render_requests', req.key, {
+      ...req.data,
+      status: 'done',
+      previews: stills.length,
+    });
+  }
+}, [dataStore]);
+useDataSubscription('render_requests', answerPending); // changes arrive at most once —
+useEffect(() => {
+  // so also check on open and every ~10 s
+  void answerPending();
+  const timer = setInterval(answerPending, 10_000);
+  return () => clearInterval(timer);
+}, [answerPending]);
+```
+
+The agent writes a request, waits on it with `plugin_data_get` (`afterVersion` + `waitSeconds`), and reads the stills back as images. Keep requests bounded in your schema (e.g. `"times": { "maxItems": 12 }`), prune old previews, and report failures in the request (e.g. `status: "failed"` with errors) so the agent can fix what it wrote. **Give both the requests and the results collections `user` scope** — in a `shared` collection any user of your app could plant a "result" that another user's agent then reads.
+
+**Testing:** in the dev harness's Fias AI window, the read tools see your local `agentAccess` block against your dev data — ask "what scenes do I have?" to see what an agent sees before you publish.
+
 **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`.

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.26.0 -->
+<!-- fias-sdk-guide-version: 2.27.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -283,6 +283,121 @@ Why this and not `createCollection` at startup: the runtime op is capped at **10
 
 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.
 
+### Letting agents use your data (`agentAccess`)
+
+**Permission:** `data:agents` (requires `data:store`)
+
+Your plugin can share some of its collections with AI agents — the platform's Fias AI assistant, and agents a user connects over MCP (Claude Code and others) — **while your plugin is closed**. Agents never run your code: they read and change documents through a fixed set of platform tools (`plugin_apps_list`, `plugin_app_describe`, `plugin_data_query`, `plugin_data_get`, `plugin_data_put`, `plugin_data_patch`, `plugin_data_delete`). Declare what you share in `fias-plugin.json`:
+
+```jsonc
+"permissions": ["data:store", "data:agents"],
+"collections": [
+  { "name": "scenes", "scope": "user" },
+  { "name": "render_requests", "scope": "user" },
+  { "name": "previews", "scope": "user" }
+],
+"agentAccess": {
+  "description": "Puppet cut scenes: a cast, scene-frames and spoken lines.",
+  "collections": {
+    "scenes": {
+      "access": "read_write",
+      "description": "One cut scene per document, keyed by scene id.",
+      "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": ["title"] }
+    },
+    "render_requests": {
+      "access": "read_write",
+      "description": "Ask the open app for stills of a scene at chosen times.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "scene": { "type": "string", "maxLength": 100 },
+          "times": { "type": "array", "items": { "type": "number", "minimum": 0 }, "minItems": 1, "maxItems": 12 },
+          "width": { "type": "integer", "minimum": 64, "maximum": 800 },
+          "status": { "enum": ["pending", "working", "done", "failed"] },
+          "error": { "type": "string", "maxLength": 2000 },
+          "previews": { "type": "integer", "minimum": 0, "maximum": 12 }
+        },
+        "required": ["scene", "times", "status"],
+        "additionalProperties": false
+      }
+    },
+    "previews": { "access": "read", "description": "Stills the open app rendered.", "images": ["/image"] }
+  }
+}
+```
+
+Rules (checked by `fias-dev validate` and at publish):
+
+- `data:agents` and the `agentAccess` block go together: declaring the permission without a block is an error.
+- Only collections you declare in `collections`, with `user` or `shared` scope. `read_write` only on `user` scope (a write to a `shared` collection would land in every user's copy), and it needs a `schema` — every agent write is validated against it. `workspace` collections can't be shared with agents yet.
+- Schemas use a restricted JSON Schema 2020-12: `type`, `properties`, `required`, `additionalProperties`, `items`, `prefixItems`, `enum`, `const`, min/max bounds, `anyOf`/`oneOf`/`allOf`/`not`, `title`, `description`, `default`, `examples`, `format` (annotation only), and `$ref` to your own `#/$defs/…`. **No `pattern`** (regular expressions), no `propertyNames`, and no remote `$ref`. `uniqueItems` only on arrays whose `items` have a scalar `type`. A `$ref` may recurse only through `properties` / `items` / `additionalProperties` (a tree), never straight back to itself. ≤ 16 KB per schema, depth ≤ 12. If you generate schemas with Zod, note that `z.record()` emits `propertyNames` and `z.email()` / `z.uuid()` / `z.regex()` emit `pattern` — neither is accepted.
+- Descriptions describe your data — they are not instructions to an AI. The publish review flags text that tells an agent what to do, links, and mentions of other apps.
+- `images` names fields holding `{ "mimeType": "image/png" | "image/jpeg" | "image/webp", "data": "<base64>" }` (≤ 96 KB, ≤ 2000 px a side; every image is fully decoded before an agent sees it, and one that doesn't decode is replaced by an error). Agents receive them as pictures and can never write them — so in a `read_write` collection an image field must be optional, never `required`.
+
+What agents can do: **Fias AI** acts as the signed-in user on what you declare. An **external agent** reaches your app only through an API key the user allowed to use it, collection by collection, read or read and change — and if you later share more, nothing new is reachable until the user allows it again. Every agent write is conditional on the version it read, so it can't silently overwrite a change made in your open UI; deletes always need the user's confirmation in Fias.
+
+**Your obligation for `read_write` collections: validate what you load.** An agent — or text an agent was shown — may have written it. Treat those documents like any untrusted input; never evaluate or render a field as code or HTML.
+
+**Answering an agent while open (previews).** Agents can't run your code, but your open plugin can do work for them through data. Watch a requests collection, do the work, and write the answer back:
+
+```tsx
+const dataStore = useFiasDataStore();
+const answerPending = useCallback(async () => {
+  const { documents } = await dataStore.query<RenderRequest>('render_requests', {
+    filters: [{ field: 'status', op: 'eq', value: 'pending' }],
+    limit: 5,
+  });
+  for (const req of documents) {
+    // Claim it first, so two open tabs never both do it.
+    const claimed = await dataStore
+      .batch(
+        [
+          {
+            op: 'put',
+            collection: 'render_requests',
+            key: req.key,
+            data: { ...req.data, status: 'working' },
+          },
+        ],
+        {
+          preconditions: [
+            { kind: 'version', collection: 'render_requests', key: req.key, version: req.version },
+          ],
+        },
+      )
+      .then(
+        () => true,
+        () => false,
+      );
+    if (!claimed) continue;
+    const stills = await renderStills(req.data); // your own code, bounded by your schema
+    for (const [i, image] of stills.entries()) {
+      await dataStore.put('previews', `${req.key}-${i}`, {
+        request: req.key,
+        t: req.data.times[i],
+        image,
+      });
+    }
+    await dataStore.put('render_requests', req.key, {
+      ...req.data,
+      status: 'done',
+      previews: stills.length,
+    });
+  }
+}, [dataStore]);
+useDataSubscription('render_requests', answerPending); // changes arrive at most once —
+useEffect(() => {
+  // so also check on open and every ~10 s
+  void answerPending();
+  const timer = setInterval(answerPending, 10_000);
+  return () => clearInterval(timer);
+}, [answerPending]);
+```
+
+The agent writes a request, waits on it with `plugin_data_get` (`afterVersion` + `waitSeconds`), and reads the stills back as images. Keep requests bounded in your schema (e.g. `"times": { "maxItems": 12 }`), prune old previews, and report failures in the request (e.g. `status: "failed"` with errors) so the agent can fix what it wrote. **Give both the requests and the results collections `user` scope** — in a `shared` collection any user of your app could plant a "result" that another user's agent then reads.
+
+**Testing:** in the dev harness's Fias AI window, the read tools see your local `agentAccess` block against your dev data — ask "what scenes do I have?" to see what an agent sees before you publish.
+
 **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`.