@fias/create-fias-plugin 1.11.0 → 1.11.2

package/package.json

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

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.18.0 -->
+<!-- fias-sdk-guide-version: 2.19.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -545,11 +545,34 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended, ... }
+//                supportsReferenceImage, isPlatformRecommended,
+//                creditsPerImage, estimatedDurationMs, company, strengths,
+//                providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+
+**Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
+
+```tsx
+// param: { key, label, description, controlType, defaultValue,
+//          min?, max?, step?, options?, category? }
+// controlType: 'slider' | 'number' | 'select' | 'checkbox' | 'textarea'
+const seed = entity.providerParams?.find((p) => p.key === 'seed');
+await generate({ entityId, prompt, providerParams: { seed: 42 } });
+```
+
+**The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
+
+```tsx
+generate({ entityId, prompt, quality: 'high' }); // honoured
+generate({ entityId, prompt, providerParams: { gpt_quality: 'high' } }); // SILENTLY IGNORED
+```
+
+Its `options` are still how you build the control — only the destination differs.
+
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`
@@ -683,7 +706,7 @@ const { url, expiresAt, contentType } = await vault.getDownloadUrl(documentId);
 // List documents this arche owns
 const { documents, nextCursor } = await vault.list({ search: 'invoice', limit: 50 });
 
-// Write a small text/JSON document (UTF-8, ≤ 1 MB)
+// Write a small text/JSON document (UTF-8, ≤ 200 KB — use upload() for anything larger)
 const { documentId } = await vault.write({
   name: 'settings.json',
   content: JSON.stringify(settings),
@@ -712,11 +735,23 @@ const { bytes: saved } = await vault.readBytes(documentId);
 // Overwrite a document THIS arche created IN PLACE — same documentId, bytes
 // replaced, no version history. The autosave path (a spreadsheet saving as
 // the user works); to publish a distinct new version use write({
-// replacesDocumentId }) instead. UTF-8 text, ≤ 200 KB (OWN_DOCUMENT_SAVE_TOO_LARGE
-// names the cap). Debounce: a few seconds of idle plus blur/close — never per
-// keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
+// replacesDocumentId }) instead. ONE method for any content up to 15 MB
+// (OWN_DOCUMENT_SAVE_TOO_LARGE names the cap — the same one readBytes serves,
+// so anything you save you can reopen): a string is saved as UTF-8 text (the
+// document must be a text type); a Uint8Array / ArrayBuffer / Blob is saved
+// as-is, for any type. Transport is automatic — never split, chunk or re-upload
+// to work around size. Debounce: a few seconds of idle plus blur/close — never
+// per keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
 // drops the document's search index and does not re-run extraction.
 await vault.saveContent({ documentId, content: JSON.stringify(sheet) });
+await vault.saveContent({ documentId, content: pdfBytes }); // a PDF editor saving its PDF
+
+// Don't let two tabs clobber each other: pass the `revision` you last saw
+// (list() items, read(), readBytes().document and every saveContent result
+// carry one — treat it as opaque). A stale one rejects with VERSION_CONFLICT
+// and the document is untouched: re-read, merge or ask, retry with the new one.
+let { revision } = (await vault.readBytes(documentId)).document;
+({ revision } = await vault.saveContent({ documentId, content, expectedRevision: revision }));
 
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
@@ -749,6 +784,19 @@ const saved = await vault.upload(bytes, {
 
 Requires the `vault:user-documents:write` permission, and the HOST asks the user to confirm each save by name — you cannot script it, batch it, or pre-approve it. A decline rejects with `SAVE_DECLINED`; that is a normal outcome, not an error to retry. The file lands in `/My-Fias/<your arche's folder>/`, which the platform assigns — you cannot choose it, and `folderPath` is rejected alongside `userVisible`. Your arche must be registered for a user-visible folder platform-side (`ARCHE_NOT_REGISTERED_FOR_USER_VAULT` if not). Passing `replacesDocumentId` saves a new version in place; a version keeps its predecessor's visibility, so you cannot flip a user's visible file to private or vice versa (`VISIBILITY_MISMATCH`). Not available in preview or the dev harness — test it in the published plugin.
 
