reorder api sections (#4519)

AGENTS.md

@@ -159,7 +159,9 @@ 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. 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.
+
+**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 `).
 
 ### Function page layout
 

src/docs/src/AI.md

@@ -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
 

src/docs/src/Apps.md

@@ -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.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.update()`](/Apps/update/)** - Update application settings
+- **[`puter.apps.delete()`](/Apps/delete/)** - Delete an application
 - **[`puter.apps.checkName()`](/Apps/checkName/)** - Check whether an app name is available
 
 ## Examples

src/docs/src/Auth.md

@@ -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.signOut()`](/Auth/signOut/)** - Sign out the current 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.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

src/docs/src/Email.md

@@ -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

src/docs/src/FS.md

@@ -298,15 +298,14 @@ 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.mkdir()`](/FS/mkdir/)** - Create a directory
-- **[`puter.fs.readdir()`](/FS/readdir/)** - List contents of a directory
-- **[`puter.fs.rename()`](/FS/rename/)** - Rename 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.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.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.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
@@ -315,6 +314,7 @@ 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
 

src/docs/src/Hosting.md

@@ -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.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.update()`](/Hosting/update/)** - Update hosting settings
+- **[`puter.hosting.delete()`](/Hosting/delete/)** - Delete a hosting deployment
 - **[`puter.hosting.attach()`](/Hosting/attach/)** - Let the user connect their own domain to a website
 
 ## Examples

src/docs/src/KV.md

@@ -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

src/docs/src/Notifications.md

@@ -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.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.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.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.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.disable()`](/Notifications/disable/)** - Turn off pushes for your app
+- **[`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.disable()`](/Notifications/disable/)** - Turn off pushes for your app
 - **[`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

src/docs/src/Peer.md

@@ -130,8 +130,8 @@ These peer features are supported out of the box when using Puter.js:
 
 - **[`puter.peer.serve()`](/Peer/serve/)** - Create a peer server and generate an invite code
 - **[`puter.peer.connect()`](/Peer/connect/)** - Connect to a peer server using an invite code
-- **[`puter.peer.ensureTurnRelays()`](/Peer/ensureTurnRelays/)** - Preload TURN relays for faster connections
 - **[`puter.peer.createGuestGrant()`](/Peer/createGuestGrant/)** - Create a grant that lets a guest without a Puter account use Puter's relays
+- **[`puter.peer.ensureTurnRelays()`](/Peer/ensureTurnRelays/)** - Preload TURN relays for faster connections
 
 ## Examples
 

src/docs/src/UI.md

@@ -7,15 +7,17 @@ The UI API provides a comprehensive set of tools for creating rich user interfac
 
 ## Available Functions
 
-### Authentication
-- **[`puter.ui.authenticateWithPuter()`](/UI/authenticateWithPuter/)** - Authenticate with Puter
-
 ### Dialogs and Alerts
 - **[`puter.ui.alert()`](/UI/alert/)** - Show alert dialogs
-- **[`puter.ui.notify()`](/UI/notify/)** - Show desktop notifications
 - **[`puter.ui.prompt()`](/UI/prompt/)** - Show input prompts
+- **[`puter.ui.notify()`](/UI/notify/)** - Show desktop notifications
 - **[`puter.ui.showFeedbackDialog()`](/UI/showFeedbackDialog/)** - Let the user send feedback to your app's developer
 
+### File Pickers
+- **[`puter.ui.showOpenFilePicker()`](/UI/showOpenFilePicker/)** - Show file open dialog
+- **[`puter.ui.showSaveFilePicker()`](/UI/showSaveFilePicker/)** - Show file save dialog
+- **[`puter.ui.showDirectoryPicker()`](/UI/showDirectoryPicker/)** - Show directory picker
+
 ### Window Management
 - **[`puter.ui.createWindow()`](/UI/createWindow/)** - Create new windows
 - **[`puter.ui.setWindowTitle()`](/UI/setWindowTitle/)** - Set window title
@@ -27,32 +29,30 @@ The UI API provides a comprehensive set of tools for creating rich user interfac
 - **[`puter.ui.setWindowY()`](/UI/setWindowY/)** - Set window Y position
 - **[`puter.ui.showWindow()`](/UI/showWindow/)** - Show the application's window
 - **[`puter.ui.hideWindow()`](/UI/hideWindow/)** - Hide the application's window
+- **[`puter.ui.onWindowClose()`](/UI/onWindowClose/)** - Handle window close events
 
-### File Pickers
-- **[`puter.ui.showOpenFilePicker()`](/UI/showOpenFilePicker/)** - Show file open dialog
-- **[`puter.ui.showSaveFilePicker()`](/UI/showSaveFilePicker/)** - Show file save dialog
-- **[`puter.ui.showDirectoryPicker()`](/UI/showDirectoryPicker/)** - Show directory picker
+### Event Handling
+- **[`puter.ui.onLaunchedWithItems()`](/UI/onLaunchedWithItems/)** - Handle launch with items
+- **[`puter.ui.wasLaunchedWithItems()`](/UI/wasLaunchedWithItems/)** - Check if launched with items
+- **[`puter.ui.onItemsOpened()`](/UI/onItemsOpened/)** - Handle items opened by user action
 
 ### System Integration
+- **[`puter.ui.setMenubar()`](/UI/setMenubar/)** - Set application menubar
+- **[`puter.ui.contextMenu()`](/UI/contextMenu/)** - Show a context menu at the cursor
 - **[`puter.ui.launchApp()`](/UI/launchApp/)** - Launch other applications
 - **[`puter.ui.parentApp()`](/UI/parentApp/)** - Get parent application info
 - **[`puter.exit()`](/UI/exit/)** - Exit the application
-- **[`puter.ui.setMenubar()`](/UI/setMenubar/)** - Set application menubar
 - **[`puter.ui.getLanguage()`](/UI/getLanguage/)** - Get current language/locale code
-
-### Event Handling
 - **[`puter.ui.on()`](/UI/on/)** - Register event handlers
-- **[`puter.ui.onItemsOpened()`](/UI/onItemsOpened/)** - Handle items opened by user action
-- **[`puter.ui.onLaunchedWithItems()`](/UI/onLaunchedWithItems/)** - Handle launch with items
-- **[`puter.ui.wasLaunchedWithItems()`](/UI/wasLaunchedWithItems/)** - Check if launched with items
-- **[`puter.ui.onWindowClose()`](/UI/onWindowClose/)** - Handle window close events
 
 ### Additional UI Elements
-- **[`puter.ui.contextMenu()`](/UI/contextMenu/)** - Show a context menu at the cursor
+- **[`puter.ui.showSpinner()`](/UI/showSpinner/)** - Show spinner
 - **[`puter.ui.hideSpinner()`](/UI/hideSpinner/)** - Hide spinner
-- **[`puter.ui.requestPictureInPicture()`](/UI/requestPictureInPicture/)** - Float a page of the app in a picture-in-picture window
-- **[`puter.ui.exitPictureInPicture()`](/UI/exitPictureInPicture/)** - Close the app's picture-in-picture window
 - **[`puter.ui.showColorPicker()`](/UI/showColorPicker/)** - Show color picker
 - **[`puter.ui.showFontPicker()`](/UI/showFontPicker/)** - Show font picker
-- **[`puter.ui.showSpinner()`](/UI/showSpinner/)** - Show spinner
 - **[`puter.ui.socialShare()`](/UI/socialShare/)** - Share content socially
+- **[`puter.ui.requestPictureInPicture()`](/UI/requestPictureInPicture/)** - Float a page of the app in a picture-in-picture window
+- **[`puter.ui.exitPictureInPicture()`](/UI/exitPictureInPicture/)** - Close the app's picture-in-picture window
+
+### Authentication
+- **[`puter.ui.authenticateWithPuter()`](/UI/authenticateWithPuter/)** - Authenticate with Puter

src/docs/src/Utils.md

@@ -9,5 +9,5 @@ The Utilities API provides helpful utility functions and properties that make de
 
 - **[`puter.print()`](/Utils/print/)** - Print text to console or output
 - **[`puter.randName()`](/Utils/randName/)** - Generate random names
-- **[`puter.appID`](/Utils/appID/)** - Get the current application ID
-- **[`puter.env`](/Utils/env/)** - Access environment variables
+- **[`puter.env`](/Utils/env/)** - Access environment variables
+- **[`puter.appID`](/Utils/appID/)** - Get the current application ID

src/docs/src/Workers.md

@@ -129,10 +129,10 @@ In addition, the Puter.js Workers API lets you create, manage, and execute these
 These workers management features are supported out of the box when using Puter.js:
 
 - **[`puter.workers.create()`](/Workers/create/)** - Create a new worker
-- **[`puter.workers.delete()`](/Workers/delete/)** - Delete a worker
+- **[`puter.workers.exec()`](/Workers/exec/)** - Execute a worker
 - **[`puter.workers.list()`](/Workers/list/)** - List all workers
 - **[`puter.workers.get()`](/Workers/get/)** - Get information about a specific worker
-- **[`puter.workers.exec()`](/Workers/exec/)** - Execute a worker
+- **[`puter.workers.delete()`](/Workers/delete/)** - Delete a worker
 
 ### Examples