@fias/arche-sdk 2.32.0 → 2.34.0

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.32.0 -->
+<!-- fias-sdk-guide-version: 2.34.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -21,19 +21,19 @@ vite.config.ts            # Vite dev server config (port 3100)
 
 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 music tracks 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.                                                                                                                                                                 |
-| Sound effects that must play on cue (hits, jumps, UI clicks)                                                              | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
-| The same sound effects shared by several arches (optional)                                                                | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
-| 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.                                                                                                                 |
+| 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 music tracks 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, 3D models | 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.                                                                                                                                                                 |
+| Sound effects that must play on cue (hits, jumps, UI clicks)                                                                         | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
+| The same sound effects shared by several arches (optional)                                                                           | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
+| 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:**
 
@@ -92,6 +92,7 @@ function MyComponent() {
 - `spacing`: `{ xs, sm, md, lg, xl }` (CSS values like `'8px'`)
 - `fonts`: `{ body, heading, mono }` (font-family strings)
 - `components`: `{ borderRadius, buttonRadius, cardRadius, inputRadius, shadowSm, shadowMd, shadowLg, borderWidth }`
+- `brand?`: `{ displayName, logoUrl, primaryColor, accentColor, headerTextColor }` — the Company's brand, present only when your app runs on that Company's portal and the Company has set one. Each field may be `null` (colours are `#RRGGBB`; `logoUrl` is for an `<img src>`). Absent on fias.io: keep your own palette as the fallback, and re-read it on every theme update (the brand can arrive after your first render). In the dev harness, set `"mockBrand": { … }` in `fias-dev.config.json` to see your app on a portal.
 
 ### `useFiasVendoredAssets(importSpecifier)` — Self-hosted vendored-library asset URLs
 
@@ -346,6 +347,30 @@ A collection can carry rules the platform checks on **every** write, so a buggy
 
 Rules that relate two documents (`references`, `ledgerSums`) are checked at the **end** of the write, so write the ledger row and the counter, or the target and the document pointing at it, together in one `batch` in any order. A violation rejects the whole write with `CONSTRAINT_VIOLATION`. Rules are **tighten-only**: you can add rules (at most 10 per kind), never remove or change one.
 
+#### Attested logs (`attested`)
+
+**Permission:** `data:attested` (requires `data:store`; human-reviewed)
+
+An audit log whose "who did it" your code can't fake. Declare it in `fias-plugin.json` on a **new** collection, with `appendOnly` beside it:
+
+```json
+"permissions": ["data:store", "data:workspace", "data:attested"],
+"collections": [
+  { "name": "audit_log", "scope": "workspace", "constraints": { "appendOnly": true, "attested": true } }
+]
+```
+
+- Fias stamps every row you add with `attestation`: `{ personRef, agentRef?, channel, recordedAt, appVersion?, buildHash? }` (`recordedAt` is when Fias stored the row; `appVersion` and `buildHash` name the release live when it was stored, on every row of your published app and never on a test row). It is never part of `data`, and nothing you send can set it. Read it from `getDocument()`, `query()` and `search()`; `put()` and each `batch()` write return the one they stamped.
+- `personRef` is the app user ref of the person accountable for the row; name it with `resolvePeople`. `agentRef` is set only when an agent key wrote it (`channel: 'agent'`), and never resolves to a name: show "an agent acting for <person>".
+- `channel` is `session`, `portal` (a Company portal), `assistant` (Fias AI), `agent` or `non_production`. Every row written in the dev harness or a Forge test is `non_production`, even after test data is carried into your published app — never present those as real.
+- Rows can't be overwritten, or deleted one by one, by you, your users, agents or your contributor CLI (which can't write to an attested collection at all, and reads attestations without `personRef` / `agentRef`; agents and Fias AI read only the channel, time and release).
+- In your published app only the publish creates it: `createCollection()` with the same constraints just finds it, and creating one there that the manifest didn't is refused (`ATTESTED_MANIFEST_ONLY`). In the dev harness and a Forge test your code creates it, as for any collection (the harness still checks your manifest declares it); a builder preview can't have one. Test data carried into your app at its first publish may hold only logs that release declares.
+- It is refused on `shared` scope and on a collection that already exists.
+- Fias turns attested logs on platform by platform, either for every app or for a short pilot list. Until it has for your app, a publish or a Forge test that creates a new log is refused (`ATTESTED_LOGS_NOT_AVAILABLE`); leave the log out of your manifest until then, never declare it without `attested` (that name could then never become a log). The dev harness's live mode is shared by all your apps, so it creates a new log only once logs are on for every app — a pilot app tests its log in Forge. A log your app already has keeps working whatever the switch says, and its Forge test channel can always recreate it.
+- **Keep it declared.** Every later release must declare it, by name, with `attested`, and keep `data:attested`; a publish that drops either is refused (`ATTESTED_LOG_UNDECLARED`) — unless the log holds no real rows (empty, or only test rows carried in from a Forge test channel) and you leave it out of `collections` entirely; naming it without `attested` is always refused. Your app can write only to the logs its live release declares. A published log is never deleted, even empty (`COLLECTION_ATTESTED`), so its name stays a log. It lasts as long as your app: no workspace that holds a log — your app's own, a guild's or a Fias org's — can be archived (`WORKSPACE_ATTESTED`), so don't offer to archive one.
+- In a Fias org workspace, adding a row also needs the workspace's approval of your app to cover `data:attested`; otherwise it is refused (`ARCHE_NOT_APPROVED`) and the workspace's admins see the app waiting to be approved again.
+- Call it **platform-attested**. It proves who wrote the row, when and through which release, not that `data` is true; never call it "tamper-evident".
+
 ### Letting agents use your data (`agentAccess`)
 
 **Permission:** `data:agents` (requires `data:store`)