+**Handing over a file you already made** — `promoteToUserFiles(documentId)`. If the artifact already exists as one of your private documents, do NOT re-upload it with `userVisible` — that creates a second copy, doubles the user's storage, and orphans anything pointing at the original. Promote it instead: the same document moves into the user's files, keeping its `documentId`.
+
+```typescript
+try {
+  await vault.promoteToUserFiles(documentId); // the HOST asks the user; you cannot script it
+} catch (err) {
+  if (err instanceof FiasBridgeError && err.code === 'SAVE_DECLINED') return; // a normal outcome
+  throw err;
+}
+```
+
+Same requirements as a user-visible upload (`vault:user-documents:write`, a registered folder — the platform picks the destination). It is **one-way and it changes what you can do**: once the file is the user's, this hook's `saveContent`, `update` and `delete` reject, and there is no way to take a file back out of the user's files. To keep saving it, declare `vault:user-documents:edit` — the host's confirmation then offers the user "let this app keep editing", the result carries `editAccess`, and when it is `true` you carry on with `useVaultUserDocuments().saveContent` (below). Without it, promote when the user is DONE — never while your editor still needs to save. After a `SAVE_DECLINED`, re-`list()` before assuming nothing moved: the host performs the move itself, and if its page is torn down mid-move you are told "declined" for a promote that completed — the document's `visibility` is the truth. Re-asking is capped at 5 a minute, like the picker. Not available in preview or the dev harness.
+
 **Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
 
 **`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.
@@ -789,8 +837,122 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - 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.
 - `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.
+- **Workspaces.** The picker offers the files of the workspace the user is acting in — the workspace switcher in Fias: their Personal vault, or an org workspace they belong to — and `list()` returns the grants made in that workspace, so switching workspace changes what `list()` shows. A document you already hold a grant on stays readable by id (`get`, `getBytes`, `getDownloadUrl`, `saveContent`) whichever workspace the user is in: a grant belongs to the workspace the document lives in. A plugin never names a workspace itself. A member's role caps what they can share and read: a viewer can only share standard-sensitivity documents, and a document above a member's tier reads as `DOCUMENT_NOT_FOUND` even if another member granted it.
 - **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.
 
