@fias/arche-sdk 2.21.0 → 2.23.0

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.21.0 -->
+<!-- fias-sdk-guide-version: 2.23.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -465,6 +465,85 @@ The text capabilities:
 
 Browse specific models with `npx fias-dev entities`.
 
+#### Multi-turn conversations — `history`
+
+`input` is the NEW user message. Send the earlier turns, oldest first, in `history`:
+
+```tsx
+import { fitHistoryToLimits } from '@fias/arche-sdk';
+
+const request = {
+  entityId: model.entityId,
+  systemPrompt: 'You are a helpful assistant.',
+  input: newMessage,
+};
+await invoke({
+  ...request,
+  // [{ role: 'user' | 'assistant', content }] — pass `request` so the history
+  // gets only the bytes the rest of the call leaves.
+  history: fitHistoryToLimits(messages, { maxTurns: 20, request }),
+});
+```
+
+Every turn is billed as input tokens on EVERY call, so send a window, not the whole transcript. Limits: 40 turns, 100,000 characters per turn, 150,000 in total (`ENTITY_INVOCATION_HISTORY_LIMITS`); a call over them, or a turn with a role other than `user` / `assistant`, is rejected with `INVALID_PARAMS`. The whole call must ALSO fit the bridge: 256 KB serialized for a text call, 1.5 MB with images (`ENTITY_INVOCATION_REQUEST_LIMITS`). A character can take up to 4 bytes (CJK 3, emoji 4, a newline or quote 2), so a history within the character limits can still be too large. `fitHistoryToLimits(turns, { request })` keeps the newest turns that fit both; `invoke()` refuses an oversized call with `REQUEST_TOO_LARGE` before sending it.
+
+#### Reasoning, thinking, and several streams at once
+
+```tsx
+const controller = new AbortController();
+const result = await invoke(
+  {
+    entityId: model.entityId,
+    input,
+    history,
+    // Only for models with capabilities.reasoning; ignored otherwise.
+    parameters: { reasoning: { effort: 'medium', includeThinking: true } }, // effort: 'off' | 'low' | 'medium' | 'high'
+  },
+  {
+    onToken: (text) => appendAnswer(text), // this call's answer chunks
+    onThinking: (text) => appendThinking(text), // this call's reasoning text
+    signal: controller.signal, // controller.abort() → rejects with code 'ABORTED'
+  },
+);
+const cost = result.metadata?.usage?.costCredits; // what this reply cost the user, for a cost label
+```
+
+- **Per-call callbacks** (`onToken` / `onThinking`) are scoped to that one call, so you can run several streams side by side — e.g. the same prompt against three models. A call that passes `onToken` leaves the hook's shared `streamingText` / `result` / `error` alone — its failure arrives only as the rejected promise.
+- **Reasoning** uses more output tokens (billed) but always fits inside the model's output ceiling, so it never raises the credit hold. Set `includeThinking` only if you show the thinking — on some providers it raises the cost of a `'low'` request.
+- **Aborting stops your UI, not the charge.** The platform finishes and bills the generation.
+- A stream fails with `TIMEOUT` only after 2 minutes with no sign of life (the host sends keepalives during silent reasoning) or 15 minutes in total.
+- `result.metadata.usage` has `inputTokens`, `outputTokens`, and `costCredits` when the platform reported them. Display only — the charge is already settled.
+- A failed call rejects with a `FiasBridgeError`: branch on `err.code` (e.g. `INSUFFICIENT_CREDITS`, `PROVIDER_OVERLOADED`), and show `err.requestId` as a support reference when present.
+
+### `useTextModels()` — Let the user pick a text model
+
+**Permission:** `entities:invoke` · **Returns:** `FiasTextModel[]`
+
+For an app whose USER chooses the model (a chat app, a model comparison), read the platform's live catalog instead of hardcoding ids. Each entry's `entityId` goes straight into `invoke`. The list is `[]` until the host delivers it (usually immediately), and retired models drop out, so fall back to a `recommended` entry when a saved choice disappears.
+
+```tsx
+import { useTextModels } from '@fias/arche-sdk';
+
+function ModelPicker({ value, onChange }: { value: string; onChange: (id: string) => void }) {
+  const models = useTextModels();
+  const selected = models.find((m) => m.entityId === value) ?? models.find((m) => m.recommended);
+  return (
+    <select value={selected?.entityId ?? ''} onChange={(e) => onChange(e.target.value)}>
+      {models.map((m) => (
+        <option key={m.entityId} value={m.entityId}>
+          {m.providerDisplayName} · {m.displayName}
+          {m.pricing
+            ? ` — ${m.pricing.inputCreditsPerMillionTokens}/${m.pricing.outputCreditsPerMillionTokens} cr per 1M tok`
+            : ''}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+`capabilities.vision` says the model accepts `images`; `capabilities.reasoning` says it honours `parameters.reasoning`. `pricing` is what the user pays per 1M tokens in credits (1 credit = 1¢), markup included — for display only.
+
 ### `useImageGeneration()` — Generate images via AI models
 
 **Permission:** `entities:image_generate`
@@ -884,6 +963,17 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - **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.
 
+**Workspace-approved reads** — `userDocs.workspace.*`, permission `vault:workspace-documents:read`, declared TOGETHER WITH `vault:user-documents:read` (escalates to human review). When the user is acting in an **org workspace** they belong to, whose admin (or its Company) has **approved your arche**, you can read that workspace's documents without a per-document pick — every document the acting member can see in Documents and Arche Saves, at their role, never proprietary:
+
+```tsx
+const docs = await userDocs.workspace.list({ search: 'invoice' }); // the acting workspace's documents
+const { document, content } = await userDocs.workspace.get(id, { includeContent: true });
+const { url } = await userDocs.workspace.getDownloadUrl(id);
+const { bytes } = await userDocs.workspace.getBytes(id);
+```
+
+Two refusals to handle: `WORKSPACE_REQUIRED` (the user is in their Personal vault, or not a member of the workspace — offer `pick()` instead) and `ARCHE_NOT_APPROVED` (this workspace has not approved your arche, or approved it before it asked for this access — say so; a workspace or Company admin approves apps under Workspace Controls). **An approval covers exactly what the admin was shown:** if you add this permission, or start reading a new kind of workspace data, after being approved, those reads are refused with `ARCHE_NOT_APPROVED` until an admin approves again — plan releases that widen access with that in mind. The workspace is fixed when your arche opens (the user reopens it to switch), approval is revocable at once, and every read is logged where the admin can see it. Not available in the builder preview. In the dev harness, `mockWorkspace` in `fias-dev.config.json` (`"approved"` default, `"unapproved"`, `"personal"`) lets you exercise both refusals.
+
 **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
@@ -1218,6 +1308,36 @@ Three things to design around:
 
 Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
 
+### `useCompanyEmail()` — Send email as the Company the app is used in
+
+**Permission:** `email:company:send`
+**Returns:** `CompanyEmailApi`
+
+For apps built for an approved partner Company: send email **from the Company's own verified domain** (e.g. `team@example.com`), not from Fias. Declaring the permission is not enough — a Company admin must also authorize your app to send, and chooses who it may email: members of the workspace it is used in, members of the whole Company, or anyone. Until then every call is refused with `COMPANY_EMAIL_NOT_AUTHORIZED`.
+
+```tsx
+import { useCompanyEmail } from '@fias/arche-sdk';
+
+const email = useCompanyEmail();
+const { results, sent } = await email.send({
+  requestKey: `digest-${weekId}`, // reuse on retry — never double-sends
+  to: members.map((m) => ({ userId: m.userId })),
+  subject: 'Your weekly digest',
+  text: digestText, // required
+  html: digestHtml, // optional, sanitized
+});
+// results[i]: { index, status: 'accepted' | 'unknown' | 'failed' | 'muted' | 'not_sent' }
+```
+
+- **You never choose the From address** — it is the address the Company assigned your app. You choose recipients and content.
+- **Name members by `userId`**; you never see their addresses. Raw `{ email }` recipients work only if the Company let your app email anyone. One recipient outside what the Company allowed refuses the whole call (without saying which).
+- **The user must be working in one of the Company's workspaces, with edit access.** Each recipient is charged to that user, like any paid call; up to 50 recipients per call, and a daily limit per app per Company.
+- **Retry with the same `requestKey`.** A recipient already sent under that key is not sent again. `unknown` means it may have gone out — do not resend it under a new key.
+- **HTML is sanitized** to the email allow-list: tables, inline presentational styles, `https` images and `https`/`mailto` links are kept; `<script>`, `<form>`, `<iframe>` and similar refuse the send (`EMAIL_CONTENT_REJECTED`).
+- **Attachments:** up to 5 files, 5 MB total, and only `.pdf`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.csv`, `.txt`, `.ics`, `.docx`, `.xlsx`. `contentType` must match the extension (e.g. `application/pdf`), and the bytes must be that format; anything else refuses the send (`EMAIL_CONTENT_REJECTED`).
+- **Every email carries one-click unsubscribe.** Recipients who used it come back as `muted`; the Company may also show a "Stop emails from this arche" line, which is always shown for `kind: 'marketing'`.
+- Not available in the builder preview or the local dev harness — it sends real email. Other refusals: `WORKSPACE_REQUIRED`, `RECIPIENT_NOT_ALLOWED`, `COMPANY_EMAIL_UNAVAILABLE` (the Company's domain is not ready or paused), `DAILY_EMAIL_LIMIT_REACHED`, `INSUFFICIENT_CREDITS`.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -1315,7 +1435,23 @@ 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.
+see locally is what ships. To test a deep link locally, open the harness with
+`?path=/map` (a root-relative path in your route space) and `currentPath`
+starts there instead of at `/`.
+
+**Correcting the URL.** Every `navigateTo` pushes a history entry by default,
+which is right for navigation the user asked for. When you are CORRECTING the
+address bar instead — normalizing a link you were opened at (`/Map/` →
+`/map`), or putting it back after refusing a route — pass `{ replace: true }`
+so Back does not land on the URL you just corrected:
+
+```tsx
+navigateTo('/map', { replace: true });
+```
+
+A host older than this option ignores it and pushes. If you correct paths
+automatically as they arrive, never repeat the same correction twice in a
+row, or a push-only host can trap the Back button between two URLs.
 
 ### Opening external links
 
@@ -1564,9 +1700,9 @@ 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`, `data:store`, `data:search`, `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`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `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`, `assets:read`, `assets:community:read`, `assets:community:publish`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`
 
-**Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
+**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`.
 
 **Defining IAP products (for `useFiasStore`):**
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.21.0 -->
+<!-- fias-sdk-guide-version: 2.23.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -465,6 +465,85 @@ The text capabilities:
 
 Browse specific models with `npx fias-dev entities`.
 
+#### Multi-turn conversations — `history`
+
+`input` is the NEW user message. Send the earlier turns, oldest first, in `history`:
+
+```tsx
+import { fitHistoryToLimits } from '@fias/arche-sdk';
+
+const request = {
+  entityId: model.entityId,
+  systemPrompt: 'You are a helpful assistant.',
+  input: newMessage,
+};
+await invoke({
+  ...request,
+  // [{ role: 'user' | 'assistant', content }] — pass `request` so the history
+  // gets only the bytes the rest of the call leaves.
+  history: fitHistoryToLimits(messages, { maxTurns: 20, request }),
+});
+```
+
+Every turn is billed as input tokens on EVERY call, so send a window, not the whole transcript. Limits: 40 turns, 100,000 characters per turn, 150,000 in total (`ENTITY_INVOCATION_HISTORY_LIMITS`); a call over them, or a turn with a role other than `user` / `assistant`, is rejected with `INVALID_PARAMS`. The whole call must ALSO fit the bridge: 256 KB serialized for a text call, 1.5 MB with images (`ENTITY_INVOCATION_REQUEST_LIMITS`). A character can take up to 4 bytes (CJK 3, emoji 4, a newline or quote 2), so a history within the character limits can still be too large. `fitHistoryToLimits(turns, { request })` keeps the newest turns that fit both; `invoke()` refuses an oversized call with `REQUEST_TOO_LARGE` before sending it.
+
+#### Reasoning, thinking, and several streams at once
+
+```tsx
+const controller = new AbortController();
+const result = await invoke(
+  {
+    entityId: model.entityId,
+    input,
+    history,
+    // Only for models with capabilities.reasoning; ignored otherwise.
+    parameters: { reasoning: { effort: 'medium', includeThinking: true } }, // effort: 'off' | 'low' | 'medium' | 'high'
+  },
+  {
+    onToken: (text) => appendAnswer(text), // this call's answer chunks
+    onThinking: (text) => appendThinking(text), // this call's reasoning text
+    signal: controller.signal, // controller.abort() → rejects with code 'ABORTED'
+  },
+);
+const cost = result.metadata?.usage?.costCredits; // what this reply cost the user, for a cost label
+```
+
+- **Per-call callbacks** (`onToken` / `onThinking`) are scoped to that one call, so you can run several streams side by side — e.g. the same prompt against three models. A call that passes `onToken` leaves the hook's shared `streamingText` / `result` / `error` alone — its failure arrives only as the rejected promise.
+- **Reasoning** uses more output tokens (billed) but always fits inside the model's output ceiling, so it never raises the credit hold. Set `includeThinking` only if you show the thinking — on some providers it raises the cost of a `'low'` request.
+- **Aborting stops your UI, not the charge.** The platform finishes and bills the generation.
+- A stream fails with `TIMEOUT` only after 2 minutes with no sign of life (the host sends keepalives during silent reasoning) or 15 minutes in total.
+- `result.metadata.usage` has `inputTokens`, `outputTokens`, and `costCredits` when the platform reported them. Display only — the charge is already settled.
+- A failed call rejects with a `FiasBridgeError`: branch on `err.code` (e.g. `INSUFFICIENT_CREDITS`, `PROVIDER_OVERLOADED`), and show `err.requestId` as a support reference when present.
+
+### `useTextModels()` — Let the user pick a text model
+
+**Permission:** `entities:invoke` · **Returns:** `FiasTextModel[]`
+
+For an app whose USER chooses the model (a chat app, a model comparison), read the platform's live catalog instead of hardcoding ids. Each entry's `entityId` goes straight into `invoke`. The list is `[]` until the host delivers it (usually immediately), and retired models drop out, so fall back to a `recommended` entry when a saved choice disappears.
+
+```tsx
+import { useTextModels } from '@fias/arche-sdk';
+
+function ModelPicker({ value, onChange }: { value: string; onChange: (id: string) => void }) {
+  const models = useTextModels();
+  const selected = models.find((m) => m.entityId === value) ?? models.find((m) => m.recommended);
+  return (
+    <select value={selected?.entityId ?? ''} onChange={(e) => onChange(e.target.value)}>
+      {models.map((m) => (
+        <option key={m.entityId} value={m.entityId}>
+          {m.providerDisplayName} · {m.displayName}
+          {m.pricing
+            ? ` — ${m.pricing.inputCreditsPerMillionTokens}/${m.pricing.outputCreditsPerMillionTokens} cr per 1M tok`
+            : ''}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+`capabilities.vision` says the model accepts `images`; `capabilities.reasoning` says it honours `parameters.reasoning`. `pricing` is what the user pays per 1M tokens in credits (1 credit = 1¢), markup included — for display only.
+
 ### `useImageGeneration()` — Generate images via AI models
 
 **Permission:** `entities:image_generate`
@@ -884,6 +963,17 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - **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.
 
+**Workspace-approved reads** — `userDocs.workspace.*`, permission `vault:workspace-documents:read`, declared TOGETHER WITH `vault:user-documents:read` (escalates to human review). When the user is acting in an **org workspace** they belong to, whose admin (or its Company) has **approved your arche**, you can read that workspace's documents without a per-document pick — every document the acting member can see in Documents and Arche Saves, at their role, never proprietary:
+
+```tsx
+const docs = await userDocs.workspace.list({ search: 'invoice' }); // the acting workspace's documents
+const { document, content } = await userDocs.workspace.get(id, { includeContent: true });
+const { url } = await userDocs.workspace.getDownloadUrl(id);
+const { bytes } = await userDocs.workspace.getBytes(id);
+```
+
+Two refusals to handle: `WORKSPACE_REQUIRED` (the user is in their Personal vault, or not a member of the workspace — offer `pick()` instead) and `ARCHE_NOT_APPROVED` (this workspace has not approved your arche, or approved it before it asked for this access — say so; a workspace or Company admin approves apps under Workspace Controls). **An approval covers exactly what the admin was shown:** if you add this permission, or start reading a new kind of workspace data, after being approved, those reads are refused with `ARCHE_NOT_APPROVED` until an admin approves again — plan releases that widen access with that in mind. The workspace is fixed when your arche opens (the user reopens it to switch), approval is revocable at once, and every read is logged where the admin can see it. Not available in the builder preview. In the dev harness, `mockWorkspace` in `fias-dev.config.json` (`"approved"` default, `"unapproved"`, `"personal"`) lets you exercise both refusals.
+
 **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
@@ -1218,6 +1308,36 @@ Three things to design around:
 
 Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
 
+### `useCompanyEmail()` — Send email as the Company the app is used in
+
+**Permission:** `email:company:send`
+**Returns:** `CompanyEmailApi`
+
+For apps built for an approved partner Company: send email **from the Company's own verified domain** (e.g. `team@example.com`), not from Fias. Declaring the permission is not enough — a Company admin must also authorize your app to send, and chooses who it may email: members of the workspace it is used in, members of the whole Company, or anyone. Until then every call is refused with `COMPANY_EMAIL_NOT_AUTHORIZED`.
+
+```tsx
+import { useCompanyEmail } from '@fias/arche-sdk';
+
+const email = useCompanyEmail();
+const { results, sent } = await email.send({
+  requestKey: `digest-${weekId}`, // reuse on retry — never double-sends
+  to: members.map((m) => ({ userId: m.userId })),
+  subject: 'Your weekly digest',
+  text: digestText, // required
+  html: digestHtml, // optional, sanitized
+});
+// results[i]: { index, status: 'accepted' | 'unknown' | 'failed' | 'muted' | 'not_sent' }
+```
+
+- **You never choose the From address** — it is the address the Company assigned your app. You choose recipients and content.
+- **Name members by `userId`**; you never see their addresses. Raw `{ email }` recipients work only if the Company let your app email anyone. One recipient outside what the Company allowed refuses the whole call (without saying which).
+- **The user must be working in one of the Company's workspaces, with edit access.** Each recipient is charged to that user, like any paid call; up to 50 recipients per call, and a daily limit per app per Company.
+- **Retry with the same `requestKey`.** A recipient already sent under that key is not sent again. `unknown` means it may have gone out — do not resend it under a new key.
+- **HTML is sanitized** to the email allow-list: tables, inline presentational styles, `https` images and `https`/`mailto` links are kept; `<script>`, `<form>`, `<iframe>` and similar refuse the send (`EMAIL_CONTENT_REJECTED`).
+- **Attachments:** up to 5 files, 5 MB total, and only `.pdf`, `.png`, `.jpg`/`.jpeg`, `.gif`, `.csv`, `.txt`, `.ics`, `.docx`, `.xlsx`. `contentType` must match the extension (e.g. `application/pdf`), and the bytes must be that format; anything else refuses the send (`EMAIL_CONTENT_REJECTED`).
+- **Every email carries one-click unsubscribe.** Recipients who used it come back as `muted`; the Company may also show a "Stop emails from this arche" line, which is always shown for `kind: 'marketing'`.
+- Not available in the builder preview or the local dev harness — it sends real email. Other refusals: `WORKSPACE_REQUIRED`, `RECIPIENT_NOT_ALLOWED`, `COMPANY_EMAIL_UNAVAILABLE` (the Company's domain is not ready or paused), `DAILY_EMAIL_LIMIT_REACHED`, `INSUFFICIENT_CREDITS`.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -1315,7 +1435,23 @@ 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.
+see locally is what ships. To test a deep link locally, open the harness with
+`?path=/map` (a root-relative path in your route space) and `currentPath`
+starts there instead of at `/`.
+
+**Correcting the URL.** Every `navigateTo` pushes a history entry by default,
+which is right for navigation the user asked for. When you are CORRECTING the
+address bar instead — normalizing a link you were opened at (`/Map/` →
+`/map`), or putting it back after refusing a route — pass `{ replace: true }`
+so Back does not land on the URL you just corrected:
+
+```tsx
+navigateTo('/map', { replace: true });
+```
+
+A host older than this option ignores it and pushes. If you correct paths
+automatically as they arrive, never repeat the same correction twice in a
+row, or a push-only host can trap the Back button between two URLs.
 
 ### Opening external links
 
@@ -1564,9 +1700,9 @@ 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`, `data:store`, `data:search`, `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`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `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`, `assets:read`, `assets:community:read`, `assets:community:publish`, `navigation:open_arche`, `sandbox:vendored-libraries`, `ai:actions`
 
-**Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
+**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`.
 
 **Defining IAP products (for `useFiasStore`):**