Fix the app browser embed doc's broken sentence about puterOrigin

Let the app browser embed find no session when storage is refused
Reading local storage can throw when the browser blocks site data. The embed now falls back to the session cookie, as it does for empty storage, so a visitor without a session sees the recommended apps instead of the unavailable state.
2026-11-13 20:12:57 -10:00 · 2026-11-06 00:05:09 -07:00 · 2026-11-06 00:04:54 -07:00 · 2026-11-06 00:04:21 -07:00 · 2026-11-05 23:58:07 -07:00
219 changed files with 4876 additions and 6751 deletions
@@ -159,9 +159,7 @@ The reference has two kinds of page:

 An overview page answers "what is this API and is it what I need?", and a function page answers "how exactly does this call behave?". A change to one function usually only touches that function's page, so a new `kv.list()` option goes in `KV/list.md` without a matching update to `KV.md`. Don't copy a function's options, limits, or edge cases onto the overview page for completeness. Where a detail goes is a judgment call, not a hard rule: update the overview when a change affects how someone would describe the API as a whole.

-When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation.
-
-**Sidebar order.** Order the API areas in the sidebar by how often developers use them, most common first. Overview stays first and Objects stays last. Inside an area, order the pages by use too, and keep pages that make up one feature next to each other, such as `share()`, `unshare()`, `listShared()`, and `listSharedByMe()`. A group goes where its most-used page would go. A helper that only supports another function, such as `listModels()` for `chat()`, goes by its own use. Put create, list, get, update, and delete in that order, and constants such as `MAX_KEY_SIZE` last. The function list on the area's overview page uses the sidebar's order. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).
+When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).

 ### Function page layout

@@ -202,7 +200,6 @@ These apply to reference pages and recipes alike.
 - **Describe behavior directly.** No quoted inner-voice phrases. Write "`isNew` is `true` when the person did not have access before", not "this tells 'I just gave this to someone' from 'they already had it'".
 - **Keep references easy to follow.** Name what a list or code block belongs to in the sentence directly above it. Name a thing once and keep that name. Introduce an actor as "a user" before giving them a role: "A user can create a team. The user who creates the team becomes its owner."
 - **Sentence mechanics.** Never start a sentence with inline code: write "To store data, use the [`set()`](/KV/set/) method." Link every inline mention of an API to its page, every time. No em dashes, and no colons or semicolons mid-sentence; a colon that introduces a code block is fine.
- **No `##` or `###` headings inside tabs.** The table of contents lists every `##` and `###` heading on the page, including the ones in a hidden tab (an `example-content` block switched by the `example-group` pills), so its links lead to content the reader can't see. Put the heading above the tabs, or use `####` inside a tab, which the table of contents skips.
 - **Show the correct way.** No "don't" and no wrong-way-first examples, in recipes and playground examples alike. Mention a wrong approach only when developers already hit it in practice, and state how it fails as a fact: "`add()` reads a plain object as a path map, so the call rejects with …".

 ### Recipes
