@fias/create-fias-plugin 1.7.0 → 1.9.0

package/package.json

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

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.14.0 -->
+<!-- fias-sdk-guide-version: 2.16.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -665,7 +665,7 @@ await invoke({ query: 'latest EU AI Act enforcement dates' });
 
 ### `useVaultDocuments()` — User-owned Vault documents
 
-**Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
+**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
 **Returns:** `VaultDocumentsApi`
 
 The Vault is the platform's persistent document store for the signed-in user. Distinct from `useFiasStorage` (per-plugin sandbox): Vault docs live in the user's My Data, survive plugin uninstall, and can be cross-referenced from other arches. Documents this arche creates are scoped to it (`source_arche_id`) and surfaced to the user under `/My-Fias/Arches/<archeId>/`.
@@ -698,6 +698,17 @@ const result = await vault.upload(bytes, {
 });
 // result.status transitions 'uploaded' → 'available' once indexed for search
 
+// Read back the raw bytes of a document THIS arche created (any content
+// type) — the reopen path for binary-processing plugins (e.g. a PDF editor
+// reloading a saved PDF). Capped at 15 MB (OWN_DOCUMENT_TOO_LARGE names the
+// cap) with its own tight per-minute budget: read sequentially and surface
+// a RATE_LIMIT error verbatim instead of retrying in a loop. Documents this
+// arche did NOT create reject with DOCUMENT_NOT_FOUND — the user's own
+// files are reachable only through useVaultUserDocuments (picker consent).
+// A document whose upload never finished rejects with OWN_DOCUMENT_NOT_READY
+// but still appears in list() — don't assume every listed doc has bytes.
+const { bytes: saved } = await vault.readBytes(documentId);
+
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
 const { matches } = await vault.search('quarterly revenue', { topK: 5 });
@@ -773,7 +784,7 @@ There are two declaration lanes, one shape:
 ```tsx
 import { useFiasAIActions } from '@fias/arche-sdk';
 
-useFiasAIActions({
+const { openAssistant } = useFiasAIActions({
   description: 'Once a document is open, the assistant can rotate its pages.',
   actions: [
     {
@@ -804,6 +815,7 @@ Rules that matter:
 - `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.
+- **`openAssistant()`** (the hook's return) asks the HOST to open the Fias AI panel — use it for a contextual affordance (an empty-state "Ask Fias AI to get started" button). The host already shows its own "Works with Fias AI" chip, debounces your requests, and ignores them for a while after the user closes the panel — never call it in a loop or on mount. There is deliberately no way to pass text along: the assistant's input belongs to the user.
 
 ### `useArcheAssets()` — Contributor-published asset library
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.14.0 -->
+<!-- fias-sdk-guide-version: 2.16.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -665,7 +665,7 @@ await invoke({ query: 'latest EU AI Act enforcement dates' });
 
 ### `useVaultDocuments()` — User-owned Vault documents
 
-**Permissions:** `vault:documents:read` (list / read / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
+**Permissions:** `vault:documents:read` (list / read / readBytes / getDownloadUrl / search), `vault:documents:write` (write / update / delete / attach / detach / upload)
 **Returns:** `VaultDocumentsApi`
 
 The Vault is the platform's persistent document store for the signed-in user. Distinct from `useFiasStorage` (per-plugin sandbox): Vault docs live in the user's My Data, survive plugin uninstall, and can be cross-referenced from other arches. Documents this arche creates are scoped to it (`source_arche_id`) and surfaced to the user under `/My-Fias/Arches/<archeId>/`.
@@ -698,6 +698,17 @@ const result = await vault.upload(bytes, {
 });
 // result.status transitions 'uploaded' → 'available' once indexed for search
 
+// Read back the raw bytes of a document THIS arche created (any content
+// type) — the reopen path for binary-processing plugins (e.g. a PDF editor
+// reloading a saved PDF). Capped at 15 MB (OWN_DOCUMENT_TOO_LARGE names the
+// cap) with its own tight per-minute budget: read sequentially and surface
+// a RATE_LIMIT error verbatim instead of retrying in a loop. Documents this
+// arche did NOT create reject with DOCUMENT_NOT_FOUND — the user's own
+// files are reachable only through useVaultUserDocuments (picker consent).
+// A document whose upload never finished rejects with OWN_DOCUMENT_NOT_READY
+// but still appears in list() — don't assume every listed doc has bytes.
+const { bytes: saved } = await vault.readBytes(documentId);
+
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
 const { matches } = await vault.search('quarterly revenue', { topK: 5 });
@@ -773,7 +784,7 @@ There are two declaration lanes, one shape:
 ```tsx
 import { useFiasAIActions } from '@fias/arche-sdk';
 
-useFiasAIActions({
+const { openAssistant } = useFiasAIActions({
   description: 'Once a document is open, the assistant can rotate its pages.',
   actions: [
     {
@@ -804,6 +815,7 @@ Rules that matter:
 - `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.
+- **`openAssistant()`** (the hook's return) asks the HOST to open the Fias AI panel — use it for a contextual affordance (an empty-state "Ask Fias AI to get started" button). The host already shows its own "Works with Fias AI" chip, debounces your requests, and ignores them for a while after the user closes the panel — never call it in a loop or on mount. There is deliberately no way to pass text along: the assistant's input belongs to the user.
 
 ### `useArcheAssets()` — Contributor-published asset library