@@ -642,7 +667,7 @@ const [assignee] = await workspaces.resolvePeople([task.assigneeRef], shared.wor
 const label = assignee?.displayName ?? 'Former member';
 ```
 
-**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives), `listMembers`, `addPeople`, `updateMember`, `removeMember`, `resolvePeople`. **Add people with `addPeople(workspaceId, { role? })`**: Fias draws a sheet in which the person picks co-members of their Fias workspace or types an exact username, and may change the role (you suggest `'admin'`, `'member'` or `'viewer'`); it resolves with `{ added: [{ ref, displayName, role }] }` — empty if they added no one. Your code never names who to add. (`addMember(workspaceId, username, …)` is deprecated: it works only for apps from before app user refs, and in the dev harness and Forge test channel; elsewhere it rejects with `ADD_MEMBER_USE_SHEET`.) Members come back named by your app's `ref` for them and their `displayName` — never a username or id — and `updateMember` / `removeMember` take that `{ ref }`. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers`/`resolvePeople` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `ADD_PEOPLE_UNAVAILABLE` (no sheet here: the Forge test channel, Company portals), `MEMBER_TARGET_USE_REF` (name members by `{ ref }`), `SHEET_BUSY`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
+**Methods:** `create`, `openForWorkspace`, `list`, `get`, `archive` (owner only — final: an archived workspace cannot be reopened, and it is deleted with its documents 30 days later; say so before your user archives. A workspace holding an attested log can't be archived), `listMembers`, `addPeople`, `updateMember`, `removeMember`, `resolvePeople`. **Add people with `addPeople(workspaceId, { role? })`**: Fias draws a sheet in which the person picks co-members of their Fias workspace or types an exact username, and may change the role (you suggest `'admin'`, `'member'` or `'viewer'`); it resolves with `{ added: [{ ref, displayName, role }] }` — empty if they added no one. Your code never names who to add. (`addMember(workspaceId, username, …)` is deprecated: it works only for apps from before app user refs, and in the dev harness and Forge test channel; elsewhere it rejects with `ADD_MEMBER_USE_SHEET`.) Members come back named by your app's `ref` for them and their `displayName` — never a username or id — and `updateMember` / `removeMember` take that `{ ref }`. **Rate limits (per minute):** `create`/`archive` 20, member ops 30, `list`/`get`/`listMembers`/`resolvePeople` 120. **Error codes:** `NOT_A_MEMBER`, `FORBIDDEN`, `ROLE_CEILING`, `ADD_PEOPLE_UNAVAILABLE` (no sheet here: the Forge test channel, Company portals), `MEMBER_TARGET_USE_REF` (name members by `{ ref }`), `SHEET_BUSY`, `MUST_KEEP_ONE_OWNER`, `WORKSPACE_NOT_FOUND`, `WORKSPACE_ATTESTED`, `HOLDER_BACKED_WORKSPACE`, `HOLDER_NOT_ELIGIBLE`. Read workspace documents with `useFiasDataStore().get`/`query`/`search` passing `{ workspaceId }` (every active member can read; make the collection `searchable` to use `search`). **Per-collection role floors:** raise a workspace collection's minimum role at creation — `createCollection('board_minutes', { userScope: 'workspace', writeMinRole: 'admin', readMinRole: 'member' })` makes that collection admin-write / member-read, above the default (write ≥ member, read ≥ viewer).
 
 ### `useFiasAccess()` — The current user's own access in a workspace
 
@@ -1590,7 +1615,7 @@ for (const sound of entries) {
 **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.
+Ship large or numerous files — lessons, articles, data, images, audio, fonts, 3D models — 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';
@@ -1605,7 +1630,7 @@ const cover = await content.getObjectUrl('img/cover.webp'); // blob: URL for <im
 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.
+- 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); `.glb` (3D models, ≤ 25 MB, read with `getBytes` — see "VR and AR apps (WebXR)" for what a model may hold). A pack holds at most 10,000 files, 2,000 images (counting the textures inside models), 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.
@@ -1828,15 +1853,18 @@ const result = await web.extract({
     },
   },
   maxAgeSeconds: 24 * 3600,
+  reads: 2, // money: read twice, keep only what both readings agree on
 });
