@fias/arche-sdk 2.19.2 → 2.21.0

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.19.0 -->
+<!-- fias-sdk-guide-version: 2.21.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -12,9 +12,34 @@ package.json              # Dependencies and scripts
 src/
   index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
   App.tsx                 # Main component
+public/                   # Optional — static images, fonts, sounds referenced as '/name.png'
+content/                  # Optional — a content pack read with useFiasContent() (lessons, data, media)
 vite.config.ts            # Vite dev server config (port 3100)
 ```
 
+## Where does each kind of data go?
+
+Decide by who writes the data and when, before you write the code: moving data to a different home after you publish means a migration.
+
+| What it is                                                                                                                | Where it goes                                             | What you get                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your code and small constants (config, a short word list)                                                                 | The bundle (`src/`)                                       | One file, max 5 MB uncompressed. Every user downloads all of it each time the plugin opens.                                                                         |
+| A few static images, fonts or sounds your UI names directly                                                               | `public/`, referenced as literal `'/name.png'` strings    | Served from a CDN. Binary only (png, jpg, webp, gif, woff, woff2, ogg), top-level files only, 4 MB each, 600 files and 120 MB in total.                             |
+| Content you write and ship with each version: lessons, articles, levels, reference data, large image or audio sets, fonts | A content pack: `content/` + `useFiasContent()`           | Not bundled, so users download only what they open. Reviewed on every publish and read-only at runtime. You pay its storage and bandwidth; reads are free to users. |
+| Images you want to change without republishing code (logos, maps, photos with alt text)                                   | The asset library: `useArcheAssets()` + `fias-dev assets` | Managed from the CLI and refreshed without a code publish.                                                                                                          |
+| Records your app writes while it runs: progress, things users create, shared catalogues, leaderboards                     | `useFiasDataStore()` collections                          | Queryable, `user` or `shared` scope, write policies, optional semantic search.                                                                                      |
+| Files only your app uses, for one user: drafts, caches, working data                                                      | `useFiasStorage()`                                        | Free-form paths, private to the plugin and the user. Not shown in their Vault.                                                                                      |
+| A small piece of UI state that should survive a reload (a setting, the last tab)                                          | `usePersistentState()`                                    | Debounced writes to `useFiasStorage()`.                                                                                                                             |
+| Images one user shares with the app's other users                                                                         | `useCommunityAssets()`                                    | Moderated before anyone else sees them.                                                                                                                             |
+| Documents the user should keep: files your app makes for them, or files they already have                                 | `useVaultDocuments()` / `useVaultUserDocuments()`         | In the user's My Data, where they outlive your plugin. Reading files they already had needs their consent.                                                          |
+
+**Common mistakes:**
+
+- **Inlining content in `src/`** — a JSON file of lessons, a level pack, base64 images. It counts against the 5 MB cap, and every user downloads all of it to use a little. Put it in `content/`.
+- **Seeding content you wrote into the DataStore from the plugin.** Every user's session tries to write it, the first writer of a `shared` document owns it, and nothing reviews it. Ship it in `content/`. If it must also be searchable, keep a searchable copy in a `shared` collection, but display the pack's version.
+- **Using the DataStore or `useFiasStorage()` for data that is the same for every user.** That is content.
+- **Building `public/` paths at runtime**, e.g. `` `/music-${name}.ogg` ``. Only literal paths are rewritten to the CDN when you publish, so a path built in code 404s in production. Use a lookup table of literal strings, or move the files to `content/` and read them by name.
+
 ## SDK API Reference
 
 All hooks require the app to be wrapped in `<FiasProvider>`:
@@ -479,6 +504,25 @@ generate({
 
 Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
 
+**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
+
+```tsx
+generate({
+  entityId: 'ent_modeldef_nano_banana_2',
+  prompt:
+    'The knight from the first image, standing on a cliff at dawn, painted in the style of the second and third images',
+  referenceImages: [
+    { fileId: knight.fileId },
+    { fileId: styleA.fileId },
+    { fileId: styleB.fileId },
+  ],
+  size: '21:9',
+  resolution: '2K', // '512px' | '1K' (default) | '2K' | '4K'
+});
+```
+
+Use `referenceImage` for one picture and `referenceImages` for several — not both. More than the model takes returns `TOO_MANY_REFERENCE_IMAGES`; a resolution it does not list returns `INVALID_RESOLUTION`. Prefer `fileId` / `archeAssetId` over `dataUrl` when sending several: each `dataUrl` counts against the bridge message size. The result's `costCents` is what the call actually cost, markup included.
+
 Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
 
 #### Full example
@@ -545,14 +589,15 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended,
-//                creditsPerImage, estimatedDurationMs, company, strengths,
-//                providerParams, ... }
+//                supportsReferenceImage, maxReferenceImages,
+//                supportedResolutions, defaultResolution, isPlatformRecommended,
+//                creditsPerImage, creditsPerImageByResolution,
+//                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.
+`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. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). `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:
 
@@ -564,6 +609,8 @@ const seed = entity.providerParams?.find((p) => p.key === 'seed');
 await generate({ entityId, prompt, providerParams: { seed: 42 } });
 ```
 
+Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed).
+
 **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
@@ -772,30 +819,26 @@ const { referenceId } = await vault.attach(documentId, {
 await vault.detach(documentId, referenceId);
 ```
 
-**Saving into the user's OWN files** — `upload(bytes, { ..., userVisible: true })`. By default everything your app writes here is _arche-private_: yours to read and write, invisible in the user's Fias files, unusable by other arches. That is the right home for your app's own state (caches, session snapshots, working files). It is the wrong home for the artifact the user made and asked you to keep — an edited image, an exported document — because they will go looking for it and it will not be there.
+**Saving into the user's Documents** — `upload(bytes, { ..., destination: 'documents' })` (`userVisible: true` is the same thing). By default everything your app writes here is _arche-private_: yours to read and write, invisible in the user's Fias files, unusable by other arches. That is the right home for your app's own state (caches, session snapshots, working files). It is the wrong home for the artifact the user made and asked you to keep — an edited image, an exported document — because they will go looking for it and it will not be there.
 
 ```tsx
 const saved = await vault.upload(bytes, {
-  name: 'sunset.png',
+  name: 'sunset.png', // a suggestion — the user can change it
   mimeType: 'image/png',
-  userVisible: true,
+  destination: 'documents',
 });
+// saved.documentId, saved.name (what the user kept), saved.access ('none' | 'read' | 'write')
 ```
 
-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.
+The host opens its **Save dialog**: the user picks a folder in their Documents, can rename the file, and settles a name clash (keep both, or replace a file of the same type). You cannot script it, batch it, or pre-approve it, and you never learn the folder. Requires `vault:user-documents:write`. Cancelling rejects with `SAVE_DECLINED`; that is a normal outcome, not an error to retry. `folderPath`, `replacesDocumentId`, `tags` and `sensitivity` are rejected alongside it (the user decides those). 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`.
+**Afterwards the file is the user's.** `useVaultDocuments()` no longer lists it. What you keep is reported as `access`: with `vault:user-documents:read` you can open it again (`'read'`) through `useVaultUserDocuments()`, and with `vault:user-documents:edit` the dialog offers the user "keep editing" (`'write'`) so you can keep saving it with `useVaultUserDocuments().saveContent`. The user can change either in Arche Access.
 
-```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;
-}
-```
+**Arche Saves, automatically** — `upload(bytes, { ..., destination: 'arche-saves' })` saves into the user's `Arche Saves/<your label>/` with no dialog. Only for an arche a Fias admin has designated (that issues its label, which is yours for good) and that declares `vault:arche-saves:write` (human-reviewed). Otherwise it rejects with `ARCHE_NOT_DESIGNATED` or `PERMISSION_DENIED`. The files are the user's to keep, move or delete; you can keep reading them while they stay in Arche Saves.
 
-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.
+**`saveCopy(documentId, { suggestedName? })`** — hand the user a copy of one of your own documents through the same dialog, without re-sending the bytes (needs `vault:documents:read` too). Your working file is unchanged; delete it afterwards if you no longer need it.
+
+**A document's visibility never changes.** Your private documents stay private, and a file in the user's files stays theirs — there is no call that moves one into the other.
 
 **Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
 
@@ -834,6 +877,7 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - Grants are **per-document** and **standing**: the plugin can re-read granted documents in later sessions until the user removes access in **Vault → App Access**.
 - 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).
+- **Say what you can open:** `pick({ accept: ['application/pdf', 'image/*', '.docx'] })` takes MIME types, MIME families or extensions, up to 20. The host's Open dialog offers the matching files; the user can still reveal the rest, shown disabled. A malformed list rejects with `INVALID_PARAMS`. Omitted, every type is offered.
 - 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.
@@ -880,7 +924,10 @@ const saved = await userDocs.saveContent({
 
 ### Sending a document for signature — Document Sign handoff
 
-**Permission:** `navigation:open_arche`.
+**Permission:** `navigation:open_arche` to hand the document over. Reading the
+envelope's status afterwards is a separate act (`docsign:envelopes:read`) —
+your app only ever sees envelopes it started this way, and never their
+document bytes.
 
 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
@@ -924,7 +971,9 @@ 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.
+existing association because a `correlationId` matched. Anything you would act
+on — who signed, what is outstanding — comes from reading the envelope under
+`docsign:envelopes:read`, not from the payload.
 
 **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
@@ -953,6 +1002,65 @@ 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.
 
+### `useDocumentSign()` — Follow an envelope you handed over
+
+**Permission:** `docsign:envelopes:read`
+
+The other half of the handoff above. Once the user has pressed Send in
+Document Sign, this is how your app learns what happened — status, who the
+recipients are, where each of them has got to, and the audit timeline.
+
+```tsx
+import { useDocumentSign } from '@fias/arche-sdk';
+
+const sign = useDocumentSign();
+
+const envelope = await sign.getEnvelope(approval.envelopeId);
+if (envelope.status === 'completed') markApproved(approval.id);
+
+// The audit timeline, oldest first.
+const { events } = await sign.listEvents(approval.envelopeId);
+```
+
+**The contract:**
+
+- **Only envelopes YOUR app started**, via a `sign_document` handoff. Not one
+  the user created in Document Sign directly, not another app's. Two
+  independent gates, both the user's: they grant access by pressing Send on an
+  envelope you handed over (named to them on the send screen, revocable in
+  Vault → App Access), and the platform separately requires the envelope to
+  record your app as its origin. Either one missing means no read.
+- **This is where truth comes from.** The `sign_document_result` handoff is a
+  pointer; it rides navigation state, which is forgeable. Write "signed" into
+  an approval record only on the strength of a read.
+- **No list verb.** Keep the `envelopeId` on your own record and read by id —
+  the same reason the result has to be matched to an outstanding `requestId`
+  and consumed once.
+- **Drafts are not readable.** Send is the moment the user grants access, so a
+  `saved_draft` result gives you an id to keep, and `getEnvelope` on it rejects
+  until the envelope is actually sent. Do not poll a draft.
+- **One error for every refusal.** `ENVELOPE_NOT_FOUND_OR_NOT_GRANTED` covers
+  an unknown id, an envelope you did not start, one on a workspace this user
+  cannot act for, a draft, and one whose access the user has removed. Deliberately
+  indistinguishable — a specific "it exists but you cannot see it" would let
+  anyone probe for envelope ids. Treat it as "we can no longer follow this",
+  not as a bug, and stop asking.
+- **You never see the document.** No bytes, no download URL — and no recipient
+  email addresses either. Name, role, status and timestamps only. If your app
+  supplied the recipients, it already has their addresses.
+- **The timeline is a projection, not the stored rows.** `type`, `actorKind`,
+  `recipientId`, `createdAt`. Signers' IP addresses and user agents, the event
+  payloads, and the hash-chain columns stay on the platform — they belong to
+  the signing certificate, not to your app.
+- **There are no webhooks.** Nothing calls you when a recipient signs. Read
+  when your UI needs to know — on mount, on a refresh the user asked for — not
+  on a timer.
+- Terminal envelopes (`voided`, `expired`, `declined`) stay readable. A
+  terminal outcome is part of the trail you came for; your UI should render it
+  rather than leaving the record stuck on "in progress".
+- Not available in the builder preview: a preview tenant has no arche row, so
+  it can never be an envelope's origin.
+
 ### `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`).
@@ -1050,6 +1158,32 @@ const fresh = await getUrl(assetId);
 
 Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
 
+### `useFiasContent()` — This plugin's content pack
+
+**Permission:** `entities:client_invoke`
+**Returns:** `FiasContentApi`
+
+Ship large or numerous files — lessons, articles, data, images, audio, fonts — in a `content/` directory beside `src/`. They are not bundled: `fias-dev submit` uploads them separately (only the files that changed), the review reads every one, and the published plugin reads them at runtime through this hook. The host page fetches, verifies and caches them; your plugin never touches the network.
+
+```tsx
+import { useFiasContent, FiasContentError } from '@fias/arche-sdk';
+
+const content = useFiasContent();
+
+const lessons = await content.list('lessons/'); // [{ path, sizeBytes, mimeType }]
+const markdown = await content.getText('lessons/01-intro.md');
+const course = await content.getJson<Course>('course.json');
+const batch = await content.getMany(['a.md', 'b.md'], 'text'); // up to 100 files per call
+const cover = await content.getObjectUrl('img/cover.webp'); // blob: URL for <img src>
+const { url } = await content.getUrl('audio/theme.ogg'); // signed URL, for long streaming audio
+```
+
+- Paths are relative to `content/`. Formats: `.md`, `.txt`, `.json` (text, ≤ 5 MB each); `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.avif` (static, single-frame images, ≤ 20 MB and 50 megapixels); `.ogg` (audio, ≤ 50 MB); `.woff2` (fonts, ≤ 5 MB). A pack holds at most 10,000 files, 2,000 images, 20 MB of text and 500 MB in total. Run `npx fias-dev content check` to validate without submitting.
+- Prefer `getObjectUrl` for images and fonts: repeat views come from the host cache. `getUrl` is for media that must stream or seek; it bypasses the cache, and a URL held past its `expiresAt` must be requested again.
+- Failures throw `FiasContentError` with a `code`: `CONTENT_NOT_FOUND`, `CONTENT_NOT_TEXT`, `CONTENT_TOO_LARGE`, `CONTENT_UNAVAILABLE`, `CONTENT_THROTTLED`, `CONTENT_UNAVAILABLE_IN_PREVIEW`, `PERMISSION_DENIED`, `RATE_LIMIT`. `getMany` returns the error for a failed path instead of throwing.
+- There is no published pack in the Arche Builder preview, so calls there fail with `CONTENT_UNAVAILABLE_IN_PREVIEW`; the dev harness serves your local `content/` directory.
+- Every publish reviews all of the content again. Reads are free for your users; the pack's storage and bandwidth are billed to you, the contributor.
+
 ### `useCommunityAssets()` — User-published images, visible to this arche's users
 
 **Permissions:** `assets:community:read` (browse/view) · `assets:community:publish` (publish/unpublish/listMine)
@@ -1159,18 +1293,29 @@ openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
 openArche('arc_0123456789abcdef0123456789abcdef', { path: 'map' });
 ```
 
-**Receiving a deep link.** There is nothing extra to opt into: `currentPath` in
-the init payload is the full platform path the host loaded you at, so an arche
-that wants to be a deep-link target just reads it once at boot.
+**Receiving a deep link.** There is nothing extra to opt into: `currentPath` is
+the host's path expressed in YOUR arche's route space — the same space
+`navigateTo` accepts — so an arche that wants to be a deep-link target just
+reads it at boot. The `/a/<arche>` prefix is stripped for you, and your home
+screen reads `/`.
 
 ```tsx
 const { currentPath } = useFiasNavigation();
-// e.g. '/a/arc_0123…/map' → 'map'
-const page = currentPath.split('/').slice(3).join('/') || 'home';
+// a deep link to '/a/arc_0123…/map' arrives here as '/map'
+const page = currentPath.replace(/^\//, '') || 'home';
 ```
 
-It is set once, when your app mounts. A deep link from another arche always
-mounts you fresh, so that is exactly when you need it.
+It is `''` until the host's `init` message lands — the bridge handshake is
+async, so your first render usually beats it. Treat `''` as "not known yet"
+rather than as your home screen; that distinction is what keeps a direct entry
+such as a share link from being lost to the race.
+
+After that it TRACKS the host: it updates when you call `navigateTo`, and when
+the user moves the host themselves with browser back/forward. So a router
+driven off `currentPath` stays in step with the address bar, and the back
+button works the way your users expect — you do not have to mirror the path in
+your own state. The dev harness echoes navigations the same way, so what you
+see locally is what ships.
 
 ### Opening external links
 
@@ -1480,6 +1625,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, 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)
+- **Content packs:** files in `content/` don't count toward the bundle either. If content (lessons, data, media) is what is pushing you toward the cap, move it there — see "Where does each kind of data go?" above. A pack holds up to 10,000 files and 500 MB (20 MB of text, 2,000 images)
 - **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`
 
@@ -1489,6 +1635,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - `storage_write`: 120/minute
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
+- Content reads (`useFiasContent()`): 120/minute — read related files together with `getMany` (up to 100 per call)
 
 A separate **runaway-loop detector** fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) …` — the path tells you where to debounce at the source.
 
@@ -1578,6 +1725,8 @@ npm run submit
 # Builds, validates, packages, uploads, submits for AI review
 ```
 
+If the plugin has a `content/` folder, submit uploads it too — only the files that changed — and the review reads the whole pack on every publish. `npx fias-dev content check` validates it without submitting.
+
 The first time you list a plugin in the marketplace there is a one-time
 listing fee; subsequent submissions of the same plugin only pay a small
 per-review fee. The harness fetches the exact amount from the server and