+**Editing the user's files** — permission `vault:user-documents:edit`, declared TOGETHER WITH `vault:user-documents:read` (escalates to human review). `:edit` does not include `:read`: the grants you save under are created and listed through the read surface (`pick`, `list`, `get`), so a manifest with `:edit` alone can ask for nothing and open nothing.
+
+```tsx
+// Ask for EDIT access up front…
+const picked = await userDocs.pick({ maxDocuments: 1, access: 'write' });
+// …or later, for a document you can already read (e.g. one that arrived by
+// handoff). The host skips the picker and asks about just that file.
+const asked = await userDocs.requestEditAccess(documentId);
+// CHECK it: a resolved promise is not "yes". If you held no grant on that
+// document the host shows the ordinary picker instead, so what comes back may
+// be a different file, or view-only.
+const granted =
+  'documents' in asked &&
+  asked.documents[0]?.documentId === documentId &&
+  asked.documents[0]?.access === 'write';
+
+// Save in place: same documentId. A string (text types) or bytes, up to 15 MB.
+const { document } = await userDocs.get(documentId);
+// `revision` is optional in the type — a host that predates edit access does
+// not send it, and without it there is nothing to save against.
+if (!document.revision) throw new Error('This host cannot save to the user’s files.');
+const saved = await userDocs.saveContent({
+  documentId,
+  content: bytes, // string | Uint8Array | ArrayBuffer | Blob
+  expectedRevision: document.revision, // REQUIRED — it is the user's file
+});
+// keep saved.revision for the next save
+```
+
+- `document.access` is `'read'` or `'write'`. Open a `'read'` document read-only; a save to one rejects with `EDIT_ACCESS_REQUIRED`. The user can lower access to view-only or remove it at any time (Vault → App Access) — handle `EDIT_ACCESS_REQUIRED` and `DOCUMENT_NOT_FOUND` on any save, and stop autosaving when you see one.
+- `expectedRevision` is required (`EXPECTED_REVISION_REQUIRED`). `VERSION_CONFLICT` means the file changed elsewhere — re-read, merge, retry; never loop blindly.
+- The document's type cannot change (`MIME_CHANGE_NOT_ALLOWED`), and a `string` can only be saved onto a text document (or one with no recorded type, which stays untyped). Rename, tags and delete stay the user's.
+- The platform keeps the user's earlier versions (at most one per 10 minutes per document). They count against the user's storage; `STORAGE_QUOTA_EXCEEDED` fails the save — tell the user, do not retry.
+- Saves are rate-limited to 12 a minute per user, text and bytes together. Debounce autosave to at most one save every 10 seconds (plus a final save on blur or close) — never per keystroke. A refusal rejects with `err.code === 'RATE_LIMIT'` whether the host or the server made it; surface it rather than retrying in a loop.
+- Content past 15 MB rejects locally with `OWN_DOCUMENT_SAVE_TOO_LARGE`, before anything is sent.
+- A save does not re-index the file for search — the user does that from the file's page.
+- Dev harness: **mock mode** implements all of this against the fixture documents (a `pick()` without `access: 'write'` leaves them read-only, so the refusal is testable). Live mode refuses — only the real user can grant edit access.
+
+### Sending a document for signature — Document Sign handoff
+
+**Permission:** `navigation:open_arche`.
+
+Hand one of the user's Vault PDFs to Document Sign with recipients pre-filled.
+They place the signature fields and press Send there — a handoff never sends
+anything, and there is no way for your app to send on their behalf.
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { openArche } = useFiasNavigation();
+
+openArche('arche_document_sign', {
+  payload: {
+    kind: 'sign_document',
+    // One uuid per user intent, NOT per call. The platform keys idempotency
+    // on it: re-presenting one resolves to the same draft instead of
+    // creating a duplicate, and reusing a stale one reopens the old draft.
+    requestId: crypto.randomUUID(),
+    documentId, // a user-vault PDF
+    title: 'MSA — Acme Corp',
+    recipients: [{ email: 'alice@acme.com', name: 'Alice', role: 'signer' }],
+    correlationId: approvalRecordId, // opaque; echoed back, never interpreted
+    // (fixed at creation — see below)
+  },
+});
+```
+
+`correlationId` is fixed when the envelope is first created. Re-presenting a
+`requestId` returns the SAME draft, and the result echoes the correlationId
+from that FIRST call — a different one sent on the repeat is ignored, not
+refused, for the same reason recipients are not re-seeded: a repeat must not
+overwrite what the first call recorded. `documentId` is part of the request's
+identity and IS refused when it differs (409); `correlationId` is metadata
+riding along. If you want fresh metadata, mint a fresh `requestId`.
+
+When the user leaves Document Sign they can come back to your app, and you
+receive a `sign_document_result`: `{ requestId, outcome, envelopeId? }`, where
+`outcome` is `sent`, `saved_draft` or `cancelled`. An `envelopeId` alone does
+NOT mean anything was sent — an envelope id exists from the moment a draft is
+created, which is why the outcome is there.
+
+**Treat the result as a pointer, never as a record.** It tells you which
+envelope to look at; it is not evidence of what happened to it. Match it to an
+outstanding request by `requestId`, consume it once, and never re-point an
+existing association because a `correlationId` matched.
+
+**A handoff ENDS YOUR APP'S PROCESS. Anything you will need afterwards has to
+be written down before you call `openArche`.** The host navigates away and
+tears your iframe down, so React state, refs, module variables — everything
+in memory — are gone when the user comes back. Your app remounts from
+nothing.
+
+That is one rule, and it is easy to under-apply. It is not only the
+outstanding `requestId`: it is the document the user selected, the record
+they were working on, the form they half-filled, the step they were on.
+Anything you would be annoyed to lose. Write it to `useFiasStorage()` or your
+Data Store on the way out and restore it on the way in. Browser storage is
+not an option — a plugin iframe is opaque-origin, so `localStorage` and
+`sessionStorage` throw.
+
+The `requestId` is the one that fails loudest: keep it in memory and every
+reply comes back unmatchable, so you cannot tell a genuine result from a
+forged one — which is the whole reason to match. The rest fail quietly, as a
+user who returns to an app that has forgotten what they were doing.
+
+Note the ordering this implies, and do not treat it as an edge case: the
+result **normally arrives before your restore read resolves** — the handoff
+is delivered as soon as your SDK reports ready, which is before your first
+storage round trip comes back. Measured at about a second's head start in
+local dev. Judging on arrival therefore rejects every genuine reply, not an
+occasional one. Hold the result until you know what was outstanding, then
+evaluate it.
+
 ### `useArcheHandoff()` — Receive a document the user asked to open in your app
 
 **Permission:** none to receive. Reading the document is a separate act (`vault:user-documents:read`, via `useVaultUserDocuments().getBytes`).
@@ -863,7 +1025,7 @@ Rules that matter:
 - **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.
+- **Test it in the dev harness:** the **✦ Fias AI** toolbar button opens the real assistant over your plugin (Live mode; turns are real and use your credits). It describes your plugin exactly as the platform would: manifest actions always, runtime (`useFiasAIActions`) actions and `state` only for a trusted arche, and the window names any runtime action it is withholding. In the harness it can use your plugin's actions plus read-only Fias tools, never writes or sends. The builder preview has no assistant.
 - **`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