@@ -27,16 +27,17 @@ import { PuterService } from '../types.js';
 */
 export const RECOMMENDED_APP_NAMES = [
    'builder',
-    'word-processor',
-    'spreadsheet',
-    'presentation',
-    'whiteboard',
-    'pdf-editor',
    'contacts',
    'calendar',
    'meetings',
    'teamchat',
    'email',
+    'whiteboard',
+    'spreadsheet',
+    'word-processor',
+    'presentation',
+    'pdf-editor',
+    'terminal',
    'dev-center',
    'cap-table',
    'invoices',
@@ -247,10 +247,10 @@ function generateTableOfContentsHTML (htmlContent, title) {
    html += '<nav class="toc-nav">';

    const cleanTitle = removeTags(title);
-    html += `<a href="#" class="toc-link toc-level-1" data-level="1">${breakAfterDots(cleanTitle)}</a>`;
+    html += `<a href="#" class="toc-link toc-level-1" data-level="1">${cleanTitle}</a>`;

    for ( const heading of headings ) {
-        html += `<a href="#${heading.slug}" class="toc-link toc-level-${heading.level}" data-level="${heading.level}">${breakAfterDots(heading.text)}</a>`;
+        html += `<a href="#${heading.slug}" class="toc-link toc-level-${heading.level}" data-level="${heading.level}">${heading.text}</a>`;
    }

    html += '</nav>';
@@ -457,12 +457,10 @@ function generateDocsHTML (filePath, rootDir, page, isIndex = false) {
    html += '</div>';
    // content
    html += `<div id="docs-content-${page.slug ?? ''}" class="docs-content col-xl-7 col-lg-7 col-md-12 col-sm-12 col-xs-12">`;
-    // title, with the context menu beside it
-    const pageTitle = breakAfterDots(page.page_title ?? page.title);
-    html += '<div class="page-title-row">';
-    html += `<h1>${page.icon ? `<img src="/${baseURL}${page.icon}" style="opacity:0.5; width: 24px; height: 24px; margin-right: 10px;">` : '' }${pageTitle}</h1>`;
+    // context menu
    html += generateMenuHTML();
-    html += '</div>';
+
+    html += `<h1>${page.icon ? `<img src="/${baseURL}${page.icon}" style="opacity:0.5; width: 24px; height: 24px; margin-right: 10px;">` : '' }${page.page_title ?? page.title}</h1>`;
    // Platform compatibility badges
    html += generatePlatformCompatibilityHTML(frontMatter);
    html += '<hr class="hr-inset">';
@@ -854,12 +852,6 @@ function removeTags (html) {
    return html.replace(/<[^>]*>?/gm, '');
 }

-// Let a long title wrap after a dot, so `puter.auth.getDetailedAppUsage()`
-// never splits inside the method name.
-function breakAfterDots (html) {
-    return html.replace(/\.(?=\w)/g, '.<wbr>');
-}
-
 // Replace '/path/to/root-directory' with the path to your root directory
 generateDocumentation('./src');
 generateRedirects();
@@ -194,18 +194,18 @@ Choose a model and compare provider rates in the [AI model directory](https://de
 These AI features are supported out of the box when using Puter.js:

 - **[`puter.ai.chat()`](/AI/chat/)** - Chat with AI models like Claude, GPT, and others
- **[`puter.ai.txt2img()`](/AI/txt2img/)** - Generate images from text descriptions
- **[`puter.ai.txt2speech()`](/AI/txt2speech/)** - Convert text to speech
- **[`puter.ai.speech2txt()`](/AI/speech2txt/)** - Transcribe audio recordings into text
- **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR)
- **[`puter.ai.txt2vid()`](/AI/txt2vid/)** - Generate short video clips from text or a reference image with Wan, Seedance, Veo, Kling, MiniMax H3 and other models, or edit a video you supply with Gemini Omni, FLUX 3 or Kling Omni
- **[`puter.ai.speech2speech()`](/AI/speech2speech/)** - Convert speech in one voice to another voice
- **[`puter.ai.convo()`](/AI/convo/)** - Prepare a beta realtime conversation with optional text, microphone, playback, and interruption helpers
- **[Realtime WebSocket API](/AI/realtime/)** - Connect directly without puter.js. This API is in beta and may change abruptly.
 - **[`puter.ai.listModels()`](/AI/listModels/)** - List available AI chat models (and providers) that Puter currently exposes.
 - **[`puter.ai.listModelProviders()`](/AI/listModelProviders/)** - List the AI providers that Puter currently exposes.
+- **[`puter.ai.txt2img()`](/AI/txt2img/)** - Generate images from text descriptions
+- **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR)
+- **[`puter.ai.txt2speech()`](/AI/txt2speech/)** - Convert text to speech
 - **[`puter.ai.txt2speech.listEngines()`](/AI/txt2speech.listEngines/)** - List available TTS engines/models
 - **[`puter.ai.txt2speech.listVoices()`](/AI/txt2speech.listVoices/)** - List available TTS voices
+- **[`puter.ai.speech2speech()`](/AI/speech2speech/)** - Convert speech in one voice to another voice
+- **[`puter.ai.txt2vid()`](/AI/txt2vid/)** - Generate short video clips from text or a reference image with Wan, Seedance, Veo, Kling, MiniMax H3 and other models, or edit a video you supply with Gemini Omni, FLUX 3 or Kling Omni
+- **[`puter.ai.speech2txt()`](/AI/speech2txt/)** - Transcribe audio recordings into text
+- **[Realtime WebSocket API](/AI/realtime/)** - Connect directly without puter.js. This API is in beta and may change abruptly.
+- **[`puter.ai.convo()`](/AI/convo/)** - Prepare a beta realtime conversation with optional text, microphone, playback, and interruption helpers

 ## Examples

@@ -29,24 +29,24 @@ An object containing the following properties:

 | Option | Type | Description |
 |--------|------|-------------|
-| `model` | `String` | The model you want to use for the completion. If not specified, defaults to `gpt-5.4-nano`. More than 500 models are available from providers including OpenAI, Anthropic, Google, Alibaba Cloud, xAI, Mistral, OpenRouter, Infron, and others. For a full list, see the [AI models list](https://developer.puter.com/ai/models/) page. |
-| `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. See [Model-specific features](#model-specific-features). |
-| `reasoning_effort` / `reasoning.effort` | `String` | 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. See [Model-specific features](#model-specific-features). |
-| `thinking` | `Object \| null` | Extended-thinking control: `{ type: "adaptive" \| "enabled" \| "disabled" \| "between_tools", budgetTokens?, display? }`. Pass `null` to send no thinking configuration at all (the model's own default); leaving it unset falls back to the legacy derivation from `reasoning_effort`. `budgetTokens` only applies to `type: "enabled"`. |
-| `verbosity` / `text.verbosity` | `String` | Controls how long or short responses are. Supported values: `low`, `medium`, and `high`. Lower values give shorter responses. OpenAI models only. |
-| `tools` | `Array` | Function definitions the AI can call. See [Function Calling](#function-calling) for details. |
-| `toolChoice` | `String \| Object` | Which tool, if any, the model must call. Pass `"auto"` (the model decides), `"none"` (never call a tool), `"required"` (call at least one), or an object naming a specific tool: `{ type: "tool", name: "..." }`. Requires `tools`. |
-| `parallelToolCalls` | `Boolean` | Whether the model may call more than one tool in a single turn. Left unset, tool calls run one at a time. |
-| `streamToolInput` | `Boolean` | Streaming only. When `true`, a tool call's arguments arrive incrementally as `tool_use_start` / `tool_input_delta` chunks instead of a single `tool_use` chunk once the call completes. |
-| `normalize` | `Boolean` | Controls the format of the non-streaming response. See [Response normalization](#response-normalization). |
-| `compaction` | `Boolean \| Object` | Opt into inline context compaction for long conversations. See [Compaction](#compaction). |
-| `signal` | `AbortSignal` | Abort the request, including while waiting for the next streamed chunk. Cancellation rejects with the signal reason (normally an `AbortError`). |
-| `provider` | `String` | Pin the request to a specific provider, for example `openrouter` or `infron`. Without it, Puter selects a provider for the requested model. Call [`puter.ai.listModelProviders()`](/AI/listModelProviders) for the available values, and [`puter.ai.listModels(provider)`](/AI/listModels) for the models a given provider serves. See [Providers](#providers). |
-| `fallback` | `Boolean` | Set to `false` to fail the request when the first provider tried fails, instead of retrying it on another provider that serves the same model. Defaults to `true`. See [Providers](#providers). |
-| `outputFormat` | `Object` | Constrains the response to a JSON schema: `{ type: "json_schema", schema, name?, strict? }`. |
-| `stopSequences` | `Array<String>` | Up to the model's limit of strings; generation stops the moment one of them appears in the output. |
+| `model` | String | The model you want to use for the completion. If not specified, defaults to `gpt-5.4-nano`. More than 500 models are available from providers including OpenAI, Anthropic, Google, Alibaba Cloud, xAI, Mistral, OpenRouter, Infron, and others. For a full list, see the [AI models list](https://developer.puter.com/ai/models/) page. |
+| `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. See [Model-specific features](#model-specific-features). |
+| `reasoning_effort` / `reasoning.effort` | String | 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. See [Model-specific features](#model-specific-features). |
+| `thinking` | Object \| null | Extended-thinking control: `{ type: "adaptive" \| "enabled" \| "disabled" \| "between_tools", budgetTokens?, display? }`. Pass `null` to send no thinking configuration at all (the model's own default); leaving it unset falls back to the legacy derivation from `reasoning_effort`. `budgetTokens` only applies to `type: "enabled"`. |
+| `verbosity` / `text.verbosity` | String | Controls how long or short responses are. Supported values: `low`, `medium`, and `high`. Lower values give shorter responses. OpenAI models only. |
+| `tools` | Array | Function definitions the AI can call. See [Function Calling](#function-calling) for details. |
+| `toolChoice` | String \| Object | Which tool, if any, the model must call. Pass `"auto"` (the model decides), `"none"` (never call a tool), `"required"` (call at least one), or an object naming a specific tool: `{ type: "tool", name: "..." }`. Requires `tools`. |
+| `parallelToolCalls` | Boolean | Whether the model may call more than one tool in a single turn. Left unset, tool calls run one at a time. |
+| `streamToolInput` | Boolean | Streaming only. When `true`, a tool call's arguments arrive incrementally as `tool_use_start` / `tool_input_delta` chunks instead of a single `tool_use` chunk once the call completes. |
+| `normalize` | Boolean | Controls the format of the non-streaming response. See [Response normalization](#response-normalization). |
+| `compaction` | Boolean \| Object | Opt into inline context compaction for long conversations. See [Compaction](#compaction). |
+| `signal` | AbortSignal | Abort the request, including while waiting for the next streamed chunk. Cancellation rejects with the signal reason (normally an `AbortError`). |
+| `provider` | String | Pin the request to a specific provider, for example `openrouter` or `infron`. Without it, Puter selects a provider for the requested model. Call [`puter.ai.listModelProviders()`](/AI/listModelProviders) for the available values, and [`puter.ai.listModels(provider)`](/AI/listModels) for the models a given provider serves. See [Providers](#providers). |
+| `fallback` | Boolean | Set to `false` to fail the request when the first provider tried fails, instead of retrying it on another provider that serves the same model. Defaults to `true`. See [Providers](#providers). |
+| `outputFormat` | Object | Constrains the response to a JSON schema: `{ type: "json_schema", schema, name?, strict? }`. |
+| `stopSequences` | Array of String | Up to the model's limit of strings; generation stops the moment one of them appears in the output. |

 Some models accept additional options or handle these options differently. See [Model-specific features](#model-specific-features).

@@ -4,9 +4,7 @@ description: Prepare an OpenAI realtime conversation with optional audio and tex
 platforms: [websites, apps, nodejs, workers]
 ---

-Prepares a realtime OpenAI conversation that your app can connect to when it's ready.
-
-Preparing the conversation verifies Puter sign-in. Realtime conversations require a paid Puter plan, and usage is billed to the signed-in user. Native OpenAI events and convenience methods use the same session. Microphone capture and speaker playback start when your app requests them.
+The conversation API prepares a realtime session, verifies Puter sign-in, and lets you connect when your app is ready. Realtime conversations require a paid Puter plan; usage is billed to the signed-in user. Native OpenAI events and convenience methods use the same session. Microphone capture and speaker playback start when your app requests them.

 In Node.js, the SDK requires a global `WebSocket`, available in Node.js 22 or later.

@@ -23,17 +21,15 @@ await conversation.connect();

 ## Parameters

-#### `options` (Object) (Optional)
-
 The options object accepts these fields.

-| Option | Type | Description |
-|--------|------|-------------|
-| `model` | `String` | The realtime model. Defaults to `gpt-realtime-2.1-mini`. Also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`. |
-| `instructions` | `String` | Session instructions, up to 8192 characters. Defaults to the provider's default. |
-| `output` | `Array<String>` | Accepts `['text']`, `['audio']`, or both. Defaults to `['audio']`. Audio includes a transcript. Requesting both uses audio output and emits transcript deltas through the `text` event. |
-| `voice` | `String` | OpenAI voice identifier, up to 128 characters. Defaults to the provider's default. |
-| `turnDetection` | `Boolean` | Whether the provider detects the end of spoken turns automatically. Defaults to `true`. Set to `false` for manual audio commits. |
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `model` | String | `gpt-realtime-2.1-mini` | Also accepts `gpt-realtime-2.1`, `gpt-realtime-2`, `gpt-realtime-1.5`, `gpt-realtime`, and `gpt-realtime-mini`. |
+| `instructions` | String | Provider default | Session instructions, up to 8192 characters. |
+| `output` | Array of Strings | `['audio']` | Accepts `['text']`, `['audio']`, or both. Audio includes a transcript. Requesting both uses audio output and emits transcript deltas through the `text` event. |
+| `voice` | String | Provider default | OpenAI voice identifier, up to 128 characters. |
+| `turnDetection` | Boolean | `true` | Whether the provider detects the end of spoken turns automatically. Set to `false` for manual audio commits. |

 ## Return value

@@ -68,14 +64,6 @@ The conversation makes up to ten attempts over about a minute. In a browser that

 Native event definitions are listed in the [OpenAI realtime reference](https://developers.openai.com/api/reference/resources/realtime/server-events). Native events retain their provider fields. Sending native events preserves direct control of the session. Puter refuses `conversation.item.retrieve` events and MCP tools (`"type": "mcp"`) in `session.update` and `response.create` events. Sending one fires an `error` event with code `invalid_event`, and the conversation closes with code 1008. Audio helpers expect the session to use PCM16 at 24 kHz.

-## Errors and limits
-
-Failures use objects containing `code` and `message`. Preparation can reject with `invalid_argument`, `model_not_found`, `auth_required`, `auth_canceled`, or `auth_failed`. Connection can reject with `subscription_required` or `insufficient_funds`, which also show the Puter upgrade prompt. Connection and asynchronous operations can reject with provider errors, `session_closed`, `connection_lost`, `operation_timeout`, or `operation_in_progress`. Sending before readiness, or while reconnecting, throws `session_not_ready`.
-
-Invalid input throws `invalid_argument`, `invalid_event`, or `input_too_large`. A full SDK send queue throws `queue_full`. Media helpers report `unsupported_environment`, `permission_denied`, `media_error`, `media_timeout`, or `queue_full`. Runtime media errors and `context_restore_failed` arrive through the `error` event. Provider errors also arrive as native `error` events with a nested `error` object.
-
-Each native event is capped at 64 KiB. The SDK bounds JSON traversal, outgoing queues, acknowledgment waits, microphone work, and playback. All numeric limits are listed on [rate limits and quotas](/rate-limits-and-quotas/).
-
 ## Convenience events

 The conversation emits these events alongside native events.
@@ -109,9 +97,15 @@ The optional microphone and speaker helpers require a browser with Web Audio sup

 Both start methods require a connected session. Capture and playback are independent, so custom audio input can use the built-in speaker, and built-in capture can use custom playback.

-## Examples
+## Errors and limits

-### Have a text conversation
+Failures use objects containing `code` and `message`. Preparation can reject with `invalid_argument`, `model_not_found`, `auth_required`, `auth_canceled`, or `auth_failed`. Connection can reject with `subscription_required` or `insufficient_funds`, which also show the Puter upgrade prompt. Connection and asynchronous operations can reject with provider errors, `session_closed`, `connection_lost`, `operation_timeout`, or `operation_in_progress`. Sending before readiness, or while reconnecting, throws `session_not_ready`.
+
+Invalid input throws `invalid_argument`, `invalid_event`, or `input_too_large`. A full SDK send queue throws `queue_full`. Media helpers report `unsupported_environment`, `permission_denied`, `media_error`, `media_timeout`, or `queue_full`. Runtime media errors and `context_restore_failed` arrive through the `error` event. Provider errors also arrive as native `error` events with a nested `error` object.
+
+Each native event is capped at 64 KiB. The SDK bounds JSON traversal, outgoing queues, acknowledgment waits, microphone work, and playback. All numeric limits are listed on [rate limits and quotas](/rate-limits-and-quotas/).
+
+## Examples

 A text conversation uses convenience methods for input and streamed output.

@@ -129,8 +123,6 @@ await conversation.connect();
 conversation.sendText('Say hello in three words.');
 ```

-### Have a voice conversation
-
 A voice conversation enables the microphone and speaker after connection.

 ```js
@@ -22,8 +22,6 @@ A `Promise` that will resolve to an array of string containing each AI providers

 ## Examples

-### List all model providers
-
 ```html;ai-list-model-providers
 <html>
 <body>
@@ -43,15 +43,13 @@ Example model entry:
 ]
 ```

-<div class="info">Successful results are cached for 60 seconds per provider.</div>
-
-## Errors
-
 Network and server failures reject the promise; they do not resolve to an empty
 catalogue. Network failures use `{ message, code: "network_error" }`, invalid
 catalogue responses use `invalid_response`, idle timeouts use `request_timeout`,
 and server errors pass through unchanged.

+<div class="info">Successful results are cached for 60 seconds per provider.</div>
+
 ## Model variants

 Some models have variants. A variant is the same model with a different price, rate limit, or speed. The variant is a suffix on the model ID, separated by a colon.
@@ -66,8 +64,6 @@ The model ID without a suffix is the standard variant. Not every model has varia

 ## Examples

-### List all models
-
 ```html;ai-list-models
 <html>
 <body>
@@ -4,9 +4,7 @@ description: Connect to OpenAI realtime conversations through Puter without pute
 platforms: [websites, apps, nodejs, workers]
 ---

-The Realtime WebSocket API lets your client send and receive native OpenAI realtime JSON events through Puter.
-
-Puter authenticates the user and charges their account for usage.
+The Realtime WebSocket API lets your client send and receive native OpenAI realtime JSON events through Puter. Puter authenticates the user and charges their account for usage.

 **Beta:** This API is incomplete. Its methods, options, events, and behavior may change abruptly, including breaking changes without notice.

@@ -54,7 +54,7 @@ Example response:

 ## Examples

-### List engines for a specific provider
+<strong class="example-title">List engines for a specific provider</strong>

 ```html;ai-txt2speech-list-engines
 <html>
@@ -73,7 +73,7 @@ Example response:
 </html>
 ```

-### List engines using options object
+<strong class="example-title">List engines using options object</strong>

 ```js
 const engines = await puter.ai.txt2speech.listEngines({ provider: 'elevenlabs' });
@@ -4,9 +4,7 @@ description: List available TTS voices, optionally filtered by provider.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns the voices available from a TTS provider.
-
-Each voice entry includes metadata such as language, category, and supported models.
+Returns the voices available from a TTS provider. Each voice entry includes metadata such as language, category, and supported models.

 ## Syntax

@@ -54,7 +52,7 @@ Example response (with `provider: 'all'`):

 ## Examples

-### List voices for a provider
+<strong class="example-title">List voices for a provider</strong>

 ```html;ai-txt2speech-list-voices
 <html>
@@ -73,7 +71,7 @@ Example response (with `provider: 'all'`):
 </html>
 ```

-### List all default (AWS Polly) voices
+<strong class="example-title">List all default (AWS Polly) voices</strong>

 ```js
 const voices = await puter.ai.txt2speech.listVoices();
@@ -83,7 +81,7 @@ for (const voice of voices) {
 }
 ```

-### List Gemini voices
+<strong class="example-title">List Gemini voices</strong>

 ```js
 const voices = await puter.ai.txt2speech.listVoices({ provider: 'gemini' });
@@ -4,9 +4,7 @@ description: Convert text to speech with AI using multiple languages, voices, an
 platforms: [websites, apps, nodejs, workers]
 ---

-Converts text into speech using AI.
-
-It supports multiple languages and voices.
+Converts text into speech using AI. Supports multiple languages and voices.

 ## Syntax

@@ -183,9 +183,9 @@ These Apps API are supported out of the box when using Puter.js:

 - **[`puter.apps.create()`](/Apps/create/)** - Create a new application
 - **[`puter.apps.list()`](/Apps/list/)** - List all applications
- **[`puter.apps.get()`](/Apps/get/)** - Get information about a specific application
- **[`puter.apps.update()`](/Apps/update/)** - Update application settings
 - **[`puter.apps.delete()`](/Apps/delete/)** - Delete an application
+- **[`puter.apps.update()`](/Apps/update/)** - Update application settings
+- **[`puter.apps.get()`](/Apps/get/)** - Get information about a specific application
 - **[`puter.apps.checkName()`](/Apps/checkName/)** - Check whether an app name is available

 ## Examples
@@ -4,9 +4,7 @@ description: Check whether an app name is still available.
 platforms: [websites, apps, nodejs, workers]
 ---

-Checks whether an app name is free, without creating anything.
-
-App names are unique across all Puter accounts, so a name is free only when no app on any account uses it. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.
+Checks whether an app name is free, without creating anything. App names are unique across all Puter accounts, so a name is free only when no app on any account uses it. Useful before calling [`puter.apps.create()`](/Apps/create/), which rejects when the name is already taken.

 ## Syntax

@@ -26,7 +24,7 @@ A `Promise` that will resolve to an object describing the name's availability.

 ## Examples

-### Check a name before creating the app
+<strong class="example-title">Check a name before creating the app</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Create apps in the Puter desktop environment.
 platforms: [websites, apps, nodejs, workers]
 ---

-Creates a Puter app with the given name.
-
-The app will be created in the user's apps, and will be accessible to this app. The app will be created with no permissions, and will not be able to access any data until permissions are granted to it.
+Creates a Puter app with the given name. The app will be created in the user's apps, and will be accessible to this app. The app will be created with no permissions, and will not be able to access any data until permissions are granted to it.

 ## Syntax

@@ -41,19 +39,17 @@ The title of the app. If this parameter is not provided, the app will be created

 An object containing the options for the app to create. The object can contain the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `String` | Required. The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected. |
-| `indexURL` | `String` | Required. The URL of the app's index page. This URL must be accessible to the user. If it's missing, the promise will be rejected. |
-| `title` | `String` | The human-readable title of the app. If it's missing, the app will be created with `name` as its title. |
-| `description` | `String` | The description of the app aimed at the end user. |
-| `icon` | `String` | The new icon of the app. |
-| `filetypeAssociations` | `Array<String>` | An array of strings representing the filetypes that the app can open. Defaults to `[]`. File extensions 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. |
-| `maximizeOnStart` | `Boolean` | Whether the app should be maximized when it is started. Defaults to `false`. |
-| `background` | `Boolean` | Whether the app should run in the background. Defaults to `false`. |
-| `feedbackEnabled` | `Boolean` | Whether users can send feedback to you through [`puter.ui.showFeedbackDialog()`](/UI/showFeedbackDialog/). Defaults to `false`. |
-| `metadata` | `Object` | 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. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the app name if it already exists. Defaults to `false`. |
+- `name` (String) (required): The name of the app to create. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
+- `indexURL` (String) (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the promise will be rejected.
+- `title` (String) (optional): The human-readable title of the app. If this parameter is not provided, the app will be created with `name` as its title.
+- `description` (String) (optional): The description of the app aimed at the end user.
+- `icon` (String) (optional): The new icon of the app.
+- `maximizeOnStart` (Boolean) (optional): Whether the app should be maximized when it is started. Defaults to `false`.
+- `filetypeAssociations` (Array<String>) (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.
+- `dedupeName` (Boolean) (optional) - Whether to deduplicate the app name if it already exists. Defaults to `false`.
+- `background` (Boolean) (optional) - Whether the app should run in the background. Defaults to `false`.
+- `feedbackEnabled` (Boolean) (optional) - Whether users can send feedback to you through [`puter.ui.showFeedbackDialog()`](/UI/showFeedbackDialog/). Defaults to `false`.
+- `metadata` (Object) (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.

 ## Return value

@@ -61,7 +57,7 @@ A `Promise` that will resolve to the [`CreateAppResult`](/Objects/createappresul

 ## Examples

-### Create an app pointing to example.com
+<strong class="example-title">Create an app pointing to example.com</strong>

 ```html;app-create
 <html>
@@ -24,7 +24,7 @@ A `Promise` that will resolve to an object `{ success: true, uid: <app uid> }` i

 ## Examples

-### Create a random app then delete it
+<strong class="example-title">Create a random app then delete it</strong>

 ```html;app-delete
 <html>
@@ -4,9 +4,7 @@ description: Retrieve details of your Puter app.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns an app with the given name.
-
-If the app does not exist, the promise will be rejected.
+Returns an app with the given name. If the app does not exist, the promise will be rejected.

 ## Syntax

@@ -21,14 +19,13 @@ puter.apps.get(name, options)

 The name of the app to get.

-#### `options` (Object) (optional)
+### options (optional)

 An object containing the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `icon_size` | `Number \| null` | An integer representing the size of the icons to return. Possible values are `null`, `16`, `32`, `64`, `128`, `256`, and `512`. Default is `null` (the original size). |
-| `stats_period` | `String` | The period for which to get the user and open count. Possible values are `today`, `yesterday`, `7d`, `30d`, `this_month`, `last_month`, `this_year`, `last_year`, `month_to_date`, `year_to_date`, `last_12_months`. Default is `all` (all time). |
+- `stats_period` (optional): A string representing the period for which to get the user and open count. Possible values are `today`, `yesterday`, `7d`, `30d`, `this_month`, `last_month`, `this_year`, `last_year`, `month_to_date`, `year_to_date`, `last_12_months`. Default is `all` (all time).
+
+- `icon_size` (optional): An integer representing the size of the icons to return. Possible values are `null`, `16`, `32`, `64`, `128`, `256`, and `512`. Default is `null` (the original size).

 ## Return value

@@ -36,7 +33,7 @@ A `Promise` that will resolve to the [`App`](/Objects/app/) object with the give

 ## Examples

-### Create a random app then get it
+<strong class="example-title">Create a random app then get it</strong>

 ```html;app-get
 <html>
@@ -4,9 +4,7 @@ description: List all apps in your Puter account.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns an array of all apps belonging to the user and that this app has access to.
-
-If the user has no apps, the array will be empty.
+Returns an array of all apps belonging to the user and that this app has access to. If the user has no apps, the array will be empty.

 ## Syntax

@@ -21,15 +19,19 @@ puter.apps.list(options)

 An object containing the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum number of apps to return in a single call. |
-| `cursor` | `String \| null` | Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. |
-| `stream` | `Boolean` | If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`. |
-| `includeTotal` | `Boolean` | If `true`, the paginated result includes a `total` count of the user's apps. |
-| `offset` | `Number` | Skips the given number of apps. Prefer `cursor` for paging through large lists. |
-| `icon_size` | `Number \| null` | An integer representing the size of the icons to return. Possible values are `null`, `16`, `32`, `64`, `128`, `256`, and `512`. Default is `null` (the original size). |
-| `stats_period` | `String` | The period for which to get the user and open count. Possible values are `today`, `yesterday`, `7d`, `30d`, `this_month`, `last_month`, `this_year`, `last_year`, `month_to_date`, `year_to_date`, `last_12_months`. Default is `all` (all time). |
+- `stats_period` (optional): A string representing the period for which to get the user and open count. Possible values are `today`, `yesterday`, `7d`, `30d`, `this_month`, `last_month`, `this_year`, `last_year`, `month_to_date`, `year_to_date`, `last_12_months`. Default is `all` (all time).
+
+- `icon_size` (optional): An integer representing the size of the icons to return. Possible values are `null`, `16`, `32`, `64`, `128`, `256`, and `512`. Default is `null` (the original size).
+
+- `limit` (optional): Maximum number of apps to return in a single call.
+
+- `offset` (optional): Skips the given number of apps. Prefer `cursor` for paging through large lists.
+
+- `cursor` (optional): Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one.
+
+- `includeTotal` (optional): If `true`, the paginated result includes a `total` count of the user's apps.
+
+- `stream` (optional): If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.

 ## Return value

@@ -55,7 +57,7 @@ for await (const page of puter.apps.list({ stream: true })) {

 ## Examples

-### Create 3 random apps and then list them
+<strong class="example-title">Create 3 random apps and then list them</strong>

 ```html;app-list
 <html>
@@ -17,19 +17,16 @@ The name of the app to update.

 #### `attributes` (required)
 An object containing the attributes to update. The object can contain the following properties:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `title` | `String` | The new title of the app. |
-| `indexURL` | `String` | The new URL of the app's index page. This URL must be accessible to the user. |
-| `description` | `String` | The new description of the app aimed at the end user. |
-| `icon` | `String` | The new icon of the app. |
-| `name` | `String` | The new name of the app. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected. |
-| `filetypeAssociations` | `Array<String>` | An array of strings representing the filetypes that the app can open. Defaults to `[]`. File extensions 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. |
-| `maximizeOnStart` | `Boolean` | Whether the app should be maximized when it is started. Defaults to `false`. |
-| `background` | `Boolean` | Whether the app should run in the background. Defaults to `false`. |
-| `feedbackEnabled` | `Boolean` | Whether users can send feedback to you through [`puter.ui.showFeedbackDialog()`](/UI/showFeedbackDialog/). Omitted leaves the app's current value unchanged. |
-| `metadata` | `Object` | 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. |
+- `name` (optional): The new name of the app. App names are unique across all Puter accounts. If any app already has this name, the promise will be rejected.
+- `indexURL` (optional): The new URL of the app's index page. This URL must be accessible to the user.
+- `title` (optional): The new title of the app.
+- `description` (optional): The new description of the app aimed at the end user.
+- `icon` (optional): The new icon of the app.
+- `maximizeOnStart` (optional): Whether the app should be maximized when it is started. Defaults to `false`.
+- `background` (optional): Whether the app should run in the background. Defaults to `false`.
+- `feedbackEnabled` (optional): Whether users can send feedback to you through [`puter.ui.showFeedbackDialog()`](/UI/showFeedbackDialog/). Omitted leaves the app's current value unchanged.
+- `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.

@@ -38,7 +35,7 @@ A `Promise` that will resolve to the [`App`](/Objects/app/) object that was upda

 ## Examples

-### Create a random app then change its title
+<strong class="example-title">Create a random app then change its title</strong>

 ```html;app-update
 <html>
@@ -98,8 +98,8 @@ This is essential for users to access the various Puter.js APIs integrated into
 These authentication features are supported out of the box when using Puter.js:

 - **[`puter.auth.signIn()`](/Auth/signIn/)** - Sign in a user
- **[`puter.auth.isSignedIn()`](/Auth/isSignedIn/)** - Check if a user is signed in
 - **[`puter.auth.signOut()`](/Auth/signOut/)** - Sign out the current user
+- **[`puter.auth.isSignedIn()`](/Auth/isSignedIn/)** - Check if a user is signed in
 - **[`puter.auth.getUser()`](/Auth/getUser/)** - Get information about the current user
 - **[`puter.auth.getProfile()`](/Auth/getProfile/)** - Get a user's profile, when available
 - **[`puter.auth.getProfilePicture()`](/Auth/getProfilePicture/)** - Get a user's profile picture, when available
@@ -29,9 +29,7 @@ The id of the application.

 A `Promise` that resolves to a [`DetailedAppUsage`](/Objects/detailedappusage) object containing resource usage statistics for the given application.

-## Examples
-
-### Get an app's usage
+## Example

 ```html
 <html>
@@ -26,9 +26,7 @@ None

 A `Promise` that resolves to a [`MonthlyUsage`](/Objects/monthlyusage) object containing the user's monthly usage information.

-## Examples
-
-### Get the user's monthly usage
+## Example

 ```html;auth-get-monthly-usage
 <html>
@@ -4,9 +4,7 @@ description: Read a user's profile, returning null when it is not available.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns a user's profile, which holds their picture, display name, and bio.
-
-Users set these on the [Account page](https://puter.com/dashboard#account) of their Puter dashboard. A user can always read their own profile. Another user's profile is available only while that user is on a paid plan; otherwise the method resolves to `null`, the same as for a user who does not exist.
+Returns a user's profile: their picture, display name, and bio. Users set these on the [Account page](https://puter.com/dashboard#account) of their Puter dashboard. A user can always read their own profile. Another user's profile is available only while that user is on a paid plan; otherwise the method resolves to `null`, the same as for a user who does not exist.

 ## Syntax

@@ -17,7 +15,7 @@ puter.auth.getProfile(username);

 ## Parameters

-#### `username` (optional)
+### `username` (optional)

 The username to look up. Defaults to the signed-in user.

@@ -27,9 +25,7 @@ A promise that resolves to a [`UserProfile`](/Objects/userprofile) object, or `n

 When signed out with no `username`, it resolves to `null` without opening a sign-in prompt.

-## Examples
-
-### Show the user's profile
+## Example

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Read a user's profile picture, returning null when unavailable.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns the `picture` field of a user's profile (see [`puter.auth.getProfile()`](/Auth/getProfile/)).
-
-A user can always read their own picture. Another user's picture is available only while that user is on a paid plan.
+Returns the `picture` field of a user's profile (see [`puter.auth.getProfile()`](/Auth/getProfile/)). A user can always read their own picture. Another user's picture is available only while that user is on a paid plan.

 ## Syntax

@@ -17,7 +15,7 @@ puter.auth.getProfilePicture(username);

 ## Parameters

-#### `username` (optional)
+### `username` (optional)

 The username to look up. Defaults to the signed-in user.

@@ -29,9 +27,7 @@ Missing users, profiles that are not public to the caller, profiles with no pict

 When signed out with no `username`, it resolves to `null` without opening a sign-in prompt.

-## Examples
-
-### Show the user's profile picture
+## Example

 ```html
 <html>
@@ -20,9 +20,7 @@ None

 A promise that resolves to a [`User`](/Objects/user) object containing the user's basic information.

-## Examples
-
-### Get the signed-in user
+## Example

 ```html;auth-get-user
 <html>
@@ -20,9 +20,7 @@ None

 Returns `true` if the user is signed in, `false` otherwise.

-## Examples
-
-### Check whether the user is signed in
+## Example

 ```html;auth-is-signed-in
 <html>
@@ -4,9 +4,7 @@ description: Initiate sign in process in your application with user's Puter acco
 platforms: [websites]
 ---

-Initiates the sign in process for the user.
-
-This will open a popup window with the appropriate authentication method. Puter automatically handles the authentication process and will resolve the promise when the user has signed in.
+Initiates the sign in process for the user. This will open a popup window with the appropriate authentication method. Puter automatically handles the authentication process and will resolve the promise when the user has signed in.

 It is important to note that all essential methods in Puter handle authentication automatically. This method is only necessary if you want to handle authentication manually, for example if you want to build your own custom authentication flow.

@@ -29,12 +27,11 @@ puter.auth.signIn(options)

 #### `options` (optional)

-An object with the following properties:
+`options` is an object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `attempt_temp_user_creation` | `Boolean` | Whether Puter should automatically create a temporary user. This is useful if you want to quickly onboard a user without requiring them to sign up. They can always sign up later if they want to. |
-| `request_auth` | `Boolean` | Asks the popup to let the user re-pick their account, even when your site already holds a token for them. Puter otherwise skips that prompt for a site it has seen before. Useful for an explicit "switch account" button. |
+- `attempt_temp_user_creation`: A boolean value that indicates whether to Puter should automatically create a temporary user. This is useful if you want to quickly onboard a user without requiring them to sign up. They can always sign up later if they want to.
+
+- `request_auth`: A boolean value that asks the popup to let the user re-pick their account, even when your site already holds a token for them. Puter otherwise skips that prompt for a site it has seen before. Useful for an explicit "switch account" button.

 Each call completes from its own sign-in window, including when multiple calls run at once.

@@ -42,7 +39,7 @@ Each call completes from its own sign-in window, including when multiple calls r

 A `Promise` that will resolve to a [`SignInResult`](/Objects/signinresult/) object when the user has signed in.

-## Errors
+## Rejection

 The promise will reject with an object containing an `error` code and a human-readable `msg` in the following cases:

@@ -56,9 +53,7 @@ The promise will reject with an object containing an `error` code and a human-re

 The promise may also reject with the failure response returned by the authentication window itself.

-## Examples
-
-### Sign in from a button click
+## Example

 ```html;auth-sign-in
 <html>
@@ -22,9 +22,7 @@ None

 A `Promise` that resolves with nothing once the user is signed out and, on a website, this browser's push subscription for your app is ended. It doesn't reject.

-## Examples
-
-### Sign the user out
+## Example

 ```html;auth-sign-out
 <html>
@@ -5,9 +5,7 @@ platforms: [websites, apps, nodejs, workers]
 draft: true
 ---

-Changes fields on the signed-in user's profile and returns the updated profile.
-
-Fields left out of the patch are left as they are; `null` clears a field.
+Changes fields on the signed-in user's profile and returns the updated profile. Fields left out of the patch are left as they are; `null` clears a field.

 ## Syntax

@@ -17,27 +15,19 @@ puter.auth.updateProfile(patch);

 ## Parameters

-#### `patch` (required)
+### `patch` (required)

 An object with any of these fields:

-| Option | Type | Description |
-|--------|------|-------------|
-| `displayName` | `String \| null` | The user's display name, at most 64 characters. Surrounding whitespace is removed. |
-| `picture` | `String \| null` | A base64 image data URL such as `data:image/png;base64,...`. At most 512 KiB. |
-| `bio` | `String \| null` | The user's bio, at most 280 characters. Surrounding whitespace is removed. |
+- `picture` (String or `null`): a base64 image data URL such as `data:image/png;base64,...`. At most 512 KiB.
+- `displayName` (String or `null`): at most 64 characters. Surrounding whitespace is removed.
+- `bio` (String or `null`): at most 280 characters. Surrounding whitespace is removed.

 Any other field is rejected.

 ## Return value

-A promise that resolves to the stored [`UserProfile`](/Objects/userprofile).
-
-The profile belongs to the account, so the call must be made with a user session; an app acting on a user's behalf cannot change it.
-
-## Errors
-
-The promise rejects with an object carrying a `code` and `message` when the patch is not accepted:
+A promise that resolves to the stored [`UserProfile`](/Objects/userprofile). It rejects with an object carrying a `code` and `message` when the patch is not accepted:

 | `code`                      | Meaning                                               |
 | --------------------------- | ----------------------------------------------------- |
@@ -47,9 +37,9 @@ The promise rejects with an object carrying a `code` and `message` when the patc
 | `profile_picture_too_large` | `picture` is over the size limit                      |
 | `profile_field_too_long`    | `displayName` or `bio` is over its length limit       |

-## Examples
+The profile belongs to the account, so the call must be made with a user session; an app acting on a user's behalf cannot change it.

-### Change the user's display name
+## Example

 ```html;auth-update-profile
 <html>
@@ -88,6 +88,6 @@ router.post('/notify', async ({ request, user }) => {

 ## Functions

- **[`puter.email.sendTransactional()`](/Email/sendTransactional/)** - Send a transactional email from your app
 - **[`puter.email.list()`](/Email/list/)** - List the messages in the user's mailbox, newest first
 - **[`puter.email.get()`](/Email/get/)** - Fetch and parse one message, attachments included
+- **[`puter.email.sendTransactional()`](/Email/sendTransactional/)** - Send a transactional email from your app
@@ -4,9 +4,7 @@ description: Fetch and parse one message from the user's mailbox by its id.
 platforms: [websites, apps, nodejs, workers]
 ---

-Reads one message by the `id` a listing returned.
-
-The whole raw message is downloaded and parsed, so the result carries the full subject, sender and recipients, the text and HTML bodies, every header, and each attachment with its bytes. Pass `raw: true` to get the unparsed `message/rfc822` bytes as a `Blob` instead.
+Reads one message by the `id` a listing returned. The whole raw message is downloaded and parsed, so the result carries the full subject, sender and recipients, the text and HTML bodies, every header, and each attachment with its bytes. Pass `raw: true` to get the unparsed `message/rfc822` bytes as a `Blob` instead.

 Reading the mailbox requires read access to the `~/.mail` folder, the same grant [`puter.email.list()`](/Email/list/) needs.

@@ -25,11 +23,9 @@ The message id from `puter.email.list()`. Looks up the inbox.

 #### `options` (Object)

-| Option | Type | Description |
-|--------|------|-------------|
-| `id` | `String` | Required. The message id. |
-| `folder` | `String` | Either `'inbox'` or `'sent'`. Default `'inbox'`. A message id is unique within a folder, so a sent message must be read with `folder: 'sent'`. |
-| `raw` | `Boolean` | When `true`, resolve with the raw message `Blob` and skip parsing. Default `false`. |
+- `id` (String) (required): The message id.
+- `folder` (String): `'inbox'` or `'sent'`. Default `'inbox'`. A message id is unique within a folder, so a sent message must be read with `folder: 'sent'`.
+- `raw` (Boolean): When `true`, resolve with the raw message `Blob` and skip parsing. Default `false`.

 ## Return value

@@ -49,7 +45,7 @@ Rejects with an object carrying a `code`:

 ## Examples

-### Read the newest message in the inbox
+<strong class="example-title">Read the newest message in the inbox</strong>

 ```html
 <html>
@@ -70,7 +66,7 @@ Rejects with an object carrying a `code`:
 </html>
 ```

-### Save every attachment of a message to the user's Documents
+<strong class="example-title">Save every attachment of a message to the user's Documents</strong>

 ```html
 <html>
@@ -93,7 +89,7 @@ Rejects with an object carrying a `code`:
 </html>
 ```

-### Download the raw message
+<strong class="example-title">Download the raw message</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: List the messages in the user's mailbox, newest first, one page at
 platforms: [websites, apps, nodejs, workers]
 ---

-Lists the messages in one folder of the user's mailbox, newest first.
-
-Every call returns one page of `items` plus, while more pages exist, a `cursor` to pass back for the next one. Listing reads the mailbox's folder structure only, so it never downloads a message: each item carries the subject, date, and size, and `puter.email.get()` fetches the rest.
+Lists the messages in one folder of the user's mailbox, newest first. Every call returns one page of `items` plus, while more pages exist, a `cursor` to pass back for the next one. Listing reads the mailbox's folder structure only, so it never downloads a message: each item carries the subject, date, and size, and `puter.email.get()` fetches the rest.

 The mailbox belongs to the user, so it is protected like the rest of their files. An app reads it only after the user grants read access to the `~/.mail` folder. To ask for it, call [`puter.perms.request()`](/Perms/request/):

@@ -25,12 +23,10 @@ puter.email.list(options)

 #### `options` (Object) (optional)

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum messages per page. Default `50`, capped at `1000`. |
-| `folder` | `String` | Use `'inbox'` for mail received at the user's address, or `'sent'` for their outgoing copies. Default `'inbox'`. |
-| `cursor` | `String \| null` | The `cursor` from the previous page. Pass `null` or leave it out to fetch the first page. |
-| `stream` | `Boolean` | When `true`, returns an async iterator of pages for `for await ... of` instead of a single page. |
+- `folder` (String): `'inbox'` for mail received at the user's address, `'sent'` for their outgoing copies. Default `'inbox'`.
+- `limit` (Number): Maximum messages per page. Default `50`, capped at `1000`.
+- `cursor` (String | null): The `cursor` from the previous page. `null` or absent fetches the first page.
+- `stream` (Boolean): When `true`, returns an async iterator of pages for `for await ... of` instead of a single page.

 `offset` and `includeTotal` are not supported for mailboxes; passing either rejects with `invalid_request`.

@@ -49,7 +45,7 @@ Rejects with an object carrying a `code`:

 ## Examples

-### List the ten newest messages
+<strong class="example-title">List the ten newest messages</strong>

 ```html
 <html>
@@ -68,7 +64,7 @@ Rejects with an object carrying a `code`:
 </html>
 ```

-### Walk the whole sent folder with a cursor
+<strong class="example-title">Walk the whole sent folder with a cursor</strong>

 ```html
 <html>
@@ -90,7 +86,7 @@ Rejects with an object carrying a `code`:
 </html>
 ```

-### Stream pages
+<strong class="example-title">Stream pages</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Send a transactional email from your app — authorized by a worker
 platforms: [websites, apps, nodejs, workers]
 ---

-Sends one transactional email from your app.
-
-Every send must be authorized by a worker: call it from inside a worker, or pass the worker's token as `emailAccessToken`. The account that makes the call is the one billed and rate-limited.
+Sends one transactional email from your app. Every send must be authorized by a worker: call it from inside a worker, or pass the worker's token as `emailAccessToken`. The account that makes the call is the one billed and rate-limited.

 <div class="info">Transactional email is available to accounts on a paid plan for now. A call from a free account fails with <code>402</code> <code>subscription_required</code>. Under the <a href="/user-pays-model/">User-Pays Model</a> that is the plan of the <em>calling</em> account — your users when your app sends with their session, your own when the worker sends directly.</div>

@@ -33,25 +31,21 @@ A plain-text body. Shorthand for `text`; use the options form for anything else.

 #### `options` (Object)

-| Option | Type | Description |
-|--------|------|-------------|
-| `to` | `String \| Array` | Required. One recipient address, or an array of them. |
-| `subject` | `String` | Required. As above. |
-| `text` | `String` | Plain-text body. At least one of `text` and `html` is required. |
-| `html` | `String` | HTML body. An inline image is shown with `<img src="cid:...">`. See `attachments.cid`. |
-| `emailAccessToken` | `String` | A worker's auth token. Inside a worker, that's `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 attachment is an object with the `attachments.*` fields in the rows that follow. |
-| `attachments.path` | `String` | A Puter path (`~/` allowed, meaning the caller's home). The file is read on the server with the caller's file permissions only, and streamed rather than uploaded. Prefer this over `content` for anything larger than a few hundred kilobytes. |
-| `attachments.uid` | `String` | A Puter file uid, as an alternative to `path`. Read with the caller's file permissions, falling back to the worker owner's. Use a uid to attach a file from the worker owner's storage. |
-| `attachments.content` | `String` | The file body as base64. Mutually exclusive with `path`/`uid`. |
-| `attachments.filename` | `String` | Required with `content`. Defaults to the file's name for a `path`/`uid` attachment. |
-| `attachments.contentType` | `String` | MIME type. Detected from the file for `path`/`uid` attachments. |
-| `attachments.cid` | `String` | Content-ID that makes the attachment an inline part of the `html` body. With `cid: 'logo'`, `<img src="cid:logo">` shows it. Printable ASCII with no whitespace or angle brackets. Inline parts are billed like any other attachment. |
-| `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. |
-| `cc` | `String \| Array` | Carbon-copy recipient(s). |
-| `bcc` | `String \| Array` | Blind-copy recipient(s). |
-
-A message can have at most **10** recipients across `to`, `cc` and `bcc`.
+- `to` (String | Array) (required) - Recipient address(es).
+- `subject` (String) (required) - As above.
+- `text` (String) - Plain-text body. At least one of `text` and `html` is required.
+- `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 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.
+  - `content` (String) - The file body as base64. Mutually exclusive with `path`/`uid`.
+  - `path` (String) - A Puter path (`~/` allowed, meaning the caller's home). The file is read on the server with the caller's file permissions only, and streamed rather than uploaded — prefer this over `content` for anything larger than a few hundred kilobytes.
+  - `uid` (String) - A Puter file uid, as an alternative to `path`. Read with the caller's file permissions, falling back to the worker owner's — use a uid to attach a file from the worker owner's storage.
+  - `contentType` (String) - MIME type. Detected from the file for `path`/`uid` attachments.
+  - `cid` (String) - Content-ID that makes the attachment an inline part of the `html` body: with `cid: 'logo'`, `<img src="cid:logo">` shows it. Printable ASCII with no whitespace or angle brackets. Inline parts are billed like any other attachment.

 ## Return value

@@ -62,11 +56,7 @@ A `Promise` that resolves to an object:
 - `suppressed` (Array) - Recipients (lowercased) dropped because they unsubscribed from your app's mail. The message went to the others.
 - `failed` (Array) - Recipients (lowercased) whose delivery failed. Everyone else got their copy — retry with just these addresses.

-Each recipient gets a private copy of the message, so the unsubscribe link in one copy can only act for the mailbox that received it. Per-recipient failures come back in `failed` rather than failing the call.
-
-## Errors
-
-The promise rejects only when no recipient could be delivered, or when every `to` recipient has unsubscribed (`400`).
+Each recipient gets a private copy of the message, so the unsubscribe link in one copy can only act for the mailbox that received it. Per-recipient failures come back in `failed` rather than failing the call; the promise rejects only when no recipient could be delivered, or when every `to` recipient has unsubscribed (`400`).

 In case of an error, the `Promise` rejects with `{ message, code }`. Codes you may see:

@@ -100,7 +90,7 @@ Sends are rate-limited per calling account; the numbers are on [Rate Limits and

 ## Examples

-### Send a plain-text notification from a worker
+<strong class="example-title">Send a plain-text notification from a worker</strong>

 ```js
 // The worker is the caller, so its owner is billed and rate-limited.
@@ -114,7 +104,7 @@ router.post('/api/alert', async ({ request }) => {
 });
 ```

-### Let the user pay for their own sends
+<strong class="example-title">Let the user pay for their own sends</strong>

 ```js
 // The user's session makes the call; the worker's token authorizes it.
@@ -132,7 +122,7 @@ router.post('/api/receipt', async ({ request, user }) => {
 });
 ```

-### Attach a file and show an inline image
+<strong class="example-title">Attach a file and show an inline image</strong>

 ```js
 // The uid of a file in the worker owner's storage, e.g. from
@@ -4,11 +4,9 @@ description: Read what a subject recorded while nothing was listening.
 platforms: [websites, apps, nodejs, workers]
 ---

-Reads the events a subject has stored, a page at a time.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-A subscription only delivers while something is listening, and `fetch()` catches up on what happened while the client was closed or offline. Only `notif:` subjects (the notification mailbox) store events. Subjects for `fs:` and `kv:` are refused with `fetch_unsupported_subject`.
+Reads the events a subject has stored, a page at a time. A subscription only delivers while something is listening, and `fetch()` catches up on what happened while the client was closed or offline. Only `notif:` subjects (the notification mailbox) store events. Subjects for `fs:` and `kv:` are refused with `fetch_unsupported_subject`.

 It's a plain query. Nothing is registered and no position is saved, so calling it twice returns the same result. You keep the `cursor` and pass it back.

@@ -27,13 +25,11 @@ puter.events.fetch(options)

 #### `options` (Object) (required)

-| Option | Type | Description |
-|--------|------|-------------|
-| `subject` | `String` | Required. What to read. Use `notif:app-user` for your app's notifications for the user, and `notif:developer` for notifications about your app, for its owner. The full form is `notif:<appId>:<audience>`, where the audience is `account`, `developer`, or `app-user`. Apps and websites never see `account` notifications, so `notif:account` returns an empty page for them. |
-| `cursor` | `String` | The `cursor` from the previous page. Leave it off to start from the oldest notification still kept. A read from a cursor returns the notifications created after it, plus any notification [replaced](/Notifications/notify/#groups) since that page was read, even one from an earlier page. |
-| `limit` | `Number` | Events per page. Defaults to 50, max 200. |
-| `from` | `String` | Where a read without a cursor starts. The default, `'start'`, starts from the oldest notification still kept. With `'end'`, the read skips what's already there. It returns no items and a `cursor` at the newest notification, and reads from that cursor return only notifications created or replaced after it. Ignored when a cursor is given. |
-| `after` | `String` | The older name for `cursor`, still accepted. If both are given, `cursor` is used. |
+- `subject` (String) (required): What to read. Use `notif:app-user` for your app's notifications for the user, and `notif:developer` for notifications about your app, for its owner. The full form is `notif:<appId>:<audience>`, where the audience is `account`, `developer`, or `app-user`. Apps and websites never see `account` notifications, so `notif:account` returns an empty page for them.
+- `cursor` (String): The `cursor` from the previous page. Leave it off to start from the oldest notification still kept. A read from a cursor returns the notifications created after it, plus any notification [replaced](/Notifications/notify/#groups) since that page was read, even one from an earlier page.
+- `after` (String): The older name for `cursor`, still accepted. If both are given, `cursor` is used.
+- `from` (String): Where a read without a cursor starts. `'start'`, the default, starts from the oldest notification still kept. `'end'` skips what's already there: it returns no items and a `cursor` at the newest notification, and reads from that cursor return only notifications created or replaced after it. Ignored when a cursor is given.
+- `limit` (Number): Events per page. Defaults to 50, max 200.

 ## Return value

@@ -46,18 +42,18 @@ Each item is a notification event:

 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `String` | The notification's uid. Live deliveries carry the same id, so you can drop duplicates. A replacement keeps the id, so tell it apart by `replaced` and `ts`. |
-| `subject` | `String` | `notif:<appId or userId>:<audience>`, the part of the mailbox it belongs to. |
-| `op` | `String` | Always `post`. |
-| `uid` | `String` | The notification's uid. |
-| `type` | `String` | The kind of notification, such as `share.received`, `app.worker.deployed`, or `app.message`. The types are listed below. |
-| `audience` | `String` | `account`, `developer`, or `app-user`. |
-| `appUid` | `String \| null` | The app it's about, or `null` for one that names no app. |
-| `notification` | `Object` | The stored payload. It always has `type`, and every type except `kv.share.received` has a `title`. Other fields depend on `type`. |
-| `replaced` | `Boolean` | Present and `true` when the notification replaced an earlier one with the same `uid`, as an app's notification with a [`group`](/Notifications/notify/#groups) does. |
-| `self` | `Boolean` | Always `true`, since a mailbox is your own. |
-| `ts` | `Number` | When it was created, in milliseconds since the epoch. On a replacement, when it was replaced, and the same on its live and fetched copies. |
-| `seq` | `Number` | Position within the page. |
+| `id` | String | The notification's uid. Live deliveries carry the same id, so you can drop duplicates. A replacement keeps the id, so tell it apart by `replaced` and `ts`. |
+| `subject` | String | `notif:<appId or userId>:<audience>`, the part of the mailbox it belongs to. |
+| `op` | String | Always `post`. |
+| `uid` | String | The notification's uid. |
+| `type` | String | The kind of notification, such as `share.received`, `app.worker.deployed`, or `app.message`. The types are listed below. |
+| `audience` | String | `account`, `developer`, or `app-user`. |
+| `appUid` | String \| null | The app it's about, or `null` for one that names no app. |
+| `notification` | Object | The stored payload. It always has `type`, and every type except `kv.share.received` has a `title`. Other fields depend on `type`. |
+| `replaced` | Boolean | Present and `true` when the notification replaced an earlier one with the same `uid`, as an app's notification with a [`group`](/Notifications/notify/#groups) does. |
+| `self` | Boolean | Always `true`, since a mailbox is your own. |
+| `ts` | Number | When it was created, in milliseconds since the epoch. On a replacement, when it was replaced, and the same on its live and fetched copies. |
+| `seq` | Number | Position within the page. |

 Besides `type` and `title`, `notification` carries these fields for each type:

@@ -78,8 +74,6 @@ Apps see `developer` notifications only for apps the user owns. Asking for a par

 Notifications are kept for the server's retention window. A client away for longer starts from what's left.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -95,7 +89,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### Catch up on everything missed
+<strong class="example-title">Catch up on everything missed</strong>

 ```html;events-fetch
 <html>
@@ -124,7 +118,7 @@ The promise rejects with `{ message, code }`:
 </html>
 ```

-### Read the missed ones, then keep listening
+<strong class="example-title">Read the missed ones, then keep listening</strong>

 ```html;events-fetch-then-listen
 <html>
@@ -4,11 +4,9 @@ description: Read one schedule, including one that has ended.
 platforms: [websites, apps, nodejs, workers]
 ---

-Reads one schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/), or one notification your app stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-An ended schedule can be read for 7 days after it ends.
+Reads one schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/), or one notification your app stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later). An ended schedule can be read for 7 days after it ends.

 An app can read only the schedules it created. An account session can read any of the user's schedules. An id this caller can't read reads as not existing, so the call doesn't reveal which schedules exist.

@@ -28,8 +26,6 @@ The `scheduleId` from [`onSchedule()`](/Events/onSchedule/), [`notify()`](/Notif

 A `Promise` that resolves to the schedule, the object [`onSchedule()`](/Events/onSchedule/#return-value) returns, without `off()`. Its `state` says whether it's `active`, `suspended`, `sending` or `ended`, and `nextRunAt` says when it's next due.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -42,7 +38,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### Check when a stored notification goes out
+<strong class="example-title">Check when a stored notification goes out</strong>

 ```html;events-get-schedule
 <html>
@@ -4,11 +4,9 @@ description: Publish, list and remove the named handlers that persistent subscri
 platforms: [websites, apps, nodejs, workers]
 ---

-A **handler** is a function that [persistent subscriptions](/Events/onPersistent/) and [schedules](/Events/onSchedule/) run in the background.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-A handler runs only when a subscription bound to it has a delivery, or a schedule bound to it is due. Nothing else can trigger it.
+A **handler** is a function that [persistent subscriptions](/Events/onPersistent/) and [schedules](/Events/onSchedule/) run in the background. A handler runs only when a subscription bound to it has a delivery, or a schedule bound to it is due. Nothing else can trigger it.

 A handler lives in one of two scopes:

@@ -99,14 +97,9 @@ puter.events.handlers.publish(name, handler, options)

 - `name` (String) (required): The name subscriptions bind to. Letters, digits, and `_ . : -`, starting with a letter or digit, up to 128 characters. Unique within the app.
 - `handler` (Function | String | Object) (required): A function (serialized with `toString()`), a source string, or `{ file: '~/AppData/…/handler.js' }`. A file is read at this call, so later edits to it take effect only when you publish again.
-
-The `options` object takes these options:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `appUid` | `String` | Required outside an app. The app to publish into. Inside an app, it can only name that app. With `scope: 'user'` it can only name the app making the call, and needs no value. Only [`workers.destroy()`](/Events/workers/) can name another app for a user scope, from an account session. |
-| `scope` | `String` | Either `'app'` or `'user'`. Defaults to `'app'`. With `'user'`, it publishes into the signed-in user's own [user scope](#user-scope) of the app. |
-| `replace` | `Boolean` | Overwrite whatever is published under the name. |
+- `options.replace` (Boolean): Overwrite whatever is published under the name.
+- `options.scope` (String): `'app'` or `'user'`. Defaults to `'app'`. `'user'` publishes into the signed-in user's own [user scope](#user-scope) of the app.
+- `options.appUid` (String): The app to publish into. Required outside an app. Inside an app, it can only name that app. With `scope: 'user'` it can only name the app making the call, and needs no value. Only [`workers.destroy()`](/Events/workers/) can name another app for a user scope, from an account session.

 Resolves to `{ name, hash, updatedAt, outcome, resumed }`. Its `outcome` is `'created'`, `'updated'`, or `'unchanged'` (the same source was already published), and `resumed` counts the suspended subscriptions this publish brought back.

@@ -191,7 +184,7 @@ All four methods reject with `{ message, code }`:

 The first example publishes into a user scope from inside an app, for the signed-in user. The others run in Node.js signed in with your account token, and `appUid` names an app you own. Inside your own app, leave out `appUid`.

-### Publish into the user's scope, list it, then remove it
+<strong class="example-title">Publish into the user's scope, list it, then remove it</strong>

 ```js
 const published = await puter.events.handlers.publish(
@@ -210,7 +203,7 @@ for (const handler of await puter.events.handlers.list({ scope: 'user' })) {
 await puter.events.handlers.remove('digest', { scope: 'user' });
 ```

-### Publish a handler, list it, then remove it
+<strong class="example-title">Publish a handler, list it, then remove it</strong>

 ```js
 const published = await puter.events.handlers.publish(
@@ -231,7 +224,7 @@ const removed = await puter.events.handlers.remove('ingestUpload', { appUid });
 console.log(removed.removed, removed.suspended);
 ```

-### Deploy a whole set from a build step
+<strong class="example-title">Deploy a whole set from a build step</strong>

 ```js
 const published = await puter.events.handlers.publishAll([
@@ -4,11 +4,9 @@ description: List the persistent subscriptions this caller holds.
 platforms: [websites, apps, nodejs, workers]
 ---

-Lists the persistent subscriptions created with [`puter.events.onPersistent()`](/Events/onPersistent/).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-Session subscriptions from [`onLocal()`](/Events/onLocal/) aren't stored, so they aren't listed.
+Lists the persistent subscriptions created with [`puter.events.onPersistent()`](/Events/onPersistent/). Session subscriptions from [`onLocal()`](/Events/onLocal/) aren't stored, so they aren't listed.

 An app sees only the subscriptions it created. Outside an app, such as in Node.js with an account token, you see all of them. Deleting an app deletes its subscriptions. A scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, sees none, whether the account or an app created it.

@@ -24,12 +22,10 @@ puter.events.list(options)

 #### `options` (Object) (optional)

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum subscriptions per request. Defaults to 50, max 200. |
-| `cursor` | `String \| null` | The cursor from a previous page. Passing it, even as `null`, returns a single page instead of the full list. |
-| `stream` | `Boolean` | Returns an async iterator of pages instead of a promise. |
-| `includeTotal` | `Boolean` | Adds `total` to the page. Ask for it on the first page only, since it gets slower as the count grows. |
+- `limit` (Number): Maximum subscriptions per request. Defaults to 50, max 200.
+- `cursor` (String | null): The cursor from a previous page. Passing it, even as `null`, returns a single page instead of the full list.
+- `includeTotal` (Boolean): Adds `total` to the page. Ask for it on the first page only, since it gets slower as the count grows.
+- `stream` (Boolean): Returns an async iterator of pages instead of a promise.

 ## Return value

@@ -44,8 +40,6 @@ Each subscription is the object [`onPersistent()`](/Events/onPersistent/#return-
 - `contextKeys` (Array | null) and `contextHash` (String | null) describe the stored `context`. The values are never returned, since context often holds secrets. The hash changes whenever a value does.
 - `suspendedAt` (Number | null) and `suspendedReason` (String | null) are set when a subscription is [suspended](/Events/onPersistent/#suspended-subscriptions), with `handler_not_found`, `failures`, `no_credit`, or `permission_revoked`.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -57,7 +51,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### List everything this account is watching
+<strong class="example-title">List everything this account is watching</strong>

 ```html;events-list
 <html>
@@ -84,7 +78,7 @@ The promise rejects with `{ message, code }`:
 </html>
 ```

-### Find the ones that stopped, and why
+<strong class="example-title">Find the ones that stopped, and why</strong>

 ```html;events-list-suspended
 <html>
@@ -4,11 +4,9 @@ description: List the schedules this caller holds, one page at a time.
 platforms: [websites, apps, nodejs, workers]
 ---

-Lists the schedules created with [`puter.events.onSchedule()`](/Events/onSchedule/), and the notifications your app stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-Ended schedules stay in the list for 7 days, with the reason they ended.
+Lists the schedules created with [`puter.events.onSchedule()`](/Events/onSchedule/), and the notifications your app stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later). Ended schedules stay in the list for 7 days, with the reason they ended.

 An app sees only the schedules it created for the user it runs for. An account session, such as the Puter desktop, sees all of the user's schedules, including ones left by apps they no longer use, so that's where to clean up stray schedules. A scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, sees none.

@@ -26,11 +24,9 @@ puter.events.listSchedules(options)

 #### `options` (Object) (optional)

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum schedules per page. Capped at 200, and defaults to 50. |
-| `cursor` | `String \| null` | The `cursor` from the previous page. Leave it out, or pass `null`, for the first page. |
-| `includeTotal` | `Boolean` | Adds `total`, the number of schedules across every page. Ask for it on the first page only. |
+- `limit` (Number): Maximum schedules per page. Capped at 200, and defaults to 50.
+- `cursor` (String | null): The `cursor` from the previous page. Leave it out, or pass `null`, for the first page.
+- `includeTotal` (Boolean): Adds `total`, the number of schedules across every page. Ask for it on the first page only.

 ## Return value

@@ -44,8 +40,6 @@ Pages can be shorter than `limit` before the last one, so keep going until `curs

 The `context` a schedule was created with is never returned, since it often holds secrets. The `contextKeys` field lists its key names, and `contextHash` changes whenever a value does.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -59,7 +53,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### List every schedule, page by page
+<strong class="example-title">List every schedule, page by page</strong>

 ```html;events-list-schedules
 <html>
@@ -4,11 +4,9 @@ description: End a subscription created with puter.events.onLocal().
 platforms: [websites, apps, nodejs]
 ---

-Ends a subscription returned by [`puter.events.onLocal()`](/Events/onLocal/).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-The handler stops being called immediately, and the server is told if the connection is still open.
+Ends a subscription returned by [`puter.events.onLocal()`](/Events/onLocal/). The handler stops being called immediately, and the server is told if the connection is still open.

 Ending a subscription counts toward its own [unsubscribe rate limit](/rate-limits-and-quotas/#events), not the `subscribe` one. Over that limit `off()` still resolves and the handler still stops, but the server may keep the subscription until the connection closes, and a warning is logged to the console.

@@ -27,7 +25,7 @@ A `Promise` that resolves when the subscription is gone. It never rejects. Calli

 ## Examples

-### Watch a directory, then stop watching it
+<strong class="example-title">Watch a directory, then stop watching it</strong>

 ```html;events-off
 <html>
@@ -4,11 +4,9 @@ description: Subscribe to changes on a file, directory, key-value key, or notifi
 platforms: [websites, apps, nodejs]
 ---

-Subscribes to a subject and calls `handler` each time something matching it changes.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-The subscription belongs to this client's connection. Nothing is stored, nothing runs while the page is closed, and the subscription ends when the connection does. Changes from other devices and regions reach it too. A change made in another region usually arrives a few hundred milliseconds later than a local one. See [Subjects and events](/Events/subjects/) for the subject syntax and the event shape.
+Subscribes to a subject and calls `handler` each time something matching it changes. The subscription belongs to this client's connection. Nothing is stored, nothing runs while the page is closed, and the subscription ends when the connection does. Changes from other devices and regions reach it too. A change made in another region usually arrives a few hundred milliseconds later than a local one. See [Subjects and events](/Events/subjects/) for the subject syntax and the event shape.

 In a Puter worker, a subscription only lasts for one invocation. To react to changes from a worker, use [`onPersistent()`](/Events/onPersistent/) with a published handler.

@@ -30,11 +28,9 @@ Called with `{ event }` for each delivery. See [The event](/Events/subjects/#the

 #### `options` (Object) (optional)

-| Option | Type | Description |
-|--------|------|-------------|
-| `onError` | `Function` | Called with `{ message, code }` once the subscription is over. That happens when it can't be restored after a disconnect (see [Reconnects](#reconnects)), or when the server ends it, with `code: 'subscription_ended'` and a `reason` (see [Subscriptions the server ends](#subscriptions-the-server-ends)). The handler isn't called after that. Call `onLocal()` again to resume. Without `onError`, the error is logged to the console. |
-| `includeValue` | `Boolean` | For a `kv:` subject, include the key's new value as `event.value`. See [Getting the new value](/Events/subjects/#getting-the-new-value) for when it's left out. Other subjects are refused with `invalid_include_value`. |
-| `timeout` | `Number` | How long to wait for the server to confirm the subscription, in milliseconds. Defaults to `30000`. |
+- `onError` (Function): Called with `{ message, code }` once the subscription is over. That happens when it can't be restored after a disconnect (see [Reconnects](#reconnects)), or when the server ends it, with `code: 'subscription_ended'` and a `reason` (see [Subscriptions the server ends](#subscriptions-the-server-ends)). The handler isn't called after that. Call `onLocal()` again to resume. Without `onError`, the error is logged to the console.
+- `timeout` (Number): How long to wait for the server to confirm the subscription, in milliseconds. Defaults to `30000`.
+- `includeValue` (Boolean): For a `kv:` subject, include the key's new value as `event.value`. See [Getting the new value](/Events/subjects/#getting-the-new-value) for when it's left out. Other subjects are refused with `invalid_include_value`.

 ## Return value

@@ -51,8 +47,6 @@ A `Promise` that resolves, once the server confirms the subscription, to a subsc
 - `includeValue` (Boolean): Whether `kv:` deliveries carry the new value.
 - `off` (Function): Ends the subscription. See [`subscription.off()`](/Events/off/).

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -104,7 +98,7 @@ If the connection is down when this happens, or drops before `onError` is called

 ## Examples

-### Watch a directory and print what changes
+<strong class="example-title">Watch a directory and print what changes</strong>

 ```html;events-watch-folder
 <html>
@@ -136,7 +130,7 @@ If the connection is down when this happens, or drops before `onError` is called
 </html>
 ```

-### React to a file that does not exist yet
+<strong class="example-title">React to a file that does not exist yet</strong>

 ```html;events-watch-missing
 <html>
@@ -169,7 +163,7 @@ If the connection is down when this happens, or drops before `onError` is called
 </html>
 ```

-### Watch this app's key-value store
+<strong class="example-title">Watch this app's key-value store</strong>

 ```html;events-watch-kv
 <html>
@@ -4,11 +4,9 @@ description: Subscribe to changes with a subscription that keeps running when yo
 platforms: [websites, apps, nodejs, workers]
 ---

-Creates a subscription that outlives this connection.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-It's stored on the account, keeps matching while your app is closed, and runs a handler in an [events worker](/Events/workers/). The handler is either inline code you pass as `handler`, which is published into the signed-in user's own [user scope](/Events/handlers/#user-scope) of your app, or a handler published under a name with [`puter.events.handlers.publish()`](/Events/handlers/). Each event also reaches every connected client. Compare [`puter.events.onLocal()`](/Events/onLocal/), which ends with the page.
+Creates a subscription that outlives this connection. It's stored on the account, keeps matching while your app is closed, and runs a handler in an [events worker](/Events/workers/). The handler is either inline code you pass as `handler`, which is published into the signed-in user's own [user scope](/Events/handlers/#user-scope) of your app, or a handler published under a name with [`puter.events.handlers.publish()`](/Events/handlers/). Each event also reaches every connected client. Compare [`puter.events.onLocal()`](/Events/onLocal/), which ends with the page.

 The subscription is live right away in the region where it was created. Right after this call resolves, changes made in other regions can take a moment longer to reach it, usually well under a second.

@@ -25,78 +23,17 @@ puter.events.onPersistent(options)

 #### `options` (Object) (required)

-| Option | Type | Description |
-|--------|------|-------------|
-| `subject` | `String` | Required. What to watch, in the same form [`onLocal()`](/Events/onLocal/) takes, such as `fs:~/Documents` or `kv:<handle>:*`. |
-| `handler` | `Function \| String \| Object` | The handler code, as a function, a source string, or `{ file: '~/AppData/…/handler.js' }`. Without `handlerName`, the source is sent and published into the signed-in user's own user scope, and it runs for this user's events only. With `handlerName`, only its hash is sent, and the subscription is created only if it matches what's published under that name. A function also runs in this client for each delivery it receives (see [Where the handler runs](#where-the-handler-runs)). |
-| `handlerName` | `String` | The published handler to run in an [events worker](/Events/workers/). Up to 128 characters. A subscription made outside an app has no events worker, so its handler runs only in connected clients. |
-| `context` | `Object` | Values the handler needs, passed to it as a frozen `ctx`. Up to 4 KB serialized. See [Context is captured once](#context-is-captured-once-up-to-4-kb). |
-| `queue` | `Boolean` | Handles events like a work queue. Each event goes to one consumer at a time, and it's offered again if a run never finishes or hits a temporary error. Requires `handlerName` or an inline `handler`. Defaults to `false`. See [Choosing a mode](#choosing-a-mode). |
-| `includeValue` | `Boolean` | For a `kv:` subject, include the key's new value as `event.value`. See [Getting the new value](/Events/subjects/#getting-the-new-value) for when it's left out. Other subjects are refused with `invalid_include_value`. |
-| `expiresAt` | `Number \| String` | When the subscription ends on its own, as unix seconds or an ISO-8601 string. Must be in the future. |
-| `handlerScope` | `String` | Where `handlerName` is looked up, `'app'` or `'user'`. Defaults to `'app'`, the handlers the app's owner published. With `'user'`, it binds to a handler in the signed-in user's own scope, published with `handlers.publish(name, handler, { scope: 'user' })`. |
-| `onError` | `Function` | Called with `{ message, code }` when this client stops running `handler` because its connection can't be restored (`reauth_required` after a sign-out, `events_connection_failed` otherwise). The subscription itself keeps going in the events worker, and this client takes deliveries again once it reconnects. Only used with a function `handler`. Without it, the stop is logged to the console. |
-| `delivery` | `String` | Deprecated. Use `queue` instead. The value `'single'` is the same as `queue: true`, and `'broadcast'` is the default. |
-| `targets` | `Array` | Deprecated and ignored. |
-
-## Return value
-
-A `Promise` that resolves to the subscription:
-
- `subId` (String): Its id, which [`puter.events.update()`](/Events/update/) and [`puter.events.unsubscribe()`](/Events/unsubscribe/) take. It never changes.
- `subject` (String): For `kv:` and `notif:`, the subject in full form, so `kv:cart` comes back as `kv:<appId>:cart`. For `fs:`, as you passed it, except a relative path comes back resolved the same way [`onLocal()`](/Events/onLocal/) returns it.
- `anchor`, `match`, `op`: As [`onLocal()`](/Events/onLocal/#return-value) returns them.
- `queue` (Boolean), `handlerName` (String | null), `includeValue` (Boolean). An inline handler comes back as its server-assigned `handlerName`, which starts with `@`.
- `handlerScope` (String): `'user'` when the subscription is bound to a handler in the user's own scope. Absent otherwise.
- `appUid` (String | null): The app that created it, or `null` if it was created outside an app.
- `contextKeys` (Array | null), `contextHash` (String | null): The key names and a hash of the stored context, never its values.
- `createdAt`, `expiresAt` (Number | null): Unix seconds.
- `suspendedAt` (Number | null), `suspendedReason` (String | null): Set when the subscription is [suspended](#suspended-subscriptions).
- `off()` (Function): Ends the subscription and stops running its handler here. Same as [`puter.events.unsubscribe(subId)`](/Events/unsubscribe/).
-
-## Errors
-
-The promise rejects with `{ message, code }`:
-
-| `code` | Meaning |
-| --- | --- |
-| `events_handler_conflict` | The inline handler couldn't be confirmed after a concurrent publish. Try again. |
-| `events_handler_hash_mismatch` | The published handler isn't the source passed as `handler`. |
-| `events_handler_not_found` | Nothing is published under `handlerName` in that scope, or source was supplied to check a named handler outside an app. |
-| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
-| `events_handler_invalid` | `handler` isn't a function, a nonempty source string, or `{ file }`. |
-| `invalid_subject` | The subject is empty, not a string, or can't be parsed, or it's a `notif:` subject and this server has notification events turned off. |
-| `auth_canceled` | Nobody was signed in, and the user closed the sign-in without finishing it. |
-| `events_user_handlers_disabled` | Publishing into a user scope isn't turned on for this server. |
-| `events_handler_forbidden` | The call can't publish into a user scope: it came from a scoped access token, a temporary account, or on behalf of a different app. |
-| `insufficient_funds` | Publishing into a user scope needs credit on a hosted Puter server, and the user has none. Arrives as HTTP 402. |
-| `forbidden` | The user already holds as many [worker units](/rate-limits-and-quotas/#worker-units) as their plan allows, so a new user scope can't be created. |
-| `events_handler_limit` | The user scope already holds the [maximum number of handlers](/rate-limits-and-quotas/#handlers). |
-| `events_handler_too_large` | The handler is over 64 KB. |
-| `events_worker_too_large` | The user scope's handlers would exceed 1 MB combined. |
-| `events_handler_name_invalid` | `handlerName` has characters that aren't allowed, or starts with `@`, which is reserved for inline handlers. |
-| `events_handler_free_variable` | The handler uses an outside variable. The message names it. |
-| `events_handler_invalid` | `handler` isn't a function, a source string, or `{ file }`. |
-| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
-| `events_handler_not_found` | Nothing is published under `handlerName` in that scope of this app. |
-| `events_handler_hash_mismatch` | The published handler isn't the source you passed as `handler`. |
-| `events_handler_required` | `queue: true` without a `handlerName` or an inline `handler`. |
-| `events_background_consent_required` | An app subscribed with a handler, and the user hasn't granted `events:background`. |
-| `events_context_too_large` | The serialized `context` is over 4 KB. |
-| `events_context_invalid` | `context` isn't JSON-serializable. |
-| `bad_request` | `queue` isn't a boolean, `delivery` isn't `'broadcast'` or `'single'`, the two disagree, or `handlerName` isn't a string or is over 128 characters. |
-| `invalid_expires_at` | `expiresAt` isn't a future time. |
-| `invalid_include_value` | `includeValue` isn't a boolean, or the subject isn't `kv:`. |
-| `invalid_subject_op`, `invalid_subject_audience`, `invalid_subject_pattern`, `invalid_kv_pattern`, `invalid_kv_handle_key`, `events_cross_app_disabled`, `events_kv_handles_disabled`, `forbidden` | As on [`onLocal()`](/Events/onLocal/#errors). |
-| `subject_does_not_exist` | The subject doesn't exist, or this account can't read it. |
-| `events_subscription_limit` | The account or app is at its [persistent subscription limit](/rate-limits-and-quotas/#events). |
-| `events_value_too_large` | A field is longer than can be stored, such as an app id over 40 characters. |
-| `events_durable_requires_account` | Temporary (anonymous) accounts only get session subscriptions. Scoped access tokens, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, get no persistent subscriptions either, whether the account or an app created them. |
-| `too_many_requests` | Over the subscribe rate limit. |
-| `events_disabled` | Events aren't enabled on this server. |
-| `events_failed` | The server sent a response the SDK couldn't read. |
-
-With a `{ file }` handler, errors from [`puter.fs.read()`](/FS/read/) also pass through.
+- `subject` (String) (required): What to watch, in the same form [`onLocal()`](/Events/onLocal/) takes, such as `fs:~/Documents` or `kv:<handle>:*`.
+- `handlerName` (String): The published handler to run in an [events worker](/Events/workers/). Up to 128 characters. A subscription made outside an app has no events worker, so its handler runs only in connected clients.
+- `handlerScope` (String): Where `handlerName` is looked up, `'app'` or `'user'`. Defaults to `'app'`, the handlers the app's owner published. `'user'` binds to a handler in the signed-in user's own scope, published with `handlers.publish(name, handler, { scope: 'user' })`.
+- `queue` (Boolean): Handles events like a work queue. Each event goes to one consumer at a time, and it's offered again if a run never finishes or hits a temporary error. Requires `handlerName` or an inline `handler`. Defaults to `false`. See [Choosing a mode](#choosing-a-mode).
+- `handler` (Function | String | Object): The handler code, as a function, a source string, or `{ file: '~/AppData/…/handler.js' }`. Without `handlerName`, the source is sent and published into the signed-in user's own user scope, and it runs for this user's events only. With `handlerName`, only its hash is sent, and the subscription is created only if it matches what's published under that name. A function also runs in this client for each delivery it receives (see [Where the handler runs](#where-the-handler-runs)).
+- `context` (Object): Values the handler needs, passed to it as a frozen `ctx`. Up to 4 KB serialized. See [Context is captured once](#context-is-captured-once-up-to-4-kb).
+- `expiresAt` (Number | String): When the subscription ends on its own, as unix seconds or an ISO-8601 string. Must be in the future.
+- `includeValue` (Boolean): For a `kv:` subject, include the key's new value as `event.value`. See [Getting the new value](/Events/subjects/#getting-the-new-value) for when it's left out. Other subjects are refused with `invalid_include_value`.
+- `onError` (Function): Called with `{ message, code }` when this client stops running `handler` because its connection can't be restored (`reauth_required` after a sign-out, `events_connection_failed` otherwise). The subscription itself keeps going in the events worker, and this client takes deliveries again once it reconnects. Only used with a function `handler`. Without it, the stop is logged to the console.
+- `delivery` (String): Deprecated. Use `queue` instead. The value `'single'` is the same as `queue: true`, and `'broadcast'` is the default.
+- `targets` (Array): Deprecated and ignored.

 ## Background delivery needs consent

@@ -226,11 +163,68 @@ Clients connect to the nearest region. Events reach a client wherever it's conne
 - Undelivered events are held in the region where the change happened. If that region goes down, only what it was holding is lost.
 - Order is kept within a region and is best effort across regions. Without `queue`, coalescing (250 ms) also runs per region, so two quick writes can arrive as one event nearby and as two farther away.

+## Return value
+
+A `Promise` that resolves to the subscription:
+
+- `subId` (String): Its id, which [`puter.events.update()`](/Events/update/) and [`puter.events.unsubscribe()`](/Events/unsubscribe/) take. It never changes.
+- `subject` (String): For `kv:` and `notif:`, the subject in full form, so `kv:cart` comes back as `kv:<appId>:cart`. For `fs:`, as you passed it, except a relative path comes back resolved the same way [`onLocal()`](/Events/onLocal/) returns it.
+- `anchor`, `match`, `op`: As [`onLocal()`](/Events/onLocal/#return-value) returns them.
+- `queue` (Boolean), `handlerName` (String | null), `includeValue` (Boolean). An inline handler comes back as its server-assigned `handlerName`, which starts with `@`.
+- `handlerScope` (String): `'user'` when the subscription is bound to a handler in the user's own scope. Absent otherwise.
+- `appUid` (String | null): The app that created it, or `null` if it was created outside an app.
+- `contextKeys` (Array | null), `contextHash` (String | null): The key names and a hash of the stored context, never its values.
+- `createdAt`, `expiresAt` (Number | null): Unix seconds.
+- `suspendedAt` (Number | null), `suspendedReason` (String | null): Set when the subscription is [suspended](#suspended-subscriptions).
+- `off()` (Function): Ends the subscription and stops running its handler here. Same as [`puter.events.unsubscribe(subId)`](/Events/unsubscribe/).
+
+The promise rejects with `{ message, code }`:
+
+| `code` | Meaning |
+| --- | --- |
+| `events_handler_conflict` | The inline handler couldn't be confirmed after a concurrent publish. Try again. |
+| `events_handler_hash_mismatch` | The published handler isn't the source passed as `handler`. |
+| `events_handler_not_found` | Nothing is published under `handlerName` in that scope, or source was supplied to check a named handler outside an app. |
+| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
+| `events_handler_invalid` | `handler` isn't a function, a nonempty source string, or `{ file }`. |
+| `invalid_subject` | The subject is empty, not a string, or can't be parsed, or it's a `notif:` subject and this server has notification events turned off. |
+| `auth_canceled` | Nobody was signed in, and the user closed the sign-in without finishing it. |
+| `events_user_handlers_disabled` | Publishing into a user scope isn't turned on for this server. |
+| `events_handler_forbidden` | The call can't publish into a user scope: it came from a scoped access token, a temporary account, or on behalf of a different app. |
+| `insufficient_funds` | Publishing into a user scope needs credit on a hosted Puter server, and the user has none. Arrives as HTTP 402. |
+| `forbidden` | The user already holds as many [worker units](/rate-limits-and-quotas/#worker-units) as their plan allows, so a new user scope can't be created. |
+| `events_handler_limit` | The user scope already holds the [maximum number of handlers](/rate-limits-and-quotas/#handlers). |
+| `events_handler_too_large` | The handler is over 64 KB. |
+| `events_worker_too_large` | The user scope's handlers would exceed 1 MB combined. |
+| `events_handler_name_invalid` | `handlerName` has characters that aren't allowed, or starts with `@`, which is reserved for inline handlers. |
+| `events_handler_free_variable` | The handler uses an outside variable. The message names it. |
+| `events_handler_invalid` | `handler` isn't a function, a source string, or `{ file }`. |
+| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
+| `events_handler_not_found` | Nothing is published under `handlerName` in that scope of this app. |
+| `events_handler_hash_mismatch` | The published handler isn't the source you passed as `handler`. |
+| `events_handler_required` | `queue: true` without a `handlerName` or an inline `handler`. |
+| `events_background_consent_required` | An app subscribed with a handler, and the user hasn't granted `events:background`. |
+| `events_context_too_large` | The serialized `context` is over 4 KB. |
+| `events_context_invalid` | `context` isn't JSON-serializable. |
+| `bad_request` | `queue` isn't a boolean, `delivery` isn't `'broadcast'` or `'single'`, the two disagree, or `handlerName` isn't a string or is over 128 characters. |
+| `invalid_expires_at` | `expiresAt` isn't a future time. |
+| `invalid_include_value` | `includeValue` isn't a boolean, or the subject isn't `kv:`. |
+| `invalid_subject_op`, `invalid_subject_audience`, `invalid_subject_pattern`, `invalid_kv_pattern`, `invalid_kv_handle_key`, `events_cross_app_disabled`, `events_kv_handles_disabled`, `forbidden` | As on [`onLocal()`](/Events/onLocal/#return-value). |
+| `subject_does_not_exist` | The subject doesn't exist, or this account can't read it. |
+| `events_subscription_limit` | The account or app is at its [persistent subscription limit](/rate-limits-and-quotas/#events). |
+| `events_value_too_large` | A field is longer than can be stored, such as an app id over 40 characters. |
+| `events_durable_requires_account` | Temporary (anonymous) accounts only get session subscriptions. Scoped access tokens, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, get no persistent subscriptions either, whether the account or an app created them. |
+| `too_many_requests` | Over the subscribe rate limit. |
+| `events_disabled` | Events aren't enabled on this server. |
+| `events_failed` | The server sent a response the SDK couldn't read. |
+
+With a `{ file }` handler, errors from [`puter.fs.read()`](/FS/read/) also pass through.
+
 ## Examples

 The first example is the inline form, which any app can use for the signed-in user. The others bind to a handler the app's owner published, so they run in your own app or from Node.js signed in as its developer.

-### Watch a folder with an inline handler
+<strong class="example-title">Watch a folder with an inline handler</strong>

 ```js
 await puter.perms.request('backgroundEvents');
@@ -248,7 +242,7 @@ await puter.events.unsubscribe(sub.subId);

 The handler is stored in the user's scope under `sub.handlerName`, and keeps running for this user until the subscription ends. After the subscription ends, Puter removes the handler about a day later, once nothing is bound to it. You can remove it sooner, as [Clean Up Background Work](/recipes/clean-up-background-work/#remove-a-user-scope) shows.

-### Watch a folder with a handler the app's owner published
+<strong class="example-title">Watch a folder with a handler the app's owner published</strong>

 Publish once as the developer to ship one shared handler to every user.

@@ -273,7 +267,7 @@ const sub = await puter.events.onPersistent({
 await puter.events.unsubscribe(sub.subId);
 ```

-### Bind to the exact source you wrote against
+<strong class="example-title">Bind to the exact source you wrote against</strong>

 ```js
 const handler = ({ event, ctx }) => console.log(ctx.label, event.path);
@@ -4,13 +4,11 @@ description: Run your app's handler at an interval, on a cron expression in a ti
 platforms: [websites, apps, nodejs, workers]
 ---

-Runs a handler on a timer.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

 <div class="info">Schedules are available on puter.com. A self-hosted Puter server answers <code>events_disabled</code>.</div>

-A schedule can run at an interval, on a cron expression in a time zone, or once at a set time. It's stored on the user's account and runs in an [events worker](/Events/workers/), whether or not your app is open. It never runs in the client that created it.
+Runs a handler on a timer. A schedule can run at an interval, on a cron expression in a time zone, or once at a set time. It's stored on the user's account and runs in an [events worker](/Events/workers/), whether or not your app is open. It never runs in the client that created it.

 The handler is either inline code you pass as `handler`, or a handler published under a name with [`puter.events.handlers.publish()`](/Events/handlers/). Inline code is published into the signed-in user's own [user scope](/Events/handlers/#user-scope) of your app and runs for that user only. A named handler published by the app's owner is shared by every user of the app.

@@ -31,87 +29,20 @@ puter.events.onSchedule(options)

 Give exactly one of `every`, `cron` or `at`.

-| Option | Type | Description |
-|--------|------|-------------|
-| `every` | `Number \| String` | Run at this interval, in milliseconds or as a duration such as `'30m'`, `'6h'` or `'1d'`. The units are `s`, `m`, `h`, `d` and `w`. The interval must be a whole number of seconds, at least your plan's [minimum interval](#how-often-a-schedule-can-run), and at most 366 days. |
-| `cron` | `String` | Run on a [cron expression](#cron-expressions), such as `'0 9 * * 1-5'` for 09:00 on weekdays. |
-| `at` | `Number \| String \| Date` | Run once, at this [time](#times). It must be at least 1 second and at most 366 days ahead. A schedule with `at` takes no `startAt`, `expiresAt` or `maxRuns`. |
-| `handler` | `Function \| String \| Object` | Required unless you pass `handlerName`. The handler code, as a function, a source string, or `{ file: '~/AppData/…/handler.js' }`. Without `handlerName`, the source is sent and published into the signed-in user's own user scope, and every run calls it. With `handlerName`, only its hash is sent, and the schedule is created only if it matches what's published under that name. It never runs in this client. |
-| `handlerName` | `String` | Required unless you pass `handler`. The published handler each run calls. |
-| `context` | `Object` | Values the handler needs, passed to every run as a frozen `ctx`. Up to 4 KB serialized. It's read once, at this call. To replace it, use [`updateSchedule()`](/Events/updateSchedule/). |
-| `tz` | `String` | The IANA time zone the `cron` expression runs in, such as `'America/New_York'`. Defaults to `'UTC'`. Only allowed with `cron`. See [Time zones and daylight saving time](#time-zones-and-daylight-saving-time). |
-| `startAt` | `Number \| String \| Date` | For `every`, the first run. Without it, the first run is one interval after this call. A `startAt` in the past sets where the intervals line up, and the first run is the next one after this call. For example, `every: '1d'` with `startAt: '2026-01-01'` runs at midnight UTC every day. For `cron`, the earliest time the schedule may run. At most 366 days ahead. |
-| `expiresAt` | `Number \| String \| Date` | The last time the schedule may run. A run due at exactly this time still runs. |
-| `maxRuns` | `Number` | How many slots the schedule has, from 1 to 100,000. It ends at its `maxRuns`-th slot counted from the first. It counts slots, not runs that happened, so slots skipped while the schedule was behind or suspended (see [When a schedule runs](#when-a-schedule-runs)) still count, and the retries of one slot count once. With `expiresAt` too, the one that comes first ends the schedule. |
-| `handlerScope` | `String` | Where `handlerName` is looked up, `'app'` or `'user'`. Defaults to `'app'`, the handlers the app's owner published. With `'user'`, it binds to a handler the signed-in user's scope holds, published with `handlers.publish(name, handler, { scope: 'user' })`. |
-| `handlerHash` | `String` | The SHA-256 hex digest of the handler source, in place of `handler`, to check it against `handlerName`. |
+- `every` (Number | String): Run at this interval, in milliseconds or as a duration such as `'30m'`, `'6h'` or `'1d'`. The units are `s`, `m`, `h`, `d` and `w`. The interval must be a whole number of seconds, at least your plan's [minimum interval](#how-often-a-schedule-can-run), and at most 366 days.
+- `cron` (String): Run on a [cron expression](#cron-expressions), such as `'0 9 * * 1-5'` for 09:00 on weekdays.
+- `tz` (String): The IANA time zone the `cron` expression runs in, such as `'America/New_York'`. Defaults to `'UTC'`. Only allowed with `cron`. See [Time zones and daylight saving time](#time-zones-and-daylight-saving-time).
+- `at` (Number | String | Date): Run once, at this [time](#times). It must be at least 1 second and at most 366 days ahead. A schedule with `at` takes no `startAt`, `expiresAt` or `maxRuns`.
+- `startAt` (Number | String | Date): For `every`, the first run. Without it, the first run is one interval after this call. A `startAt` in the past sets where the intervals line up, and the first run is the next one after this call. For example, `every: '1d'` with `startAt: '2026-01-01'` runs at midnight UTC every day. For `cron`, the earliest time the schedule may run. At most 366 days ahead.
+- `expiresAt` (Number | String | Date): The last time the schedule may run. A run due at exactly this time still runs.
+- `maxRuns` (Number): How many slots the schedule has, from 1 to 100,000. It ends at its `maxRuns`-th slot counted from the first. It counts slots, not runs that happened, so slots skipped while the schedule was behind or suspended (see [When a schedule runs](#when-a-schedule-runs)) still count, and the retries of one slot count once. With `expiresAt` too, the one that comes first ends the schedule.
+- `handler` (Function | String | Object): The handler code, as a function, a source string, or `{ file: '~/AppData/…/handler.js' }`. Required unless you pass `handlerName`. Without `handlerName`, the source is sent and published into the signed-in user's own user scope, and every run calls it. With `handlerName`, only its hash is sent, and the schedule is created only if it matches what's published under that name. It never runs in this client.
+- `handlerName` (String): The published handler each run calls. Required unless you pass `handler`.
+- `handlerScope` (String): Where `handlerName` is looked up, `'app'` or `'user'`. Defaults to `'app'`, the handlers the app's owner published. `'user'` binds to a handler the signed-in user's scope holds, published with `handlers.publish(name, handler, { scope: 'user' })`.
+- `handlerHash` (String): The SHA-256 hex digest of the handler source, in place of `handler`, to check it against `handlerName`.
+- `context` (Object): Values the handler needs, passed to every run as a frozen `ctx`. Up to 4 KB serialized. It's read once, at this call. To replace it, use [`updateSchedule()`](/Events/updateSchedule/).

-## Return value
-
-A `Promise` that resolves to the schedule. All times are in milliseconds since the epoch.
-
- `scheduleId` (String): Its id, which [`getSchedule()`](/Events/getSchedule/), [`updateSchedule()`](/Events/updateSchedule/) and [`removeSchedule()`](/Events/removeSchedule/) take.
- `kind` (String): `'recurring'` for `every` and `cron`, `'once'` for `at`, and `'deferred'` for a notification sent later with [`notify()`](/Notifications/notify/#send-it-later).
- `appUid` (String): The app that created it.
- `handlerName` (String | null): The handler each run calls, or `null` once the schedule has ended. For a schedule created with an inline `handler`, it's the name Puter gave the handler, which starts with `@`.
- `handlerScope` (String): `'user'` when the handler is in the user's own [user scope](/Events/handlers/#user-scope). Absent for an app handler.
- `contextKeys` (Array | null), `contextHash` (String | null): The key names and a hash of the stored context, never its values. The `contextKeys` field is `null` when there's no context, and once the schedule has ended.
- `every` (Number | null): The interval, in milliseconds, of an `every` schedule.
- `cron` (String | null): The expression of a `cron` schedule.
- `tz` (String): The time zone of a `cron` schedule, and `'UTC'` for the others.
- `startAt` (Number): The first time it may run. For `at`, its only run.
- `endsAt` (Number | null): The last time it may run, from `expiresAt` or `maxRuns`. For `at`, its only run.
- `state` (String): `'active'`, `'suspended'`, `'sending'`, or `'ended'`. A delayed notification is `'sending'` during a send attempt. A failed attempt can return it to `'active'` before retrying.
- `suspendedReason` (String | null): Why it's [suspended](#suspended-and-ended-schedules).
- `endReason` (String | null), `endedAt` (Number | null): Why and when it [ended](#suspended-and-ended-schedules).
- `nextRunAt` (Number | null): The next slot of the schedule, worked out from its definition and the clock. A late or retried run for an earlier slot can still happen first. After the last slot is due, it stays at that slot until the run for it is done. It's `null` while the schedule is suspended or sending, and once it has ended.
- `createdAt` (Number): When it was created.
- `off()` (Function): Removes the schedule. Same as [`puter.events.removeSchedule(scheduleId)`](/Events/removeSchedule/). Only on the object `onSchedule()` returns.
-
-## Errors
-
-The promise rejects with `{ message, code }`:
-
-| `code` | Meaning |
-| --- | --- |
-| `events_value_too_large` | A field is longer than can be stored. |
-| `events_handler_conflict` | The inline handler couldn't be confirmed after a concurrent publish. Try again. |
-| `invalid_request` | `options` isn't an object. |
-| `events_handler_required` | There's neither a `handler` nor a `handlerName`. |
-| `events_user_handlers_disabled` | Publishing into a user scope isn't turned on for this server. |
-| `events_handler_forbidden` | The call can't publish into a user scope: it came from a scoped access token, a temporary account, or on behalf of a different app. |
-| `insufficient_funds` | Publishing into a user scope needs credit on a hosted Puter server, and the user has none. Arrives as HTTP 402. |
-| `forbidden` | The user already holds as many [worker units](/rate-limits-and-quotas/#worker-units) as their plan allows, so a new user scope can't be created. |
-| `events_handler_limit` | The user scope already holds the [maximum number of handlers](/rate-limits-and-quotas/#handlers). |
-| `events_handler_too_large` | The handler is over 64 KB. |
-| `events_worker_too_large` | The user scope's handlers would exceed 1 MB combined. |
-| `events_handler_name_invalid` | `handlerName` is empty, too long, has characters that aren't allowed, or starts with `@`, which is reserved for inline handlers. |
-| `events_handler_free_variable` | The handler uses an outside variable. The message names it. |
-| `events_handler_invalid` | `handler` isn't a function, a source string, or `{ file }`. |
-| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
-| `events_context_invalid` | `context` isn't JSON-serializable. |
-| `events_context_too_large` | The serialized `context` is over 4 KB. |
-| `auth_canceled` | Nobody was signed in, and the user closed the sign-in without finishing it. |
-| `events_schedule_app_required` | The call wasn't made by an app, for example from Node.js with an account token. |
-| `events_durable_requires_account` | The call came from a scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, or from a temporary (guest) account. |
-| `too_many_requests` | Over the create rate limit, which is shared with subscribing. |
-| `events_background_consent_required` | The user hasn't granted your app `events:background`. |
-| `events_schedule_invalid` | An option is malformed. For example, more than one of `every`, `cron` and `at`, an `every` that isn't a whole number of seconds, a time with no zone, an `at` less than 1 second or more than 366 days ahead, an unsupported cron expression, an unknown `tz`, or `tz` without `cron`. The message says which. |
-| `events_schedule_never_fires` | The schedule would never run. Its first run or its `startAt` is more than 366 days away, or it ends before its first run. |
-| `events_schedule_too_frequent` | It would run more often than your plan's [minimum interval](#how-often-a-schedule-can-run). |
-| `events_schedule_too_deep` | The call was made from a handler at the end of a [handler chain](/Events/onPersistent/#handlers-that-trigger-handlers), so the schedule could never run. |
-| `bad_request` | `handlerName` is empty or over 128 characters, `handlerHash` isn't a SHA-256 hex digest, or `handlerScope` isn't `'app'` or `'user'`. |
-| `events_handler_not_found` | Nothing is published under `handlerName` in that scope. The schedule isn't created. |
-| `events_handler_hash_mismatch` | The published handler isn't the source you passed as `handler`. |
-| `events_schedule_limit` | The user holds as many schedules as their plan allows, for your app or in total. |
-| `events_schedule_budget` | The schedule would make your app's schedules, or all of the user's schedules, run more times an hour than their plan allows. |
-| `events_schedule_busy` | Puter is checking too many cron expressions at once. Try again in a moment. |
-| `events_disabled` | Schedules aren't available on this server, as on self-hosted servers. |
-| `events_failed` | The server sent a response the SDK couldn't read. |
-
-With a `{ file }` handler, errors from [`puter.fs.read()`](/FS/read/) also pass through.
-
-## Times
+### Times

 The `at`, `startAt` and `expiresAt` options each take one of these:

@@ -213,15 +144,15 @@ A run's `event` carries:

 | Field | Type | Description |
 | --- | --- | --- |
-| `subject` | `String` | `schedule:<scheduleId>`. |
-| `op` | `String` | Always `'tick'`. |
-| `id` | `String` | `<scheduleId>:<scheduledFor>`. The same on every attempt at one run, so use it to skip work you've already done. |
-| `scheduleId` | `String` | The schedule this run belongs to. |
-| `scheduledFor` | `Number` | The slot this run is for, in milliseconds since the epoch. |
-| `firedAt` | `Number` | When this attempt was sent to the handler, in milliseconds since the epoch. |
-| `missed` | `Number` | Slots skipped since the last run, for example while the schedule was suspended. Only this run happens for them. |
-| `missedCapped` | `Boolean` | Present, and `true`, when `missed` stopped counting at 1,000. |
-| `attempt` | `Number` | Attempts at this run, this one included. `1` on the first try. |
+| `subject` | String | `schedule:<scheduleId>`. |
+| `op` | String | Always `'tick'`. |
+| `id` | String | `<scheduleId>:<scheduledFor>`. The same on every attempt at one run, so use it to skip work you've already done. |
+| `scheduleId` | String | The schedule this run belongs to. |
+| `scheduledFor` | Number | The slot this run is for, in milliseconds since the epoch. |
+| `firedAt` | Number | When this attempt was sent to the handler, in milliseconds since the epoch. |
+| `missed` | Number | Slots skipped since the last run, for example while the schedule was suspended. Only this run happens for them. |
+| `missedCapped` | Boolean | Present, and `true`, when `missed` stopped counting at 1,000. |
+| `attempt` | Number | Attempts at this run, this one included. `1` on the first try. |

 The `user` binding is valid for 15 minutes, so use it only during the run. Writes made through `user` count toward the same [handler chain](/Events/onPersistent/#handlers-that-trigger-handlers) limit as a subscription's, starting from the depth of the call that created the schedule.

@@ -277,11 +208,74 @@ An ended schedule never runs again. It has `state: 'ended'` and an `endReason`,

 When schedules end with `permission_revoked`, the user's app gets an `app.events.ended` notification about them, which you can read with [`puter.events.fetch()`](/Events/fetch/).

+## Return value
+
+A `Promise` that resolves to the schedule. All times are in milliseconds since the epoch.
+
+- `scheduleId` (String): Its id, which [`getSchedule()`](/Events/getSchedule/), [`updateSchedule()`](/Events/updateSchedule/) and [`removeSchedule()`](/Events/removeSchedule/) take.
+- `kind` (String): `'recurring'` for `every` and `cron`, `'once'` for `at`, and `'deferred'` for a notification sent later with [`notify()`](/Notifications/notify/#send-it-later).
+- `appUid` (String): The app that created it.
+- `handlerName` (String | null): The handler each run calls, or `null` once the schedule has ended. For a schedule created with an inline `handler`, it's the name Puter gave the handler, which starts with `@`.
+- `handlerScope` (String): `'user'` when the handler is in the user's own [user scope](/Events/handlers/#user-scope). Absent for an app handler.
+- `contextKeys` (Array | null), `contextHash` (String | null): The key names and a hash of the stored context, never its values. The `contextKeys` field is `null` when there's no context, and once the schedule has ended.
+- `every` (Number | null): The interval, in milliseconds, of an `every` schedule.
+- `cron` (String | null): The expression of a `cron` schedule.
+- `tz` (String): The time zone of a `cron` schedule, and `'UTC'` for the others.
+- `startAt` (Number): The first time it may run. For `at`, its only run.
+- `endsAt` (Number | null): The last time it may run, from `expiresAt` or `maxRuns`. For `at`, its only run.
+- `state` (String): `'active'`, `'suspended'`, `'sending'`, or `'ended'`. A delayed notification is `'sending'` during a send attempt. A failed attempt can return it to `'active'` before retrying.
+- `suspendedReason` (String | null): Why it's [suspended](#suspended-and-ended-schedules).
+- `endReason` (String | null), `endedAt` (Number | null): Why and when it [ended](#suspended-and-ended-schedules).
+- `nextRunAt` (Number | null): The next slot of the schedule, worked out from its definition and the clock. A late or retried run for an earlier slot can still happen first. After the last slot is due, it stays at that slot until the run for it is done. It's `null` while the schedule is suspended or sending, and once it has ended.
+- `createdAt` (Number): When it was created.
+- `off()` (Function): Removes the schedule. Same as [`puter.events.removeSchedule(scheduleId)`](/Events/removeSchedule/). Only on the object `onSchedule()` returns.
+
+The promise rejects with `{ message, code }`:
+
+| `code` | Meaning |
+| --- | --- |
+| `events_value_too_large` | A field is longer than can be stored. |
+| `events_handler_conflict` | The inline handler couldn't be confirmed after a concurrent publish. Try again. |
+| `invalid_request` | `options` isn't an object. |
+| `events_handler_required` | There's neither a `handler` nor a `handlerName`. |
+| `events_user_handlers_disabled` | Publishing into a user scope isn't turned on for this server. |
+| `events_handler_forbidden` | The call can't publish into a user scope: it came from a scoped access token, a temporary account, or on behalf of a different app. |
+| `insufficient_funds` | Publishing into a user scope needs credit on a hosted Puter server, and the user has none. Arrives as HTTP 402. |
+| `forbidden` | The user already holds as many [worker units](/rate-limits-and-quotas/#worker-units) as their plan allows, so a new user scope can't be created. |
+| `events_handler_limit` | The user scope already holds the [maximum number of handlers](/rate-limits-and-quotas/#handlers). |
+| `events_handler_too_large` | The handler is over 64 KB. |
+| `events_worker_too_large` | The user scope's handlers would exceed 1 MB combined. |
+| `events_handler_name_invalid` | `handlerName` is empty, too long, has characters that aren't allowed, or starts with `@`, which is reserved for inline handlers. |
+| `events_handler_free_variable` | The handler uses an outside variable. The message names it. |
+| `events_handler_invalid` | `handler` isn't a function, a source string, or `{ file }`. |
+| `events_handler_hash_unavailable` | This environment has no `crypto.subtle`, so `handler` can't be hashed. Pass `handlerName` alone. |
+| `events_context_invalid` | `context` isn't JSON-serializable. |
+| `events_context_too_large` | The serialized `context` is over 4 KB. |
+| `auth_canceled` | Nobody was signed in, and the user closed the sign-in without finishing it. |
+| `events_schedule_app_required` | The call wasn't made by an app, for example from Node.js with an account token. |
+| `events_durable_requires_account` | The call came from a scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, or from a temporary (guest) account. |
+| `too_many_requests` | Over the create rate limit, which is shared with subscribing. |
+| `events_background_consent_required` | The user hasn't granted your app `events:background`. |
+| `events_schedule_invalid` | An option is malformed. For example, more than one of `every`, `cron` and `at`, an `every` that isn't a whole number of seconds, a time with no zone, an `at` less than 1 second or more than 366 days ahead, an unsupported cron expression, an unknown `tz`, or `tz` without `cron`. The message says which. |
+| `events_schedule_never_fires` | The schedule would never run. Its first run or its `startAt` is more than 366 days away, or it ends before its first run. |
+| `events_schedule_too_frequent` | It would run more often than your plan's [minimum interval](#how-often-a-schedule-can-run). |
+| `events_schedule_too_deep` | The call was made from a handler at the end of a [handler chain](/Events/onPersistent/#handlers-that-trigger-handlers), so the schedule could never run. |
+| `bad_request` | `handlerName` is empty or over 128 characters, `handlerHash` isn't a SHA-256 hex digest, or `handlerScope` isn't `'app'` or `'user'`. |
+| `events_handler_not_found` | Nothing is published under `handlerName` in that scope. The schedule isn't created. |
+| `events_handler_hash_mismatch` | The published handler isn't the source you passed as `handler`. |
+| `events_schedule_limit` | The user holds as many schedules as their plan allows, for your app or in total. |
+| `events_schedule_budget` | The schedule would make your app's schedules, or all of the user's schedules, run more times an hour than their plan allows. |
+| `events_schedule_busy` | Puter is checking too many cron expressions at once. Try again in a moment. |
+| `events_disabled` | Schedules aren't available on this server, as on self-hosted servers. |
+| `events_failed` | The server sent a response the SDK couldn't read. |
+
+With a `{ file }` handler, errors from [`puter.fs.read()`](/FS/read/) also pass through.
+
 ## Examples

 The handler is published once, by the app's developer, from a deploy script or the browser console. The schedule is created from the app, for each user.

-### Run a handler on weekday mornings in the user's time zone
+<strong class="example-title">Run a handler on weekday mornings in the user's time zone</strong>

 ```js
 // Deploy script, run as the app's developer
@@ -314,7 +308,7 @@ const schedule = await puter.events.onSchedule({
 if (schedule.nextRunAt !== null) console.log(`next digest at ${new Date(schedule.nextRunAt).toString()}`);
 ```

-### Run once, an hour from now
+<strong class="example-title">Run once, an hour from now</strong>

 ```js
 const reminder = await puter.events.onSchedule({
@@ -330,7 +324,7 @@ await puter.events.updateSchedule(reminder.scheduleId, { at: Date.now() + 2 * 60
 await reminder.off();
 ```

-### Run every 6 hours, on the hour, 28 times
+<strong class="example-title">Run every 6 hours, on the hour, 28 times</strong>

 ```js
 await puter.events.onSchedule({
@@ -4,11 +4,9 @@ description: End a schedule, or cancel a notification stored to send later.
 platforms: [websites, apps, nodejs, workers]
 ---

-Ends a schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-It doesn't run again, and it stays in [`listSchedules()`](/Events/listSchedules/) for 7 days with `endReason: 'removed'`. A run that already started isn't stopped.
+Ends a schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/). It doesn't run again, and it stays in [`listSchedules()`](/Events/listSchedules/) for 7 days with `endReason: 'removed'`. A run that already started isn't stopped.

 It also cancels a notification your app stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later), the same as [`puter.notifications.cancel()`](/Notifications/cancel/).

@@ -32,8 +30,6 @@ A `Promise` that resolves when the schedule has ended.

 An app can only remove schedules it created. An account session can remove any of the user's schedules, including ones left by apps they no longer use. A scoped access token can't remove any.

-## Errors
-
 An id this caller doesn't hold, or a schedule that already ended, is reported as not existing, so removing a schedule twice rejects the second time. With `events_schedule_sending`, `auth_canceled`, `too_many_requests` or `events_disabled`, nothing was removed. When the call fails any other way, such as a network error or `events_failed`, the removal may still have happened, so read the schedule again with [`getSchedule()`](/Events/getSchedule/) to find out.

 It rejects with `{ message, code }`:
@@ -49,7 +45,7 @@ It rejects with `{ message, code }`:

 ## Examples

-### Cancel a notification, then read it
+<strong class="example-title">Cancel a notification, then read it</strong>

 ```html;events-remove-schedule
 <html>
@@ -4,11 +4,9 @@ description: The subject strings Events subscriptions watch, and the events they
 platforms: [websites, apps, nodejs, workers]
 ---

-A subject is the string that says what a subscription watches.
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-[`onLocal()`](/Events/onLocal/) and [`onPersistent()`](/Events/onPersistent/) take the same subjects and deliver the same events.
+A subject is the string that says what a subscription watches. [`onLocal()`](/Events/onLocal/) and [`onPersistent()`](/Events/onPersistent/) take the same subjects and deliver the same events.

 ## Syntax

@@ -151,30 +149,30 @@ The handler is called with `{ event }`. A file change carries:

 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `String` | Unique id for the event. |
-| `subject` | `String` | The node it happened to, as `fs:<uid>:<op>`. Not the subject you subscribed with. |
-| `op` | `String` | `add` (a create, or a copy's destination), `write`, `move` (a move or a rename), or `remove`. |
-| `uid` | `String` | The uid of the node that changed. |
-| `path` | `String` | The path of the node that changed. In another user's files, it's a [masked path](/FS/listShared/), `/<owner>/<uid>/<name>/…`, where `<uid>` and `<name>` are those of the node the subscription is attached to. |
-| `from` | `String` | On a `move`, the path the node left, masked the same way. Only present when the subscription was watching that location. |
-| `self` | `Boolean` | `true` when the account holding the subscription made the change. Mail filed into the account's `~/.mail` folder is always `false`, including mail the account sent to itself. |
-| `viaWorker` | `Boolean` | `true` when the change came from server-side code running as an account, such as a worker using `me.puter` or an [events handler](/Events/handlers/) running in the events worker. A worker using `user.puter` acts as the user who called it, so its changes are that user's own, with `viaWorker` set to `false`. A handler running in a client writes as that client, also with `viaWorker` set to `false`. To skip your own changes, check `self && !viaWorker`, which still lets through the ones a worker made as your account. |
-| `ts` | `Number` | When it happened, in milliseconds since the epoch. |
-| `seq` | `Number` | Position within one dispatch, when a change goes to several subscriptions. |
+| `id` | String | Unique id for the event. |
+| `subject` | String | The node it happened to, as `fs:<uid>:<op>`. Not the subject you subscribed with. |
+| `op` | String | `add` (a create, or a copy's destination), `write`, `move` (a move or a rename), or `remove`. |
+| `uid` | String | The uid of the node that changed. |
+| `path` | String | The path of the node that changed. In another user's files, it's a [masked path](/FS/listShared/), `/<owner>/<uid>/<name>/…`, where `<uid>` and `<name>` are those of the node the subscription is attached to. |
+| `from` | String | On a `move`, the path the node left, masked the same way. Only present when the subscription was watching that location. |
+| `self` | Boolean | `true` when the account holding the subscription made the change. Mail filed into the account's `~/.mail` folder is always `false`, including mail the account sent to itself. |
+| `viaWorker` | Boolean | `true` when the change came from server-side code running as an account, such as a worker using `me.puter` or an [events handler](/Events/handlers/) running in the events worker. A worker using `user.puter` acts as the user who called it, so its changes are that user's own, with `viaWorker` set to `false`. A handler running in a client writes as that client, also with `viaWorker` set to `false`. To skip your own changes, check `self && !viaWorker`, which still lets through the ones a worker made as your account. |
+| `ts` | Number | When it happened, in milliseconds since the epoch. |
+| `seq` | Number | Position within one dispatch, when a change goes to several subscriptions. |

 A key-value change carries `key` instead of `uid` and `path`, and different ops:

 | Field | Type | Description |
 | --- | --- | --- |
-| `id` | `String` | Unique id for the event. |
-| `subject` | `String` | `kv:<appId>:<key>`, naming the key that changed. Through a share, `kv:<handle>:<key>`. |
-| `op` | `String` | `set` for a write, `del` for a removal, `expire` when only the key's lifetime changed. |
-| `key` | `String` | The key that changed. Through a share, relative to the handle. |
-| `value` | `Any` | The new value, or `null` on a `del`. Only with `includeValue`, and only within the [limits above](#getting-the-new-value). Never on an `expire`. |
-| `self` | `Boolean` | As above. |
-| `viaWorker` | `Boolean` | As above. |
-| `ts` | `Number` | As above. |
-| `seq` | `Number` | As above. |
+| `id` | String | Unique id for the event. |
+| `subject` | String | `kv:<appId>:<key>`, naming the key that changed. Through a share, `kv:<handle>:<key>`. |
+| `op` | String | `set` for a write, `del` for a removal, `expire` when only the key's lifetime changed. |
+| `key` | String | The key that changed. Through a share, relative to the handle. |
+| `value` | Any | The new value, or `null` on a `del`. Only with `includeValue`, and only within the [limits above](#getting-the-new-value). Never on an `expire`. |
+| `self` | Boolean | As above. |
+| `viaWorker` | Boolean | As above. |
+| `ts` | Number | As above. |
+| `seq` | Number | As above. |

 A posted notification carries the fields listed on [`fetch()`](/Events/fetch/#return-value). An app message's live dismissal carries `op: 'dismiss'` and its `uid`, with no `notification` content. Dismissals follow the same audience rules. The notification SDK exposes them through [`on('dismiss')`](/Notifications/on/).

@@ -4,11 +4,9 @@ description: End a persistent subscription.
 platforms: [websites, apps, nodejs, workers]
 ---

-Ends a subscription created with [`puter.events.onPersistent()`](/Events/onPersistent/).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-It stops right away, and any undelivered backlog is dropped. For a session subscription from [`puter.events.onLocal()`](/Events/onLocal/), use [`subscription.off()`](/Events/off/).
+Ends a subscription created with [`puter.events.onPersistent()`](/Events/onPersistent/). It stops right away, and any undelivered backlog is dropped. For a session subscription from [`puter.events.onLocal()`](/Events/onLocal/), use [`subscription.off()`](/Events/off/).

 An app can end only the subscriptions it created. Outside an app, you can end any of yours, including ones left by deleted apps. A scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, can't end any.

@@ -28,8 +26,6 @@ The `subId` of the subscription, from [`onPersistent()`](/Events/onPersistent/)

 A `Promise` that resolves when the subscription is gone.

-## Errors
-
 An id you don't hold, because it already ended or another app created it, is reported as not existing, so the call doesn't reveal which subscriptions exist. If the call rejects with any other code, the subscription is still running, and so is any handler it runs on this page.

 The promise rejects with `{ message, code }`:
@@ -45,7 +41,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### Create a persistent subscription, then end it
+<strong class="example-title">Create a persistent subscription, then end it</strong>

 ```html;events-unsubscribe
 <html>
@@ -4,11 +4,9 @@ description: Change the context of a persistent subscription without ending it.
 platforms: [websites, apps, nodejs, workers]
 ---

-Changes the `context` of a subscription created with [`puter.events.onPersistent()`](/Events/onPersistent/).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-The subscription keeps its `subId`, its handler, and any events it hasn't delivered yet, and later deliveries in the events worker run with the new `context` as `ctx`. Ending the subscription and subscribing again would give it a new `subId` and drop its undelivered events. To change a [schedule's](/Events/onSchedule/) context, use [`updateSchedule()`](/Events/updateSchedule/).
+Changes the `context` of a subscription created with [`puter.events.onPersistent()`](/Events/onPersistent/). The subscription keeps its `subId`, its handler, and any events it hasn't delivered yet, and later deliveries in the events worker run with the new `context` as `ctx`. Ending the subscription and subscribing again would give it a new `subId` and drop its undelivered events. To change a [schedule's](/Events/onSchedule/) context, use [`updateSchedule()`](/Events/updateSchedule/).

 An app can change only the subscriptions it created. Outside an app, you can change any of yours. A scoped access token, such as the one in a [`getReadURL()`](/FS/getReadURL/) URL, can't change any.

@@ -33,8 +31,6 @@ A `Promise` that resolves to the updated subscription, in the same shape [`puter

 A delivery already running when you call `update()` finishes with the old context. A suspended subscription stays suspended and uses the new context once it resumes. If this page runs a function `handler` for the subscription, that handler gets the new context too. Handlers in other open pages keep the context they registered with.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -51,7 +47,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### Point a subscription at a new endpoint
+<strong class="example-title">Point a subscription at a new endpoint</strong>

 ```html;events-update
 <html>
@@ -4,11 +4,9 @@ description: Move a schedule to a new time, change its context, or edit a notifi
 platforms: [websites, apps, nodejs, workers]
 ---

-Changes a schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/), or a notification stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-The schedule keeps its `scheduleId`, its kind and its handler, so ids you saved elsewhere stay valid.
+Changes a schedule created with [`puter.events.onSchedule()`](/Events/onSchedule/), or a notification stored to send later with [`puter.notifications.notify()`](/Notifications/notify/#send-it-later). The schedule keeps its `scheduleId`, its kind and its handler, so ids you saved elsewhere stay valid.

 An app can change only the schedules it created. An account session can change any of the user's schedules. A scoped access token can't change any. On a website with nobody signed in, the call asks the user to sign in first, as other Puter.js calls do.

@@ -28,36 +26,13 @@ The `scheduleId` from [`onSchedule()`](/Events/onSchedule/), [`notify()`](/Notif

 For a schedule from [`onSchedule()`](/Events/onSchedule/), pass new timing, a new `context`, or both:

-| Option | Type | Description |
-|--------|------|-------------|
-| `every` | `Number \| String` | The new interval. A recurring schedule can switch between `every` and `cron`. |
-| `cron` | `String` | The new cron expression. A recurring schedule can switch between `every` and `cron`. |
-| `at` | `Number \| String \| Date` | The new time for a one-time schedule. An `at` schedule stays a one-time schedule. |
-| `context` | `Object \| null` | Replaces the whole context. Pass `null` to clear it. Up to 4 KB serialized, as in [`onSchedule()`](/Events/onSchedule/#parameters). |
-| `tz` | `String` | The time zone the `cron` expression runs in. |
-| `startAt` | `Number \| String \| Date` | For `every`, the first run. For `cron`, the earliest time the schedule may run. |
-| `expiresAt` | `Number \| String \| Date` | The last time the schedule may run. |
-| `maxRuns` | `Number` | How many slots the schedule has. |
-
-The timing options are `at`, `every`, `cron`, `tz`, `startAt`, `expiresAt` and `maxRuns`. Any of them replaces the whole timing, so pass exactly one of `at`, `every` or `cron`, together with every other timing option you want to keep. They take the same values as in [`onSchedule()`](/Events/onSchedule/#parameters). Without timing options, the timing stays as it is.
+- **Timing.** Any of `at`, `every`, `cron`, `tz`, `startAt`, `expiresAt` and `maxRuns` replaces the whole timing, so pass exactly one of `at`, `every` or `cron`, together with every other timing option you want to keep. They take the same values as in [`onSchedule()`](/Events/onSchedule/#parameters). A recurring schedule can switch between `every` and `cron`, and an `at` schedule stays a one-time schedule. Without timing options, the timing stays as it is.
+- `context` (Object | null): Replaces the whole context. Pass `null` to clear it. Up to 4 KB serialized, as in [`onSchedule()`](/Events/onSchedule/#parameters).

 For a stored notification, pass a new `sendAt`, new content, or both:

-| Option | Type | Description |
-|--------|------|-------------|
-| `sendAt` | `Number \| String \| Date` | The new time to send it, as in [`notify()`](/Notifications/notify/#parameters). A time within 5 seconds, or in the past, sends it now, with the [retries](/Notifications/notify/#send-it-later) of any stored notification. |
-| `title` | `String` | Replaces the stored title. It can't be cleared. |
-| `text` | `String` | Replaces the stored text. |
-| `icon` | `String` | Replaces the stored icon. |
-| `target` | `String` | Replaces the stored target. |
-| `data` | `Any` | Replaces the stored data. |
-| `group` | `String` | Replaces the stored group. |
-| `channel` | `String` | Replaces the stored channel. |
-| `sensitive` | `Boolean` | Replaces the stored `sensitive` setting. |
-| `priority` | `String` | Replaces the stored priority. |
-| `ttl` | `Number` | Replaces the stored `ttl`. |
-
-The content options follow the same rules as in [`notify()`](/Notifications/notify/#parameters). Fields you leave out keep their values. Pass `null` to clear an optional field.
+- `sendAt` (Number | String | Date): The new time to send it, as in [`notify()`](/Notifications/notify/#parameters). A time within 5 seconds, or in the past, sends it now, with the [retries](/Notifications/notify/#send-it-later) of any stored notification.
+- `title`, `text`, `icon`, `target`, `data`, `group`, `channel`, `sensitive`, `priority`, `ttl`: Replace the stored values, with the same rules as [`notify()`](/Notifications/notify/#parameters). Fields you leave out keep their values. Pass `null` to clear an optional field. The `title` can't be cleared.

 The handler and the recipient can't change. Passing `handler`, `handlerName`, `handlerScope`, `handlerHash`, `handlerSource` or `to` rejects with `invalid_request`. To run different code, remove the schedule and create a new one.

@@ -65,8 +40,6 @@ The handler and the recipient can't change. Passing `handler`, `handlerName`, `h

 A `Promise` that resolves to the updated schedule, in the shape [`getSchedule()`](/Events/getSchedule/#return-value) returns. Its `nextRunAt` is the next run under the new timing. It describes the context by its key names and a hash, and never includes a stored notification's content. A stored notification whose new `sendAt` is due now is sent during the call, so the schedule can come back already ended.

-## Errors
-
 The promise rejects with `{ message, code }`:

 | `code` | Meaning |
@@ -98,7 +71,7 @@ The promise rejects with `{ message, code }`:

 ## Examples

-### Move a reminder to a later time
+<strong class="example-title">Move a reminder to a later time</strong>

 ```html;events-update-reminder
 <html>
@@ -130,7 +103,7 @@ The promise rejects with `{ message, code }`:
 </html>
 ```

-### Move a weekday schedule to another time
+<strong class="example-title">Move a weekday schedule to another time</strong>

 ```html;events-update-cron
 <html>
@@ -4,11 +4,9 @@ description: List and destroy the events worker a published handler set stands u
 platforms: [websites, apps, nodejs, workers]
 ---

-An **events worker** runs published [handlers](/Events/handlers/), the app's own or one user's in a [user scope](/Events/handlers/#user-scope).
-
 <div class="info">The Events API is in beta. Event shapes, limits, and behavior may change between releases.</div>

-It runs them for every event on a subscription with a `handlerName`, whether or not a client is connected, for a [`queue`](/Events/onPersistent/#choosing-a-mode) delivery once no connected client takes it, and for every run of a [schedule](/Events/onSchedule/). Each app has at most one for its own handlers, created when it publishes its first handler. Each user scope is a unit of its own, created when the user's first handler in an app is published, whether by publishing it or by passing an inline `handler`.
+An **events worker** runs published [handlers](/Events/handlers/), the app's own or one user's in a [user scope](/Events/handlers/#user-scope). It runs them for every event on a subscription with a `handlerName`, whether or not a client is connected, for a [`queue`](/Events/onPersistent/#choosing-a-mode) delivery once no connected client takes it, and for every run of a [schedule](/Events/onSchedule/). Each app has at most one for its own handlers, created when it publishes its first handler. Each user scope is a unit of its own, created when the user's first handler in an app is published, whether by publishing it or by passing an inline `handler`.

 A hosted Puter server may bill each app's events worker as a monthly cost, even if nothing ever delivers to it, and bills a user scope to the user the same way. Use this API to see which apps and scopes have one and remove the ones you don't need.

@@ -30,12 +28,8 @@ puter.events.workers.list()
 puter.events.workers.list(options)
 ```

-The `options` object takes these options:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Apps per page. |
-| `cursor` | `String` | The `cursor` from a previous page. Leave it off to start from the first page. |
+- `options.limit` (Number): Apps per page.
+- `options.cursor` (String): The `cursor` from a previous page. Leave it off to start from the first page.

 Resolves to `{ items, cursor, deployable }`:

@@ -50,13 +44,7 @@ puter.events.workers.destroy(appUid)
 puter.events.workers.destroy(appUid, options)
 ```

-The `options` object takes these options:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `scope` | `String` | Either `'app'` or `'user'`. Defaults to `'app'`. With `'user'`, it removes the signed-in user's own scope of the app. |
-
-Inside an app, `appUid` can only name that app. With an account session, outside an app such as the desktop or Node.js with your account token, `appUid` can name any app you hold a user scope in, and it works even when the server has user-scope handlers turned off.
+- `options.scope` (String): `'app'` or `'user'`. Defaults to `'app'`. `'user'` removes the signed-in user's own scope of the app. Inside an app, `appUid` can only name that app. With an account session, outside an app such as the desktop or Node.js with your account token, `appUid` can name any app you hold a user scope in, and it works even when the server has user-scope handlers turned off.

 Removes every handler the app has published, or every handler in the user's scope with `scope: 'user'`, the same as calling [`puter.events.handlers.remove()`](/Events/handlers/) on each. Their subscriptions and schedules are suspended with `handler_not_found`, not deleted, and publishing the handlers again resumes them.

@@ -78,9 +66,9 @@ Both methods reject with `{ message, code }`:
 | `events_disabled` | Events aren't enabled on this server. |
 | `events_failed` | The server sent a response the SDK couldn't read. |

-## Examples
+## Example

-### List your events workers, and destroy one you no longer need
+<strong class="example-title">List your events workers, and destroy one you no longer need</strong>

 This runs in Node.js signed in with your account token.

@@ -95,7 +83,7 @@ const destroyed = await puter.events.workers.destroy(appUid);   // an app you ow
 console.log(`removed ${destroyed.removed}, suspended ${destroyed.suspended}`);
 ```

-### Remove the signed-in user's scope of your app
+<strong class="example-title">Remove the signed-in user's scope of your app</strong>

 The user scope belongs to the user, so it needs no owner step. In your app, name the app itself. With an account session outside an app, name any app you hold a scope in.

@@ -298,14 +298,15 @@ These cloud storage features are supported out of the box when using Puter.js:

 - **[`puter.fs.write()`](/FS/write/)** - Write data to a file
 - **[`puter.fs.read()`](/FS/read/)** - Read data from a file
- **[`puter.fs.upload()`](/FS/upload/)** - Upload a file from the local system
- **[`puter.fs.readdir()`](/FS/readdir/)** - List contents of a directory
 - **[`puter.fs.mkdir()`](/FS/mkdir/)** - Create a directory
- **[`puter.fs.delete()`](/FS/delete/)** - Delete a file or directory
- **[`puter.fs.stat()`](/FS/stat/)** - Get information about a file or directory
+- **[`puter.fs.readdir()`](/FS/readdir/)** - List contents of a directory
 - **[`puter.fs.rename()`](/FS/rename/)** - Rename a file or directory
- **[`puter.fs.move()`](/FS/move/)** - Move a file or directory
 - **[`puter.fs.copy()`](/FS/copy/)** - Copy a file or directory
+- **[`puter.fs.move()`](/FS/move/)** - Move a file or directory
+- **[`puter.fs.stat()`](/FS/stat/)** - Get information about a file or directory
+- **[`puter.fs.space()`](/FS/space/)** - Get the user's storage capacity and usage
+- **[`puter.fs.delete()`](/FS/delete/)** - Delete a file or directory
+- **[`puter.fs.upload()`](/FS/upload/)** - Upload a file from the local system
 - **[`puter.fs.getReadURL()`](/FS/getReadURL/)** - Generate a URL that can be used to read a file
 - **[`puter.fs.revokeReadURL()`](/FS/revokeReadURL/)** - Revoke a URL created by `getReadURL()`
 - **[`puter.fs.share()`](/FS/share/)** - Give another user access to a file or directory
@@ -314,7 +315,6 @@ These cloud storage features are supported out of the box when using Puter.js:
 - **[`puter.fs.listSharedByMe()`](/FS/listSharedByMe/)** - List everything you have shared out
 - **[`puter.fs.getShares()`](/FS/getShares/)** - List who has access to an item
 - **[`puter.fs.getShareLink()`](/FS/getShareLink/)** - Build a link that opens a file in an app
- **[`puter.fs.space()`](/FS/space/)** - Get the user's storage capacity and usage

 ## Examples

@@ -30,25 +30,19 @@ Relative paths resolve against the app's root directory. A relative name that lo

 The options for the `copy` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `source` | `String` | Path to the file or directory to copy. Required when passing options as the only argument. |
-| `destination` | `String` | Path to the destination. Required when passing options as the only argument. |
-| `overwrite` | `Boolean` | Whether to overwrite the destination file or directory if it already exists. Defaults to `false`. |
-| `newName` | `String` | The new name to use for the copied file or directory. Defaults to `undefined`. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the file or directory name if it already exists. Defaults to `false`. |
+- `source` (String) - Path to the file or directory to copy. Required when passing options as the only argument.
+- `destination` (String) - Path to the destination. Required when passing options as the only argument.
+- `overwrite` (Boolean) - Whether to overwrite the destination file or directory if it already exists. Defaults to `false`.
+- `dedupeName` (Boolean) - Whether to deduplicate the file or directory name if it already exists. Defaults to `false`.
+- `newName` (String) - The new name to use for the copied file or directory. Defaults to `undefined`.

 ## Return value

-A `Promise` that will resolve to the [`FSItem`](/Objects/fsitem) object of the copied file or directory.
-
-## Errors
-
-If the source file or directory does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to the [`FSItem`](/Objects/fsitem) object of the copied file or directory. If the source file or directory does not exist, the promise will be rejected with an error.

 ## Examples

-### Copy a file
+<strong class="example-title"> Copy a file</strong>

 ```html;fs-copy
 <html>
@@ -25,11 +25,9 @@ If a path is not absolute, it will be resolved relative to the app's root direct

 The options for the `delete` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `paths` | `String \| String[]` | A single path or array of paths to delete. Required when passing options as the only argument. |
-| `recursive` | `Boolean` | Whether to delete the directory recursively. Defaults to `true`. |
-| `descendantsOnly` | `Boolean` | Whether to delete only the descendants of the directory and not the directory itself. Defaults to `false`. |
+- `paths` (String | String[]) - A single path or array of paths to delete. Required when passing options as the only argument.
+- `recursive` (Boolean) - Whether to delete the directory recursively. Defaults to `true`.
+- `descendantsOnly` (Boolean) - Whether to delete only the descendants of the directory and not the directory itself. Defaults to `false`.

 ## Return value

@@ -41,7 +39,7 @@ as deleting it here, and restoring it does not bring the shares back.

 ## Examples

-### Delete a file
+<strong class="example-title">Delete a file</strong>

 ```html;fs-delete
 <html>
@@ -63,7 +61,7 @@ as deleting it here, and restoring it does not bring the shares back.
 </html>
 ```

-### Delete a directory
+<strong class="example-title">Delete a directory</strong>

 ```html;fs-delete-directory
 <html>
@@ -4,9 +4,7 @@ description: Generate a temporary URL that lets anyone read one file from the us
 platforms: [websites, apps, nodejs, workers]
 ---

-Generates a URL that can be used to read a file.
-
-To stop it from working before it expires, revoke it with [`revokeReadURL()`](/FS/revokeReadURL/).
+Generates a URL that can be used to read a file. To stop it from working before it expires, revoke it with [`revokeReadURL()`](/FS/revokeReadURL/).

 ## Syntax

@@ -29,9 +27,7 @@ How long the URL stays valid, in [jsonwebtoken](https://github.com/auth0/node-js

 A promise that resolves to a URL string that can be used to read the file.

-## Examples
-
-### Get a read URL for a file
+## Example

 ```javascript
 const url = await puter.fs.getReadURL("~/myfile.txt");
@@ -4,9 +4,7 @@ description: Build a link that opens a file in an app on Puter, for the people t
 platforms: [websites, apps, nodejs, workers]
 ---

-Builds a link that opens a file in an app on Puter.
-
-The link has the form `https://puter.com/app/<appName>?file=<uid>`. Send it to whoever the file is shared with. Following it signs them in if needed. Puter then asks them to allow the app to open the file, and opens the app with the file.
+Builds the link that opens a file in an app on Puter, of the form `https://puter.com/app/<appName>?file=<uid>`. Send it to whoever the file is shared with: following it signs them in if needed, then opens the app with the file — after Puter has asked them to allow the app to open it.

 The link carries no access of its own. It works for the file's owner, for anyone the file was shared with through [`share()`](/FS/share/), and for any signed-in account once the file is open to **anyone with the link**. For everyone else the file is not found, and the app opens without it.

@@ -32,11 +30,9 @@ The name of the app the link opens the file with. Defaults to the app the code i

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | The file. Required when passing options as the only argument, unless `uid` is given. |
-| `appName` | `String` | The name of the app the link opens the file with. Same as the `appName` argument. |
-| `uid` | `String` | The file, by UID. Can be used instead of `path`. |
+- `path` (String) - The file. Required when passing options as the only argument, unless `uid` is given.
+- `uid` (String) - The file, by UID. Can be used instead of `path`.
+- `appName` (String) - As above.

 ## Return value

@@ -56,14 +52,9 @@ A file that does not exist, or that you cannot see, rejects the way [`stat()`](/

 The app opens on the recipient's Puter, and before it is handed the file Puter shows them what is being asked — which app, which file — and lets them refuse. Refused, the app still opens, just without the file. The app receives the access the recipient has: a file shared read-only opens read-only.

-## Related
-
- [`puter.fs.share()`](/FS/share/) - Grant access, or open the file to anyone with the link
- [`puter.fs.getReadURL()`](/FS/getReadURL/) - A URL that reads the file's bytes without signing in
-
 ## Examples

-### Open a shared file in an app
+<strong class="example-title">Open a shared file in an app</strong>

 ```html;fs-getShareLink
 <html>
@@ -83,10 +74,15 @@ The app opens on the recipient's Puter, and before it is handed the file Puter s
 </html>
 ```

-### Send a collaborator straight into your app
+<strong class="example-title">Send a collaborator straight into your app</strong>

 ```js
 // Inside a Puter app, the link opens the file in this app.
 await puter.fs.share('draft.md', 'friend@example.com', 'write');
 const link = await puter.fs.getShareLink('draft.md');
 ```
+
+## Related
+
+- [`puter.fs.share()`](/FS/share/) - Grant access, or open the file to anyone with the link
+- [`puter.fs.getReadURL()`](/FS/getReadURL/) - A URL that reads the file's bytes without signing in
@@ -35,10 +35,8 @@ The path to the file or directory. If `path` is not absolute, it will be resolve

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | The item. Required when passing options as the only argument. |
-| `uid` | `String` | The item, by UID. Can be used instead of `path`. |
+- `path` (String) - The item. Required when passing options as the only argument.
+- `uid` (String) - The item, by UID. Can be used instead of `path`.

 ## Return value

@@ -58,18 +56,11 @@ It also includes **invitations** — shares aimed at an email address with no co

 `recipientEmail` is set only for the item's **owner** and for whoever **sent** that invitation; for anyone else the invitation is listed without it. Someone else's invitation is not yours to cancel either, so nothing is lost with the address. An app never sees it, whoever it acts for.

-## Errors
-
 If you cannot see the item at all, this rejects the same way a missing file would — it will not confirm that the item exists.

-## Related
-
- [`puter.fs.share()`](/FS/share/) - Grant access
- [`puter.fs.unshare()`](/FS/unshare/) - Withdraw access
-
 ## Examples

-### See who can reach a file
+<strong class="example-title">See who can reach a file</strong>

 ```html;fs-getShares
 <html>
@@ -90,7 +81,7 @@ If you cannot see the item at all, this rejects the same way a missing file woul
 </html>
 ```

-### Withdraw everyone's access
+<strong class="example-title">Withdraw everyone's access</strong>

 ```js
 const shares = await puter.fs.getShares('report.txt');
@@ -98,3 +89,8 @@ for (const share of shares) {
    await puter.fs.unshare('report.txt', share.holder);
 }
 ```
+
+## Related
+
+- [`puter.fs.share()`](/FS/share/) - Grant access
+- [`puter.fs.unshare()`](/FS/unshare/) - Withdraw access
@@ -29,11 +29,9 @@ puter.fs.listShared(options)

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum shares per page. |
-| `cursor` | `String` | Continuation token from a previous page. |
-| `includeTotal` | `Boolean` | Include the total count in the response. Defaults to `false`. |
+- `limit` (Number) - Maximum shares per page.
+- `cursor` (String) - Continuation token from a previous page.
+- `includeTotal` (Boolean) - Include the total count in the response. Defaults to `false`.

 ## Return value

@@ -47,14 +45,9 @@ Iterate until `cursor` is absent rather than comparing `items.length` to `limit`

 Items shared with you appear at a **masked path**, `/<owner>/<uid>/<name>`, where `<uid>` stands in for wherever the owner keeps the item. Pass that path back to any `puter.fs` method and it resolves normally; what it does not tell you is the folder the item lives in, or what sits beside it. Your own items are never listed here.

-## Related
-
- [`puter.fs.share()`](/FS/share/) - Grant access
- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach an item you manage
-
 ## Examples

-### List everything shared with you
+<strong class="example-title">List everything shared with you</strong>

 ```html;fs-listShared
 <html>
@@ -73,7 +66,7 @@ Items shared with you appear at a **masked path**, `/<owner>/<uid>/<name>`, wher
 </html>
 ```

-### Page through every share
+<strong class="example-title">Page through every share</strong>

 ```js
 let cursor;
@@ -85,7 +78,7 @@ do {
 } while (cursor);
 ```

-### Open a file someone shared with you
+<strong class="example-title">Open a file someone shared with you</strong>

 ```js
 const page = await puter.fs.listShared();
@@ -95,3 +88,8 @@ if (shared) {
    puter.print(await blob.text());
 }
 ```
+
+## Related
+
+- [`puter.fs.share()`](/FS/share/) - Grant access
+- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach an item you manage
@@ -4,9 +4,7 @@ description: List everything you have shared with other users, across all items.
 platforms: [websites, apps, nodejs, workers]
 ---

-This method lists everything you have shared out, a page at a time, without naming an item first.
-
-To list the shares on one item you already know, use [`getShares()`](/FS/getShares/). This method lists them when you don't know the item. The listing includes invites to addresses that have no account yet (marked `pending`), items you opened to anyone with the link (marked `anyone`), and, for items you own, shares that a delegate with `manage` access issued on your behalf.
+This method lists everything you have shared out, a page at a time, without naming an item first. [`getShares()`](/FS/getShares/) answers the same question for one item you can already point at; this is what answers it when you can't. The listing includes invites to addresses that have no account yet (marked `pending`), items you opened to anyone with the link (marked `anyone`), and — for items you own — shares that a delegate with `manage` access issued on your behalf.

 > **What an app sees.** An app never gets more reach than it was given: this
 > listing shows an app only the shares on items it can reach in its own right.
@@ -26,12 +24,10 @@ puter.fs.listSharedByMe(options)

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum shares per page. |
-| `cursor` | `String` | Continuation token from a previous page. |
-| `includeTotal` | `Boolean` | Include the total count in the response. Defaults to `false`. |
-| `appUid` | `String` | Narrow the listing to the shares one app issued in your name, or pass `'none'` for the ones you made yourself. An app calling this is bound to its own grants whatever it asks for. |
+- `limit` (Number) - Maximum shares per page.
+- `cursor` (String) - Continuation token from a previous page.
+- `includeTotal` (Boolean) - Include the total count in the response. Defaults to `false`.
+- `appUid` (String) - Narrow the listing to the shares one app issued in your name, or pass `'none'` for the ones you made yourself. An app calling this is bound to its own grants whatever it asks for.

 ## Return value

@@ -45,15 +41,9 @@ Iterate until `cursor` is absent rather than comparing `items.length` to `limit`

 Items you own appear at their real path. An item you shared as a delegate (from someone else's folder you hold `manage` on) appears at the same masked path you reach it by.

-## Related
-
- [`puter.fs.share()`](/FS/share/) - Grant access
- [`puter.fs.listShared()`](/FS/listShared/) - List what others shared with you
- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach one item you manage
-
 ## Examples

-### See everything you have shared
+<strong class="example-title">See everything you have shared</strong>

 ```html
 <html>
@@ -75,7 +65,7 @@ Items you own appear at their real path. An item you shared as a delegate (from
 </html>
 ```

-### Page through every share you made
+<strong class="example-title">Page through every share you made</strong>

 ```js
 let cursor;
@@ -87,7 +77,7 @@ do {
 } while (cursor);
 ```

-### Withdraw everything shared on one item
+<strong class="example-title">Withdraw everything shared on one item</strong>

 ```js
 const page = await puter.fs.listSharedByMe();
@@ -96,3 +86,9 @@ if (target && !target.pending) {
    await puter.fs.unshare(target.path, target.holder);
 }
 ```
+
+## Related
+
+- [`puter.fs.share()`](/FS/share/) - Grant access
+- [`puter.fs.listShared()`](/FS/listShared/) - List what others shared with you
+- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach one item you manage
@@ -25,12 +25,10 @@ If path is not absolute, it will be resolved relative to the app's root director

 The options for the `mkdir` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | The directory path to be created if not specified via function parameter. |
-| `createMissingParents` | `Boolean` | Whether to create missing parent directories. Defaults to `false`. |
-| `overwrite` | `Boolean` | Whether to overwrite the directory if it already exists. Defaults to `false`. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the directory name if it already exists. Defaults to `false`. |
+- `path` (String) The directory path to be created if not specified via function parameter.
+- `overwrite` (Boolean) - Whether to overwrite the directory if it already exists. Defaults to `false`.
+- `dedupeName` (Boolean) - Whether to deduplicate the directory name if it already exists. Defaults to `false`.
+- `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.

 ## Return value

@@ -38,7 +36,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t

 ## Examples

-### Create a new directory
+<strong class="example-title">Create a new directory</strong>

 ```html;fs-mkdir
 <html>
@@ -57,7 +55,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t
 </html>
 ```

-### Create a directory with duplicate name handling
+<strong class="example-title">Create a directory with duplicate name handling</strong>

 ```html;fs-mkdir-dedupe
 <html>
@@ -77,7 +75,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t
 </html>
 ```

-### Create a new directory with missing parent directories
+<strong class="example-title">Create a new directory with missing parent directories</strong>

 ```html;fs-mkdir-create-missing-parents
 <html>
@@ -32,26 +32,20 @@ Without `newName`, the destination is looked up first to tell the two cases apar

 The options for the `move` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `source` | `String` | Path to the file or directory to move. Required when passing options as the only argument. |
-| `destination` | `String` | Path to the destination. Required when passing options as the only argument. |
-| `overwrite` | `Boolean` | Whether to overwrite the destination file or directory if it already exists. Defaults to `false`. |
-| `newName` | `String` | The name to give the moved file or directory. When set, `destination` is always treated as the directory to move into. Defaults to the source's own name. |
-| `createMissingParents` | `Boolean` | Whether to create missing parent directories. Defaults to `false`. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the file or directory name if it already exists. Defaults to `false`. |
+- `source` (String) - Path to the file or directory to move. Required when passing options as the only argument.
+- `destination` (String) - Path to the destination. Required when passing options as the only argument.
+- `overwrite` (Boolean) - Whether to overwrite the destination file or directory if it already exists. Defaults to `false`.
+- `dedupeName` (Boolean) - Whether to deduplicate the file or directory name if it already exists. Defaults to `false`.
+- `newName` (String) - The name to give the moved file or directory. When set, `destination` is always treated as the directory to move into. Defaults to the source's own name.
+- `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.

 ## Return value

-A `Promise` that will resolve to the [`FSItem`](/Objects/fsitem) object of the moved file or directory.
-
-## Errors
-
-If the source file or directory does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to the [`FSItem`](/Objects/fsitem) object of the moved file or directory. If the source file or directory does not exist, the promise will be rejected with an error.

 ## Examples

-### Move a file
+<strong class="example-title">Move a file</strong>

 ```html;fs-move
 <html>
@@ -82,7 +76,7 @@ If the source file or directory does not exist, the promise will be rejected wit
 </html>
 ```

-### Move a file and create missing parent directories
+<strong class="example-title">Move a file and create missing parent directories</strong>

 ```html;fs-move-create-missing-parents
 <html>
@@ -25,11 +25,11 @@ If `path` is not absolute, it will be resolved relative to the app's root direct

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | Path to the file to read. Required when passing options as the only argument. |
-| `offset` | `Number` | The offset to start reading from. |
-| `byte_count` | `Number` | The number of bytes to read from the offset. When omitted with `offset`, reads through the end of the file. |
+- `path` (String) - Path to the file to read. Required when passing options as the only argument.
+- `offset` (Number) (optional)
+The offset to start reading from.
+- `byte_count` (Number) (optional)
+The number of bytes to read from the offset. When omitted with `offset`, reads through the end of the file.

 ## Return value

@@ -37,7 +37,7 @@ A `Promise` that will resolve to a `Blob` object containing the contents of the

 ## Examples

-### Read a file
+<strong class="example-title">Read a file</strong>

 ```html;fs-read
 <html>
@@ -4,9 +4,7 @@ description: List files and directories in the user's own Puter file system.
 platforms: [websites, apps, nodejs, workers]
 ---

-Reads the contents of a directory, returning an array of items (files and directories) within it.
-
-This method is useful for listing all items in a specified directory in the Puter cloud storage.
+Reads the contents of a directory, returning an array of items (files and directories) within it. This method is useful for listing all items in a specified directory in the Puter cloud storage.

 ## Syntax

@@ -27,19 +25,17 @@ If `path` is not absolute, it will be resolved relative to the app's root direct

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | The path to the directory to read. Required when passing options as the only argument. |
-| `recursive` | `Boolean` | If `true`, the contents of subdirectories are listed too. Defaults to `false`. |
-| `depth` | `Number` | How many levels to descend when `recursive` is `true`. Defaults to `10`, which is also the maximum. |
-| `sortBy` | `String` | Sort field. One of `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` | Either `asc` or `desc`. Default is `asc`. |
-| `limit` | `Number` | Maximum number of entries to return. |
-| `cursor` | `String \| null` | Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. The cursor pins the sort, so later pages must not request a different `sortBy` or `sortOrder`. |
-| `offset` | `Number` | 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`. |
-| `includeTotal` | `Boolean` | If `true`, the paginated result includes a `total` count of all entries in the directory. |
-| `stream` | `Boolean` | If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`. |
-| `uid` | `String` | The UID of the directory to read. |
+- `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. 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`.
+- `depth` (Number) (optional) - How many levels to descend when `recursive` is `true`. Defaults to `10`, which is also the maximum.
+- `cursor` (String | null) (optional) - Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. The cursor pins the sort, so later pages must not request a different `sortBy`/`sortOrder`.
+- `includeTotal` (Boolean) (optional) - If `true`, the paginated result includes a `total` count of all entries in the directory.
+- `stream` (Boolean) (optional) - If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.

 ## Return value

@@ -67,7 +63,7 @@ for await (const page of puter.fs.readdir({ path: './large-dir', stream: true })

 ## Examples

-### Read a directory
+<strong class="example-title">Read a directory</strong>

 ```html;fs-readdir
 <html>
@@ -4,9 +4,7 @@ description: Rename files or directories in the user's own Puter file system.
 platforms: [websites, apps, nodejs, workers]
 ---

-Renames a file or directory to a new name.
-
-This method allows you to change the name of a file or directory in the Puter cloud storage.
+Renames a file or directory to a new name. This method allows you to change the name of a file or directory in the Puter cloud storage.

 ## Syntax

@@ -30,11 +28,9 @@ The new name of the file or directory.

 The options for the `rename` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | Path to the file or directory to rename. Required when passing options as the only argument. |
-| `newName` | `String` | The new name for the file or directory. Required when passing options as the only argument. |
-| `uid` | `String` | The UID of the file or directory to rename. Can be used instead of `path`. |
+- `path` (String) - Path to the file or directory to rename. Required when passing options as the only argument.
+- `uid` (String) - The UID of the file or directory to rename. Can be used instead of `path`.
+- `newName` (String) - The new name for the file or directory. Required when passing options as the only argument.

 ## Return value

@@ -42,7 +38,7 @@ Returns a promise that resolves to the [`FSItem`](/Objects/fsitem) object of the

 ## Examples

-### Rename a file
+<strong class="example-title">Rename a file</strong>

 ```html;fs-rename
 <html>
@@ -4,9 +4,7 @@ description: Revoke a URL created by getReadURL(), so it stops serving the file.
 platforms: [websites, apps, nodejs, workers]
 ---

-Revokes a URL created by [`getReadURL()`](/FS/getReadURL/), so it immediately stops serving the file.
-
-An app can revoke only URLs it created. The account itself, through its own session or API token, can revoke any of its read URLs. Revoking a URL that is already revoked or has expired resolves without error.
+Revokes a URL created by [`getReadURL()`](/FS/getReadURL/), so it immediately stops serving the file. An app can revoke only URLs it created; the account itself, through its own session or API token, can revoke any of its read URLs. Revoking a URL that is already revoked or has expired resolves without error.

 ## Syntax

@@ -39,9 +37,9 @@ A rejection carries an `Error` with a stable `code`:
 | `not_found` | The URL was created by a different app, or belongs to another account. |
 | `too_many_requests` | The rate limit was exceeded. See [Rate Limits & Quotas](/rate-limits-and-quotas/). |

-## Examples
+## Example

-### Revoke a read URL
+<strong class="example-title">Revoke a read URL</strong>

 ```html
 <html>
@@ -54,13 +54,11 @@ How much access to grant. Defaults to `'read'`.

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | Item to share. Required when passing options as the only argument. |
-| `recipient` | `String \| Object \| Array` | Who to share with. |
-| `mode` | `String` | Access to grant. Defaults to `'read'`. |
-| `paths` | `Array` | Several items to share in one call. |
-| `uid` | `String` | Item to share, by UID. Can be used instead of `path`. |
+- `path` (String) - Item to share. Required when passing options as the only argument.
+- `uid` (String) - Item to share, by UID. Can be used instead of `path`.
+- `paths` (Array) - Several items to share in one call.
+- `recipient` (String | Object | Array) - Who to share with.
+- `mode` (String) - Access to grant. Defaults to `'read'`.

 ## Return value

@@ -146,6 +144,48 @@ if ( share.pending ) {
 }
 ```

+## Examples
+
+<strong class="example-title">Share a file with another user</strong>
+
+```html;fs-share
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            // (1) create a file
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+
+            // (2) share it, read-only
+            const shares = await puter.fs.share('report.txt', 'friend@example.com');
+            puter.print(`Shared with ${shares[0].holder} as ${shares[0].mode}<br>`);
+        })()
+    </script>
+</body>
+</html>
+```
+
+<strong class="example-title">Let someone edit, and let someone else re-share</strong>
+
+```js
+// An editor can change the file but cannot pass it on.
+await puter.fs.share('report.txt', 'editor@example.com', 'write');
+
+// A manager can edit it AND share it with other people.
+await puter.fs.share('report.txt', 'manager@example.com', 'manage');
+```
+
+<strong class="example-title">Share one item with several people</strong>
+
+```js
+await puter.fs.share({
+    path: 'report.txt',
+    recipient: ['a@example.com', 'b@example.com'],
+    mode: 'read',
+});
+```
+
 ## Live updates

 Changes inside a shared item are not pushed to recipients in real time —
@@ -196,45 +236,3 @@ Trash does not bring them back; share it again.
 - [`puter.fs.unshare()`](/FS/unshare/) - Withdraw access
 - [`puter.fs.getShares()`](/FS/getShares/) - See who can reach an item
 - [`puter.fs.listShared()`](/FS/listShared/) - See what others have shared with you
-
-## Examples
-
-### Share a file with another user
-
-```html;fs-share
-<html>
-<body>
-    <script src="https://js.puter.com/v2/"></script>
-    <script>
-        (async () => {
-            // (1) create a file
-            await puter.fs.write('report.txt', 'Quarterly numbers');
-
-            // (2) share it, read-only
-            const shares = await puter.fs.share('report.txt', 'friend@example.com');
-            puter.print(`Shared with ${shares[0].holder} as ${shares[0].mode}<br>`);
-        })()
-    </script>
-</body>
-</html>
-```
-
-### Let someone edit, and let someone else re-share
-
-```js
-// An editor can change the file but cannot pass it on.
-await puter.fs.share('report.txt', 'editor@example.com', 'write');
-
-// A manager can edit it AND share it with other people.
-await puter.fs.share('report.txt', 'manager@example.com', 'manage');
-```
-
-### Share one item with several people
-
-```js
-await puter.fs.share({
-    path: 'report.txt',
-    recipient: ['a@example.com', 'b@example.com'],
-    mode: 'read',
-});
-```
@@ -25,7 +25,7 @@ A `Promise` that resolves to a [`SpaceInfo`](/Objects/spaceinfo/) object with th

 ## Examples

-### Show how much storage the user has used
+<strong class="example-title">Show how much storage the user has used</strong>

 ```html
 <html>
@@ -24,16 +24,14 @@ If `path` is not absolute, it will be resolved relative to the app's root direct

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | Path to the file or directory. Required when passing options as the only argument. |
-| `returnSize` | `Boolean` | Whether to return size information. Defaults to `false`. |
-| `returnShares` | `Boolean` | Whether to include who the item is shared with, as a `shares` array on the result. Defaults to `false`. |
-| `returnSubdomains` | `Boolean` | Whether to return subdomain information. Defaults to `false`. |
-| `returnWorkers` | `Boolean` | Whether to return the workers attached to the item. Workers are served alongside subdomains, so this is an alias of `returnSubdomains`. Setting either one returns both. Defaults to `false`. |
-| `returnPermissions` | `Boolean` | Whether to return permission information. Defaults to `false`. |
-| `returnVersions` | `Boolean` | Whether to return version information. Defaults to `false`. |
-| `uid` | `String` | The UID of the file or directory. Can be used instead of `path`. |
+- `path` (String) - Path to the file or directory. Required when passing options as the only argument.
+- `uid` (String) - The UID of the file or directory. Can be used instead of `path`.
+- `returnSubdomains` (Boolean) - Whether to return subdomain information. Defaults to `false`.
+- `returnWorkers` (Boolean) - Whether to return the workers attached to the item. Workers are served alongside subdomains, so this is an alias of `returnSubdomains` — setting either one returns both. Defaults to `false`.
+- `returnPermissions` (Boolean) - Whether to return permission information. Defaults to `false`.
+- `returnVersions` (Boolean) - Whether to return version information. Defaults to `false`.
+- `returnSize` (Boolean) - Whether to return size information. Defaults to `false`.
+- `returnShares` (Boolean) - Whether to include who the item is shared with, as a `shares` array on the result. Defaults to `false`.

 ## Return value

@@ -43,14 +41,9 @@ The item carries `is_shared`: `true` when it has been shared with someone, `fals

 With `returnShares: true`, the result also carries `shares` — an array of the same share objects [`getShares()`](/FS/getShares/) returns, including access inherited from a parent folder and unclaimed invitations. It is empty unless you own the item or hold `manage` on it, so asking for it never fails a `stat()` you were otherwise allowed to make. An app or API token sees only the shares it issued itself, and an invitation's `recipientEmail` is withheld from everyone but the owner and its sender — see [`getShares()`](/FS/getShares/). Because it does `getShares()`'s work, it also spends from the [share-read limit](/rate-limits-and-quotas/#sharing) on top of `stat()`'s own.

-## Related
-
- [`puter.fs.getShares()`](/FS/getShares/) - List who can reach an item
- [`puter.fs.share()`](/FS/share/) - Grant access
-
 ## Examples

-### Get information about a file
+<strong class="example-title">Get information about a file</strong>

 ```html;fs-stat
 <html>
@@ -74,7 +67,7 @@ With `returnShares: true`, the result also carries `shares` — an array of the
 </html>
 ```

-### See whether a file is shared, and with whom
+<strong class="example-title">See whether a file is shared, and with whom</strong>

 ```html;fs-stat-shares
 <html>
@@ -95,3 +88,8 @@ With `returnShares: true`, the result also carries `shares` — an array of the
 </body>
 </html>
 ```
+
+## Related
+
+- [`puter.fs.getShares()`](/FS/getShares/) - List who can reach an item
+- [`puter.fs.share()`](/FS/share/) - Grant access
@@ -39,11 +39,9 @@ Pass **yourself** to leave a share someone else gave you. Pass `{ team: uid }` t

 An object with the following properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `path` | `String` | The item. Required when passing options as the only argument. |
-| `recipient` | `String \| Object` | Whose access to withdraw. |
-| `uid` | `String` | The item, by UID. Can be used instead of `path`. |
+- `path` (String) - The item. Required when passing options as the only argument.
+- `uid` (String) - The item, by UID. Can be used instead of `path`.
+- `recipient` (String | Object) - Whose access to withdraw.

 ## Return value

@@ -70,14 +68,9 @@ Withdrawing someone's access also withdraws whatever **they** re-shared of that

 Passing an email address that was **invited** but has not yet joined cancels the invitation. Nothing was granted, so nothing is revoked from anyone — the pending share simply stops waiting.

-## Related
-
- [`puter.fs.share()`](/FS/share/) - Grant access
- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach an item
-
 ## Examples

-### Stop sharing a file
+<strong class="example-title">Stop sharing a file</strong>

 ```html;fs-unshare
 <html>
@@ -96,9 +89,14 @@ Passing an email address that was **invited** but has not yet joined cancels the
 </html>
 ```

-### Leave a share someone gave you
+<strong class="example-title">Leave a share someone gave you</strong>

 ```js
 const me = await puter.auth.getUser();
 await puter.fs.unshare('/alice/report.txt', me.username);
 ```
+
+## Related
+
+- [`puter.fs.share()`](/FS/share/) - Grant access
+- [`puter.fs.getShares()`](/FS/getShares/) - See who can reach an item
@@ -28,20 +28,19 @@ The path of the directory to upload the items to. If not set, the items will be

 A set of key/value pairs that configure the upload process. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `overwrite` | `Boolean` | Whether to overwrite the destination file if it already exists. Defaults to `false`. |
-| `progress` | `Function` | Called with `(operationId, progress)` as bytes are sent, where `progress` is a percentage between `0` and `100`. |
-| `createMissingParents` | `Boolean` | Whether to create missing parent directories. Defaults to `false`. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the file name if it already exists. Defaults to `true`. Ignored when `overwrite` is `true`. |
-| `generateThumbnails` | `Boolean` | Generate image thumbnails in the browser before uploading. Defaults to `false`. Unsupported files and generation failures are skipped. |
-| `thumbnail` | `String` | Optional thumbnail data URL or URL to use when a file has no generated thumbnail. Data URLs exceeding 2 MiB are discarded. |
-| `thumbnailGenerator` | `Function` | Optional `(file, context) => string \| undefined` callback (which may also return a promise), called once per file instead of the built-in image generator. Return a thumbnail data URL or URL, or `undefined` to skip. Exceptions are ignored. Call `context.defaultGenerator(file)` to use the built-in image generator. The `context.signal` property is an `AbortSignal` for upload preparation cancellation. Existing one-argument callbacks continue to work. A custom generator enables thumbnail preparation even when `generateThumbnails` is omitted. |
-| `init` | `Function` | Called with `(operationId, xhr)` once the request has been created, before it is sent. The `XMLHttpRequest` is passed so you can abort the upload yourself. |
-| `start` | `Function` | Called with no arguments when the upload starts sending. |
-| `abort` | `Function` | Called with `(operationId)` if the upload is aborted. |
+- `overwrite` (Boolean) - Whether to overwrite the destination file if it already exists. Defaults to `false`.
+- `dedupeName` (Boolean) - Whether to deduplicate the file name if it already exists. Defaults to `true`. Ignored when `overwrite` is `true`.
+- `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
+- `generateThumbnails` (Boolean) - Generate image thumbnails in the browser before uploading. Defaults to `false`. Unsupported files and generation failures are skipped.
+- `thumbnailGenerator` (Function) - Optional `(file, context) => string | undefined` callback (which may also return a promise), called once per file instead of the built-in image generator. Return a thumbnail data URL or URL, or `undefined` to skip. Exceptions are ignored. `context.defaultGenerator(file)` delegates to the built-in image generator; `context.signal` is an `AbortSignal` for upload preparation cancellation. Existing one-argument callbacks continue to work. A custom generator enables thumbnail preparation even when `generateThumbnails` is omitted.
+- `thumbnail` (String) - Optional thumbnail data URL or URL to use when a file has no generated thumbnail. Data URLs exceeding 2 MiB are discarded.

-The `init`, `start`, `progress`, and `abort` callbacks report on the upload as it runs. Their `operationId` argument identifies the upload, so a page running several uploads at once can tell them apart.
+The following callbacks report on the upload as it runs. `operationId` identifies the upload, so a page running several uploads at once can tell them apart:
+
+- `init` (Function) - Called with `(operationId, xhr)` once the request has been created, before it is sent. The `XMLHttpRequest` is passed so you can abort the upload yourself.
+- `start` (Function) - Called with no arguments when the upload starts sending.
+- `progress` (Function) - Called with `(operationId, progress)` as bytes are sent, where `progress` is a percentage between `0` and `100`.
+- `abort` (Function) - Called with `(operationId)` if the upload is aborted.

 Cancelling through the `init` request handle during thumbnail preparation rejects with `{ code: 'upload_aborted', message: 'Upload aborted.' }` and prevents the upload from starting. Custom generators should stop their work when `context.signal` aborts and impose their own time and resource budgets; the SDK awaits thumbnail preparation before sending files.

@@ -60,8 +59,6 @@ Returns a `Promise` that resolves to:
 - A single [`FSItem`](/Objects/fsitem/) object if `items` parameter contains one item
 - An array of [`FSItem`](/Objects/fsitem/) objects if `items` parameter contains multiple items

-## Errors
-
 If any part of the upload fails, the promise is rejected — it never resolves to a mix of items and errors. The rejection value always carries a `message`, and a `failedItems` array when individual items failed rather than the request as a whole. Each entry in `failedItems` carries the `path`, `message`, and — when the server gave one — the `code` and `status` for that item. A partially failed upload is not rolled back: the items that were written stay written.

 When every failed item failed the same way, that `code` and `status` are also set on the rejection value itself, because the cause belongs to the request rather than to any one file. An upload that exceeds the account's storage quota is the common case: it rejects with `code: 'storage_limit_reached'` and `status: 413` however many files were in it.
@@ -88,7 +85,7 @@ When using signed uploads, a separate thumbnail transfer that fails or exceeds f

 ## Examples

-### Upload a file from a file input
+<strong class="example-title">Upload a file from a file input</strong>

 ```html;fs-upload
 <html>
@@ -4,9 +4,7 @@ description: Write data to files in the user's own Puter file system.
 platforms: [websites, apps, nodejs, workers]
 ---

-Writes data to a specified file path.
-
-This method is useful for creating new files or modifying existing ones in the Puter cloud storage.
+Writes data to a specified file path. This method is useful for creating new files or modifying existing ones in the Puter cloud storage.

 ## Syntax

@@ -32,11 +30,9 @@ The data to write to the file. If omitted, an empty file is created.

 The options for the `write` operation. The following options are supported:

-| Option | Type | Description |
-|--------|------|-------------|
-| `createMissingParents` | `Boolean` | Whether to create missing parent directories. Defaults to `false`. |
-| `overwrite` | `Boolean` | Whether to overwrite the file if it already exists. Defaults to `true`. |
-| `dedupeName` | `Boolean` | Whether to deduplicate the file name if it already exists. Defaults to `false`. |
+- `overwrite` (boolean) - Whether to overwrite the file if it already exists. Defaults to `true`.
+- `dedupeName` (boolean) - Whether to deduplicate the file name if it already exists. Defaults to `false`.
+- `createMissingParents` (boolean) - Whether to create missing parent directories. Defaults to `false`.

 #### `file` (File)

@@ -48,7 +44,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t

 ## Examples

-### Create a new file containing "Hello, world!"
+<strong class="example-title">Create a new file containing "Hello, world!"</strong>

 ```html;fs-write
 <html>
@@ -64,7 +60,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t
 </html>
 ```

-### Create a new file with input coming from a file input
+<strong class="example-title">Create a new file with input coming from a file input</strong>

 ```html;fs-write-from-input
 <html>
@@ -85,7 +81,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t
 </html>
 ```

-### Create a file with duplicate name handling
+<strong class="example-title">Create a file with duplicate name handling</strong>

 ```html;fs-write-dedupe
 <html>
@@ -105,7 +101,7 @@ Returns a `Promise` that resolves to the [`FSItem`](/Objects/fsitem) object of t
 </html>
 ```

-### Create a new file with missing parent directories
+<strong class="example-title">Create a new file with missing parent directories</strong>

 ```html;fs-write-create-missing-parents
 <html>
@@ -188,9 +188,9 @@ These hosting features are supported out of the box when using Puter.js:

 - **[`puter.hosting.create()`](/Hosting/create/)** - Create a new hosting deployment
 - **[`puter.hosting.list()`](/Hosting/list/)** - List all hosting deployments
- **[`puter.hosting.get()`](/Hosting/get/)** - Get information about a specific deployment
- **[`puter.hosting.update()`](/Hosting/update/)** - Update hosting settings
 - **[`puter.hosting.delete()`](/Hosting/delete/)** - Delete a hosting deployment
+- **[`puter.hosting.update()`](/Hosting/update/)** - Update hosting settings
+- **[`puter.hosting.get()`](/Hosting/get/)** - Get information about a specific deployment
 - **[`puter.hosting.attach()`](/Hosting/attach/)** - Let the user connect their own domain to a website

 ## Examples
@@ -4,9 +4,7 @@ description: Let the user connect one of their own domains to a website hosted o
 platforms: [websites, apps]
 ---

-Opens a Puter dialog where the user connects a domain they own, such as `www.example.com`, to one of their websites.
-
-In the dialog, the user can pick a domain already on their account or add a new one. A domain the user picks that currently serves another of their websites moves to this one.
+Opens a Puter dialog where the user connects a domain they own, such as `www.example.com`, to one of their websites. In the dialog, the user can pick a domain already on their account or add a new one. A domain the user picks that currently serves another of their websites moves to this one.

 When the user adds a new domain, the dialog shows the DNS records to set at their DNS provider. The domain starts serving the website once those records are in place, usually within a few minutes.

@@ -34,8 +32,6 @@ A newly added domain resolves with `status` set to `pending`. Its `records` list

 On a website that is cross-origin isolated, the popup can't send its result back to your page, so the promise resolves `null` even if the user goes on to connect a domain in the popup.

-## Errors
-
 The promise rejects with an error whose `code` is one of the following:

 - `invalid_argument` when `subdomain` is missing or empty.
@@ -44,7 +40,7 @@ The promise rejects with an error whose `code` is one of the following:

 ## Examples

-### Connect a custom domain to a website
+<strong class="example-title">Connect a custom domain to a website</strong>

 ```html;hosting-attach
 <html>
@@ -4,9 +4,7 @@ description: Create and host a website from a directory on Puter.
 platforms: [websites, apps, nodejs, workers]
 ---

-Creates a new subdomain that will be served by the hosting service.
-
-You must specify a path to a directory that will be served by the subdomain.
+Will create a new subdomain that will be served by the hosting service. You must specify a path to a directory that will be served by the subdomain.

 ## Syntax

@@ -31,22 +29,16 @@ The directory must be one you own. Hosting serves everything under it publicly,

 Alternative way to create hosting via options.

-| Option | Type | Description |
-|--------|------|-------------|
-| `subdomain` | `String` | Name of the subdomain you want to create. |
-| `root_dir` | `String` | Required. Absolute path to the directory you want to serve. Unlike `dirPath`, this value is not resolved against the app's root directory, so it must be an absolute path. |
+- `subdomain` (String) - Name of the subdomain you want to create.
+- `root_dir` (String) (required) - Absolute path to the directory you want to serve. Unlike `dirPath`, this value is not resolved against the app's root directory, so it must be an absolute path.

 ## Return value

-A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been created.
-
-## Errors
-
-If a subdomain with the given name already exists, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been created. If a subdomain with the given name already exists, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error.

 ## Examples

-### Create a simple website displaying "Hello world!"
+<strong class="example-title">Create a simple website displaying "Hello world!"</strong>

 ```html;hosting-create
 <html>
@@ -4,9 +4,7 @@ description: Delete a subdomain from your account.
 platforms: [websites, apps, nodejs, workers]
 ---

-Deletes a subdomain from your account.
-
-The subdomain will no longer be served by the hosting service. If the subdomain has a directory, it will be disconnected from the subdomain. The associated directory will not be deleted.
+Deletes a subdomain from your account. The subdomain will no longer be served by the hosting service. If the subdomain has a directory, it will be disconnected from the subdomain. The associated directory will not be deleted.

 ## Syntax

@@ -22,15 +20,11 @@ A string containing the name of the subdomain you want to delete.

 ## Return value

-A `Promise` that will resolve to an object of the form `{ success: true, uid: <subdomain-uid> }` when the subdomain has been deleted.
-
-## Errors
-
-If a subdomain with the given name does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to an object of the form `{ success: true, uid: <subdomain-uid> }` when the subdomain has been deleted. If a subdomain with the given name does not exist, the promise will be rejected with an error.

 ## Examples

-### Create a random website then delete it
+<strong class="example-title">Create a random website then delete it</strong>

 ```html;hosting-delete
 <html>
@@ -4,9 +4,7 @@ description: Get information on a subdomain hosted on Puter.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns a subdomain.
-
-If the subdomain does not exist, the promise will be rejected with an error.
+Returns a subdomain. If the subdomain does not exist, the promise will be rejected with an error.

 ## Syntax

@@ -19,15 +17,11 @@ puter.hosting.get(subdomain)
 A string containing the name of the subdomain you want to retrieve.

 ## Return value
-A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been retrieved.
-
-## Errors
-
-If a subdomain with the given name does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been retrieved. If a subdomain with the given name does not exist, the promise will be rejected with an error.

 ## Examples

-### Get a subdomain
+<strong class="example-title">Get a subdomain</strong>

 ```html;hosting-get
 <html>
@@ -4,9 +4,7 @@ description: List all subdomains in your Puter account.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns an array of all subdomains in the user's subdomains that this app has access to.
-
-If the user has no subdomains, the array will be empty.
+Returns an array of all subdomains in the user's subdomains that this app has access to. If the user has no subdomains, the array will be empty.

 ## Syntax
 ```js
@@ -20,13 +18,11 @@ puter.hosting.list(options)

 An object with the following optional properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Maximum number of subdomains to return in a single call. |
-| `cursor` | `String \| null` | Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. |
-| `stream` | `Boolean` | If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`. |
-| `includeTotal` | `Boolean` | If `true`, the paginated result includes a `total` count. |
-| `offset` | `Number` | Skips the given number of subdomains. Prefer `cursor` for paging through large lists. |
+- `limit` (Number): Maximum number of subdomains to return in a single call.
+- `offset` (Number): Skips the given number of subdomains. Prefer `cursor` for paging through large lists.
+- `cursor` (String | null): Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one.
+- `includeTotal` (Boolean): If `true`, the paginated result includes a `total` count.
+- `stream` (Boolean): If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.

 ## Return value
 A `Promise` that will resolve to an array of all [`Subdomain`](/Objects/subdomain/) objects belonging to the user that this app has access to.
@@ -53,7 +49,7 @@ Worker-backed subdomains are never included in the results — pages and `total`

 ## Examples

-### Create 3 random websites and then list them
+<strong class="example-title">Create 3 random websites and then list them</strong>

 ```html;hosting-list
 <html>
@@ -24,15 +24,11 @@ A string containing the path to the directory you want to serve.

 ## Return value

-A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been updated.
-
-## Errors
-
-If a subdomain with the given name does not exist, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error.
+A `Promise` that will resolve to a [`Subdomain`](/Objects/subdomain/) object when the subdomain has been updated. If a subdomain with the given name does not exist, the promise will be rejected with an error. If the path does not exist, the promise will be rejected with an error.

 ## Examples

-### Update a subdomain to point to a new directory
+<strong class="example-title">Update a subdomain to point to a new directory</strong>

 ```html;hosting-update
 <html>
@@ -215,15 +215,15 @@ These Key-Value Store features are supported out of the box when using Puter.js:

 - **[`puter.kv.set()`](/KV/set/)** - Set a key-value pair
 - **[`puter.kv.get()`](/KV/get/)** - Get a value by key
- **[`puter.kv.del()`](/KV/del/)** - Delete a key-value pair
- **[`puter.kv.list()`](/KV/list/)** - List keys in ascending or descending order
 - **[`puter.kv.incr()`](/KV/incr/)** - Increment a numeric value
 - **[`puter.kv.decr()`](/KV/decr/)** - Decrement a numeric value
- **[`puter.kv.update()`](/KV/update/)** - Update values by path
 - **[`puter.kv.add()`](/KV/add/)** - Add values to an existing key
 - **[`puter.kv.remove()`](/KV/remove/)** - Remove values by path
+- **[`puter.kv.update()`](/KV/update/)** - Update values by path
+- **[`puter.kv.del()`](/KV/del/)** - Delete a key-value pair
 - **[`puter.kv.expire()`](/KV/expire/)** - Set key expiration in seconds
 - **[`puter.kv.expireAt()`](/KV/expireAt/)** - Set key expiration timestamp
+- **[`puter.kv.list()`](/KV/list/)** - List keys in ascending or descending order
 - **[`puter.kv.flush()`](/KV/flush/)** - Clear all data
 - **[`puter.kv.share()`](/KV/share/)** - Share the keys under a prefix with another user
 - **[`puter.kv.unshare()`](/KV/unshare/)** - Stop a share, as its owner or its holder
@@ -4,9 +4,7 @@ description: Returns the maximum key size (in bytes) for the key-value store.
 platforms: [websites, apps, nodejs, workers]
 ---

-The largest key the key-value store accepts, in bytes.
-
-It's `1024` (1 KB). A key is measured in UTF-8 bytes, so a key with non-ASCII characters fits fewer characters. Through a share's `handle`, a key can be at most 768 bytes.
+The largest key the key-value store accepts, in bytes. It's `1024` (1 KB). A key is measured in UTF-8 bytes, so a key with non-ASCII characters fits fewer characters. Through a share's `handle`, a key can be at most 768 bytes.

 ## Syntax

@@ -16,7 +14,7 @@ puter.kv.MAX_KEY_SIZE

 ## Examples

-### Get the max key size
+<strong class="example-title">Get the max key size</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Returns the maximum value size (in bytes) for the key-value store.
 platforms: [websites, apps, nodejs, workers]
 ---

-The largest value the key-value store accepts, in bytes.
-
-It's `408576` (399 KB). A value is measured as the UTF-8 bytes of `JSON.stringify(value)`, so a string's quotes and escapes count.
+The largest value the key-value store accepts, in bytes. It's `408576` (399 KB). A value is measured as the UTF-8 bytes of `JSON.stringify(value)`, so a string's quotes and escapes count.

 ## Syntax

@@ -16,7 +14,7 @@ puter.kv.MAX_VALUE_SIZE

 ## Examples

-### Get the max value size
+<strong class="example-title">Get the max value size</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Add values to an existing key or nested path in the user's own key-
 platforms: [websites, apps, nodejs, workers]
 ---

-Adds values to the list stored at a key.
-
-When you pass an array, its elements are appended to that list. When you pass an object, each of its keys is a path, and its value is added to the list at that path. A missing or expired key starts from an empty list, or for a path map, an object holding an empty list at each path.
+Adds values to the list stored at a key. When you pass an array, its elements are appended to that list. When you pass an object, each of its keys is a path, and its value is added to the list at that path. A missing or expired key starts from an empty list, or for a path map, an object holding an empty list at each path.

 ## Syntax

@@ -44,10 +42,8 @@ A plain object is read as a path map, never appended as an element. To append an

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 Pass `optConfig` after `value`, as in `puter.kv.add('tags', ['new'], { handle })`. An object in the place of `value` is read as a path map.

@@ -81,7 +77,7 @@ A rejection carries an `Error` with a stable `code`:

 ## Examples

-### Append to an array stored at a key
+<strong class="example-title">Append to an array stored at a key</strong>

 ```html;kv-add-array
 <html>
@@ -104,7 +100,7 @@ A rejection carries an `Error` with a stable `code`:
 </html>
 ```

-### Add values to an array inside an object
+<strong class="example-title">Add values to an array inside an object</strong>

 ```html;kv-add
 <html>
@@ -4,9 +4,7 @@ description: Decrement numeric values in the user's own key-value store by a spe
 platforms: [websites, apps, nodejs, workers]
 ---

-Decrements the value of a key.
-
-A missing or expired key starts from 0 and loses any TTL it had, and a live key keeps its TTL. The call rejects if the target holds anything other than a number, including a numeric string. The target is the whole value, or with a path map, the field at each path.
+Decrements the value of a key. A missing or expired key starts from 0 and loses any TTL it had, and a live key keeps its TTL. The call rejects if the target holds anything other than a number, including a numeric string. The target is the whole value, or with a path map, the field at each path.

 ## Syntax

@@ -39,10 +37,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 Pass `optConfig` after `amount`, as in `puter.kv.decr('stats', 1, { handle })`. An object in the place of `amount` is read as a path map.

@@ -76,7 +72,7 @@ A rejection carries an `Error` with a stable `code`:

 ## Examples

-### Decrement the value of a key
+<strong class="example-title">Decrement the value of a key</strong>

 ```html;kv-decr
 <html>
@@ -91,7 +87,7 @@ A rejection carries an `Error` with a stable `code`:
 </html>
 ```

-### Decrement a property within an object value
+<strong class="example-title">Decrement a property within an object value</strong>

 ```html;kv-decr-nested
 <html>
@@ -4,9 +4,7 @@ description: Remove keys from the user's own key-value store.
 platforms: [websites, apps, nodejs, workers]
 ---

-Removes a key from the user's key-value store.
-
-Deleting a key that doesn't exist does nothing and resolves the same way.
+Removes a key from the user's key-value store. Deleting a key that doesn't exist does nothing and resolves the same way.

 ## Syntax

@@ -27,10 +25,8 @@ The key to remove.

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Deletes from data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. A key the owner's app keeps private reads as missing through the share, so deleting it resolves to `true` and leaves it in place. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Deletes from another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Deletes from data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. A key the owner's app keeps private reads as missing through the share, so deleting it resolves to `true` and leaves it in place. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Deletes from another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -50,7 +46,7 @@ With `handle`, the promise can reject with these codes:

 ## Examples

-### Delete the key 'name'
+<strong class="example-title">Delete the key 'name'</strong>

 ```html;kv-del
 <html>
@@ -29,10 +29,8 @@ The number of seconds until the key is removed. A value of `0` or less expires t

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -58,7 +56,7 @@ To remove a key's TTL instead of setting one, use [`puter.kv.set()`](/KV/set/) o

 ## Examples

-### Retrieve the value of a key after a 1-second expiration
+<strong class="example-title">Retrieve the value of a key after a 1-second expiration</strong>

 ```html;kv-expire
 <html>
@@ -29,10 +29,8 @@ The Unix timestamp, in seconds, when the key is removed. Use seconds, not the mi

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -58,7 +56,7 @@ To remove a key's TTL instead of setting one, use [`puter.kv.set()`](/KV/set/) o

 ## Examples

-### Retrieve the value of a key after it expires
+<strong class="example-title">Retrieve the value of a key after it expires</strong>

 ```html;kv-expireAt
 <html>
@@ -4,9 +4,7 @@ description: Remove all key-value pairs from the user's own store for your app.
 platforms: [websites, apps, nodejs, workers]
 ---

-Removes every key-value pair from the user's key-value store for the current app.
-
-It's also available as `puter.kv.clear()`.
+Removes every key-value pair from the user's key-value store for the current app. It's also available as `puter.kv.clear()`.

 ## Syntax

@@ -33,8 +31,6 @@ Flushing works only on your app's own store. To clear a prefix someone shared wi

 ## Examples

-### Remove every key
-
 ```html;kv-flush
 <html>
 <body>
@@ -4,9 +4,7 @@ description: Get the value stored in a key from the user's own key-value store.
 platforms: [websites, apps, nodejs, workers]
 ---

-Returns the value stored at a key, or `null` if the key doesn't exist or has expired.
-
-Pass an array of keys to read several in one request.
+Returns the value stored at a key, or `null` if the key doesn't exist or has expired. Pass an array of keys to read several in one request.

 ## Syntax

@@ -33,10 +31,8 @@ Up to **1,000** keys to read in one request. More than that rejects with `bad_re

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Reads data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `read` or `write` access. A key the owner's app keeps private reads as `null`. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Reads another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Reads data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `read` or `write` access. A key the owner's app keeps private reads as `null`. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Reads another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -58,7 +54,7 @@ With `handle`, the promise can reject with these codes:

 ## Examples

-### Retrieve the value of key 'name'
+<strong class="example-title">Retrieve the value of key 'name'</strong>

 ```html;kv-get
 <html>
@@ -79,7 +75,7 @@ With `handle`, the promise can reject with these codes:
 </html>
 ```

-### Read several keys in one request
+<strong class="example-title">Read several keys in one request</strong>

 ```html
 <html>
@@ -4,9 +4,7 @@ description: Increment values in the user's own key-value store by a specified a
 platforms: [websites, apps, nodejs, workers]
 ---

-Increments the value of a key.
-
-A missing or expired key starts from 0 and loses any TTL it had, and a live key keeps its TTL. The call rejects if the target holds anything other than a number, including a numeric string. The target is the whole value, or with a path map, the field at each path.
+Increments the value of a key. A missing or expired key starts from 0 and loses any TTL it had, and a live key keeps its TTL. The call rejects if the target holds anything other than a number, including a numeric string. The target is the whole value, or with a path map, the field at each path.

 ## Syntax

@@ -39,10 +37,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 Pass `optConfig` after `amount`, as in `puter.kv.incr('stats', 1, { handle })`. An object in the place of `amount` is read as a path map.

@@ -76,7 +72,7 @@ A rejection carries an `Error` with a stable `code`:

 ## Examples

-### Increment the value of a key
+<strong class="example-title">Increment the value of a key</strong>

 ```html;kv-incr
 <html>
@@ -91,7 +87,7 @@ A rejection carries an `Error` with a stable `code`:
 </html>
 ```

-### Increment a property within an object value
+<strong class="example-title">Increment a property within an object value</strong>

 ```html;kv-incr-nested
 <html>
@@ -39,27 +39,23 @@ When `true`, the result holds [`KVPair`](/Objects/kvpair) objects with `key` and

 The last argument of the positional forms. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Lists data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). Listing keys works at any access level, and listing values needs `read` or `write` access. The `pattern` is relative to the shared prefix and can be at most 768 bytes, and the returned keys are relative to the prefix too. The results and `total` leave out entries the owner's app keeps private. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Lists another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Lists data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). Listing keys works at any access level, and listing values needs `read` or `write` access. The `pattern` is relative to the shared prefix and can be at most 768 bytes, and the returned keys are relative to the prefix too. The results and `total` leave out entries the owner's app keeps private. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Lists another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 #### `options` (Object) (optional)

 An object with these optional properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `pattern` | `String` | Same as the `pattern` parameter. |
-| `returnValues` | `Boolean` | Same as the `returnValues` parameter. |
-| `limit` | `Number` | The most items to return in one call, at most `1000`. A larger value is lowered to `1000`, and the `cursor` picks up from there. |
-| `cursor` | `String` | The `cursor` from the previous page, to fetch the next one. The cursor keeps the listing's direction, so leave out `reverse` or pass the same value. A different `reverse` is rejected. |
-| `reverse` | `Boolean` | Lists keys in descending order when `true`. Defaults to `false`. It works with full listings, pages, and streams. On its own, it keeps the plain array return shape. |
-| `stream` | `Boolean` | When `true`, the method returns an async iterator of [`KVListPage`](/Objects/kvlistpage) objects instead of a promise, for use with `for await ... of`. Combine it with `limit` to set the page size, or with `cursor` to resume from a page. It can't be combined with `offset`. With `includeTotal`, only the first page has `total`. |
-| `includeTotal` | `Boolean` | When `true`, the result includes `total`, the number of items that match across all pages. The count is metered, and its cost grows with the size of your store. Request it once, on the first page, and keep it out of hot paths. To find out whether more pages exist, check for `cursor` instead. |
-| `offset` | `Number` | Skips this many items before the page starts, at most `5000`. It can't be combined with `cursor`. Requests get slower and more expensive the larger the offset, so prefer `cursor`. |
-| `fetchUntilFull` | `Boolean` | A page can come back with fewer than `limit` items even when more exist, such as when expired keys are left out. When `true`, the page is filled up to `limit` items when possible. Requires `limit`. |
-| `optConfig` | `Object` | Same as the `optConfig` parameter, as in `list({ pattern, optConfig: { handle } })`. |
+- `pattern` (String): Same as the `pattern` parameter.
+- `returnValues` (Boolean): Same as the `returnValues` parameter.
+- `reverse` (Boolean): Lists keys in descending order when `true`. Defaults to `false`. It works with full listings, pages, and streams. On its own, it keeps the plain array return shape.
+- `limit` (Number): The most items to return in one call, at most `1000`. A larger value is lowered to `1000`, and the `cursor` picks up from there.
+- `cursor` (String): The `cursor` from the previous page, to fetch the next one. The cursor keeps the listing's direction, so leave out `reverse` or pass the same value. A different `reverse` is rejected.
+- `offset` (Number): Skips this many items before the page starts, at most `5000`. It can't be combined with `cursor`. Requests get slower and more expensive the larger the offset, so prefer `cursor`.
+- `includeTotal` (Boolean): When `true`, the result includes `total`, the number of items that match across all pages. The count is metered, and its cost grows with the size of your store. Request it once, on the first page, and keep it out of hot paths. To find out whether more pages exist, check for `cursor` instead.
+- `fetchUntilFull` (Boolean): A page can come back with fewer than `limit` items even when more exist, such as when expired keys are left out. When `true`, the page is filled up to `limit` items when possible. Requires `limit`.
+- `optConfig` (Object): Same as the `optConfig` parameter, as in `list({ pattern, optConfig: { handle } })`.
+- `stream` (Boolean): When `true`, the method returns an async iterator of [`KVListPage`](/Objects/kvlistpage) objects instead of a promise, for use with `for await ... of`. Combine it with `limit` to set the page size, or with `cursor` to resume from a page. It can't be combined with `offset`. With `includeTotal`, only the first page has `total`.

 ## Return value

@@ -98,7 +94,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'

 ## Examples

-### List keys in reverse order
+<strong class="example-title">List keys in reverse order</strong>

 ```html
 <html>
@@ -116,7 +112,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'
 </html>
 ```

-### Retrieve all keys in the user's key-value store for the current app
+<strong class="example-title">Retrieve all keys in the user's key-value store for the current app</strong>

 ```html;kv-list
 <html>
@@ -152,7 +148,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'
 </html>
 ```

-### Paginate results with a cursor
+<strong class="example-title">Paginate results with a cursor</strong>

 ```html;kv-list-pagination
 <html>
@@ -199,7 +195,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'

 ```

-### Sort keys lexicographically
+<strong class="example-title">Sort keys lexicographically</strong>

 ```html;kv-list-sort
 <html>
@@ -225,7 +221,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'
 </html>
 ```

-### Sort numeric keys with zero-padding
+<strong class="example-title">Sort numeric keys with zero-padding</strong>

 ```html;kv-list-padding
 <html>
@@ -253,7 +249,7 @@ The promise rejects with `{ message, code }`. With `stream: true`, the iterator'
 </html>
 ```

-### Design keys for query-like filtering with prefix patterns
+<strong class="example-title">Design keys for query-like filtering with prefix patterns</strong>

 ```html;kv-prefix-patterns
 <html>
@@ -4,11 +4,9 @@ description: List the key-value data other users have shared with you.
 platforms: [websites, apps, nodejs, workers]
 ---

-Lists the live shares other users made with you, a page at a time.
-
 <div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>

-Each share comes with the `handle` you pass to the other [`puter.kv`](/KV/) methods to use it.
+Lists the live shares other users made with you, a page at a time. Each share comes with the `handle` you pass to the other [`puter.kv`](/KV/) methods to use it.

 A share tells you its level, its app, and the owner's label, but not who shared it or what the prefix is. To tell shares apart, read the label, or read a key the owner keeps for that, such as `meta`, through the handle. Reading needs `read` or `write` access, so for a `watch` share you have only the label.

@@ -25,14 +23,10 @@ puter.kv.listShared(options)

 #### `options` (Object) (optional)

-An object with these properties:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Shares per page. Defaults to `50`. A value over `200` is lowered to `200`. |
-| `cursor` | `String` | The `cursor` from the previous page. |
-| `includeTotal` | `Boolean` | Add `total` to the result. Defaults to `false`. |
-| `appUid` | `String \| null` | List only the shares of this app's data. Pass `null` for the store that belongs to no app. In an app, the only uid you can pass is the app's own. |
+- `limit` (Number): Shares per page. Defaults to `50`. A value over `200` is lowered to `200`.
+- `cursor` (String): The `cursor` from the previous page.
+- `includeTotal` (Boolean): Add `total` to the result. Defaults to `false`.
+- `appUid` (String | null): List only the shares of this app's data. Pass `null` for the store that belongs to no app. In an app, the only uid you can pass is the app's own.

 ## Return value

@@ -60,15 +54,9 @@ The promise rejects with `{ message, code }`:
 | `bad_request` | `limit` isn't a positive number, or `appUid` isn't an app uid. |
 | `too_many_requests` | Over the rate limit. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events). |

-## Related
-
- [`puter.kv.share()`](/KV/share/) - Share keys with another user
- [`puter.kv.unshare()`](/KV/unshare/) - Remove your own access
- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
-
 ## Examples

-### Read every list shared with you
+<strong class="example-title">Read every list shared with you</strong>

 ```js
 const { items } = await puter.kv.listShared();
@@ -81,7 +69,7 @@ for (const { handle, access, label } of items) {
 }
 ```

-### Page through every share
+<strong class="example-title">Page through every share</strong>

 ```js
 let cursor;
@@ -92,3 +80,9 @@ do {
    cursor = page.cursor;
 } while (cursor);
 ```
+
+## Related
+
+- [`puter.kv.share()`](/KV/share/) - Share keys with another user
+- [`puter.kv.unshare()`](/KV/unshare/) - Remove your own access
+- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
@@ -4,11 +4,9 @@ description: List the key-value shares you made with other users, including ones
 platforms: [websites, apps, nodejs, workers]
 ---

-Lists the shares you made with [`puter.kv.share()`](/KV/share/), a page at a time.
-
 <div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>

-A share that stopped stays in the listing for 30 days with `revokedAt` and `revokedBy` set, so you can see who had access and when it ended. After 30 days it's deleted.
+Lists the shares you made with [`puter.kv.share()`](/KV/share/), a page at a time. A share that stopped stays in the listing for 30 days with `revokedAt` and `revokedBy` set, so you can see who had access and when it ended. After 30 days it's deleted.

 In an app, the listing has only the shares of that app's data. Outside an app, it has every share you made, and `appUid` narrows it to one app.

@@ -23,15 +21,11 @@ puter.kv.listSharedByMe(options)

 #### `options` (Object) (optional)

-An object with these properties:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `limit` | `Number` | Shares per page. Defaults to `50`. A value over `200` is lowered to `200`. |
-| `cursor` | `String` | The `cursor` from the previous page. |
-| `state` | `String` | Which shares to list. Pass `'live'` for only shares that are still live, `'revoked'` for only shares that stopped, or `'all'` for both. Defaults to `'all'`. |
-| `includeTotal` | `Boolean` | Add `total` to the result. Defaults to `false`. |
-| `appUid` | `String \| null` | List only the shares of this app's data. Pass `null` for the store that belongs to no app. In an app, the only uid you can pass is the app's own. |
+- `limit` (Number): Shares per page. Defaults to `50`. A value over `200` is lowered to `200`.
+- `cursor` (String): The `cursor` from the previous page.
+- `includeTotal` (Boolean): Add `total` to the result. Defaults to `false`.
+- `appUid` (String | null): List only the shares of this app's data. Pass `null` for the store that belongs to no app. In an app, the only uid you can pass is the app's own.
+- `state` (String): `'live'` lists only shares that are still live, `'revoked'` only shares that stopped, and `'all'` both. Defaults to `'all'`.

 ## Return value

@@ -62,15 +56,9 @@ The promise rejects with `{ message, code }`:
 | `bad_request` | `limit` isn't a positive number, `appUid` isn't an app uid, or `state` isn't `'live'`, `'revoked'`, or `'all'`. |
 | `too_many_requests` | Over the rate limit. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events). |

-## Related
-
- [`puter.kv.share()`](/KV/share/) - Share keys with another user
- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
-
 ## Examples

-### Show who has access, and who left
+<strong class="example-title">Show who has access, and who left</strong>

 ```js
 const { items } = await puter.kv.listSharedByMe();
@@ -82,7 +70,7 @@ for (const share of items) {
 }
 ```

-### Revoke everyone's access to one prefix
+<strong class="example-title">Revoke everyone's access to one prefix</strong>

 ```js
 let cursor;
@@ -96,3 +84,9 @@ do {
    cursor = page.cursor;
 } while (cursor);
 ```
+
+## Related
+
+- [`puter.kv.share()`](/KV/share/) - Share keys with another user
+- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
+- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
@@ -4,9 +4,7 @@ description: Remove values at one or more paths from a key in the user's own key
 platforms: [websites, apps, nodejs, workers]
 ---

-Removes values from the value stored at a key, by path.
-
-Paths can point at nested fields and array elements.
+Removes values from the value stored at a key, by path. Paths can point at nested fields and array elements.

 ## Syntax

@@ -33,10 +31,8 @@ Paths support dot notation, array indexes at any level (`[0]`, `items[0]`, or `s

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -64,7 +60,7 @@ A rejection carries an `Error` with a stable `code`:

 ## Examples

-### Remove nested fields from an object
+<strong class="example-title">Remove nested fields from an object</strong>

 ```html;kv-remove
 <html>
@@ -47,12 +47,10 @@ Every `set()` replaces the whole entry, TTL included, so a later `set()` without

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `onlyIfAbsent` | `Boolean` | Writes the key only when it has no live entry. See [Writing only if absent](#writing-only-if-absent). The batch form rejects it with `invalid_request`. |
-| `disableSharing` | `Boolean` | Makes the entry private to your app. See [Private entries](#private-entries). |
-| `handle` | `String` | Writes into data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix and can be at most 768 bytes, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Writes to another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). |
+- `disableSharing` (Boolean): Makes the entry private to your app. See [Private entries](#private-entries).
+- `onlyIfAbsent` (Boolean): Writes the key only when it has no live entry. See [Writing only if absent](#writing-only-if-absent). The batch form rejects it with `invalid_request`.
+- `handle` (String): Writes into data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix and can be at most 768 bytes, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Writes to another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/).

 The `handle` option can't be combined with `appUuid` or `disableSharing`.

@@ -64,6 +62,20 @@ An array of `{ key, value, expireAt? }` objects, written in one request. Pass it

 A `Promise` that resolves to `true` when the key was written. With `onlyIfAbsent`, it resolves to `false` when a live entry already held the key and nothing was written.

+## Private entries
+
+An entry written with `disableSharing: true` is private to your app. No other app can read, list, change, or delete it, even one the user let reach your app's data with [`puter.perms.request('appData', …)`](/Perms/appData/). Use it for anything another app should never see, such as a cached access token. A user approving such a request can't see what your store holds.
+
+A private entry is also hidden from users you share its prefix with through [`puter.kv.share()`](/KV/share/). They can't read, list, or watch it. Deleting it through the share resolves the same way deleting a missing key does and leaves the entry in place. Any other write to it through the share is refused with `kv_handle_access_denied`. So a holder with write access can tell that the key exists, but can't read its value.
+
+Your own app reads and writes the entry normally. Writing the key again without the flag makes it shareable again, since `set()` replaces the whole entry. In the batch form, `disableSharing` marks every entry in the batch.
+
+## Writing only if absent
+
+With `onlyIfAbsent: true`, `set()` writes the key only when it has no live entry. An expired entry counts as absent. When a live entry holds the key, nothing is written and the promise resolves to `false`.
+
+Two writes at nearly the same time from different places may both succeed and both resolve to `true`, and the later write wins. Use it to create something once where a rare double create is harmless, such as claiming a room id or setting up a new document. It isn't a lock, and it can't hand out unique numbers. For a log of changes, give each change its own key, such as `chg:<timestamp>-<writer>-<random>`, and order the changes by timestamp instead of using a shared counter. A counter kept with [`puter.kv.incr()`](/KV/incr/) has the same limit.
+
 ## Errors

 The promise rejects with `{ message, code }`:
@@ -82,23 +94,9 @@ The promise rejects with `{ message, code }`:
 | `kv_handle_key_invalid` | With `handle`, a key is empty or longer than 768 bytes. |
 | `kv_handles_disabled` | Shares can't be used this way on this deployment. |

-## Private entries
-
-An entry written with `disableSharing: true` is private to your app. No other app can read, list, change, or delete it, even one the user let reach your app's data with [`puter.perms.request('appData', …)`](/Perms/appData/). Use it for anything another app should never see, such as a cached access token. A user approving such a request can't see what your store holds.
-
-A private entry is also hidden from users you share its prefix with through [`puter.kv.share()`](/KV/share/). They can't read, list, or watch it. Deleting it through the share resolves the same way deleting a missing key does and leaves the entry in place. Any other write to it through the share is refused with `kv_handle_access_denied`. So a holder with write access can tell that the key exists, but can't read its value.
-
-Your own app reads and writes the entry normally. Writing the key again without the flag makes it shareable again, since `set()` replaces the whole entry. In the batch form, `disableSharing` marks every entry in the batch.
-
-## Writing only if absent
-
-With `onlyIfAbsent: true`, `set()` writes the key only when it has no live entry. An expired entry counts as absent. When a live entry holds the key, nothing is written and the promise resolves to `false`.
-
-Two writes at nearly the same time from different places may both succeed and both resolve to `true`, and the later write wins. Use it to create something once where a rare double create is harmless, such as claiming a room id or setting up a new document. It isn't a lock, and it can't hand out unique numbers. For a log of changes, give each change its own key, such as `chg:<timestamp>-<writer>-<random>`, and order the changes by timestamp instead of using a shared counter. A counter kept with [`puter.kv.incr()`](/KV/incr/) has the same limit.
-
 ## Examples

-### Create a new key-value pair
+<strong class="example-title">Create a new key-value pair</strong>

 ```html;kv-set
 <html>
@@ -113,7 +111,7 @@ Two writes at nearly the same time from different places may both succeed and bo
 </html>
 ```

-### Set multiple key-value pairs at once
+<strong class="example-title">Set multiple key-value pairs at once</strong>

 ```html
 <html>
@@ -132,14 +130,14 @@ Two writes at nearly the same time from different places may both succeed and bo
 </html>
 ```

-### Claim a name only if nobody has it yet
+<strong class="example-title">Claim a name only if nobody has it yet</strong>

 ```js
 const claimed = await puter.kv.set('room:lobby', { createdAt: Date.now() }, { onlyIfAbsent: true });
 puter.print(claimed ? 'Room created' : 'That room already exists');
 ```

-### Store a value no other app can ever read
+<strong class="example-title">Store a value no other app can ever read</strong>

 ```html
 <html>
@@ -4,11 +4,9 @@ description: Share the keys under a prefix with another Puter user, so they can
 platforms: [websites, apps, nodejs, workers]
 ---

-Shares the keys under a prefix with another Puter user, or with up to 50 users in one call.
-
 <div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>

-The other user becomes the share's holder, and you stay its owner. The keys stay in your store, and the holder reaches them through the share.
+Shares the keys under a prefix with another Puter user, or with up to 50 users in one call. The other user becomes the share's holder, and you stay its owner. The keys stay in your store, and the holder reaches them through the share.

 Each share has a `handle`. The holder finds it with [`puter.kv.listShared()`](/KV/listShared/) and passes it as `handle` to the other [`puter.kv`](/KV/) methods, in the app whose data it is or outside any app. You can pass it too, with keys relative to the prefix, the same way the holder does. [Sharing with other users](/KV/#sharing-with-other-users) shows how a holder uses a share.

@@ -54,15 +52,13 @@ What the holder can do. Defaults to `'read'`. Each level includes the ones befor

 The options form takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `prefix` | `String` | Required. The key prefix, as above. |
-| `recipient` | `String \| Object` | Who to share with, as above. |
-| `recipients` | `Array` | Several users to share with, as above. Pass one of `recipient` or `recipients`. With both, `recipient` is ignored. |
-| `access` | `String` | What the holder can do, as above. Defaults to `'read'`. |
-| `label` | `String \| null` | Plain text the holder is shown with the share, such as `'Groceries from Dan'`. Whitespace at either end is trimmed, and the rest can be at most 128 characters and 512 bytes of UTF-8. Control characters, invisible formatting characters (such as zero-width spaces and text direction marks), line breaks, and more than 3 combining marks on one character are rejected with `kv_share_label_invalid`. An empty string means no label. |
-| `notify` | `Boolean` | Whether you and the holder can send each other notifications through the share's handle with [`puter.notifications.notify()`](/Notifications/notify/), from the app whose data it is. Defaults to `false`. Turning it on also sends the holder a `kv.share.received` notification, as [What the holder sees](#what-the-holder-sees) describes. Shares of the store that belongs to no app can't carry notifications. |
-| `appUuid` | `String` | The app whose data to share. Outside an app, such as in a Node.js script using the user's auth token, it can name any app that exists. An app always shares its own data, and passing a different app's id fails with `events_kv_handle_outside_namespace`. |
+- `prefix` (String) (required): The key prefix, as above.
+- `recipient` (String | Object): Who to share with, as above.
+- `recipients` (Array): Several users to share with, as above. Pass one of `recipient` or `recipients`. With both, `recipient` is ignored.
+- `access` (String): What the holder can do, as above. Defaults to `'read'`.
+- `label` (String | null): Plain text the holder is shown with the share, such as `'Groceries from Dan'`. Whitespace at either end is trimmed, and the rest can be at most 128 characters and 512 bytes of UTF-8. Control characters, invisible formatting characters (such as zero-width spaces and text direction marks), line breaks, and more than 3 combining marks on one character are rejected with `kv_share_label_invalid`. An empty string means no label.
+- `notify` (Boolean): Whether you and the holder can send each other notifications through the share's handle with [`puter.notifications.notify()`](/Notifications/notify/), from the app whose data it is. Defaults to `false`. Turning it on also sends the holder a `kv.share.received` notification, as [What the holder sees](#what-the-holder-sees) describes. Shares of the store that belongs to no app can't carry notifications.
+- `appUuid` (String): The app whose data to share. Outside an app, such as in a Node.js script using the user's auth token, it can name any app that exists. An app always shares its own data, and passing a different app's id fails with `events_kv_handle_outside_namespace`.

 Without an app, [`puter.kv`](/KV/) uses a store that belongs to no app. Shares of that store have an `appUid` of `null`.

@@ -83,34 +79,8 @@ With `recipients`, the `Promise` resolves to an array with one item per recipien

 - `error` (Object): Why that recipient didn't get a share, as `{ message, code }`. Its code is one of the [errors](#errors) about a recipient, which are `invalid_recipient`, `subject_does_not_exist`, `bad_request` when it's you, `invalid_kv_share_prefix` when a share with that user has the same prefix in different letter case, `recipient_not_accepting_shares`, or `events_kv_handle_limit_reached` when you already have 256 live shares with that user.

-## Errors
-
 Any other error, such as a bad `prefix`, rejects the whole call. Before it shares with anyone, the call checks that all the new shares fit within your limits and rate limits, and rejects the whole call if they don't.

-The promise rejects with `{ message, code }`:
-
-| Code | Meaning |
-| -- | -- |
-| `invalid_recipient` | A username contains `@`, or `recipient` isn't a username, `{ username }`, or `{ uid }`. |
-| `subject_does_not_exist` | No user has that username or uuid. |
-| `bad_request` | You named yourself as the recipient, `appUuid` isn't the id of an app that exists, or `recipients` is empty or has more than 50 entries. |
-| `invalid_kv_share_prefix` | `prefix` is empty, too long, has an empty segment, or has a character other than lowercase letters, digits, `_`, `.`, and `-` between its separators. Also returned when one of your shares with the same user has the same prefix in different letter case. |
-| `kv_share_access_invalid` | `access` isn't `'watch'`, `'read'`, or `'write'`. |
-| `kv_share_label_invalid` | `label` isn't a string or `null`, is too long, or contains a character it can't have. |
-| `kv_share_notify_invalid` | `notify` isn't a boolean. |
-| `recipient_not_accepting_shares` | The recipient blocked you, or doesn't accept shares. On an existing share, you raised its access, set a new label, or turned `notify` on. |
-| `account_is_not_verified` | Your email address isn't confirmed. |
-| `events_kv_handle_requires_account` | A temporary account tried to share. |
-| `events_kv_handle_limit_reached` | You already have as many live shares as your plan allows, in total, in this app, or with this user. With `recipients`, the new shares would go over your limit in total or in this app. |
-| `events_kv_handle_not_delegated` | An app shared without the user's consent for that prefix and level. |
-| `events_kv_handle_outside_namespace` | An app named another app's data. |
-| `events_kv_handle_owner_only` | The call came from an access token with less access than the account. |
-| `forbidden` | An app shared through an access token it issued. |
-| `kv_handles_disabled` | `read` and `write` shares are turned off on this deployment. |
-| `events_kv_handles_disabled` | `watch` shares are turned off on this deployment. |
-| `events_disabled` | Events, which `watch` shares need, are turned off on this deployment. |
-| `too_many_requests` | Over the rate limit, or another change to the same share was still running. Try again. |
-
 ## Sharing the same prefix again

 Sharing the same prefix of the same app's data with the same user again changes the existing share instead of making a second one. The share keeps its `handle` and `createdAt`, and gets the `access` of the new call. Use this to raise or lower a holder's access. Since `access` defaults to `'read'`, a call without it sets the share to `'read'`, lowering a `'write'` share.
@@ -137,15 +107,35 @@ When a share of an app's data allows notifications, the holder gets a `kv.share.

 See [Rate Limits and Quotas](/rate-limits-and-quotas/#events) for how many shares an account can make per minute and hold at once, and [Key-value store](/rate-limits-and-quotas/#key-value-store) for how much all the holders of your shares can read and write together.

-## Related
+## Errors

- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
+The promise rejects with `{ message, code }`:
+
+| Code | Meaning |
+| -- | -- |
+| `invalid_recipient` | A username contains `@`, or `recipient` isn't a username, `{ username }`, or `{ uid }`. |
+| `subject_does_not_exist` | No user has that username or uuid. |
+| `bad_request` | You named yourself as the recipient, `appUuid` isn't the id of an app that exists, or `recipients` is empty or has more than 50 entries. |
+| `invalid_kv_share_prefix` | `prefix` is empty, too long, has an empty segment, or has a character other than lowercase letters, digits, `_`, `.`, and `-` between its separators. Also returned when one of your shares with the same user has the same prefix in different letter case. |
+| `kv_share_access_invalid` | `access` isn't `'watch'`, `'read'`, or `'write'`. |
+| `kv_share_label_invalid` | `label` isn't a string or `null`, is too long, or contains a character it can't have. |
+| `kv_share_notify_invalid` | `notify` isn't a boolean. |
+| `recipient_not_accepting_shares` | The recipient blocked you, or doesn't accept shares. On an existing share, you raised its access, set a new label, or turned `notify` on. |
+| `account_is_not_verified` | Your email address isn't confirmed. |
+| `events_kv_handle_requires_account` | A temporary account tried to share. |
+| `events_kv_handle_limit_reached` | You already have as many live shares as your plan allows, in total, in this app, or with this user. With `recipients`, the new shares would go over your limit in total or in this app. |
+| `events_kv_handle_not_delegated` | An app shared without the user's consent for that prefix and level. |
+| `events_kv_handle_outside_namespace` | An app named another app's data. |
+| `events_kv_handle_owner_only` | The call came from an access token with less access than the account. |
+| `forbidden` | An app shared through an access token it issued. |
+| `kv_handles_disabled` | `read` and `write` shares are turned off on this deployment. |
+| `events_kv_handles_disabled` | `watch` shares are turned off on this deployment. |
+| `events_disabled` | Events, which `watch` shares need, are turned off on this deployment. |
+| `too_many_requests` | Over the rate limit, or another change to the same share was still running. Try again. |

 ## Examples

-### Share a list with another user
+<strong class="example-title">Share a list with another user</strong>

 ```js
 const prefix = `list:${crypto.randomUUID()}:`;
@@ -155,7 +145,7 @@ const share = await puter.kv.share(prefix, 'alice', 'write');
 puter.print(`Shared with ${share.holder} as ${share.access}`);
 ```

-### Add a label, and lower the access later
+<strong class="example-title">Add a label, and lower the access later</strong>

 ```js
 const share = await puter.kv.share({
@@ -169,7 +159,7 @@ const share = await puter.kv.share({
 await puter.kv.share('trip:japan-2027:', 'alice', 'read');
 ```

-### Let you and the holder notify each other
+<strong class="example-title">Let you and the holder notify each other</strong>

 ```js
 const share = await puter.kv.share({
@@ -181,7 +171,7 @@ const share = await puter.kv.share({
 puter.print(`Alice can be notified through ${share.handle}`);
 ```

-### Share with several users at once
+<strong class="example-title">Share with several users at once</strong>

 ```js
 const results = await puter.kv.share('board:planning:', ['alice', 'bob', 'carol'], 'read');
@@ -190,3 +180,9 @@ for (const result of results) {
    else puter.print(`Shared with ${result.holder}<br>`);
 }
 ```
+
+## Related
+
+- [`puter.kv.unshare()`](/KV/unshare/) - Stop a share
+- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
+- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
@@ -4,11 +4,9 @@ description: Stop sharing key-value data with another user, or remove your own a
 platforms: [websites, apps, nodejs, workers]
 ---

-Stops a share made with [`puter.kv.share()`](/KV/share/).
-
 <div class="info">KV sharing is in beta. Method shapes, limits, and behavior may change between releases.</div>

-Either side can call it:
+Stops a share made with [`puter.kv.share()`](/KV/share/). Either side can call it:

 - **The owner** revokes the share. The holder loses access, and any narrower share you made with the same holder inside the same prefix stops too.
 - **The holder** removes their own access. Any narrower share they hold from the same owner inside the same prefix stops too.
@@ -38,6 +36,13 @@ A `Promise` that resolves to:

 Stopping a share that already stopped resolves the same way again.

+## Who can unshare
+
+- The owner and the holder can unshare in the app whose data it is, or outside any app. A handle that isn't yours, as owner or holder, is rejected with `subject_does_not_exist`, the same as one that doesn't exist.
+- To revoke as the owner, an app also needs the user's consent for the prefix, the same consent [`puter.kv.share()`](/KV/share/) needs. To remove the user's own access as the holder, it needs no consent.
+
+Unsharing works when sharing is turned off on the deployment, so you can always stop a share.
+
 ## Errors

 The promise rejects with `{ message, code }`:
@@ -50,22 +55,9 @@ The promise rejects with `{ message, code }`:
 | `events_kv_handle_owner_only` | The owner called from an app other than the one whose data it shares, or from an access token with less access than the account. |
 | `too_many_requests` | Over the rate limit, which sharing and unsharing count toward together. See [Rate Limits and Quotas](/rate-limits-and-quotas/#events). |

-## Who can unshare
-
- The owner and the holder can unshare in the app whose data it is, or outside any app. A handle that isn't yours, as owner or holder, is rejected with `subject_does_not_exist`, the same as one that doesn't exist.
- To revoke as the owner, an app also needs the user's consent for the prefix, the same consent [`puter.kv.share()`](/KV/share/) needs. To remove the user's own access as the holder, it needs no consent.
-
-Unsharing works when sharing is turned off on the deployment, so you can always stop a share.
-
-## Related
-
- [`puter.kv.share()`](/KV/share/) - Share keys with another user
- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
-
 ## Examples

-### Revoke a share you made
+<strong class="example-title">Revoke a share you made</strong>

 ```js
 const share = await puter.kv.share('list:42:', 'alice', 'write');
@@ -74,7 +66,7 @@ const { revokedAt } = await puter.kv.unshare(share.handle);
 puter.print(`Stopped at ${new Date(revokedAt * 1000).toISOString()}`);
 ```

-### Remove your own access to a share
+<strong class="example-title">Remove your own access to a share</strong>

 ```js
 const { items } = await puter.kv.listShared();
@@ -84,3 +76,9 @@ for (const share of items) {
    }
 }
 ```
+
+## Related
+
+- [`puter.kv.share()`](/KV/share/) - Share keys with another user
+- [`puter.kv.listSharedByMe()`](/KV/listSharedByMe/) - List the shares you made
+- [`puter.kv.listShared()`](/KV/listShared/) - List the shares made with you
@@ -4,9 +4,7 @@ description: Update one or more paths within a stored value in the user's own ke
 platforms: [websites, apps, nodejs, workers]
 ---

-Updates one or more paths inside the value stored at a key, without replacing the whole value.
-
-A missing or expired key is built from the paths you give, with no TTL unless you pass one.
+Updates one or more paths inside the value stored at a key, without replacing the whole value. A missing or expired key is built from the paths you give, with no TTL unless you pass one.

 ## Syntax

@@ -41,10 +39,8 @@ Time-to-live in seconds. Omit it, or pass an empty string or `false`, to keep th

 The last argument. It takes these properties:

-| Option | Type | Description |
-|--------|------|-------------|
-| `handle` | `String` | Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users). |
-| `appUuid` | `String` | Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`. |
+- `handle` (String): Works on data another user shared with you, using the `handle` from [`puter.kv.listShared()`](/KV/listShared/). The key is then relative to the shared prefix, and the share needs `write` access. See [Sharing with other users](/KV/#sharing-with-other-users).
+- `appUuid` (String): Works on another app's data, which the user let your app reach with [`puter.perms.request('appData', …)`](/Perms/appData/). It can't be combined with `handle`.

 ## Return value

@@ -76,7 +72,7 @@ A rejection carries an `Error` with a stable `code`:

 ## Examples

-### Update an element of a root array
+<strong class="example-title">Update an element of a root array</strong>

 ```html
 <html>
@@ -93,7 +89,7 @@ A rejection carries an `Error` with a stable `code`:
 </html>
 ```

-### Update nested fields and refresh the TTL
+<strong class="example-title">Update nested fields and refresh the TTL</strong>

 ```html;kv-update
 <html>
@@ -4,7 +4,7 @@ description: Create a raw TCP socket directly in the browser.
 platforms: [websites, apps]
 ---

-Creates a raw TCP socket that can be used directly in the browser.
+The Socket API lets you create a raw TCP socket which can be used directly in the browser.

 ## Syntax

@@ -88,7 +88,7 @@ Fired when the socket encounters an error. The close event is fired shortly afte

 ## Examples

-### Connect to a server and print the response
+<strong class="example-title">Connect to a server and print the response</strong>

 ```html;net-basic
 <html>
@@ -4,9 +4,7 @@ description: Create a TLS protected TCP socket connection directly in the browse
 platforms: [websites, apps]
 ---

-Creates a TLS-protected TCP socket connection that can be used directly in the browser.
-
-The interface is exactly the same as the normal <a href="/Networking/Socket/">`puter.net.Socket`</a> but connections are encrypted instead of being in plain text.
+The TLS Socket API lets you create a TLS protected TCP socket connection which can be used directly in the browser. The interface is exactly the same as the normal <a href="/Networking/Socket/">`puter.net.Socket`</a> but connections are encrypted instead of being in plain text.

 ## Syntax

@@ -92,7 +90,7 @@ The encryption is done by [rustls-wasm](https://github.com/MercuryWorkshop/rustl

 ## Examples

-### Connect to a server with TLS and print the response
+<strong class="example-title">Connect to a server with TLS and print the response</strong>

 ```html;net-tls
 <html>
@@ -4,7 +4,7 @@ description: Fetch web resources securely without being bound by CORS restrictio
 platforms: [websites, apps]
 ---

-Securely fetches an HTTP or HTTPS resource without being bound by CORS restrictions.
+The puter fetch API lets you securely fetch a http/https resource without being bound by CORS restrictions.

 ## Syntax

@@ -13,7 +13,7 @@ puter.net.fetch(url)
 puter.net.fetch(url, options)
 ```

-## Parameters
+## Parameters 

 #### `url` (String) (Required)
 The url of the resource to access. The URL can be either http or https.
@@ -26,8 +26,6 @@ A `Promise` to a `Response` object.

 ## Examples

-### Send a GET request
-
 ```html;net-fetch
 <html>
 <body>
@@ -138,15 +138,15 @@ Your app's notifications are events on the `notif:app-user` [subject](/Events/su
 ## Functions

 - **[`puter.notifications.notify()`](/Notifications/notify/)** - Send a notification to the user, or to the other side of a key-value share
- **[`puter.notifications.onNotification()`](/Notifications/onNotification/)** - Receive your app's notifications, including the ones sent while it was closed
- **[`puter.notifications.on()`](/Notifications/on/)** - React when one of your notifications is clicked or dismissed
- **[`puter.notifications.dismiss()`](/Notifications/dismiss/)** - Dismiss a notification and close it on the user's other devices
 - **[`puter.notifications.markShown()`](/Notifications/markShown/)** - Mark a notification as shown, so the next one in its group is new
+- **[`puter.notifications.dismiss()`](/Notifications/dismiss/)** - Dismiss a notification and close it on the user's other devices
 - **[`puter.notifications.cancel()`](/Notifications/cancel/)** - Cancel a notification stored to send later
- **[`puter.notifications.enable()`](/Notifications/enable/)** - Turn on pushes for your app in this browser
+- **[`puter.notifications.onNotification()`](/Notifications/onNotification/)** - Receive your app's notifications, including the ones sent while it was closed
 - **[`puter.notifications.onPush()`](/Notifications/onPush/)** - Say what a push shows for one channel, and handle its notifications while the page is open
- **[`puter.notifications.status()`](/Notifications/status/)** - Check whether pushes reach this browser, without asking
+- **[`puter.notifications.on()`](/Notifications/on/)** - React when one of your notifications is clicked or dismissed
+- **[`puter.notifications.enable()`](/Notifications/enable/)** - Turn on pushes for your app in this browser
 - **[`puter.notifications.disable()`](/Notifications/disable/)** - Turn off pushes for your app
+- **[`puter.notifications.status()`](/Notifications/status/)** - Check whether pushes reach this browser, without asking
 - **[`puter.notifications.requestPermission()`](/Notifications/requestPermission/)** - Ask the user to allow pushes from your app
 - **[`puter.notifications.hasPermission()`](/Notifications/hasPermission/)** - Check whether the user allows pushes from your app, without asking
 - **[`puter.notifications.enablePush()`](/Notifications/enablePush/)** - Turn on pushes through Puter in this browser
@@ -4,9 +4,7 @@ description: Cancel a notification your app stored to send later, before it goes
 platforms: [websites, apps]
 ---

-Cancels a notification your app stored to send later with [`notify()`](/Notifications/notify/#send-it-later) and `sendAt`.
-
-The cancelled notification isn't sent, and it stops counting toward the [limit on what your app has waiting](/rate-limits-and-quotas/#schedules) for the user.
+Cancels a notification your app stored to send later with [`notify()`](/Notifications/notify/#send-it-later) and `sendAt`. It isn't sent, and it stops counting toward the [limit on what your app has waiting](/rate-limits-and-quotas/#schedules) for the user.

 It does the same thing as [`puter.events.removeSchedule()`](/Events/removeSchedule/), and shares its rate limit with it. The cancelled notification stays in [`puter.events.listSchedules()`](/Events/listSchedules/) for 7 days, with `state: 'ended'` and `endReason: 'removed'`.

@@ -28,9 +26,7 @@ The `scheduleId` that [`notify()`](/Notifications/notify/#send-it-later) resolve

 A `Promise` that resolves when the notification is cancelled.

-## Errors
-
-The promise rejects with an error carrying `message` and `code`:
+It rejects with an error carrying `message` and `code`:

 | `code` | Meaning |
 | --- | --- |
@@ -43,7 +39,7 @@ The promise rejects with an error carrying `message` and `code`:

 ## Examples

-### Store a reminder, then cancel it
+<strong class="example-title">Store a reminder, then cancel it</strong>

 ```html;notifications-send-later
 <html>
@@ -4,9 +4,7 @@ description: Turn off push notifications for your app.
 platforms: [websites, apps]
 ---

-Turns push notifications off for your app.
-
-Notifications still reach your app live while it's open.
+Turns push notifications off for your app. Notifications still reach your app live while it's open.

 On a website, it ends this browser's push subscription for your app and removes it from Puter. Only the subscription Puter made is removed, so a subscription another push service made on your site stays as it is. The browser's permission isn't changed, so a later [`enable()`](/Notifications/enable/) turns pushes back on without a prompt.

@@ -23,21 +21,16 @@ puter.notifications.disable(options)
 ## Parameters

 #### `options` (Object) (optional)
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `serviceWorker` | `String` | The path of the worker passed to [`enable()`](/Notifications/enable/). When it's set, only that worker's subscription is removed. Without it, Puter's subscription is removed under whichever of your site's service workers holds it. Only used on a website. |
+- `serviceWorker` (String): The path of the worker passed to [`enable()`](/Notifications/enable/). When it's set, only that worker's subscription is removed. Without it, Puter's subscription is removed under whichever of your site's service workers holds it. Only used on a website.

 ## Return value
 A `Promise` that resolves to `true` when a subscription was removed, and `false` when there was none. Inside the Puter desktop, it resolves `true` when your app held the permission. It resolves `false` in a browser that can't receive pushes.

-## Errors
-
-If Puter can't remove the subscription, the promise rejects with an error carrying `message` and `code`, such as `push_unavailable` when this server has no push notification service. This browser's subscription is ended either way. Inside the Puter desktop, it rejects with `ipc_handler_failed` when the permission couldn't be removed.
+If Puter can't remove the subscription, it rejects with an error carrying `message` and `code`, such as `push_unavailable` when this server has no push notification service. This browser's subscription is ended either way. Inside the Puter desktop, it rejects with `ipc_handler_failed` when the permission couldn't be removed.

 ## Examples

-### Turn pushes off from a settings switch
+<strong class="example-title">Turn pushes off from a settings switch</strong>

 ```js
 document.getElementById('pushes-off').addEventListener('click', async () => {
Author	SHA1	Message	Date
jelveh	d885b5d4f6	Fix the app browser embed doc's broken sentence about puterOrigin	2026-11-06 00:05:09 -07:00
jelveh	faef532aa1	Let the app browser embed find no session when storage is refused Reading local storage can throw when the browser blocks site data. The embed now falls back to the session cookie, as it does for empty storage, so a visitor without a session sees the recommended apps instead of the unavailable state.	2026-11-06 00:04:54 -07:00
jelveh	4a9ea5544c	Show the app browser embed's error state when the session lookup fails Only a 401 from /get-gui-token now means there is no session. A rate limit or server error shows the unavailable state, as before, instead of the signed-out list of recommended apps.	2026-11-06 00:04:21 -07:00
jelveh	90231bfcb2	Show recommended apps in the app browser embed without a session /embed/apps only worked for a signed-in user; without a session it showed an unavailable state. The route now puts the recommended apps (RecommendedAppsService) in the page's config as guestApps, and when the embed finds no session it shows those, without loading puter.js or reading installed apps, folders, or saved order. Selecting one opens it at the same URL a signed-in launch uses, with no opener and no token on offer, so the app signs in on its own; apps that need the desktop open /app/<name>. Signed-in behavior is unchanged. createAppBrowser takes a guestApps option for this, and appTabLaunch's URL building is shared between launchAppInTab and the new guestAppLaunchUrl.	2026-11-05 23:58:07 -07:00