Merge origin/main into juancastro/put-2251-let-apps-send-notifications-to-their-own-user

src/docs/src/AI/chat.md

@@ -32,9 +32,9 @@ An object containing the following properties:
 - `signal` (AbortSignal) (Optional) - Abort the request, including while waiting for the next streamed chunk. Cancellation rejects with the signal reason (normally an `AbortError`).
 - `stream` (Boolean) - A boolean indicating whether you want to stream the completion. Defaults to `false`.
 - `max_tokens` (Number) - The maximum number of tokens to generate in the completion. By default, the specific model's maximum is used.
-- `temperature` (Number) - A number between 0 and 2 indicating the randomness of the completion. Lower values make the output more focused and deterministic, while higher values make it more random. By default, the model's own temperature is used. Some OpenAI reasoning models ignore `temperature` and `top_p`. GPT-5.6 and GPT-6 Sol/Luna accept them only with `reasoning_effort: 'none'`, and GPT-6 Astra, GPT-6.1 Sol, and GPT-5.3 Codex always ignore them. `gemini-4-argon` ignores `temperature` too. `gemini-3.1-flash-lite` and `gemini-3-flash-preview` use it.
+- `temperature` (Number) - A number between 0 and 2 indicating the randomness of the completion. Lower values make the output more focused and deterministic, while higher values make it more random. By default, the model's own temperature is used. Some OpenAI reasoning models ignore `temperature` and `top_p`. GPT-5.6, GPT-6 Sol/Luna, and GPT-6.1 Terra accept them only with `reasoning_effort: 'none'`, and GPT-6 Astra, GPT-6.1 Sol, and GPT-5.3 Codex always ignore them. `gemini-4-argon` ignores `temperature` too. `gemini-3.1-flash-lite` and `gemini-3-flash-preview` use it.
 - `tools` (Array) (Optional) - Function definitions the AI can call. See [Function Calling](#function-calling) for details.
-- `reasoning_effort` / `reasoning.effort` (String) (Optional) - Controls how much effort reasoning models spend thinking. Supported values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Lower values give faster responses with less reasoning. OpenAI models, Moonshot's Kimi K3.1 Pro models, Meta's Muse Spark models, `gemini-4-argon`, `gemini-3.1-flash-lite` and `gemini-3-flash-preview` only; Muse Spark always reasons, so `none` is ignored for it. Kimi K3.1 Pro accepts `low`, `high` and `max`, uses `max` when you leave it unset, and fails with `400 bad_request` on any other value. `gemini-4-argon` accepts `low`, `medium` and `high`, and uses `medium` when you leave it unset. `gemini-3.1-flash-lite` and `gemini-3-flash-preview` accept `minimal`, `low`, `medium` and `high`, and use Google's default level when you leave it unset. For these three Gemini models, any other value fails with `400 bad_request`, and messages can contain text and images only.
+- `reasoning_effort` / `reasoning.effort` (String) (Optional) - Controls how much effort reasoning models spend thinking. Supported values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. GPT-6.1 Terra accepts `none`, `low`, `medium` (default), `high`, `xhigh`, and `max`. Lower values give faster responses with less reasoning. OpenAI models, Moonshot's Kimi K3.1 Pro models, Meta's Muse Spark models, `gemini-4-argon`, `gemini-3.1-flash-lite` and `gemini-3-flash-preview` only; Muse Spark always reasons, so `none` is ignored for it. Kimi K3.1 Pro accepts `low`, `high` and `max`, uses `max` when you leave it unset, and fails with `400 bad_request` on any other value. `gemini-4-argon` accepts `low`, `medium` and `high`, and uses `medium` when you leave it unset. `gemini-3.1-flash-lite` and `gemini-3-flash-preview` accept `minimal`, `low`, `medium` and `high`, and use Google's default level when you leave it unset. For these three Gemini models, any other value fails with `400 bad_request`, and messages can contain text and images only.
 - `verbosity` / `text.verbosity` (String) (Optional) - Controls how long or short responses are. Supported values: `low`, `medium`, and `high`. Lower values give shorter responses. OpenAI models only.
 - `normalize` (Boolean) (Optional) - Controls the format of the non-streaming response. When `true`, the response is normalized to the OpenAI format regardless of the model's vendor: `message.content` is a string, tool calls appear as `message.tool_calls`, and `finish_reason` is one of `stop`, `length`, `tool_calls`, or `content_filter` — or the vendor's own stop reason, passed through unchanged when it has no OpenAI equivalent. When `false`, the response keeps the vendor's native format (for Anthropic models, an array of content blocks). When unset, the SDK-wide `puter.ai.normalize` applies — itself tri-state: set it to `true` to normalize every call regardless of release date, `false` to disable normalization for every call, and when it is left unset too (the default) the release-date policy applies: **models released on or after September 1, 2026 return normalized (OpenAI-format) responses by default**, and for older models the default is unchanged — `message.content` keeps its vendor-native shape. (A handful of reasoning fields were made consistent across all models independently of this option; see [Reasoning fields on existing models](#reasoning-fields-on-existing-models).) Streaming responses are unaffected — chunks already share one format across vendors. See [Response normalization](#response-normalization).
 - `compaction` (Boolean | Object) (Optional) - Opt into inline context compaction for long conversations. Pass `true` to enable it with provider defaults, or `{ trigger_tokens: number }` to set the token threshold at which earlier context is summarized. When the model compacts, you receive a `compaction` chunk while streaming (or a `compaction` field on the result when not streaming) containing an opaque `encrypted_content` summary. Resend that item in `messages` on the next turn in place of the summarized history. The compaction chunk shape is identical across providers, so the same code works whether `model` is an OpenAI or Anthropic model. See [Compaction](#compaction).

src/docs/src/Apps/update.md

@@ -28,6 +28,8 @@ An object containing the attributes to update. The object can contain the follow
 - `filetypeAssociations` (optional): An array of strings representing the filetypes that the app can open. Defaults to `[]`. File extentions and MIME types are supported; For example, `[".txt", ".md", "application/pdf"]` would allow the app to open `.txt`, `.md`, and PDF files. At most 200 entries, each at most 60 characters.
 - `metadata` (optional): An object containing custom metadata for the app. This can be used to store arbitrary key-value pairs associated with the app. At most 16 KiB when serialized as JSON.
 
+Changing `indexURL` can merge the app into an existing app for that hosted origin. The returned app can have a different UID. The deleted source app's KV data and KV shares are removed. Data already belonging to the surviving app is retained.
+
 ## Return value
 A `Promise` that will resolve to the [`App`](/Objects/app/) object that was updated.
 

src/docs/src/Email/sendTransactional.md

@@ -37,7 +37,7 @@ A plain-text body. Shorthand for `text`; use the options form for anything else.
 - `html` (String) - HTML body. An inline image is shown with `<img src="cid:...">` — see `cid` under `attachments`.
 - `cc` (String | Array) - Carbon-copy recipient(s).
 - `bcc` (String | Array) - Blind-copy recipient(s). At most **10** recipients across `to`, `cc` and `bcc`.
-- `replyTo` (String) - Where replies go. Defaults to the confirmed account email of the worker's owner when the worker has no app binding or its owner owns the bound app. Otherwise, or while the address is unconfirmed, the message goes out without a Reply-To.
+- `replyTo` (String) - Where replies go. Defaults to the confirmed account email of the worker's owner when the worker has no app binding, or its owner owns the bound app and that app wasn't created by another app. Otherwise, or while the address is unconfirmed, the message goes out without a Reply-To.
 - `emailAccessToken` (String) - A worker's auth token — inside a worker, `me.puter.authToken`. Required when the caller is not itself a worker. The caller stays the billed and rate-limited identity.
 - `attachments` (Array) - Up to **10** attachments, **25 MB** in total. Each is an object:
   - `filename` (String) - Required with `content`; defaults to the file's name for a `path`/`uid` attachment.

src/docs/src/FS/listShared.md

@@ -37,7 +37,7 @@ An object with the following properties:
 
 A `Promise` that resolves to an object with:
 
-- `items` (Array) - The shares on this page. Each has `uid`, `mode`, `path`, `entryUid`, `isDir`, `name`, `type`, `thumbnail`, `owner`, `issuer`, `holder`, `modified` and `size`. A share row has no directory listing behind it, so `name`, `type` and `thumbnail` are carried on the row itself for rendering.
+- `items` (Array) - The shares on this page. Each has `uid`, `mode`, `path`, `entryUid`, `isDir`, `name`, `type`, `thumbnail`, `owner`, `issuer`, `holder`, `modified` and `size`. A share row has no directory listing behind it, so `name`, `type` and `thumbnail` are carried on the row itself for rendering. An item shared with a team you belong to also has `holderTeam`, `{ uid, name, handle }`, and a `holder` of `null`; you can't leave it with [`unshare()`](/FS/unshare/), since the access is the team's. Items you shared with your own team, and team shares of items you own, are not listed. An item shared with you both directly and through a team appears once for each.
 - `cursor` (String) - Pass to the next call to get the following page. **Present only while more pages remain.**
 - `total` (Number) - Present only when `includeTotal` was set, and only when you are acting as the account: an app reads the page it was handed, not the size of everything else shared with you. An approximation even then: it counts the shares recorded for you, before the filtering described below, so it can be higher than the number of items paging actually yields. Treat it as a headline figure, not a count to reconcile against.
 

src/docs/src/FS/readdir.md

@@ -28,7 +28,7 @@ An object with the following properties:
 - `path` (String) - The path to the directory to read. Required when passing options as the only argument.
 - `uid` (String) (optional) - The UID of the directory to read.
 - `limit` (Number) (optional) - Maximum number of entries to return.
-- `offset` (Number) (optional) - Skips the given number of entries. Prefer `cursor` for paging through large directories.
+- `offset` (Number) (optional) - Skips the given number of entries. Prefer `cursor` for paging through large directories. On a `recursive` listing, `offset` is ignored when a `cursor` is passed; start with `offset`, then follow the returned `cursor`.
 - `sortBy` (String) (optional) - Sort field: `name`, `modified`, `type`, or `size`. Default is `name`. With `recursive`, sorting by `name` orders by full path, so each directory's contents stay together; the other fields sort across the whole subtree.
 - `sortOrder` (String) (optional) - `asc` or `desc`. Default is `asc`.
 - `recursive` (Boolean) (optional) - If `true`, the contents of subdirectories are listed too. Defaults to `false`.

src/docs/src/FS/unshare.md

@@ -47,12 +47,20 @@ An object with the following properties:
 
 A `Promise` that resolves to `{ revoked }`, where `revoked` is how many grants were actually removed. It is `0` when there was nothing to withdraw, which is not an error.
 
+## Errors
+
+A rejection carries `{ message, code }`.
+
+| `code` | Meaning |
+| --- | --- |
+| `team_share` | You tried to leave an item you hold only through a team. That access is the team's grant, not yours to drop; ask whoever shared it with the team, or leave the team. Returned with status `409`. If you also hold a share of your own, leaving drops that one and succeeds. |
+
 ## Who can withdraw what
 
 - The item's **owner** can withdraw any share of it, whoever granted it.
 - Anyone else can withdraw the shares **they** granted.
 - An **app** acting for you withdraws only the shares that app issued, whatever authority you have over the rest: your own shares, another app's and a delegate's all report `revoked: 0` to it. Leaving a share yourself still works through an app, since that is your own access to drop.
-- **Anyone** can withdraw their own access, whoever granted it.
+- **Anyone** can withdraw their own access, whoever granted it — except access held only through a team, which is the team's (see `team_share` above).
 
 An item's owner cannot be removed from their own item.
 

src/docs/src/Perms/request.md

@@ -48,7 +48,7 @@ The fields the resource takes:
 
 - **`path`** (string): for `'fs'`, the file or folder. Pass an absolute path, or `~` or a path that starts with `~/` for the user's home folder. Access to a folder covers everything inside it.
 - **`uid`** (string): for `'fs'`, the file or folder's uid, in place of `path`. Pass one or the other.
-- **`access`** (string): `'read'` (the default) or `'write'`, also available as `puter.perms.Access.READ` and `puter.perms.Access.WRITE`. Write access includes read access. For `'apps'`, write access lets the app see who uses the user's apps, including email addresses those users shared with them. For `'subdomains'`, write access covers creating, changing and deleting them. For `'kvShare'`, `access` is the highest level of share the app may create, and is `'watch'` (the default), `'read'`, or `'write'`. A `'watch'` share sends change events for the region, a `'read'` share also lets the holder read it, and a `'write'` share also lets them change and delete keys in it. Each level includes the ones below it, so an app allowed `'write'` can also create `'read'` and `'watch'` shares. See [`puter.kv.share()`](/KV/share/).
+- **`access`** (string): `'read'` (the default) or `'write'`, also available as `puter.perms.Access.READ` and `puter.perms.Access.WRITE`. Write access includes read access. For `'apps'`, write access lets the app see who uses the user's apps, including email addresses those users shared with them. For `'subdomains'`, read access lets the app list and read all of the user's websites, not only the ones it created, and write access also lets it change and delete them. For `'kvShare'`, `access` is the highest level of share the app may create, and is `'watch'` (the default), `'read'`, or `'write'`. A `'watch'` share sends change events for the region, a `'read'` share also lets the holder read it, and a `'write'` share also lets them change and delete keys in it. Each level includes the ones below it, so an app allowed `'write'` can also create `'read'` and `'watch'` shares. See [`puter.kv.share()`](/KV/share/).
 - **`create`** (boolean | `'dir'` | `'file'`): for `'fs'`, whether to create a missing `path` once the user allows it, and as what. Defaults to `true`. See [Creating a path on request](#creating-a-path-on-request) below.
 - **`name`** (string): for `'folder'`, one of `'Desktop'`, `'Documents'`, `'Pictures'`, or `'Videos'`. These are also constants on `puter.perms.Folder`.
 - **`app`** (string | object): for `'appData'`, the target app, by uid or by registered name. For `'appRootDir'`, the app's uid, or an object with one.

src/docs/src/UI/launchApp.md

@@ -60,6 +60,8 @@ running on its own.
 ## Return value 
 A `Promise` that will resolve to an [`AppConnection`](/Objects/AppConnection) once the app is launched.
 
+If the desktop cannot complete the launch, the promise rejects with `code: 'ipc_handler_failed'` and a `message`.
+
 ## Examples
 
 ```html

src/docs/src/rate-limits-and-quotas.md

@@ -77,6 +77,8 @@ An input over its limit is rejected before it reaches the model, as is an image
 
 The standard chat timeout is 10 minutes for a response to start, or to finish if it isn't streamed. Stream durations depend on the provider. Native Gemini applies the 10-minute timeout to the whole response, including streaming. Groq uses 60 seconds to start a response. Mistral streams have no timeout of their own. If the caller disconnects, a stream that's still running gets 10 more minutes to finish, and is then stopped. See the [AI model directory](https://developer.puter.com/ai/models/) for model specifications.
 
+GPT-6.1 Terra has a 1,050,000-token context window and a maximum output of 128,000 tokens. Requests with more than 272,000 input tokens are charged at twice the input and cache rates and 1.5 times the output rate for the whole request.
+
 A `gemini-4-argon` response that isn't streamed is capped at 32,768 output tokens, and a larger `max_tokens` is lowered to that cap. Streaming uses the model-directory limit.
 
 Text-to-speech calls to ElevenLabs, xAI, Speechify, Kling and Gemini time out after 2 minutes; xAI speech-to-text and voice-changer calls after 10 minutes, upload included. A call that times out before any audio or transcript comes back fails with `504 upstream_timeout`. For Gemini, the 2 minutes cover the whole reply, audio included.
@@ -262,6 +264,7 @@ Per minute unless stated:
 | Signed-URL reads | 3,000/min | Per network |
 | Signed-URL writes | 600/min | Per network |
 | Signed-URL concurrent requests | 60 | Per network |
+| Thumbnail read URLs | Valid for at least 6 days and 23 hours, refreshed hourly | Per URL |
 | `getReadURL()` (shared with all access-token creation) | 20/hour | |
 | `revokeReadURL()` | 60/min | |