@@ -1317,7 +1479,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 
 ### Size and File Limits
 
-- **Bundle size:** Max 5 MB compressed
+- **Bundle size:** Max 5 MB, measured **uncompressed** — the raw bytes of the final single HTML file with your JS and CSS inlined. Files in `public/` don't count toward it (they have their own caps: 4 MB per file, 120 MB and 600 files total)
 - **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
 - Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.18.0 -->
+<!-- fias-sdk-guide-version: 2.19.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -545,11 +545,34 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended, ... }
+//                supportsReferenceImage, isPlatformRecommended,
+//                creditsPerImage, estimatedDurationMs, company, strengths,
+//                providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+
+**Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
+
+```tsx
+// param: { key, label, description, controlType, defaultValue,
+//          min?, max?, step?, options?, category? }
+// controlType: 'slider' | 'number' | 'select' | 'checkbox' | 'textarea'
+const seed = entity.providerParams?.find((p) => p.key === 'seed');
+await generate({ entityId, prompt, providerParams: { seed: 42 } });
+```
+
+**The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
+
+```tsx
+generate({ entityId, prompt, quality: 'high' }); // honoured
+generate({ entityId, prompt, providerParams: { gpt_quality: 'high' } }); // SILENTLY IGNORED
+```
+
+Its `options` are still how you build the control — only the destination differs.
+
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`
@@ -683,7 +706,7 @@ const { url, expiresAt, contentType } = await vault.getDownloadUrl(documentId);
 // List documents this arche owns
 const { documents, nextCursor } = await vault.list({ search: 'invoice', limit: 50 });
 
-// Write a small text/JSON document (UTF-8, ≤ 1 MB)
+// Write a small text/JSON document (UTF-8, ≤ 200 KB — use upload() for anything larger)
 const { documentId } = await vault.write({
   name: 'settings.json',
   content: JSON.stringify(settings),
@@ -712,11 +735,23 @@ const { bytes: saved } = await vault.readBytes(documentId);
 // Overwrite a document THIS arche created IN PLACE — same documentId, bytes
 // replaced, no version history. The autosave path (a spreadsheet saving as
 // the user works); to publish a distinct new version use write({
-// replacesDocumentId }) instead. UTF-8 text, ≤ 200 KB (OWN_DOCUMENT_SAVE_TOO_LARGE
-// names the cap). Debounce: a few seconds of idle plus blur/close — never per
-// keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
+// replacesDocumentId }) instead. ONE method for any content up to 15 MB
+// (OWN_DOCUMENT_SAVE_TOO_LARGE names the cap — the same one readBytes serves,
+// so anything you save you can reopen): a string is saved as UTF-8 text (the
+// document must be a text type); a Uint8Array / ArrayBuffer / Blob is saved
+// as-is, for any type. Transport is automatic — never split, chunk or re-upload
+// to work around size. Debounce: a few seconds of idle plus blur/close — never
+// per keystroke — and surface RATE_LIMIT verbatim rather than retrying. A save
 // drops the document's search index and does not re-run extraction.
 await vault.saveContent({ documentId, content: JSON.stringify(sheet) });
+await vault.saveContent({ documentId, content: pdfBytes }); // a PDF editor saving its PDF
+
+// Don't let two tabs clobber each other: pass the `revision` you last saw
+// (list() items, read(), readBytes().document and every saveContent result
+// carry one — treat it as opaque). A stale one rejects with VERSION_CONFLICT
+// and the document is untouched: re-read, merge or ask, retry with the new one.
+let { revision } = (await vault.readBytes(documentId)).document;
+({ revision } = await vault.saveContent({ documentId, content, expectedRevision: revision }));
 
 // Semantic search across documents this arche owns
 // (burns user credits per the AI Markup Invariant — call sparingly)
@@ -749,6 +784,19 @@ const saved = await vault.upload(bytes, {
 
 Requires the `vault:user-documents:write` permission, and the HOST asks the user to confirm each save by name — you cannot script it, batch it, or pre-approve it. A decline rejects with `SAVE_DECLINED`; that is a normal outcome, not an error to retry. The file lands in `/My-Fias/<your arche's folder>/`, which the platform assigns — you cannot choose it, and `folderPath` is rejected alongside `userVisible`. Your arche must be registered for a user-visible folder platform-side (`ARCHE_NOT_REGISTERED_FOR_USER_VAULT` if not). Passing `replacesDocumentId` saves a new version in place; a version keeps its predecessor's visibility, so you cannot flip a user's visible file to private or vice versa (`VISIBILITY_MISMATCH`). Not available in preview or the dev harness — test it in the published plugin.
 
