sync limits ai, fs, events, networking (#4088)

src/docs/src/FS/readdir.md

@@ -32,7 +32,7 @@ An object with the following properties:
 - `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 unlimited.
+- `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`.

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

@@ -61,6 +61,16 @@ Shared by chat, image generation, video, TTS, speech and OCR. Each interface and
 | Requests per 10 s   | 200  | 30   | 20        |
 | Concurrent requests | 20   | 3    | 2         |
 
+| Input                                          | Limit            |
+| ---------------------------------------------- | ---------------- |
+| Text for `txt2speech()`                        | 3,000 characters |
+| Audio for `speech2speech()`                    | 25 MiB           |
+| Image inlined in a chat message                | 5 MB             |
+| File attached to a chat message, Claude models | 30 MB            |
+| File attached to a chat message, OpenAI models | 5 MB             |
+
+An input over its limit is rejected before it reaches the model. OCR input limits are under [OCR](#ocr).
+
 The OpenAI- and Anthropic-compatible endpoints (`/puterai/openai/v1/*`, `/puterai/anthropic/v1/messages`) require a paid plan; a free account gets `402 subscription_required`. The same models are available to every account through `puter.ai.*` and `/drivers/call`, and the model catalogue endpoints are open to everyone.
 
 `/puterai/anthropic/v1/messages/count_tokens` has its own budget of 120 requests per minute per user, with no concurrency limit, and is not charged.
@@ -154,6 +164,8 @@ Per minute unless stated:
 | Limit | Value | Scope |
 | ----- | ----- | ----- |
 | Uploads in progress | 10,000 | Per user, all apps |
+| Entries in one `readdir` response | 10,000 (1,000 per page by default when paginated or `recursive`) | Per request |
+| Levels a `recursive` `readdir` descends | 10 | Per request |
 | Files and folders in one `startBatchWrite`, `completeBatchWrite` or `batchWrite` | 500 | Per request |
 | Entries in one `/sign` request | 500 | Per request |
 | Part numbers in one `signMultipartParts` | 10,000 | Per request |
@@ -397,6 +409,8 @@ Unsubscribing counts toward its own `unsubscribe` limit, not the `subscribe` one
 | Failures in a row before suspension    | 5                              | Per subscription   |
 | `user` token lifetime in the events worker | 15 minutes                 | Per run            |
 
+Failures count as in a row until the handler takes a delivery or an hour passes without another failure; either resets the count to zero.
+
 Over the deploy limit, deliveries stay queued and retry after the hour rolls over.
 
 #### Handler chains
@@ -445,6 +459,16 @@ Free: idle subscriptions, events a filter excluded, writes merged by coalescing,
 
 When the holder's balance runs out, deliveries stop and persistent subscriptions are suspended with `no_credit`, and the holder is notified. The backlog is kept for 1 hour. Topping up resumes them within a few minutes.
 
+### Networking
+
+[`puter.net`](/Networking/) sockets connect through a relay that takes a single-use token. A page fetches one token when it opens its first socket and reuses the connection for later sockets; `puter.net.generateWispV1URL()` fetches a new one on every call.
+
+| Limit                     | Paid | Free | Anonymous |
+| ------------------------- | ---- | ---- | --------- |
+| Relay tokens per minute   | 60   | 30   | 10        |
+
+The relay checks each token against Puter, at most **300 checks/min** per relay IP.
+
 ### Peer connections
 
 | Limit                          | Paid | Free | Anonymous |