@fias/create-fias-plugin 1.0.2 → 1.0.4

package/package.json

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

package/templates/default/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project is a FIAS platform plugin — a React application that runs in a sandboxed iframe within the FIAS marketplace. This file provides the context AI coding assistants need to build, test, and submit plugins effectively.
 
-For other AI tool instruction files, see `CLAUDE.md` (identical content).
+For other AI tool instruction files, see `AGENTS.md` (identical content).
 
 ## Project Structure
 
@@ -82,6 +82,8 @@ const user = useFiasUser();
 **Permission:** `storage:sandbox`
 **Returns:** `FiasStorageApi`
 
+Storage is S3-backed and scoped per plugin + user. Data persists across sessions, browsers, and devices in live mode (staging/production). In mock mode, storage is in-memory and resets when the dev server restarts.
+
 ```tsx
 import { useFiasStorage } from '@fias/arche-sdk';
 
@@ -93,6 +95,73 @@ const files = await listFiles('data/'); // string[]
 await deleteFile('data/old.json');
 ```
 
+**Error handling:** Storage calls can reject on infrastructure errors. Always use `.catch()` or `try/catch` -- an unhandled rejection will crash the plugin to a white screen.
+
+### `useFiasDataStore()` — Document database
+
+**Permission:** `data:store`
+**Returns:** `FiasDataStoreApi`
+
+A document database with collections, queries, and filtering. Data persists across sessions in live mode. Each collection can be `user`-scoped (private to each user) or `shared` (visible to all users of the plugin).
+
+```tsx
+import { useFiasDataStore } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const dataStore = useFiasDataStore();
+
+  // Collection management
+  await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
+  const collections = await dataStore.listCollections();
+  await dataStore.deleteCollection('scores');
+
+  // Document CRUD
+  await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
+  const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
+  await dataStore.delete('scores', 'doc-key');
+
+  // Query with filters, sorting, pagination
+  const results = await dataStore.query<MyType>('scores', {
+    filters: [
+      { field: 'score', op: 'gte', value: 50 },
+      { field: 'name', op: 'eq', value: 'Alice' },
+    ],
+    orderBy: { field: 'score', direction: 'desc' },
+    limit: 20,
+    cursor: nextCursor, // for pagination
+  });
+  // results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
+}
+```
+
+Also available as an imperative API outside React components:
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+await fias.dataStore.put('scores', 'key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'key');
+```
+
+**Collection scopes:**
+
+- `user` (default): Each user sees only their own documents
+- `shared`: All users of the plugin see and share the same documents
+
+**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
+
+**Limits:**
+
+- 50 collections per plugin
+- 10,000 documents per collection
+- 100 KB per document
+- 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
+
+**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`.
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -129,6 +198,41 @@ function AISummarizer() {
 
 The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
 
+### `useImageGeneration()` — Generate images via AI models
+
+**Permission:** `entities:image_generate`
+**Returns:** `ImageGenerationApi`
+
+Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned. Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+
+```tsx
+import { useImageGeneration } from '@fias/arche-sdk';
+
+function ImageMaker() {
+  const { generate, isLoading, result, error } = useImageGeneration();
+
+  return (
+    <div>
+      <button
+        onClick={() =>
+          generate({
+            entityId: 'ent_modeldef_dalle3',
+            prompt: 'A serene mountain landscape at sunset',
+            size: '1024x1024',
+            quality: 'hd',
+          })
+        }
+        disabled={isLoading}
+      >
+        {isLoading ? 'Generating...' : 'Generate Image'}
+      </button>
+      {result && <img src={result.imageUrl} alt="Generated" />}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -155,6 +259,8 @@ const { currentStep, setCurrentStep } = useStepNavigation('step-1');
 
 **Permission:** `storage:sandbox`
 
+Uses `useFiasStorage` under the hood — same persistence rules apply (durable in live mode, in-memory in mock mode).
+
 ```tsx
 import { usePersistentState } from '@fias/arche-sdk';
 
@@ -203,7 +309,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 | `sdk`          | Yes      | SDK version range                                         |
 | `dependencies` | No       | npm packages with **exact** versions (max 20)             |
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
 
 **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`.
 
@@ -249,6 +355,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
 
 ## Development Workflow
 
+### Check for Updates (DO THIS FIRST)
+
+**At the start of every new session**, check if the FIAS packages and tooling are up to date:
+
+```bash
+npm outdated @fias/arche-sdk @fias/plugin-dev-harness
+npx fias-dev sync --dry-run
+```
+
+If newer package versions are available, tell the user and ask if they want to update before proceeding. Stale packages can cause subtle bugs (e.g., mismatched API return types) that are hard to diagnose.
+
+If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
+
 ### Starting Development
 
 ```bash
@@ -279,9 +398,10 @@ npx fias-dev login --env production   # Authenticate with production
 ### Browsing Available Entities
 
 ```bash
-npx fias-dev entities                    # List all
-npx fias-dev entities --search "text"    # Search by keyword
-npx fias-dev entities --type "prompt"    # Filter by type
+npx fias-dev entities                              # List all
+npx fias-dev entities --search "image"             # Search by keyword
+npx fias-dev entities --type "model-definition"    # Filter by type
+npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
 ```
 
 ### Validating the Manifest

package/templates/default/CLAUDE.md

@@ -82,6 +82,8 @@ const user = useFiasUser();
 **Permission:** `storage:sandbox`
 **Returns:** `FiasStorageApi`
 
+Storage is S3-backed and scoped per plugin + user. Data persists across sessions, browsers, and devices in live mode (staging/production). In mock mode, storage is in-memory and resets when the dev server restarts.
+
 ```tsx
 import { useFiasStorage } from '@fias/arche-sdk';
 
@@ -93,6 +95,73 @@ const files = await listFiles('data/'); // string[]
 await deleteFile('data/old.json');
 ```
 
+**Error handling:** Storage calls can reject on infrastructure errors. Always use `.catch()` or `try/catch` -- an unhandled rejection will crash the plugin to a white screen.
+
+### `useFiasDataStore()` — Document database
+
+**Permission:** `data:store`
+**Returns:** `FiasDataStoreApi`
+
+A document database with collections, queries, and filtering. Data persists across sessions in live mode. Each collection can be `user`-scoped (private to each user) or `shared` (visible to all users of the plugin).
+
+```tsx
+import { useFiasDataStore } from '@fias/arche-sdk';
+
+function MyComponent() {
+  const dataStore = useFiasDataStore();
+
+  // Collection management
+  await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
+  const collections = await dataStore.listCollections();
+  await dataStore.deleteCollection('scores');
+
+  // Document CRUD
+  await dataStore.put<MyType>('scores', 'doc-key', { score: 100, name: 'Alice' });
+  const doc = await dataStore.get<MyType>('scores', 'doc-key'); // MyType | null
+  await dataStore.delete('scores', 'doc-key');
+
+  // Query with filters, sorting, pagination
+  const results = await dataStore.query<MyType>('scores', {
+    filters: [
+      { field: 'score', op: 'gte', value: 50 },
+      { field: 'name', op: 'eq', value: 'Alice' },
+    ],
+    orderBy: { field: 'score', direction: 'desc' },
+    limit: 20,
+    cursor: nextCursor, // for pagination
+  });
+  // results = { documents: [{ key, data, updatedAt }], nextCursor: string | null }
+}
+```
+
+Also available as an imperative API outside React components:
+
+```tsx
+import { fias } from '@fias/arche-sdk';
+
+await fias.dataStore.put('scores', 'key', { score: 100 });
+const doc = await fias.dataStore.get('scores', 'key');
+```
+
+**Collection scopes:**
+
+- `user` (default): Each user sees only their own documents
+- `shared`: All users of the plugin see and share the same documents
+
+**Filter operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (JSONB containment), `exists`
+
+**Limits:**
+
+- 50 collections per plugin
+- 10,000 documents per collection
+- 100 KB per document
+- 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
+
+**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`.
+
 ### `useEntityInvocation()` — Invoke AI models
 
 **Permission:** `entities:invoke`
@@ -129,6 +198,41 @@ function AISummarizer() {
 
 The `entityId` references a published model entity. Browse available models with `npx fias-dev entities`. The `systemPrompt` tells the AI how to behave — this is where your plugin's intelligence lives.
 
+### `useImageGeneration()` — Generate images via AI models
+
+**Permission:** `entities:image_generate`
+**Returns:** `ImageGenerationApi`
+
+Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned. Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
+
+```tsx
+import { useImageGeneration } from '@fias/arche-sdk';
+
+function ImageMaker() {
+  const { generate, isLoading, result, error } = useImageGeneration();
+
+  return (
+    <div>
+      <button
+        onClick={() =>
+          generate({
+            entityId: 'ent_modeldef_dalle3',
+            prompt: 'A serene mountain landscape at sunset',
+            size: '1024x1024',
+            quality: 'hd',
+          })
+        }
+        disabled={isLoading}
+      >
+        {isLoading ? 'Generating...' : 'Generate Image'}
+      </button>
+      {result && <img src={result.imageUrl} alt="Generated" />}
+      {error && <p>Error: {error.message}</p>}
+    </div>
+  );
+}
+```
+
 ### `useFiasNavigation()` — In-plugin routing
 
 **Permission:** None required
@@ -155,6 +259,8 @@ const { currentStep, setCurrentStep } = useStepNavigation('step-1');
 
 **Permission:** `storage:sandbox`
 
+Uses `useFiasStorage` under the hood — same persistence rules apply (durable in live mode, in-memory in mock mode).
+
 ```tsx
 import { usePersistentState } from '@fias/arche-sdk';
 
@@ -203,7 +309,7 @@ fias.showToast('Saved!', 'success'); // Toast: 'info' | 'success' | 'warning' |
 | `sdk`          | Yes      | SDK version range                                         |
 | `dependencies` | No       | npm packages with **exact** versions (max 20)             |
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `entities:invoke`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `entities:invoke`, `entities:image_generate`
 
 **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`.
 
@@ -249,6 +355,19 @@ These are hard limits enforced by the platform. Code that violates these will fa
 
 ## Development Workflow
 
+### Check for Updates (DO THIS FIRST)
+
+**At the start of every new session**, check if the FIAS packages and tooling are up to date:
+
+```bash
+npm outdated @fias/arche-sdk @fias/plugin-dev-harness
+npx fias-dev sync --dry-run
+```
+
+If newer package versions are available, tell the user and ask if they want to update before proceeding. Stale packages can cause subtle bugs (e.g., mismatched API return types) that are hard to diagnose.
+
+If `sync --dry-run` shows pending changes, tell the user and offer to run `npx fias-dev sync` to update AI instruction files and config from the latest SDK templates. This never touches source code or project-specific files (`package.json`, `fias-plugin.json`, `src/`).
+
 ### Starting Development
 
 ```bash
@@ -279,9 +398,10 @@ npx fias-dev login --env production   # Authenticate with production
 ### Browsing Available Entities
 
 ```bash
-npx fias-dev entities                    # List all
-npx fias-dev entities --search "text"    # Search by keyword
-npx fias-dev entities --type "prompt"    # Filter by type
+npx fias-dev entities                              # List all
+npx fias-dev entities --search "image"             # Search by keyword
+npx fias-dev entities --type "model-definition"    # Filter by type
+npx fias-dev entities --detail ent_modeldef_dalle3 # Full entity details (capabilities, sizes, pricing)
 ```
 
 ### Validating the Manifest