+**Handing over a file you already made** — `promoteToUserFiles(documentId)`. If the artifact already exists as one of your private documents, do NOT re-upload it with `userVisible` — that creates a second copy, doubles the user's storage, and orphans anything pointing at the original. Promote it instead: the same document moves into the user's files, keeping its `documentId`.
+
+```typescript
+try {
+  await vault.promoteToUserFiles(documentId); // the HOST asks the user; you cannot script it
+} catch (err) {
+  if (err instanceof FiasBridgeError && err.code === 'SAVE_DECLINED') return; // a normal outcome
+  throw err;
+}
+```
+
+Same requirements as a user-visible upload (`vault:user-documents:write`, a registered folder — the platform picks the destination). It is **one-way and it changes what you can do**: once the file is the user's, this hook's `saveContent`, `update` and `delete` reject, and there is no way to take a file back out of the user's files. To keep saving it, declare `vault:user-documents:edit` — the host's confirmation then offers the user "let this app keep editing", the result carries `editAccess`, and when it is `true` you carry on with `useVaultUserDocuments().saveContent` (below). Without it, promote when the user is DONE — never while your editor still needs to save. After a `SAVE_DECLINED`, re-`list()` before assuming nothing moved: the host performs the move itself, and if its page is torn down mid-move you are told "declined" for a promote that completed — the document's `visibility` is the truth. Re-asking is capped at 5 a minute, like the picker. Not available in preview or the dev harness.
+
 **Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
 
 **`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.
@@ -789,8 +837,122 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - 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.
 - `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.
+- **Workspaces.** The picker offers the files of the workspace the user is acting in — the workspace switcher in Fias: their Personal vault, or an org workspace they belong to — and `list()` returns the grants made in that workspace, so switching workspace changes what `list()` shows. A document you already hold a grant on stays readable by id (`get`, `getBytes`, `getDownloadUrl`, `saveContent`) whichever workspace the user is in: a grant belongs to the workspace the document lives in. A plugin never names a workspace itself. A member's role caps what they can share and read: a viewer can only share standard-sensitivity documents, and a document above a member's tier reads as `DOCUMENT_NOT_FOUND` even if another member granted it.
 - **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.
 