-// result.data.rates, result.site.name, result.fetchedAt, result.fromCache, result.discarded
+// result.data.rates, result.site.name, result.fetchedAt, result.fromCache, result.discarded, result.disagreed
 ```
 
 Your app reads pages only on **websites Fias approved** (regulated institutions such as credit unions and banks, and government sites) — any page on an approved site, so a redesigned or moved page keeps working. To have a site approved, ask Fias. `listSites()` lists them (free).
 
-`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a product type, not a product name). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a heading the page prints is fine as a choice if you listed it; a string the page chose never is). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. A model reading a page is not deterministic, so **where a wrong number matters (money), pass `reads: 2`**: the page is read twice, independently, and only a value both readings agree on is returned — a field they disagree on is `null` (a list keeps only the rows both produced) and is named in `disagreed`, for a person to confirm. A list named in `disagreed` may be missing rows the page prints: never conclude "absent on the page" (not offered) from a field in `disagreed` — treat it as unknown. Agreement says a value was stable across two readings, not that it is right; always show `site.name` and `fetchedAt` beside a figure so a person can check it. With two readings `discarded` names a list whole (`rates`), not a row. After the field names, `disagreed` names each row a list lost by its index in the in-order reading (`rates[3]`): the list you get is that reading with those rows removed. **Give a list a `key`** — the item fields that identify a row on the page (`key: ['product', 'months']`) — and a row both readings produced under one key is kept and agreed cell by cell: a cell they disagree on is `null` in the row and named `rates[3].apy` after the row entries, instead of the whole row being dropped because one cell differed (a row with a `null` key cell, or a key value a reading gave twice, is matched whole; the `3` is the row's index in the in-order reading, not in the list you received). `disagreedEntries(disagreed)` splits the entries into `fields`, `rows` and `cells`, each cell with its `position` in the list you received, and `disagreedFieldNames(disagreed)` gives the names alone; match entries by name or the `name[` prefix, never by equality or count. The reader never sees a key: a single reading Fias holds is paired, not bought again, when you add one; what two readings agreed on is read again. Two readings are two reader charges; the platform may raise the floor for every app, so check `disagreed` whatever you asked for. The reader's model, and so a reading's price, is chosen by the platform. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+
+**Write the form from the page, not from what pages usually look like.** Read the page yourself first (you can; the reader cannot show it to you) and write the form from what that page prints, one per product you read off it (each is its own reading pair). List the page's own words — its table headings, its model-year bands, its term column headers — as `enum` choices on each row (up to 50 values of up to 60 characters) plus a fixed escape such as `(none of these)`, so the reader copies and never classifies; keep a small table in the app that turns each heading into the cells your code reads, and key each list by that cell and the printed term. Ask only for cells the page prints: a cell the page never prints is answered `null` by one reading and guessed by the other, whatever its description says. A page changes: rows under your escape choice, a withheld row whose key cell the readings could not agree on, the list named whole in `discarded` (with two readings it never names a row), an empty list where the page says the product is published, or far fewer rows than last time mean the form must be rewritten — tell the user which page, in plain words. On the Rate Research pilot a generic form that asked the reader to classify had 63 of 117 counted rows withheld and agreed twice on three plain misreadings; forms written from each page lost no rows on the next refresh and matched one institution's pages in 57 of 57 values. `reads: 2` stays on either way: it catches the misread digit, which no form can.
 
-One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and the reading (a fast model's tokens — well under a cent for a typical page) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
+One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and each reading (a fast model's tokens — well under a cent for a typical page; two with `reads: 2`) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
 
 ### `useFiasX()` / `useFiasLinkedIn()` — Act as a connected account
 
@@ -2145,6 +2173,110 @@ Notes:
 - Only `http(s)` URLs make sense here; `javascript:`/`data:` URLs are blocked
   by the sandbox.
 
+### VR and AR apps (WebXR)
+
+A plugin can be a VR or AR app: a game, a 3D viewer, a space to walk around.
+On a headset such as a Meta Quest, the person opens your arche in the
+headset's browser and presses your "Enter VR" button. No SDK hook or
+permission is needed: the plugin frame is allowed WebXR, and you use the
+browser's own API or a library. With three.js, add `three` to the manifest's
+`dependencies` (the published arche loads it at runtime) and to `package.json`,
+with `@types/three` in `devDependencies`, all at the same exact version.
+
+**Import from `three` itself, never `three/addons/...`.** The published build
+maps a dependency's bare name but not its subpaths, so `three/addons/...`
+(VRButton, OrbitControls, GLTFLoader) works under `npm run dev` and then fails
+the build with "no importmap entry". An Enter VR button is a few lines:
+
+```tsx
+import * as THREE from 'three';
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.xr.enabled = true;
+renderer.xr.setReferenceSpaceType('local-floor'); // y = 0 is the room's floor
+container.appendChild(renderer.domElement);
+
+// Offer VR only where it exists. On a phone or desktop this resolves false and
+// the same scene stays a normal 3D view.
+const vr = (await navigator.xr?.isSessionSupported('immersive-vr').catch(() => false)) ?? false;
+
+// Call from the button's click handler, and request the session before any
+// other await: the click is what lets the browser start it.
+async function enterVr(xr: XRSystem) {
+  const session = await xr.requestSession('immersive-vr', { optionalFeatures: ['local-floor'] });
+  await renderer.xr.setSession(session);
+}
+
+// Not requestAnimationFrame: in VR the headset drives the frames.
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
+```
+
+When you need an addon, copy its file from `node_modules/three/examples/jsm/`
+into `src/vendor/three/`, with the files it imports by relative path, keeping
+the folders. Its other imports are `three`, which the build maps. Beside it, add
+a one-line `.d.ts` so TypeScript uses `@types/three`'s types, for example
+`src/vendor/three/loaders/GLTFLoader.d.ts` holding
+`export * from 'three/examples/jsm/loaders/GLTFLoader.js';`.
+
+**3D models.** Put each model in your content pack as a `.glb`
+(`content/models/chair.glb`) and read its bytes with `useFiasContent()` (see
+that section; it needs the `entities:client_invoke` permission). Your plugin
+cannot fetch, so `GLTFLoader.load(url)` fails, but `parseAsync` takes the
+bytes. Copy GLTFLoader in as above (`loaders/GLTFLoader.js` plus
+`utils/BufferGeometryUtils.js` and `utils/SkeletonUtils.js`) and swap its
+texture loader: three.js decodes embedded textures with `fetch()`, which the
+sandbox blocks, and the model then loads with NO textures and only a console
+warning says why.
+
+```tsx
+import * as THREE from 'three';
+import { useFiasContent } from '@fias/arche-sdk';
+import { GLTFLoader } from './vendor/three/loaders/GLTFLoader.js';
+
+const content = useFiasContent();
+const loader = new GLTFLoader();
+loader.register((parser) => {
+  parser.textureLoader = new THREE.TextureLoader(parser.options.manager); // loads through <img>
+  return { name: 'fias_no_fetch_textures' };
+});
+const gltf = await loader.parseAsync(await content.getBytes('models/chair.glb'), '');
+scene.add(gltf.scene);
+```
+
+What a model may hold, and why:
+
+- One self-contained binary glTF 2.0 file, at most 25 MB: everything packed
+  inside, with no separate `.bin` or image files. A `.gltf` with side files is
+  refused; Blender's glTF exporter makes the right kind with "glTF Binary (.glb)".
+- At most 64 textures, each a still PNG, JPEG, WebP or AVIF. Every texture is
+  screened like an image file and counts toward the pack's 2,000 images; the
+  names and `extras` in the model are reviewed like text.
+- Export without compression. KTX2 / Basis textures are refused, and Draco or
+  meshopt geometry cannot be decoded in a plugin: their three.js decoders need
+  WebAssembly, which the plugin's sandbox does not run.
+
+A texture you apply in code can be its own image file in the pack: pass the URL
+from `content.getObjectUrl('textures/wall.webp')` to
+`new THREE.TextureLoader().loadAsync(url)`.
+
+Notes:
+
+- Entering VR or AR needs a click, and the browser may ask the person for
+  consent. `immersive-ar` (passthrough on Quest) starts the same way: create
+  the renderer with `alpha: true` and hide your sky so the room shows through.
+- Head and controller positions reveal things about the person, like their
+  height. Use them to draw the scene, not as data you save or send.
+- To test on a headset with `fias-dev`, the page must be a secure context.
+  `localhost` is one and a LAN address (`http://192.168.…`) is not, so connect
+  the headset by USB with developer mode on, run the commands below, and open
+  `http://localhost:3200` in the headset's browser. A published arche needs
+  nothing extra.
+
+```bash
+adb reverse tcp:3100 tcp:3100   # your plugin's dev server
+adb reverse tcp:3200 tcp:3200   # the fias-dev harness
+```
+
 ### `useStepNavigation()` — Multi-step workflows
 
 **Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
@@ -2342,7 +2474,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 | `expandedDescription` | No            | Long-form marketplace copy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `main`                | Yes           | Entry point source file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `archeType`           | Yes           | `"tool"` or `"site"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `categorySlug`        | No            | Marketplace category for discovery                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `categorySlug`        | No            | Deprecated and ignored — Arche Store categories are `store.categories`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `icon`                | No            | Path to an icon image **under `public/`** (e.g. `public/icon.png`) — only `src/` and `public/` are packaged. Applied on every publish (local, staging and prod) and rehosted as your marketplace/store icon. PNG, JPEG, WebP or SVG, ≤5 MB; raster images must also be ≤1024×1024 px (SVG has no pixel limit). An invalid icon rejects the submission: a first-publish listing fee is refunded, but the AI review that already ran is still billed. To change it, replace the file (or the path) and republish; removing the field keeps the current icon. |
 | `tags`                | No            | Discovery tags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `pricing`             | Yes           | Marketplace **listing** pricing (see "Pricing detail" below). NOT for in-arche charges — use `products`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -2355,6 +2487,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 | `isListed`            | No            | Default `true`. Visible in marketplace store                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `isGame`              | No            | Default `false`. `true` lists your arche on the Games page (`/a/games`) and badges it as a game in the Arche Store. Requires `game`. Omitting it on a republish takes the arche out of Games                                                                                                                                                                                                                                                                                                                                                               |
 | `game`                | With `isGame` | `{ "genres": [...] }` — 1-4 (more only where a Fias admin allowed your arche) of `action`, `rpg`, `board`, `cards`, `casual`, `crafting`, `flying`, `match`, `platform`, `puzzle`, `strategy`, `word`, `racing`, `sports`, `simulation`, `trivia`, `music`, `educational`, `cozy`, `idle`, `tower-defense` (a kind of `strategy`: its games are listed there too). Refused without `isGame: true`                                                                                                                                                          |
+| `store`               | No            | How your arche presents itself in the Arche Store: `{ "subtitle", "categories", "releaseNotes", "languages", "screenshots" }`, every field optional (see "Your Arche Store page" below). Omitting a field on a republish clears it                                                                                                                                                                                                                                                                                                                         |
 | `sdk`                 | Yes           | SDK version range                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `dependencies`        | No            | npm packages with **exact** versions (max 20)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `archeIds`            | Auto          | Per-environment IDs written by the CLI after first publish — don't hand-edit                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -2372,7 +2505,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`, `connections:use`, `schedule:invoke`, `web:sources:read`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `storage:local`, `data:store`, `data:search`, `data:workspace`, `data:attested`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `vault:user-documents:read`, `vault:user-documents:write`, `vault:user-documents:edit`, `vault:workspace-documents:read`, `vault:creative:read`, `vault:creative:write`, `opener:send`, `assets:read`, `assets:community:read`, `assets:community:publish`, `litcraft:hub`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`, `connections:use`, `schedule:invoke`, `web:sources:read`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID (or a `{ capability }` selector, or an entry from `useTextModels()`) and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
@@ -2434,6 +2567,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - **`window.alert()` / `confirm()` / `prompt()` do nothing** (no `allow-modals`): they don't throw — `confirm()` silently returns `false`, so gated actions never run. Build confirmation into your UI (a two-step button or an inline dialog) instead
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
 - **You _can_ open external links in a new tab** (e.g. `window.open('https://…', '_blank')`) — see "Opening external links" above
+- **You _can_ build VR and AR apps (WebXR)** for headsets like the Meta Quest — see "VR and AR apps (WebXR)" above
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
 - All platform communication goes through the bridge (SDK hooks)
@@ -2563,6 +2697,33 @@ If the AI review rejects your submission, the listing-fee portion is
 refunded automatically (the per-review portion is not, since review work
 happened either way).
 
+### Your Arche Store page
+
+Every listed arche gets a public page in the Arche Store. The manifest's `store` block decides how it reads; every field is optional, and a republish that omits one clears it.
+
+```json
+{
+  "store": {
+    "subtitle": "Budgets that balance",
+    "categories": ["finance", "productivity"],
+    "releaseNotes": "New: monthly reports.\nFixed: rounding in CSV exports.",
+    "languages": ["en", "pt-BR"],
+    "screenshots": [
+      { "src": "store/dashboard.png", "alt": "This month's spending by category" },
+      { "src": "store/phone.png" }
+    ]
+  }
+}
+```
+
+- `subtitle` — the line under your app's name, up to 40 characters, one line.
+- `categories` — one or two of `ai-assistants`, `productivity`, `business`, `finance`, `communication`, `social`, `graphics-design`, `photo-video`, `music-audio`, `education`, `developer-tools`, `utilities`, `entertainment`, `lifestyle`, `health-fitness`, `travel`, `food-drink`, `shopping`, `news`, `reference`, `sports`. The first is your primary category: it shows under your app's name and is the one you are ranked in. **Games don't take categories** — a game is listed under its `game.genres`.
+- `releaseNotes` — this release's "What's New", up to 4,000 characters of plain text.
+- `languages` — the languages your app works in, as language tags (`"en"`, `"pt-BR"`), up to 20.
+- `screenshots` — up to 10, shown in order on your page. Each `src` is a file directly in a `store/` folder at your plugin's root (not `public/`, which is served as part of your app). PNG, JPEG or WebP, at most 2 MB, the shorter side at least 320 pixels and the longer at most 4096, between 0.4:1 (a tall phone screen) and 2.5:1 (a wide desktop one). `alt` (up to 120 characters) says what it shows. Only the files you name are sent. Each one is checked by an image safety screen when you publish, billed with your review; one the screen is unsure of is shown once a person at Fias approves it, and the rest of your release goes live meanwhile. A wide screenshot becomes your page's link preview.
+
+Your app answers searches for its categories' words too — a `finance` app is found by "budget apps" even if its description never says "budget". `npx fias-dev validate` checks the block offline.
+
 ### Managing the asset library (for `useArcheAssets`)
 
 `useArcheAssets()` reads a contributor-curated set of images pinned to the arche's published version. Populate that library with the `assets` subcommands. Each command accepts `--env <prod|staging|local>` (default `prod`) and `--arche-id <id>` (auto-resolved from the manifest when omitted).
@@ -2611,11 +2772,22 @@ Manage them on your arche's settings page ("Store listings"), or from a `store-l
       "isGame": true,
       "genres": ["word"],
       "icon": "store-art/wordtrace.png"
+    },
+    {
+      "path": "/tools/budget",
+      "title": "Budget Planner",
+      "description": "Plan a month of spending in five minutes.",
+      "isGame": false,
+      "genres": [],
+      "categories": ["finance"],
+      "icon": "store-art/budget.png"
     }
   ]
 }
 ```
 
+A listing that isn't a game names up to two Arche Store `categories` instead of genres (the same ids as the manifest's `store.categories`, the first its primary one); a game's `categories` stay empty.
+
 ```bash
 npx fias-dev listings list --env staging                # Slots, live and retired listings
 npx fias-dev listings push --env staging                # Show the plan and the charge, then ask