-- ① Select the chip.
-- ② Click `Browse` and select the firmware file to flash (the bin file containing `_QIO`).
-- ③ Select the device port for flashing. For Tuya official development boards and some partner development boards, hovering over a serial port indicates whether it is a flashing/authorization port or a log port.
-- ④ Click `Start flash` to begin flashing the firmware.
+1. Select the chip.
+2. Click `Browse` and select the firmware file to flash (the bin file containing `_QIO`).
+3. Select the device port for flashing. For Tuya official development boards and some partner development boards, hovering over a serial port indicates whether it is a flashing/authorization port or a log port.
+4. Click `Start flash` to begin flashing the firmware.
:::tip
The default baud rate for flashing is 921600. If you find the flashing speed too slow, you can increase the baud rate appropriately. However, increasing the baud rate may cause the firmware flashing to fail.
@@ -86,11 +86,11 @@ After opening tyutool_gui, click the `Authorize` tab. The interface is as follow
-- ① Click the `Authorize` tab.
-- ② Select the authorization serial port.
-- ③ Select the authorization baud rate.
-- ④ Enter the `UUID` and `AuthKey`.
-- ⑤ Click `Start Authorization`.
+1. Click the `Authorize` tab.
+2. Select the authorization serial port.
+3. Select the authorization baud rate.
+4. Enter the `UUID` and `AuthKey`.
+5. Click `Start Authorization`.
:::tip
The authorization UART and the flashing UART are the same. Keep the UART default configuration (baud rate: 115200, data bits: 8, stop bits: 1, parity: none).
diff --git a/docs/tyutool/batch-auth-developer.md b/docs/tyutool/batch-auth-developer.md
new file mode 100644
index 000000000..7c19cf148
--- /dev/null
+++ b/docs/tyutool/batch-auth-developer.md
@@ -0,0 +1,115 @@
+---
+title: "Batch Auth: Developer Guide"
+sidebar_label: Developer Guide
+description: "For firmware developers — the TuyaOpen UART CLI command contract a firmware must implement to be batch-authorizable by tyutool, plus a self-test checklist."
+keywords:
+ - tyutool batch auth
+ - developer guide
+ - uart cli protocol
+ - authorize contract
+ - self-test
+ - tuyaopen
+---
+
+Written for **firmware developers**: to make a firmware batch-authorizable by tyutool, it must implement a set of TuyaOpen UART CLI commands. Below is the complete protocol contract and a **self-test checklist**.
+
+:::note[On the wrong page?]
+Operators should read the [Operator Guide](./batch-auth-operator.md).
+:::
+
+## Protocol essence
+
+The authorization protocol is a set of **text commands for the TuyaOpen interactive shell** (pure ASCII, each terminated by `\r\n`, no frame header / checksum / opcode). It is a completely separate thing from the Beken BootROM binary protocol used for flashing. The default baud rate is `115200` 8N1; on power-up the device presents a `tuya>` prompt. The authoritative source is `tuya_authorize.c`.
+
+:::tip[How to enable the CLI on a TuyaOpen-based firmware]
+The firmware must register it actively: ① `tal_cli_init()` (defaults to uart0; for a different uart use `tal_cli_init_with_uart(uart_num)`); ② `tuya_authorize_init()` (registers `auth` / `auth-read` / `read_mac`). Call both in `user_main()`. Code:
+
+```c
+void user_main(void)
+{
+ // ... tal_kv_init / tal_sw_timer_init / tal_workq_init etc.
+#if !defined(PLATFORM_UBUNTU) || (PLATFORM_UBUNTU == 0)
+ tal_cli_init(); // Initialize the CLI (default uart0)
+ tuya_authorize_init(); // Register auth / auth-read / read_mac commands
+ tuya_app_cli_init(); // Your app-specific commands (optional)
+#endif
+ // ... tuya_iot_init(...) etc.
+}
+```
+
+:::note
+On a TuyaOpen-based firmware, three lines are enough. The command table and self-test checklist below mainly target self-built or ported firmware.
+:::
+
+## Commands you must implement
+
+| Command (`\r\n` terminated) | Purpose | What the firmware must echo |
+| :-- | :-- | :-- |
+| `sys_log_enable off` | Capability probe + disable logging | New: `OK: log disabled`; old: `No command` or just `tuya>` |
+| `sys_version` | Read firmware version | One line: `project.version x.y.z` |
+| `read_mac` | Read MAC | `XX:XX:XX:XX:XX:FF` (6 colon-separated segments; or with a prefix label `LABEL:XX:...:FF` — 7 segments) |
+| `auth-read` or `auth-read 
+
+*Batch page — completion banner / dashboard (flash totals · auth totals · this batch) / config panel / toolbar (auto-assign · port filter · read-all · start-all) / port list.*
+
+## Pre-flight checklist
+
+| Item | How to know it is ready |
+| :-- | :-- |
+| Desktop tyutool | Installed and launches |
+| Authorization-code Excel | Has at least `UUID` + `AuthKey` columns; purchased from [tuyaopen.ai/pricing](https://tuyaopen.ai/pricing) |
+| Devices + serial cables | Wired and devices can enter download mode |
+| Serial drivers | CH340/CP2102/FT232 installed |
+| Firmware file | The `.bin` for this batch |
+
+Installer packages (version pinned for reference — always check [GitHub Releases](https://github.com/tuya/tyutool/releases) for the latest):
+
+| Platform | File |
+| :-- | :-- |
+| Windows | `..._windows_x86_64_nsis_x.x.x.exe` |
+| macOS (Universal) | `..._macos_universal_dmg_x.x.x.dmg` |
+| Linux | `..._linux_x86_64_appimage_x.x.x.AppImage` (run `chmod +x` first) |
+
+:::warning[T5/T5AI wiring]
+These devices have two serial ports — be sure to connect the flashing/authorization port, not the log port.
+:::
+
+:::warning[Authorization codes are valuable]
+Keep the Excel safe.
+:::
+
+### Configuration handoff
+
+| Config item | Developer fills | Operator verifies |
+| :-- | :-- | :-- |
+| Chip model | e.g. `esp32` / `t5ai` | Matches the device |
+| Operation mode | auth-only vs flash-then-auth (Path A/B) | "Flash firmware" switch matches |
+| Firmware file & version | filename + version | `batch-summary.json` records SHA256 |
+| Flash baud rate | e.g. 921600 | Set correctly |
+| Auth baud rate | e.g. 115200 | Set correctly |
+| Storage mode | KV / OTP | OTP → single-device validation first |
+| Conflict policy | skip / overwrite | OTP can only skip |
+| Authorization sheet | remaining ≥ new devices in this batch | Recover/retry of registered devices doesn't consume new codes |
+| Wiring | notes | **Confirm RTS wired to reset pin** |
+| MAC uniqueness | each MAC globally unique | tyutool does **not** check MAC conflicts — a duplicate MAC makes devices share an auth code |
+| Single-device smoke test | passed | Done before scaling |
+| Special notes | — | Read |
+
+:::tip
+If something doesn't line up, stop and confirm with the developer — don't change the configuration yourself.
+:::
+
+## Workflow
+
+Go to **Toolbox → Batch flash & auth**.
+
+:::note
+The first time you enter, a disclaimer dialog appears (irreversible operation). You can tick "don't show again"; to re-show it see [Settings](./settings.md#about).
+:::
+
+### Phase 1 — Configuration
+
+1. Pick the chip (ESP32 / T5AI; for auth-only choose `other`).
+2. Flash baud rate.
+3. Auth baud rate.
+4. Whether to flash firmware (flash-then-auth).
+5. Firmware file (local / default auth-firmware).
+6. Pick the firmware location or choose a version.
+
+
+
+*Configuration area — shared config panel.*
+
+1. Pick the authorization sheet (`.xlsx`).
+2. View statistics: total / used / in-use / remaining (assigning codes to new devices needs remaining > 0; recovering/retrying already-registered devices can start even with remaining 0 — they find their original code by MAC).
+3. Devices already carrying authorization: skip (recommended) / overwrite.
+
+
+
+*Batch auth configuration — sheet statistics.*
+
+(T5AI only) Pick the storage mode: KV is rewritable; OTP writes once and is irreversible (see [Safety](#safety-rules)).
+
+### Phase 2 — Wiring & start
+
+:::tip
+First run one device all the way through → small-batch 2–4 devices → then the whole batch.
+:::
+
+Once wired, two steps:
+
+1. Click **Auto-assign** (scans and adds slots, one row per port showing "idle").
+2. Click **Start all** (if more than 8 idle ports, a confirmation prompt appears first).
+
+:::warning[Last 30-second check before start]
+Re-read each config line against the handoff sheet. If OTP: single-device validation done?
+:::
+
+
+
+*Toolbar and port list — slots per port.*
+
+:::note[Other toolbar buttons]
+**② Port filter · ③ Read all (read-only, no write) · ④ Cancel · ⑤ Retry failed · ⑦ Read single port**.
+:::
+
+### Phase 3 — Wait and verify
+
+1. Watch the dashboard until it completes (the banner shows: all success / all failed / partial success / all skipped).
+2. Verify row by row (on failure, look at retry).
+3. Once the whole order is done, click "Archive" (you don't need to archive mid-batch rounds).
+
+
+
+*Dashboard and completion banner (archive button on the right).*
+
+## Reading results
+
+| Status | Meaning | What to do |
+| :-- | :-- | :-- |
+| `done` | Complete, good unit | — |
+| `failed` | Failed | Retry |
+| `skipped` | Already authorized, skipped per policy | — |
+| `no_code` | New device but remaining = 0 | Top up the sheet and rerun |
+| other | In progress | Wait |
+
+## Archiving
+One "Start all" = one round; one authorization sheet = one order (often many rounds). Archiving is per order.
+
+:::info
+One-click archive: pick a directory and it creates a timestamped folder `batch-archive_20260717-143205_esp32/` containing: authorization-sheet copy / firmware (with SHA256) / logs.zip / `batch-summary.json` / `batch-slots.csv`. The summary's `lastRun` and the CSV are only a snapshot of the last round.
+:::
+
+Archive contents:
+
+| File | What it is |
+| :-- | :-- |
+| Authorization-sheet Excel copy | The sheet used |
+| Firmware file | The flashed `.bin` |
+| logs.zip | Compressed logs |
+| batch-summary.json | Run summary |
+| batch-slots.csv | Per-slot snapshot of the last round |
+| Completion banner screenshot | Optional record |
+
+:::warning
+The archive contains UUID + AuthKey — prevent leaks. For troubleshooting, share only the logs and error info; do not send the authorization sheet out.
+:::
+
+## Troubleshooting
+
+| Symptom | What to do |
+| :-- | :-- |
+| App won't open / blank screen | See [FAQ · Linux blank window](./faq.md#linux-blank-window-webkit-compositing-failure) |
+| Port doesn't appear | Swap cable/port, install drivers, close other apps — see [FAQ · ports](./faq.md#device--serial-port-not-in-the-dropdown) |
+| All failed | Run a single device through, drop to 115200, check power supply |
+| Excel "file in use" | Close Excel/WPS and reselect |
+| Excel sheet invalid | Check the `UUID` + `AuthKey` columns and their lengths |
+| Need detailed logs | Save per [Save the scene](#save-the-scene-first), see [FAQ · logs](./faq.md#how-to-report-a-bug-with-logs) |
+
+### Save the scene first
+While the scene is still live, click "Archive" to save everything; then manually add three things: a UI screenshot (mask the AuthKey, UUID can stay) / the problem device itself (label it and set it aside) / a one-line symptom description.
+
+:::note
+Don't wait and don't leak: archive the same day; when sharing out, give only the logs and error info.
+:::
+
+## Safety rules
+This is the only feature that triggers irreversible hardware operations.
+
+:::danger[Rule 1: OTP writes are irreversible]
+OTP (T5AI only) burns authorization into the chip once and can never be undone. A wrong configuration ruins the whole batch — always validate by running one device all the way through before going to scale.
+:::
+
+
+
+*When OTP is selected, the UI warns the write cannot be undone.*
+
+:::danger[Rule 2: devices marked "cancelled after write" must be set aside]
+Devices carrying the "cancelled-after-write" danger badge may already have had authorization written and their state is uncertain — they are neither good units nor safe to rerun directly. Set them aside and verify individually.
+:::
diff --git a/docs/tyutool/batch-flash-auth.md b/docs/tyutool/batch-flash-auth.md
new file mode 100644
index 000000000..ddff6f939
--- /dev/null
+++ b/docs/tyutool/batch-flash-auth.md
@@ -0,0 +1,45 @@
+---
+title: Batch Flash & Auth
+description: "Overview of tyutool batch flashing and authorization — flash firmware and write authorization codes to many devices in parallel, driven by an .xlsx sheet."
+keywords:
+ - tyutool batch
+ - batch flashing
+ - batch authorization
+ - otp
+ - parallel flashing
+ - tuyaopen
+---
+
+import FeatureCardGrid from '@site/src/components/FeatureCardGrid';
+
+Plug several devices into several serial ports and **flash firmware + write authorization codes in parallel**, with the authorization codes driven by an `.xlsx` sheet. This is the most complex feature in tyutool; when the storage mode is set to **OTP**, it performs irreversible eFuse operations (T5AI only).
+
+:::note[Where to find it]
+In the desktop app, this feature lives under **Toolbox → Batch Flash & Auth**.
+:::
+
+## Choose your guide
+
+This feature involves two very different kinds of people, with two separate guides:
+
+
+
+*Figure 1 — Topology of the flashing link from tyutool to the device: tyutool → USB → adapter → UART (TX/RX/GND) → SoC → Flash chip.*
+
+:::note[Reading suggestion]
+New to firmware flashing? Read the first six sections in order; sections 7 and 8 work as a quick terminology reference.
+:::
+
+## What is firmware
+
+Firmware is the program stored in a device's flash chip. You flash firmware to **upgrade** the device (add features), **repair** it (fix a bug), or **customize** it (load your own build). Firmware is, at its core, a block of byte data.
+
+## What is flashing
+
+Flashing (also called "burning" or "writing") is the action of writing firmware bytes into a device's flash chip. The link carries the data like this: ① tyutool reads the firmware and chops it into blocks → ② the blocks go over USB to the adapter, which converts them to UART → ③ the UART lines (TX/RX/GND) reach the SoC, which writes the flash.
+
+:::warning
+Flashing is an overwriting write. Back up important data by [reading](#read) it first.
+:::
+
+## Erase
+
+Erase clears certain regions of the flash to `0xFF`. Typical uses: clearing a region before writing, or erasing the whole chip. Erase presets:
+
+| Preset | Meaning |
+| :-- | :-- |
+| `authInfo` | Erase only the authorization-info region (UUID/AuthKey), keeping firmware and other data |
+| `fullChipNoRf` | Erase the whole chip but keep the RF calibration (RF cal) region |
+| `fullChip` | Erase the entire chip completely (including RF calibration) |
+
+:::tip
+`fullChipNoRf` is the most-used "safe thorough erase."
+:::
+
+## Read
+Read is the inverse of flashing: it reads bytes out of the flash chip, used for backup (whole-chip read or read by segment).
+
+## Authorize
+Authorize (TuyaOpen UART auth) writes a `UUID` + `AuthKey` so the device can connect to the Tuya cloud. Authorization and firmware are two independent things.
+
+:::danger
+The `UUID` and `AuthKey` are credentials you **purchase** from Tuya. Writing forged or duplicate credentials pollutes the device pool.
+:::
+
+Authorization has two operations: authorization read (auth-read) and authorization write (auth-write).
+
+## Serial / UART / baud rate
+Serial communication, the USB-to-serial adapter (CH340/CP2102/FT232), the three UART lines (TX/RX/GND, wired crossed), and the baud rate:
+
+| Baud rate | Typical use |
+| :-- | :-- |
+| `115200` | The most universal, most stable default rate |
+| `460800` | Faster, still reasonably stable |
+| `921600` | High-speed; needs the chip and cabling to support it |
+
+:::tip
+Starting at `115200` is the safest bet.
+:::
+
+## Chip models
+The chip model decides the communication protocol, baud rate, and flash capacity. For the full list see [Firmware Flash](./flash.md#select-a-chip) and the [command line](./cli.md).
+
+## tyutool terminology
+
+| Term | Meaning |
+| :-- | :-- |
+| Flash | Write firmware into the flash chip |
+| Erase | Clear flash regions to `0xFF` |
+| Read | Read bytes out of the flash chip |
+| Authorize | Write `UUID`/`AuthKey` credentials |
+| UUID | A unique device identifier (credential) |
+| AuthKey | The authentication key paired with a UUID |
+| Baud | The serial communication rate |
+| UART | The serial protocol over TX/RX/GND lines |
+| Segment | One contiguous chunk of a multi-segment flash |
+| Erase preset | A named erase scope (e.g. `authInfo`) |
+| MAC | The device's media-access-control address |
diff --git a/docs/tyutool/faq.md b/docs/tyutool/faq.md
new file mode 100644
index 000000000..594229aae
--- /dev/null
+++ b/docs/tyutool/faq.md
@@ -0,0 +1,135 @@
+---
+title: FAQ
+description: "Symptom-first troubleshooting for tyutool — ports and connections, flashing failures, authorization, and platform issues (Linux blank window, Windows WebView2), plus how to report a bug with logs."
+keywords:
+ - tyutool faq
+ - troubleshooting
+ - flashing fails
+ - authorize fails
+ - linux blank window
+ - webview2
+ - tuyaopen
+---
+
+
+This page is problem-first: it lists the **symptom**, then gives the shortest path to diagnose and fix it. Both CLI snippets and GUI actions are included.
+
+## Connection / ports
+
+### Device / serial port not in the dropdown
+**Symptom:** the port selector is empty, or `tyutool list-ports` prints nothing.
+
+1. Unplug/replug, swap cable, swap port.
+2. Install the driver (CH340/CP2102/FT232).
+3. Re-check with the CLI:
+
+```bash
+tyutool list-ports
+tyutool usb-port-survey # raw USB metadata for cross-system debugging
+```
+
+4. On macOS see [macOS serial permission](#macos-serial-permission).
+5. On Linux, confirm you are in the `dialout` / `tty` group and log out and back in.
+
+:::tip
+Click refresh or reopen the app.
+:::
+
+### macOS serial permission
+**Symptom:** the port is visible but you get a permission error.
+
+```bash
+sudo dseditgroup -o edit -a $USER -t user dialout
+```
+
+Then log out and back in. On newer macOS, allow it under **Privacy & Security → Accessories**. See the project [README Troubleshooting](https://github.com/tuya/tyutool#readme).
+
+### Port busy
+**Symptom:** `Permission denied` / `Device or resource busy`.
+
+Close other programs (Serial Debug, Arduino IDE, minicom, picocom); avoid running the GUI and CLI at the same time; you can turn on auto-release.
+
+## Flashing
+
+### Flash fails / handshake fails
+**Symptom:** Handshake failed / Failed to sync.
+
+Causes: wrong chip model (`-d bk7231n` / `-d esp32` / `-d t5ai`); wrong baud (drop to 115200 first); device not in download mode (`tyutool reset`); wiring / power.
+
+:::warning
+First do a minimal repro: `tyutool read -d 
+
+*Flash page connection bar — serial dropdown, baud rate, chip selector, status dot.*
+
+## Connection bar
+
+- **Serial** (rescanned each time you open it)
+- **Baud rate** — `115200` / `460800` / `921600` / `1000000` / `1500000` / `2000000`, plus custom (300–4,000,000). Under the Authorize tab this is the authorization baud rate.
+- **Chip selector** — under Authorize, an extra `other` option appears.
+- **Status dot** — green = connected and ready; gray/red = not connected or handshake failed.
+
+:::note[Auto-connect / auto-release]
+tyutool connects automatically when you start an operation and releases the port when it finishes.
+:::
+
+## Select a chip
+The authoritative chip list (source: `chip-manifests.ts`):
+
+| Chip (`-d`) | Flash baud | Auth baud | Flash capacity | Erase presets |
+| :-- | :-- | :-- | :-- | :-- |
+| `esp32` | 460800 | 115200 | 4 MiB | fullChip |
+| `esp32c3` | 460800 | 115200 | 4 MiB | fullChip |
+| `esp32c6` | 460800 | 115200 | 8 MiB | fullChip |
+| `esp32p4` | 460800 | 115200 | 16 MiB | fullChip |
+| `esp32s3` | 460800 | 115200 | 16 MiB | fullChip |
+| `t5ai` (alias `t5`) | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf |
+| `t1` | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf |
+| `t3` | 921600 | 115200 | 4 MiB | authInfo, fullChipNoRf |
+| `t2` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf |
+| `bk7231n` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf |
+| `ln882h` | 115200 | 115200 | 2 MiB | fullChip |
+| `other` (auth only) | — | 115200 | — | none |
+
+:::note
+`t5ai` is selected by default; the legacy `t5`/`T5` aliases normalize to `t5ai`.
+:::
+
+:::tip
+The flash baud is adjustable, but going above `2000000` is not recommended.
+:::
+
+:::info
+Erase requires 4 KiB alignment (a multiple of `0x1000`); only `other` is exempt.
+:::
+
+## Flash tab — flashing
+Multi-segment flashing: up to 10 segments, each with a firmware path (`.bin`/`.hex`/`.elf`/`.img`) plus a start/end address (hexadecimal). A new segment's start defaults to the previous segment's end; once you pick firmware, the end address is auto-computed as start + file size. The Flash button is only enabled once every segment is filled in.
+
+
+
+*Flash tab — multi-segment flashing with firmware path and start/end addresses.*
+
+:::tip
+Typical use case: write a bootloader + app in one pass.
+:::
+
+## Erase tab — erasing
+Erase by address (alignment is validated in real time) or use an advanced erase preset (same meanings as in [Concepts](./concepts.md#authorize): `authInfo` / `fullChipNoRf` / `fullChip`). A confirmation dialog runs before execution; when an address is unaligned, an "align" action is offered.
+
+:::danger[Erase destroys data]
+Erase is irreversible. A full-chip erase that clears the RF cal region may leave the device unable to connect to a network. Back up first.
+:::
+
+
+
+*Erase tab — erase by address and the advanced erase presets.*
+
+## Read tab — reading
+
+Used for backup. Choose the save directory (Tauri) or let the browser download; the default filename is `tyutool_read_
+
+*Read tab — read the flash to a file for backup.*
+
+## Authorize tab — authorizing
+
+TuyaOpen UART authorization writes `UUID` + `AuthKey` (shown masked, not copyable); a Copy credentials button is available. External links point to TuyaOpen authorization purchase and the localization docs. Operations:
+
+- **Read Auth** — reads authorization, only holds the port, writes nothing.
+- **Authorize** — writes; requires `UUID` + `AuthKey` filled in first and runs a confirmation flow.
+
+:::danger
+Keep your credentials safe (they are purchased). The `other` chip supports authorization only and has no flash plugin.
+:::
+
+
+
+*Authorize tab — UUID/AuthKey entry (masked), read-auth and authorize actions.*
+
+## Progress and log
+
+The always-on panel on the right: a phased progress bar (each phase has its own color, percentage, and indeterminate state) plus a log panel (toggle auto-scroll, clear, copy).
+
+
+
+*Progress bar and log panel — phased progress with log entries.*
+
+## Port contention
+
+The Flash page shares the same set of serial ports with the [Serial Debug](./serial-debug.md#auto-release--auto-save) page.
+
+:::warning
+When a port is busy, tyutool asks you to release it first; you can turn on auto-release in Serial Debug (see [Serial Debug](./serial-debug.md#auto-release--auto-save)).
+:::
diff --git a/docs/tyutool/getting-started.md b/docs/tyutool/getting-started.md
new file mode 100644
index 000000000..d406a877e
--- /dev/null
+++ b/docs/tyutool/getting-started.md
@@ -0,0 +1,124 @@
+---
+title: "Getting Started: First Flash"
+sidebar_label: Getting Started
+description: "Walk from a fresh tyutool install to a successful first firmware flash in 5–10 minutes — prerequisites, connection, and flashing steps."
+keywords:
+ - tyutool getting started
+ - first flash
+ - connect device
+ - flashing
+ - tuyaopen
+---
+
+import FeatureCardGrid from '@site/src/components/FeatureCardGrid';
+
+This page walks you from "I just downloaded the app" all the way to "I flashed my first device." The path is linear — read it in order and you will complete your first flash, typically in 5–10 minutes.
+
+:::tip[Read first]
+If you have never flashed firmware before, read [Concepts](./concepts.md) first.
+:::
+
+## Prerequisites
+
+Before you start, confirm everything on this checklist is ready — flashing needs both hardware and software, and none of it is optional.
+
+- **A supported device.** tyutool targets Tuya ecosystem IoT devices; for the exact supported chip models see the [firmware flash](./flash.md#select-a-chip) page.
+- **A USB-to-serial adapter.** Connect it to the device's UART (TX/RX/GND, and power if needed). Wiring must be **crossed**: your computer's TX goes to the device's RX, and vice versa.
+- **The device in download/flash mode.** Different devices enter this mode in different ways (button combinations, shorted solder pads, power-on timing).
+
+:::warning
+Wiring and how to enter download mode are **device-specific** — there is no universal procedure. Check your device's manual or the [FAQ](./faq.md#device--serial-port-not-in-the-dropdown) first. tyutool **cannot** switch a device into download mode for you; you must do it manually. When the device is not in download mode, tyutool will keep waiting for the handshake and eventually time out. See [Concepts](./concepts.md#serial--uart--baud-rate) for the relevant terms (UART / download mode / baud rate).
+:::
+
+## Download and install
+
+tyutool ships pre-built installers for Windows, macOS, and Linux. Go to the project README's download table, pick the build for your OS, and install it the usual way. Common platform pitfalls (full details in the [FAQ](./faq.md)):
+
+:::warning[macOS serial permission]
+macOS forbids normal users from accessing serial devices by default. Add your user to the `dialout` group, then **log out and back in** for it to take effect:
+
+```bash
+sudo dseditgroup -o edit -a $USER -t user dialout
+```
+
+See the [FAQ](./faq.md#macos-serial-permission) for more.
+:::
+
+:::warning[Linux blank window]
+On some Linux desktops tyutool starts with an empty, unrendered window. Work around it by setting this environment variable before launch:
+
+```bash
+WEBKIT_DISABLE_COMPOSITING_MODE=1 ./tyutool-gui_linux_x86_64_appimage_x.x.x.AppImage
+```
+
+See the [FAQ](./faq.md#linux-blank-window-webkit-compositing-failure) for more.
+:::
+
+:::tip
+These snags are **environment** problems, unrelated to tyutool itself; once solved they tend to stay solved.
+:::
+
+## First launch
+
+Once installed, start tyutool. The main window has two parts: a navigation **sidebar** on the left and the workspace for the active feature on the right. The sidebar has four main entries:
+
+- **Flash** (firmware flashing) — flash, read, and erase the flash chip.
+- **Serial Debug** — send and receive serial data in real time and inspect device logs.
+- **Toolbox** — a collection of auxiliary tools.
+- **Settings** — configure paths, log levels, and other application options.
+
+The rest of this page all happens on the **Flash** page — the only entry point you need to care about for your first flash.
+
+
+
+*tyutool main window on the Flash page, with the serial dropdown open and showing detected ports.*
+
+## Connect the device
+
+Once the wiring is checked and the device is in download mode, build the connection in tyutool in this order:
+
+1. Plug the USB-to-serial adapter into your computer's USB port.
+2. On the Flash page, click the **serial** dropdown.
+3. Select your adapter from the listed ports (e.g. `COM3` / `/dev/ttyUSB0` / `/dev/cu.SLAB_USBtoUART`).
+4. Watch the **status dot** next to it: green means connected and ready; gray or red means not connected or handshake failed.
+
+After you pick a port, tyutool **auto-fills** the recommended baud rate and chip model — you can accept them as-is. **Higher** is faster but more prone to failure; **lower** is slower but steadier. See [Firmware Flash](./flash.md#flash-tab--flashing).
+
+:::tip
+If no ports show in the dropdown, first confirm the adapter is plugged in and its driver is installed (CH340/CP2102/FT232), and check your macOS/Linux serial access permissions (see the installation notes above).
+:::
+
+## Complete your first flash
+
+Once the device is connected, the flash itself is short. Walk these steps in order to write your first firmware:
+
+1. **Select the chip model.** At the top of the Flash page, pick the chip that matches your device — the model decides the communication protocol and address layout, and picking the wrong one fails the flash.
+2. **Select firmware.** Switch to the **Flash** tab, click to choose a firmware file, and pick a `.bin` firmware.
+3. **Confirm the address.** After you pick firmware, the write address is **auto-filled** to a default and usually needs no change.
+4. **Start flashing.** Click the **Flash** button to begin writing.
+5. **Watch progress.** Keep an eye on the progress bar and the log below; it should advance steadily to 100%.
+6. **Wait for reboot.** When writing finishes, the device **reboots automatically** and runs the new firmware — your first flash is complete.
+
+
+
+*Flash page mid-flash — chip and firmware selected, port connected, and the flash in progress at 25%, with numbered callouts matching the steps above.*
+
+For the advanced options at each step (address tweaking, erase strategy, verification, saving logs, etc.), see the [Firmware Flash](./flash.md) page.
+
+:::danger
+While flashing, **never** unplug the USB cable or cut power — you may corrupt the data. If a flash fails, first drop to `115200` baud and retry; if it still fails, see the [FAQ](./faq.md#flash-fails--handshake-fails).
+:::
+
+## Next steps
+
+Congratulations on your first flash! From here, dive into each feature page as needed:
+
+
+
+*Serial Debug overview — terminal workspace with log view and send bar.*
+
+:::note
+The serial ports here are shared with the [Firmware Flash](./flash.md) page.
+:::
+
+## Connection and serial config
+Serial selection (rescan) / connect-disconnect / status indicator. The advanced UART settings live in the serial-settings dialog:
+
+| Parameter | Options | Notes |
+| :-- | :-- | :-- |
+| Baud rate | `9600`–`921600` + custom | When unset, defaults to the current flash chip's log baud rate |
+| Data bits | `5` / `6` / `7` / `8` | Data bits per frame |
+| Parity | `none` / `odd` / `even` | None / odd / even |
+| Stop bits | `1` / `1.5` / `2` | Stop bits per frame |
+
+:::tip[Baud follows the chip]
+Pick a chip on the Flash page first and the Serial Debug baud rate aligns to it automatically.
+:::
+
+## Device reset
+
+Reset via DTR/RTS. Reset the current session port, or reset another controlled port (use the runtime chip id to target a different port).
+
+:::note
+Reset is not the same as disconnect.
+:::
+
+## Log view
+ASCII view / Hex view (8/16/32 bytes per row); ANSI coloring toggle; font size 10–18px; timestamp toggle; direction badges (TX/RX/SYS); clear; export.
+
+
+
+*Log rows with RX badges and timestamps, with the Serial Settings dialog open — data bits, parity, stop bits, auto-release for flash, hex view, and ANSI color parsing.*
+
+:::warning[3000-line visible window cap]
+Older rows are removed once the visible window exceeds 3000 lines. Use auto-save or export promptly.
+:::
+
+## Send bar
+
+ASCII or Hex mode; optional `\r\n`; press `Enter` to send; history holds up to 20 entries, cycle with `↑` / `↓`.
+
+
+
+*Send bar with a command list open above the input, and live log rows with RX badges in the background.*
+
+## Hex popup
+
+Select a span of RX data and the popup shows hex + ASCII side by side.
+
+:::tip
+Useful for checking structured binary (protocol frames, authorization replies).
+:::
+
+## Filter tabs
+
+Give each keyword its own tab. A keyword can be plain text or a regular expression; tabs cycle through six colors, count matches live, and clicking a tab shows only matching rows. "All" restores the full view and "Load earlier" pages back. Filtering runs server-side against the whole session.
+
+
+
+*Filter tabs — keyword tabs with live match counts and color coding.*
+
+## Auto-release / auto-save
+- **Auto-release** solves port contention. When the Flash page needs a port, Serial Debug releases it automatically (an optional confirmation prompt can be turned on); once flashing finishes, the connection is restored automatically.
+- **Auto-save** keeps the full session log (also configurable under [Settings](./settings.md#serial-logs)). Set the save directory; filenames are timestamped; writes are chunked (max 128 KiB).
+
+:::note
+Manual export = the current visible window; auto-save = the whole session.
+:::
diff --git a/docs/tyutool/settings.md b/docs/tyutool/settings.md
new file mode 100644
index 000000000..833899af0
--- /dev/null
+++ b/docs/tyutool/settings.md
@@ -0,0 +1,83 @@
+---
+title: Settings
+description: "Complete reference for the tyutool Settings page — update center, appearance and language, diagnostics and logs, serial logs, about, and how settings are persisted."
+keywords:
+ - tyutool settings
+ - update center
+ - appearance
+ - diagnostics
+ - log files
+ - tuyaopen
+---
+
+This page is the complete reference for the **Settings** page: the update center, appearance and language, diagnostics and logs, serial logs, about, and how settings persist.
+
+## Update center
+- **Installed build** — the current version.
+- **Check for updates** — desktop (Tauri) only; opens the Update dialog and is not bound by the interval.
+- **Auto-check interval** — silently checks on startup and only fires once the interval has elapsed. Options: `Off` / `1h` / `6h` / `12h` / `24h`.
+
+
+
+*Update center — installed version, check-for-updates, auto-check interval.*
+
+:::note
+The web build has no auto-update (it depends on the Tauri updater plugin).
+:::
+
+## Appearance and language
+- **Theme** — `Light` / `Dark` / `System` (applies immediately; System follows the OS).
+- **Language** — `Auto` / `简体中文` / `English` (Auto: uses Chinese for a `zh`-prefixed locale).
+- **Serial indicator** toggle.
+
+
+
+*Appearance and language — theme, language, serial-indicator toggle.*
+
+:::info
+Advanced UART parameters live on the Serial Debug page (see [Serial Debug](./serial-debug.md#connection-and-serial-config)).
+:::
+
+## Diagnostics and logs
+- **Debug log toggle** — the master switch; when off, the backend log level is set to `off`.
+- **Log level** — Error / Warn / Info / Debug / Trace, applied to the Rust backend via `log::set_max_level`.
+- **Open log folder.**
+- **View logs** — opens the Log Viewer dialog.
+- **Export logs and report a problem** — zips logs and opens a pre-filled GitHub issue (version/OS included); desktop only.
+
+
+
+*Diagnostics and logs — log toggle, level, open/view/export actions.*
+
+### How log files land
+
+Logs are written by `tauri-plugin-log`. Each session is named `tyutool-
+
+*批量页面——完成横幅 / 仪表盘（烧录累计·授权累计·本次批次）/ 配置面板 / 工具栏（自动分配·串口过滤·全部读取·全部开始）/ 端口列表。*
+
+## 开工前清单
+
+| 准备项 | 怎么算就绪 |
+| :-- | :-- |
+| 桌面版 tyutool | 已安装并能启动 |
+| 授权码 Excel | 至少有 `UUID` + `AuthKey` 两列；从 [tuyaopen.ai/zh/pricing](https://tuyaopen.ai/zh/pricing) 购买 |
+| 设备 + 串口线 | 已接线，设备能进下载模式 |
+| 串口驱动 | CH340/CP2102/FT232 已装 |
+| 固件文件 | 本次批次用的 `.bin` |
+
+安装包（版本号仅作参考，始终以 [GitHub Releases](https://github.com/tuya/tyutool/releases) 为准）：
+
+| 平台 | 文件 |
+| :-- | :-- |
+| Windows | `..._windows_x86_64_nsis_x.x.x.exe` |
+| macOS（Universal） | `..._macos_universal_dmg_x.x.x.dmg` |
+| Linux | `..._linux_x86_64_appimage_x.x.x.AppImage`（先 `chmod +x`） |
+
+:::warning[T5/T5AI 接线注意]
+这些设备有两个串口——务必接烧录/授权口，不要接日志口。
+:::
+
+:::warning[授权码很贵重]
+妥善保管 Excel。
+:::
+
+### 配置交接单
+
+| 配置项 | 开发者填 | 操作员核对 |
+| :-- | :-- | :-- |
+| 芯片型号 | 如 `esp32` / `t5ai` | 与设备一致 |
+| 操作模式 | 只授权 vs 先烧再授（路径 A/B） | "烧录固件"开关一致 |
+| 固件文件与版本 | 文件名 + 版本 | `batch-summary.json` 记 SHA256 |
+| 烧录波特率 | 如 921600 | 设置正确 |
+| 授权波特率 | 如 115200 | 设置正确 |
+| 存储模式 | KV / OTP | OTP → 先单台验证 |
+| 冲突策略 | 跳过 / 覆盖 | OTP 只能跳过 |
+| 授权表 | 剩余 ≥ 本批新设备数 | 恢复/重试已登记设备不占新码 |
+| 接线 | 说明 | **确认 RTS 接到复位脚** |
+| MAC 唯一性 | 每台 MAC 全球唯一 | tyutool **不校验** MAC 冲突，重复 MAC 让设备共用授权码 |
+| 单台试通 | 已通过 | 上量前已做 |
+| 特殊事项 | — | 阅读 |
+
+:::tip
+对不上先停下来找开发者确认，不要自行改配置。
+:::
+
+## 操作流程
+
+工具箱 → 批量烧录授权。
+
+:::note
+第一次进入会弹免责声明对话框（不可逆操作），可勾"不再提示"；重显见[设置](./settings.md)。
+:::
+
+### 阶段一 · 配置
+
+1. 选芯片（ESP32 / T5AI；只授权选 `other`）。
+2. 烧录波特率。
+3. 授权波特率。
+4. 是否烧录固件（先烧再授）。
+5. 固件文件（本地 / 默认授权固件）。
+6. 选固件位置或选版本。
+
+
+
+*配置区——共享配置面板。*
+
+1. 选授权表（`.xlsx`）。
+2. 查看统计：总计 / 已用 / 占用中 / 剩余（给新设备分码需剩余 > 0；仅恢复/重试已登记设备剩余 0 也可启动，按 MAC 找回原码）。
+3. 已带授权设备：跳过（推荐）/ 覆盖。
+
+
+
+*批量授权配置——授权表统计。*
+
+（仅 T5AI）选存储模式：KV 可重写；OTP 写一次不可逆（见[安全](#安全铁律)）。
+
+### 阶段二 · 接线与启动
+
+:::tip
+先 1 台完整跑通 → 2～4 台小批量试跑 → 再上整批。
+:::
+
+接好后两步：
+
+1. 点**自动分配**（扫描加插槽，每口一行"空闲"）。
+2. 点**全部开始**（空闲端口 > 8 时先弹确认）。
+
+:::warning[启动前最后 30 秒检查]
+逐行对照交接单核对配置；OTP 是否已单台验证？
+:::
+
+
+
+*工具栏与端口列表——每口一个插槽。*
+
+:::note[工具栏其他按钮]
+**② 串口过滤 · ③ 全部读取（只读不写）· ④ 取消 · ⑤ 重试失败 · ⑦ 单口读取**。
+:::
+
+### 阶段三 · 等待与核对
+
+1. 看仪表盘等完成（完成横幅：全部成功 / 全失败 / 部分成功 / 全跳过）。
+2. 逐行核对（失败看重试）。
+3. 整单跑完点"归档"（中间轮次不用归档）。
+
+
+
+*仪表盘与完成横幅（右侧归档按钮）。*
+
+## 看懂结果
+
+| 状态 | 意思 | 做什么 |
+| :-- | :-- | :-- |
+| `done` | 完成，好品 | — |
+| `failed` | 失败 | 重试 |
+| `skipped` | 已有授权按策略跳过 | — |
+| `no_code` | 新设备但剩余 = 0 | 补表重跑 |
+| 其他 | 处理中 | 等 |
+
+## 归档
+一次"全部开始" = 一轮；一份授权表 = 一单（往往多轮）。归档以单为单位。
+
+:::info
+一键归档：选目录，建带时间戳文件夹 `batch-archive_20260717-143205_esp32/`，含：授权表副本 / 固件(含 SHA256) / logs.zip / `batch-summary.json` / `batch-slots.csv`。summary 的 lastRun 和 csv 只是最后一轮快照。
+:::
+
+档案内容：
+
+| 文件 | 是什么 |
+| :-- | :-- |
+| 授权表 Excel 副本 | 所用的表 |
+| 固件文件 | 烧录的 `.bin` |
+| logs.zip | 压缩日志 |
+| batch-summary.json | 运行汇总 |
+| batch-slots.csv | 最后一轮的按槽快照 |
+| 完成横幅截图 | 可选记录 |
+
+:::warning
+档案含 UUID + AuthKey，防泄露；排查只给日志和错误信息，授权表不外发。
+:::
+
+## 出错速查
+
+| 现象 | 处理 |
+| :-- | :-- |
+| 应用打不开 / 白屏 | 见 [FAQ · Linux 白屏](./faq.md) |
+| 端口没出现 | 换线换口、装驱动、关其他程序，见 [FAQ · 端口](./faq.md) |
+| 全部失败 | 单台试通、降到 115200、查供电 |
+| Excel"文件被占用" | 关掉 Excel/WPS 重选 |
+| Excel 表无效 | 查 `UUID` + `AuthKey` 两列及长度 |
+| 需详细日志 | 按[保存现场](#先保存现场)保存，见 [FAQ · 日志](./faq.md) |
+
+### 先保存现场
+趁现场点"归档"全存下；再手工补三样：界面截图（遮 AuthKey，UUID 可留）/ 问题设备实物（贴标签单独放）/ 一句话现象描述。
+
+:::note
+别拖也别泄露：当天归档；外发只给日志和错误信息。
+:::
+
+## 安全铁律
+这是唯一会触发不可逆硬件操作的功能。
+
+:::danger[铁律一：OTP 写一次不可逆]
+OTP（仅 T5AI）把授权烧进芯片后永远无法撤销。配错毁整批——务必先用一台完整跑通验证再批量。
+:::
+
+
+
+*选 OTP 时界面提示写入后不可撤销。*
+
+:::danger[铁律二：带"已写入后取消"危险徽标的设备必须单独放一边]
+这类设备授权可能已写、状态不确定，既不能当好品也不能直接重跑，必须单独核实。
+:::
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md
new file mode 100644
index 000000000..8d64dca96
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md
@@ -0,0 +1,45 @@
+---
+title: 批量烧录授权
+description: "tyutool 批量烧录授权总览——把多台设备插到多个串口上，并行烧录固件并写入授权码，授权码由一份 .xlsx 表格驱动。"
+keywords:
+ - tyutool 批量
+ - 批量烧录
+ - 批量授权
+ - OTP
+ - 并行烧录
+ - tuyaopen
+---
+
+import FeatureCardGrid from '@site/src/components/FeatureCardGrid';
+
+把多台设备插到多个串口上，**并行**烧录固件 + 写入授权码，授权码由一份 `.xlsx` 表格驱动。这是 tyutool 里最复杂的功能，当存储模式选 **OTP** 时会进行不可逆的 eFuse 操作（仅 T5AI）。
+
+:::note[在哪里找到它]
+桌面客户端中，这个功能位于 **工具箱（Toolbox）→ 批量烧录授权**。
+:::
+
+## 选择你的指南
+
+这个功能涉及两类完全不同的人，两份独立指南：
+
+
+
+*tyutool 主窗口停在 Flash 页，串口下拉框展开、显示已检测到的端口。*
+
+## 连接设备
+
+接线检查无误、设备已进入下载模式后，按下面顺序在 tyutool 里建立连接。
+
+1. 把 USB 转串口适配器插到电脑的 USB 口。
+2. 在 tyutool 的 Flash 页，点击**串口**下拉框。
+3. 在列出的端口里选择你的适配器（如 `COM3` / `/dev/ttyUSB0` / `/dev/cu.SLAB_USBtoUART`）。
+4. 留意旁边的**状态点**：绿色表示已连接并就绪；灰色或红色表示未连上或握手失败。
+
+选好端口后，波特率与芯片型号由 tyutool **自动填入推荐值**，可直接采用。**调高**更快但易失稳失败，**调低**更慢更稳。详见[固件烧录](./flash.md)。
+
+:::tip
+如果下拉框里看不到任何端口，先确认适配器已插好、驱动已装（CH340/CP2102/FT232），并检查 macOS/Linux 的串口访问权限（见上方安装小节）。
+:::
+
+## 完成第一次烧录
+
+设备连上后，烧录本身的操作非常简短。按顺序走完以下步骤即可写入第一份固件。
+
+1. **选择芯片型号**：在 Flash 页顶部选择你设备对应的芯片（型号决定了通信协议与地址布局，选错会烧录失败）。
+2. **选择固件**：切到 **Flash** 标签，点击选择固件文件，挑一份 `.bin` 固件。
+3. **确认地址**：选好固件后，写入地址会**自动填入**默认值，一般无需修改。
+4. **点击烧录**：点击 **Flash** 按钮开始写入。
+5. **观察进度**：盯着进度条与下方日志，正常会一路推进到 100%。
+6. **等待重启**：写入完成后设备会**自动重启**并运行新固件——到这里你的第一次烧录就完成了。
+
+
+
+*烧录页正在写入——已选好芯片与固件、端口已连接，烧录进度 25%，图上编号对应上方各步骤。*
+
+各步骤的进阶选项（地址微调、擦除策略、校验、保存日志等）请见[固件烧录](./flash.md)页。
+
+:::danger
+烧录期间**切勿**拔掉 USB 线或断电，否则可能写坏数据。万一烧录失败，先降到 `115200` 波特率重试；仍不行则参考[常见问题](./faq.md)。
+:::
+
+## 下一步
+
+恭喜完成第一次烧录！接下来可以按需求深入各个功能页：
+
+
+
+*串口调试总览——终端工作区，含日志视图与发送栏。*
+
+:::note
+这里的串口与[固件烧录](./flash.md)页共用。
+:::
+
+## 连接与串口配置
+串口选择（重扫）/ 连接-断开 / 状态指示。高级 UART 设置在串口设置弹窗：
+
+| 参数 | 可选值 | 说明 |
+| :-- | :-- | :-- |
+| 波特率 Baud | `9600`–`921600` + 自定义 | 未覆盖时默认取当前 flash 芯片的日志波特率 |
+| 数据位 Data bits | `5` / `6` / `7` / `8` | 每帧数据位数 |
+| 校验位 Parity | `none` / `odd` / `even` | 无/奇/偶 |
+| 停止位 Stop bits | `1` / `1.5` / `2` | 每帧停止位 |
+
+:::tip[波特率跟随芯片]
+先在烧录页选好芯片，串口调试波特率自动对齐。
+:::
+
+## 设备复位
+
+通过 DTR/RTS 复位。复位当前会话端口 / 复位其他控制端口（用 runtime chip id 指定另一端口）。
+
+:::note
+复位 ≠ 断开。
+:::
+
+## 日志视图
+ASCII 视图 / Hex 视图（每行 8/16/32 字节）；ANSI 着色开关；字号 10–18px；时间戳开关；方向徽标（TX/RX/SYS）；清空；导出。
+
+
+
+*日志视图——ASCII 与 Hex 行，带方向徽标与时间戳。*
+
+:::warning[可见窗口上限 3000 行]
+超出旧行移除；请用自动保存或及时导出。
+:::
+
+## 发送栏
+
+ASCII 或 Hex 模式；可选 `\r\n`；按 `Enter` 发送；历史最多 20 条，用 `↑` / `↓` 翻选。
+
+
+
+*发送栏——ASCII/Hex 模式切换、发送按钮、历史。*
+
+## Hex 弹窗
+
+选中一段 RX 数据后并排展示 hex + ASCII。
+
+:::tip
+适合核对结构化二进制（协议帧/授权回复）。
+:::
+
+## 过滤标签
+
+给关键词各建一标签。关键词可纯文本或正则；6 色循环配色；实时计数命中条数；点标签只看匹配行；"全部"恢复；"加载更早"分页。过滤在服务端针对整个会话执行。
+
+
+
+*过滤标签——关键词标签，带实时命中计数与配色。*
+
+## 自动释放 / 自动保存
+- **自动释放（Auto-release）**：解决端口争用。固件烧录页需要端口时串口调试自动释放（可开启确认提示）；烧录结束后自动恢复连接。
+- **自动保存（Auto-save）**：留存完整会话日志（也可在[设置](./settings.md)配置）。设置保存目录；时间戳文件名；分块写入（最大 128 KiB）。
+
+:::note
+手动导出 = 当前可见窗口；自动保存 = 整个会话。
+:::
diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md
new file mode 100644
index 000000000..276acf6d2
--- /dev/null
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md
@@ -0,0 +1,83 @@
+---
+title: 设置
+description: "设置页的完整参考——更新中心、外观与语言、诊断与日志、串口日志、关于，以及设置的持久化方式。"
+keywords:
+ - tyutool 设置
+ - 更新中心
+ - 外观
+ - 诊断
+ - 日志文件
+ - tuyaopen
+---
+
+本页是**设置**页的完整参考：更新中心、外观与语言、诊断与日志、串口日志、关于，以及设置的持久化方式。
+
+## 更新中心
+- **当前版本（Installed build）**。
+- **检查更新** —— 仅桌面端（Tauri），打开 Update 对话框，不受间隔限制。
+- **自动检查间隔** —— 启动时静默检查，超间隔才触发。选项：`Off` / `1h` / `6h` / `12h` / `24h`。
+
+
+
+*更新中心——当前版本、检查更新、自动检查间隔。*
+
+:::note
+Web 端无自动更新（依赖 Tauri updater 插件）。
+:::
+
+## 外观与语言
+- **主题** —— `Light` / `Dark` / `System`（立即生效，System 跟随系统）。
+- **语言** —— `Auto` / `简体中文` / `English`（Auto：`zh` 开头用中文）。
+- **串口指示器** 开关。
+
+
+
+*外观与语言——主题、语言、串口指示器开关。*
+
+:::info
+高级 UART 参数在串口调试页（见[串口调试](./serial-debug.md)）。
+:::
+
+## 诊断与日志
+- **调试日志开关** —— 总开关，关闭则后端 log level = `off`。
+- **日志级别** —— Error / Warn / Info / Debug / Trace，经 `log::set_max_level` 应用到 Rust 后端。
+- **打开日志文件夹。**
+- **查看日志** —— 打开 LogViewer 对话框。
+- **导出日志并报告问题** —— 打包日志并打开预填的 GitHub issue（含版本/OS）；仅桌面端。
+
+
+
+*诊断与日志——日志开关、级别、打开/查看/导出操作。*
+
+### 日志文件如何落地
+
+日志由 `tauri-plugin-log` 写入。按会话命名 `tyutool-<时间戳>.log`；10 MB 滚动到 `-1.log`、`-2.log`，启动时清理旧文件。日志目录：
+
+- Linux：`~/.local/share/tyutool/`
+- macOS：`~/Library/Application Support/tyutool/`
+- Windows：`%APPDATA%\tyutool\`
+
+:::note
+级别作用在 Rust 后端。
+:::
+
+## 串口日志
+串口调试自动保存的镜像入口：自动保存开关、保存目录、时间戳格式。
+
+:::note
+与串口调试页是同一份 store。
+:::
+
+## 关于
+- **应用版本。**
+- **开源许可** —— 打开 LICENSE 页面。
+
+## 持久化
+
+- **桌面端**写 `settings.json`（`tauri-plugin-store`）。
+- **Web 端**写 localStorage。
+- 主题应用到 DOM（System 模式监听系统配色）。
+
+:::note
+桌面端 `settings.json` 键名与 Web 端 localStorage 一一对应。
+:::
diff --git a/sidebars.js b/sidebars.js
index 558875e4e..12516ed82 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -7,6 +7,7 @@
// hardwareSidebar -> Hardware (/docs/hardware/*)
// cloudSidebar -> Cloud & AI (/docs/cloud/*)
// duckyclawSidebar -> TuyaOpenClaw (/docs/duckyclaw/*) (brand formerly DuckyClaw; route kept)
+// tyutoolSidebar -> tyutool (/docs/tyutool/*)
//
// SHARED / UNIVERSAL DOCS
// -----------------------
@@ -558,9 +559,33 @@ const duckyclawSidebar = [
'duckyclaw/DuckyClaw-TuyaClaw',
]
+// =============================================================================
+// tyutool (parallel to the TuyaOpen SDK docs — not nested inside them)
+// =============================================================================
+const tyutoolSidebar = [
+ { type: 'doc', id: 'tyutool/index', label: 'Overview' },
+ // Concepts before Getting Started: both pages tell readers new to flashing
+ // to read Concepts first, so the sidebar order should match that advice.
+ 'tyutool/concepts',
+ 'tyutool/getting-started',
+ 'tyutool/flash',
+ 'tyutool/serial-debug',
+ 'tyutool/settings',
+ {
+ type: 'category',
+ label: 'Batch Flash & Auth',
+ collapsed: false,
+ link: { type: 'doc', id: 'tyutool/batch-flash-auth' },
+ items: ['tyutool/batch-auth-operator', 'tyutool/batch-auth-developer'],
+ },
+ 'tyutool/cli',
+ 'tyutool/faq',
+]
+
module.exports = {
sdkSidebar,
hardwareSidebar,
cloudSidebar,
duckyclawSidebar,
+ tyutoolSidebar,
}
diff --git a/src/components/FeatureCardGrid.jsx b/src/components/FeatureCardGrid.jsx
new file mode 100644
index 000000000..91b59e3af
--- /dev/null
+++ b/src/components/FeatureCardGrid.jsx
@@ -0,0 +1,29 @@
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import styles from './FeatureCardGrid.module.css';
+
+export default function FeatureCardGrid({ items = [], columns = 3 }) {
+ if (!items.length) return null;
+
+ const colClass = `col--${Math.max(1, Math.round(12 / columns))}`;
+
+ return (
+
-
- {fromLearn ? learnLabel : c.backToOverview}
-
- {c.badge}
-
- {c.title}
-{c.subtitle}
-
- {/* ----------------------------------------------------- TOC */}
-
-
- {/* ------------------------------------------------- Content */}
-
-
- {/* Install */}
-
-
-
- {/* First flash */}
-
-
-
- {/* Authorize */}
-
-
-
- {/* Serial debug */}
-
-
-
- {/* Batch */}
-
-
-
- {/* CLI reference */}
-
-
-
- {/* Troubleshooting */}
-
-
-
- {/* Getting help */}
-
-
-
- {c.install.title}
-{c.install.intro}
- - {c.install.releasesBtn} - -
- {c.install.platforms.map((p) => (
-
-
-
- ))}
- {p.name}
--
- {p.steps.map((s, i) => (
-
- {s} - ))} -
- ℹ️
-
- {c.install.cliNote}
-{c.firstFlash.title}
-
-
-
-
- {c.firstFlash.guiTitle}
--
- {c.firstFlash.guiSteps.map((s, i) => (
-
- {s} - ))} -
- 💡
-
- {c.firstFlash.tip}
-{c.firstFlash.cliTitle}
-{c.firstFlash.cliIntro}
-{c.firstFlash.cliCode}
- {c.authorize.title}
-{c.authorize.intro}
-
-
- 
- {c.authorize.authShot}
-
-
- -
- {c.authorize.guiSteps.map((s, i) => (
-
- {s} - ))} -
{c.authorize.cliTitle}
-{c.authorize.cliCode}
-
- ℹ️
-
-
- {c.authorize.where}
-
- - {c.authorize.whereBody}{' '} - - {c.authorize.platformLink} - - . -
-{c.authorize.authOnly}
-{c.serial.title}
-{c.serial.intro}
-
-
- -
- {c.serial.points.map((p, i) => (
-
- {p} - ))} -
- 💡
-
- {c.serial.note}
-{c.batch.title}
-{c.batch.intro}
-
-
- -
- {c.batch.points.map((p, i) => (
-
- {p} - ))} -
{c.cli.title}
-{c.cli.intro}
-
-
-
-
-
- | {c.cli.headers[0]} | -{c.cli.headers[1]} | -
|---|---|
- {r[0]}
- |
- {r[1]} | -
{c.cli.globalsTitle}
-
-
-
- {c.cli.globals.map((r, i) => (
-
-
-
- {c.cli.fullRef} →
-
-
- {r[0]}
- |
- {r[1]} | -
{c.trouble.title}
-
- {c.trouble.items.map((item, i) => (
-
-
-
- ))}
- {item.q}
-
-
- {item.body}
- {item.code &&{item.code}}
- {item.links && (
-
- {item.links.map((l) => (
-
- {l.label} →
-
- ))}
-
- )}
- {c.help.title}
-{c.help.intro}
--
- {c.help.points.map((p, i) => (
-
- {p} - ))} -
{c.help.logPaths}
- -