+**Editing the user's files** — permission `vault:user-documents:edit`, declared TOGETHER WITH `vault:user-documents:read` (escalates to human review). `:edit` does not include `:read`: the grants you save under are created and listed through the read surface (`pick`, `list`, `get`), so a manifest with `:edit` alone can ask for nothing and open nothing.
+
+```tsx
+// Ask for EDIT access up front…
+const picked = await userDocs.pick({ maxDocuments: 1, access: 'write' });
+// …or later, for a document you can already read (e.g. one that arrived by
+// handoff). The host skips the picker and asks about just that file.
+const asked = await userDocs.requestEditAccess(documentId);
+// CHECK it: a resolved promise is not "yes". If you held no grant on that
+// document the host shows the ordinary picker instead, so what comes back may
+// be a different file, or view-only.
+const granted =
+  'documents' in asked &&
+  asked.documents[0]?.documentId === documentId &&
+  asked.documents[0]?.access === 'write';
+
+// Save in place: same documentId. A string (text types) or bytes, up to 15 MB.
+const { document } = await userDocs.get(documentId);
+// `revision` is optional in the type — a host that predates edit access does
+// not send it, and without it there is nothing to save against.
+if (!document.revision) throw new Error('This host cannot save to the user’s files.');
+const saved = await userDocs.saveContent({
+  documentId,
+  content: bytes, // string | Uint8Array | ArrayBuffer | Blob
+  expectedRevision: document.revision, // REQUIRED — it is the user's file
+});
+// keep saved.revision for the next save
+```
+
+- `document.access` is `'read'` or `'write'`. Open a `'read'` document read-only; a save to one rejects with `EDIT_ACCESS_REQUIRED`. The user can lower access to view-only or remove it at any time (Vault → App Access) — handle `EDIT_ACCESS_REQUIRED` and `DOCUMENT_NOT_FOUND` on any save, and stop autosaving when you see one.
+- `expectedRevision` is required (`EXPECTED_REVISION_REQUIRED`). `VERSION_CONFLICT` means the file changed elsewhere — re-read, merge, retry; never loop blindly.
+- The document's type cannot change (`MIME_CHANGE_NOT_ALLOWED`), and a `string` can only be saved onto a text document (or one with no recorded type, which stays untyped). Rename, tags and delete stay the user's.
+- The platform keeps the user's earlier versions (at most one per 10 minutes per document). They count against the user's storage; `STORAGE_QUOTA_EXCEEDED` fails the save — tell the user, do not retry.
+- Saves are rate-limited to 12 a minute per user, text and bytes together. Debounce autosave to at most one save every 10 seconds (plus a final save on blur or close) — never per keystroke. A refusal rejects with `err.code === 'RATE_LIMIT'` whether the host or the server made it; surface it rather than retrying in a loop.
+- Content past 15 MB rejects locally with `OWN_DOCUMENT_SAVE_TOO_LARGE`, before anything is sent.
+- A save does not re-index the file for search — the user does that from the file's page.
+- Dev harness: **mock mode** implements all of this against the fixture documents (a `pick()` without `access: 'write'` leaves them read-only, so the refusal is testable). Live mode refuses — only the real user can grant edit access.
+
+### Sending a document for signature — Document Sign handoff
+
+**Permission:** `navigation:open_arche`.
+
+Hand one of the user's Vault PDFs to Document Sign with recipients pre-filled.
+They place the signature fields and press Send there — a handoff never sends
+anything, and there is no way for your app to send on their behalf.
+
+```tsx
+import { useFiasNavigation } from '@fias/arche-sdk';
+
+const { openArche } = useFiasNavigation();
+
+openArche('arche_document_sign', {
+  payload: {
+    kind: 'sign_document',
+    // One uuid per user intent, NOT per call. The platform keys idempotency
+    // on it: re-presenting one resolves to the same draft instead of
+    // creating a duplicate, and reusing a stale one reopens the old draft.
+    requestId: crypto.randomUUID(),
+    documentId, // a user-vault PDF
+    title: 'MSA — Acme Corp',
+    recipients: [{ email: 'alice@acme.com', name: 'Alice', role: 'signer' }],
+    correlationId: approvalRecordId, // opaque; echoed back, never interpreted
+    // (fixed at creation — see below)
+  },
+});
+```
+
+`correlationId` is fixed when the envelope is first created. Re-presenting a
+`requestId` returns the SAME draft, and the result echoes the correlationId
+from that FIRST call — a different one sent on the repeat is ignored, not
+refused, for the same reason recipients are not re-seeded: a repeat must not
+overwrite what the first call recorded. `documentId` is part of the request's
+identity and IS refused when it differs (409); `correlationId` is metadata
+riding along. If you want fresh metadata, mint a fresh `requestId`.
+
+When the user leaves Document Sign they can come back to your app, and you
+receive a `sign_document_result`: `{ requestId, outcome, envelopeId? }`, where
+`outcome` is `sent`, `saved_draft` or `cancelled`. An `envelopeId` alone does
+NOT mean anything was sent — an envelope id exists from the moment a draft is
+created, which is why the outcome is there.
+
+**Treat the result as a pointer, never as a record.** It tells you which
+envelope to look at; it is not evidence of what happened to it. Match it to an
+outstanding request by `requestId`, consume it once, and never re-point an
+existing association because a `correlationId` matched.
+
+**A handoff ENDS YOUR APP'S PROCESS. Anything you will need afterwards has to
+be written down before you call `openArche`.** The host navigates away and
+tears your iframe down, so React state, refs, module variables — everything
+in memory — are gone when the user comes back. Your app remounts from
+nothing.
+
+That is one rule, and it is easy to under-apply. It is not only the
+outstanding `requestId`: it is the document the user selected, the record
+they were working on, the form they half-filled, the step they were on.
+Anything you would be annoyed to lose. Write it to `useFiasStorage()` or your
+Data Store on the way out and restore it on the way in. Browser storage is
+not an option — a plugin iframe is opaque-origin, so `localStorage` and
+`sessionStorage` throw.
+
+The `requestId` is the one that fails loudest: keep it in memory and every
+reply comes back unmatchable, so you cannot tell a genuine result from a
+forged one — which is the whole reason to match. The rest fail quietly, as a
+user who returns to an app that has forgotten what they were doing.
+
+Note the ordering this implies, and do not treat it as an edge case: the
+result **normally arrives before your restore read resolves** — the handoff
+is delivered as soon as your SDK reports ready, which is before your first
+storage round trip comes back. Measured at about a second's head start in
+local dev. Judging on arrival therefore rejects every genuine reply, not an
+occasional one. Hold the result until you know what was outstanding, then
+evaluate it.
+
 ### `useArcheHandoff()` — Receive a document the user asked to open in your app
 
 **Permission:** none to receive. Reading the document is a separate act (`vault:user-documents:read`, via `useVaultUserDocuments().getBytes`).
@@ -863,7 +1025,7 @@ Rules that matter:
 - **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.
+- **Test it in the dev harness:** the **✦ Fias AI** toolbar button opens the real assistant over your plugin (Live mode; turns are real and use your credits). It describes your plugin exactly as the platform would: manifest actions always, runtime (`useFiasAIActions`) actions and `state` only for a trusted arche, and the window names any runtime action it is withholding. In the harness it can use your plugin's actions plus read-only Fias tools, never writes or sends. The builder preview has no assistant.
 - **`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
@@ -1317,7 +1479,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 
 ### Size and File Limits
 
-- **Bundle size:** Max 5 MB compressed
+- **Bundle size:** Max 5 MB, measured **uncompressed** — the raw bytes of the final single HTML file with your JS and CSS inlined. Files in `public/` don't count toward it (they have their own caps: 4 MB per file, 120 MB and 600 files total)
 - **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
 - Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`