diff --git a/apps/web/src/App.tsx b/apps/web/src/App.tsx
index 49c15d0f..879da483 100644
--- a/apps/web/src/App.tsx
+++ b/apps/web/src/App.tsx
@@ -1,3 +1,5 @@
+// Web app root. App walks start-up (Desktop setup, install and connection, login, onboarding,
+// model setup); AuthenticatedWorkspace then renders the signed-in workspace and its unread counts.
 import type { ApprovalDecision, AuthSessionSnapshot, Channel, RunFrame } from "@openbot/domain";
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
index f15a4dba..b0d50174 100644
--- a/apps/web/src/api.ts
+++ b/apps/web/src/api.ts
@@ -1,3 +1,5 @@
+// Browser client for the Server's /api/v1 routes and realtime streams. Responses are validated
+// before the UI uses them; the Server stays the source of truth for state and authorization.
 import type {
   Approval,
   ApprovalDecision,
diff --git a/apps/web/src/artifact-shell-save.ts b/apps/web/src/artifact-shell-save.ts
index 4068c4c6..57275d19 100644
--- a/apps/web/src/artifact-shell-save.ts
+++ b/apps/web/src/artifact-shell-save.ts
@@ -1,3 +1,4 @@
+// Lets an artifact card save a report through the Desktop shell instead of a browser download.
 import { getOpenBotDesktopBridge } from "./desktop-runtime";
 
 export type ArtifactSaveStatus = "saved" | "cancelled" | "busy" | "unavailable" | "exists";
diff --git a/apps/web/src/auth-session-recovery.ts b/apps/web/src/auth-session-recovery.ts
index 5fc72d0e..26a2d662 100644
--- a/apps/web/src/auth-session-recovery.ts
+++ b/apps/web/src/auth-session-recovery.ts
@@ -1,3 +1,4 @@
+// Reads the Owner's sign-in session at start-up and, on a local Desktop host, restores it once.
 import type { AuthSessionSnapshot } from "@openbot/domain";
 
 /** Recover identity only; never replay the operation that received HTTP 401. */
diff --git a/apps/web/src/bounded-response.ts b/apps/web/src/bounded-response.ts
index 937c07d1..8a5906a3 100644
--- a/apps/web/src/bounded-response.ts
+++ b/apps/web/src/bounded-response.ts
@@ -1,3 +1,4 @@
+// Reads a fetch response body with a byte limit, so a large or endless body cannot exhaust memory.
 export interface BoundedResponseMessages {
   readonly missingBody: string;
   readonly tooLarge: string;
diff --git a/apps/web/src/channel-attachment-client.ts b/apps/web/src/channel-attachment-client.ts
index 286a21c8..5c37e186 100644
--- a/apps/web/src/channel-attachment-client.ts
+++ b/apps/web/src/channel-attachment-client.ts
@@ -1,3 +1,5 @@
+// Channel file client: fetch, preview, rename, download and 回收站 purge/cleanup of attachments,
+// plus file-name formatting shared by the composer, messages, task cards and the 文件 manager.
 import {
   type AttachmentOperation,
   attachmentByteLimit,
diff --git a/apps/web/src/color-scheme.ts b/apps/web/src/color-scheme.ts
index 32f7eff1..a3d48e9f 100644
--- a/apps/web/src/color-scheme.ts
+++ b/apps/web/src/color-scheme.ts
@@ -1,3 +1,5 @@
+// Light/dark/system colour scheme: resolves the Owner's choice and sets it on the page root. On
+// Desktop the main process owns the choice and this module syncs with it through the bridge.
 import { getOpenBotDesktopBridge } from "./desktop-runtime";
 import type { WorkspacePreferences } from "./workspace-preferences";
 
diff --git a/apps/web/src/components/AddMemberPopover.tsx b/apps/web/src/components/AddMemberPopover.tsx
index 3155fa44..c4f0ce5e 100644
--- a/apps/web/src/components/AddMemberPopover.tsx
+++ b/apps/web/src/components/AddMemberPopover.tsx
@@ -1,3 +1,5 @@
+// 添加成员 popover (AddMember artboard): searches the Bots not yet in a 频道 and adds the chosen one.
+// Opened from the members tab of the channel context rail.
 import type { Bot } from "@openbot/domain";
 import { type KeyboardEvent, useEffect, useId, useRef, useState } from "react";
 import { RobotAvatar } from "./RobotAvatar";
diff --git a/apps/web/src/components/ApprovalCard.tsx b/apps/web/src/components/ApprovalCard.tsx
index 922c9897..03f18bf8 100644
--- a/apps/web/src/components/ApprovalCard.tsx
+++ b/apps/web/src/components/ApprovalCard.tsx
@@ -1,3 +1,5 @@
+// One pending approval: risk, expiry, summary and target, with 拒绝 / 批准 buttons that send the
+// Owner's decision. Used in the rail's approval stack and inside task cards.
 import type { Approval, ApprovalDecision, Bot, Channel } from "@openbot/domain";
 import { useState } from "react";
 import "./ApprovalCard.css";
diff --git a/apps/web/src/components/ApprovalStack.tsx b/apps/web/src/components/ApprovalStack.tsx
index 049ffa05..02620d90 100644
--- a/apps/web/src/components/ApprovalStack.tsx
+++ b/apps/web/src/components/ApprovalStack.tsx
@@ -1,3 +1,4 @@
+// 需要处理 approval stack in the right rail (LongLists): soonest-expiring approval on top.
 import type { Approval, ApprovalDecision, Bot, Channel } from "@openbot/domain";
 import { useState } from "react";
 import { ApprovalCard } from "./ApprovalCard";
diff --git a/apps/web/src/components/ArtifactCard.tsx b/apps/web/src/components/ArtifactCard.tsx
index 2b65e4ee..0f5ae48a 100644
--- a/apps/web/src/components/ArtifactCard.tsx
+++ b/apps/web/src/components/ArtifactCard.tsx
@@ -1,3 +1,5 @@
+// Card and download link for a Bot's output file (PNG image or Markdown report). Downloads go
+// through the Desktop shell's save dialog when one is available, else the browser.
 import type { Artifact } from "@openbot/domain";
 import { type ReactNode, useState } from "react";
 import { getArtifactShellSaver } from "../artifact-shell-save";
diff --git a/apps/web/src/components/AttachmentActions.tsx b/apps/web/src/components/AttachmentActions.tsx
index 56286a88..ab6dbf4c 100644
--- a/apps/web/src/components/AttachmentActions.tsx
+++ b/apps/web/src/components/AttachmentActions.tsx
@@ -1,3 +1,5 @@
+// 附件操作 menu on one attachment: extract text, OCR or transcribe, move to or restore from the
+// 回收站, and download. Shown in the composer picker and on message attachments.
 import type { AttachmentOperation } from "@openbot/protocol";
 import { useEffect, useRef, useState } from "react";
 import {
diff --git a/apps/web/src/components/AttachmentPreview.tsx b/apps/web/src/components/AttachmentPreview.tsx
index 75d3ffd8..27da7c2b 100644
--- a/apps/web/src/components/AttachmentPreview.tsx
+++ b/apps/web/src/components/AttachmentPreview.tsx
@@ -1,3 +1,5 @@
+// Attachment thumbnail: PNG/JPEG files load as an image that expands in a modal; other files show
+// their extension badge.
 import { useEffect, useState } from "react";
 import { extensionOf, getAttachmentImage } from "../channel-attachment-client";
 import type { UploadedComposerAttachment } from "../composer-context";
diff --git a/apps/web/src/components/AttachmentsManager.tsx b/apps/web/src/components/AttachmentsManager.tsx
index 60db9203..80e9fdfb 100644
--- a/apps/web/src/components/AttachmentsManager.tsx
+++ b/apps/web/src/components/AttachmentsManager.tsx
@@ -1,3 +1,5 @@
+// 频道文件 dialog (ChannelFiles artboard): uploads and Bot outputs, the 回收站, permanent delete and
+// 查看引用. Also exports the hook that loads a channel's attachment list.
 import type { Artifact } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/AutomationsScreen.tsx b/apps/web/src/components/AutomationsScreen.tsx
index eeb773fe..5188d894 100644
--- a/apps/web/src/components/AutomationsScreen.tsx
+++ b/apps/web/src/components/AutomationsScreen.tsx
@@ -1,3 +1,5 @@
+// Settings → 例行任务 (SettingsRoutines artboard): lists, creates, pauses and deletes the Server's
+// scheduled routines for the workspace's Bots.
 import type { Bot, Channel } from "@openbot/domain";
 import { type FormEvent, useCallback, useEffect, useRef, useState } from "react";
 import { ApiError } from "../api";
diff --git a/apps/web/src/components/AvatarEditor.tsx b/apps/web/src/components/AvatarEditor.tsx
index 6bc2327d..ff9f1500 100644
--- a/apps/web/src/components/AvatarEditor.tsx
+++ b/apps/web/src/components/AvatarEditor.tsx
@@ -1,3 +1,5 @@
+// 编辑头像 popover on the Bot 信息 rail (BotInfo artboard): random, reset, head shape and jaw colour,
+// each saved at once against the profile revision.
 import type { Bot, BotAppearance, EmployeeProfile } from "@openbot/domain";
 import { type CSSProperties, useEffect, useRef, useState } from "react";
 import { ApiError, updateBotAppearance } from "../api";
diff --git a/apps/web/src/components/BotInfoRail.tsx b/apps/web/src/components/BotInfoRail.tsx
index a0d7da21..57706b7b 100644
--- a/apps/web/src/components/BotInfoRail.tsx
+++ b/apps/web/src/components/BotInfoRail.tsx
@@ -1,3 +1,5 @@
+// Bot 信息 rail beside a 单聊 (BotInfo artboard): details (name, tag, 介绍, avatar, approvals,
+// routines), work, library and computer tabs for one Bot. Edits go through revision-checked routes.
 import type {
   ApprovalDecision,
   Bot,
diff --git a/apps/web/src/components/BrandMark.tsx b/apps/web/src/components/BrandMark.tsx
index 6650868a..18744566 100644
--- a/apps/web/src/components/BrandMark.tsx
+++ b/apps/web/src/components/BrandMark.tsx
@@ -1,3 +1,5 @@
+// Logos for model providers and plugins (LobeHub icons, SVG Logos), falling back to a letter.
+// Presentation only: a logo never says what a plugin may do.
 import discord from "@iconify-icons/logos/discord-icon";
 import figma from "@iconify-icons/logos/figma";
 import github from "@iconify-icons/logos/github-icon";
diff --git a/apps/web/src/components/ChannelWorkspace.tsx b/apps/web/src/components/ChannelWorkspace.tsx
index 57ad040d..9d2becb9 100644
--- a/apps/web/src/components/ChannelWorkspace.tsx
+++ b/apps/web/src/components/ChannelWorkspace.tsx
@@ -1,3 +1,5 @@
+// The open conversation (Main and Composer artboards): message list with task cards and replies,
+// and the composer with @ recipients, / skills, attachments and voice input.
 import type {
   Approval,
   ApprovalDecision,
diff --git a/apps/web/src/components/ComposerAttachmentPicker.tsx b/apps/web/src/components/ComposerAttachmentPicker.tsx
index c2e43677..6871440f 100644
--- a/apps/web/src/components/ComposerAttachmentPicker.tsx
+++ b/apps/web/src/components/ComposerAttachmentPicker.tsx
@@ -1,3 +1,5 @@
+// Composer attachment strip: pick, drag-drop or paste files, upload them and show the draft's
+// attachments, within the per-message limit of 8 files and 20 MB.
 import { type RefObject, useEffect, useRef, useState } from "react";
 import { extensionOf, formatAttachmentSize, middleEllipsis } from "../channel-attachment-client";
 import {
diff --git a/apps/web/src/components/ContextRail.tsx b/apps/web/src/components/ContextRail.tsx
index ac470d26..bee272a7 100644
--- a/apps/web/src/components/ContextRail.tsx
+++ b/apps/web/src/components/ContextRail.tsx
@@ -1,3 +1,5 @@
+// Right rail for a 频道 (Main and ChannelInfo artboards): details, 资料库 and members tabs, with
+// approvals, recent runs and work computers. A 单聊 uses BotInfoRail instead.
 import type {
   ApprovalDecision,
   Artifact,
diff --git a/apps/web/src/components/DeleteIdentityDialog.tsx b/apps/web/src/components/DeleteIdentityDialog.tsx
index ea49d617..8e5138b4 100644
--- a/apps/web/src/components/DeleteIdentityDialog.tsx
+++ b/apps/web/src/components/DeleteIdentityDialog.tsx
@@ -1,3 +1,5 @@
+// Permanent-delete confirmation for a Bot or 频道 (DialogDelete artboard). The Server decides what is
+// removed and may refuse; closing never deletes.
 import type { Bot, Channel } from "@openbot/domain";
 import { useState } from "react";
 import { ApiError } from "../api";
diff --git a/apps/web/src/components/DesktopConnectionScreen.tsx b/apps/web/src/components/DesktopConnectionScreen.tsx
index 44ab9e27..cfe507c7 100644
--- a/apps/web/src/components/DesktopConnectionScreen.tsx
+++ b/apps/web/src/components/DesktopConnectionScreen.tsx
@@ -1,3 +1,4 @@
+// Desktop onboarding step 连接服务电脑: enter the server computer's URL and connect to it.
 import { type FormEvent, useState } from "react";
 import type {
   ConfigureDesktopServerResult,
diff --git a/apps/web/src/components/DesktopInstallScreen.tsx b/apps/web/src/components/DesktopInstallScreen.tsx
index fff31e61..c5e5ecc2 100644
--- a/apps/web/src/components/DesktopInstallScreen.tsx
+++ b/apps/web/src/components/DesktopInstallScreen.tsx
@@ -1,3 +1,4 @@
+// Desktop onboarding progress screen while the bundled server installs or resumes on this computer.
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { NativeServerState, OpenBotDesktopBridge } from "../desktop-runtime";
 import { LaunchScreen, OnboardingFrame } from "./Onboarding";
diff --git a/apps/web/src/components/DesktopLocalWorkerScreen.tsx b/apps/web/src/components/DesktopLocalWorkerScreen.tsx
index 264dda81..c522fc33 100644
--- a/apps/web/src/components/DesktopLocalWorkerScreen.tsx
+++ b/apps/web/src/components/DesktopLocalWorkerScreen.tsx
@@ -1,3 +1,4 @@
+// Desktop onboarding step 让这台电脑也能干活: register this computer as a work computer for Bots.
 import { type FormEvent, useState } from "react";
 import type {
   DesktopLocalWorkerOperationResult,
diff --git a/apps/web/src/components/DesktopSettingsScreen.tsx b/apps/web/src/components/DesktopSettingsScreen.tsx
index 48de8a0e..70fdd9e6 100644
--- a/apps/web/src/components/DesktopSettingsScreen.tsx
+++ b/apps/web/src/components/DesktopSettingsScreen.tsx
@@ -1,3 +1,5 @@
+// Settings dialog (SettingsNav artboard): grouped section list with search, the 通用 section, and
+// the switch that renders every other Settings* section.
 import { useEffect, useState } from "react";
 import { colorSchemeAvailable, sendDesktopColorScheme } from "../color-scheme";
 import {
diff --git a/apps/web/src/components/DesktopSetupScreen.tsx b/apps/web/src/components/DesktopSetupScreen.tsx
index 02245b4c..c03c1a7d 100644
--- a/apps/web/src/components/DesktopSetupScreen.tsx
+++ b/apps/web/src/components/DesktopSetupScreen.tsx
@@ -1,3 +1,4 @@
+// Desktop first-run 欢迎使用 OpenBot: choose whether this computer hosts the server or connects to one.
 import { type FormEvent, useState } from "react";
 import type {
   DesktopSetupPlanInput,
diff --git a/apps/web/src/components/Dialog.tsx b/apps/web/src/components/Dialog.tsx
index be4b0aef..96cb335e 100644
--- a/apps/web/src/components/Dialog.tsx
+++ b/apps/web/src/components/Dialog.tsx
@@ -1,3 +1,4 @@
+// Shared modal dialog frame (DESIGN.md › Dialogs) on a native <dialog>; callers supply the actions.
 import { type CSSProperties, type ReactNode, useId } from "react";
 import { useModalDialog } from "./useModalDialog";
 
diff --git a/apps/web/src/components/EmployeeBrowser.tsx b/apps/web/src/components/EmployeeBrowser.tsx
index 942582ff..ee44f5ca 100644
--- a/apps/web/src/components/EmployeeBrowser.tsx
+++ b/apps/web/src/components/EmployeeBrowser.tsx
@@ -1,3 +1,5 @@
+// 员工浏览器 dialog (EmployeeBrowser artboard): live view of a Bot's Docker browser, where the Owner
+// can take control (接管), navigate, click, type and scroll, then hand it back to the Bot.
 import type { Bot } from "@openbot/domain";
 import type { BrowserAction, BrowserSessionView } from "@openbot/protocol";
 import { useCallback, useEffect, useRef, useState } from "react";
diff --git a/apps/web/src/components/EmployeeEvolutionArchive.tsx b/apps/web/src/components/EmployeeEvolutionArchive.tsx
index 25372247..1854c508 100644
--- a/apps/web/src/components/EmployeeEvolutionArchive.tsx
+++ b/apps/web/src/components/EmployeeEvolutionArchive.tsx
@@ -1,3 +1,4 @@
+// Helpers for the Bot rail's 工作 → 成长 list: filter, label and date the Server's evolution events.
 import type {
   EmployeeEvidenceKind,
   EmployeeEvolutionEvent,
diff --git a/apps/web/src/components/EmployeeMemoryPanel.tsx b/apps/web/src/components/EmployeeMemoryPanel.tsx
index 7b3c9431..803c7c01 100644
--- a/apps/web/src/components/EmployeeMemoryPanel.tsx
+++ b/apps/web/src/components/EmployeeMemoryPanel.tsx
@@ -1,3 +1,5 @@
+// Settings → 记忆 for one Bot (ProfileMemory artboard): candidate knowledge to review, then its
+// long-term memories with search, type filter and per-memory model-use switch.
 import type { CreateEmployeeMemoryInput, EmployeeMemory, EmployeeProfile } from "@openbot/domain";
 import { type FormEvent, type ReactNode, useId, useMemo, useState } from "react";
 import { createEmployeeMemory, deleteEmployeeMemory, updateEmployeeMemory } from "../api";
diff --git a/apps/web/src/components/EmployeeSkillImport.tsx b/apps/web/src/components/EmployeeSkillImport.tsx
index 1e00f866..8d56e80d 100644
--- a/apps/web/src/components/EmployeeSkillImport.tsx
+++ b/apps/web/src/components/EmployeeSkillImport.tsx
@@ -1,3 +1,4 @@
+// 导入 SKILL.md button: uploads one skill file as a candidate that is used only after review.
 import { type FormEvent, useState } from "react";
 import { importEmployeeSkill } from "../api";
 
diff --git a/apps/web/src/components/EmployeeSkillReview.tsx b/apps/web/src/components/EmployeeSkillReview.tsx
index a72ebeef..28068033 100644
--- a/apps/web/src/components/EmployeeSkillReview.tsx
+++ b/apps/web/src/components/EmployeeSkillReview.tsx
@@ -1,3 +1,5 @@
+// Settings → 技能 for one Bot (ProfileSkills artboard): skills by state and the Owner's review of the
+// selected one. Skill state never grants computer authority.
 import type {
   EmployeeProfile,
   EmployeeSkill,
diff --git a/apps/web/src/components/EmptyWorkspace.tsx b/apps/web/src/components/EmptyWorkspace.tsx
index 41576dd9..c0d1ee1e 100644
--- a/apps/web/src/components/EmptyWorkspace.tsx
+++ b/apps/web/src/components/EmptyWorkspace.tsx
@@ -1,3 +1,4 @@
+// 你的工作，从这里开始 (EmptyWorkspace artboard): home screen while the workspace has no conversation.
 import type { Bot } from "@openbot/domain";
 import { GroupAvatar } from "./GroupAvatar";
 import { useModelServices } from "./ModelSelector";
diff --git a/apps/web/src/components/ExportEmployeeDialog.tsx b/apps/web/src/components/ExportEmployeeDialog.tsx
index 7bfcc59f..1cfd8bc1 100644
--- a/apps/web/src/components/ExportEmployeeDialog.tsx
+++ b/apps/web/src/components/ExportEmployeeDialog.tsx
@@ -1,3 +1,5 @@
+// 分享 Bot 模板 dialog (DialogExport artboard): review the Server's redacted preview, then download
+// that exact package. Preview parts are reused by the import dialog.
 import type { Bot, EmployeeExportExclusion, EmployeeExportPreview } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import { type ApiError, getEmployeeExportPreview } from "../api";
diff --git a/apps/web/src/components/GroupAvatar.tsx b/apps/web/src/components/GroupAvatar.tsx
index 12419ef4..dc81e58d 100644
--- a/apps/web/src/components/GroupAvatar.tsx
+++ b/apps/web/src/components/GroupAvatar.tsx
@@ -1,3 +1,4 @@
+// A 频道's stacked-heads avatar with one status dot (GroupAvatars artboard).
 import type { Bot, BotStatus, RunStatus } from "@openbot/domain";
 import type { CSSProperties } from "react";
 import { avatarPresence, RobotAvatar } from "./RobotAvatar";
diff --git a/apps/web/src/components/Icons.tsx b/apps/web/src/components/Icons.tsx
index 412d7c37..bbd32f35 100644
--- a/apps/web/src/components/Icons.tsx
+++ b/apps/web/src/components/Icons.tsx
@@ -1,3 +1,4 @@
+// Shared inline SVG line icons (sidebar, header, composer, settings); decorative, aria-hidden.
 import type { ReactNode } from "react";
 
 interface IconProps {
diff --git a/apps/web/src/components/ImportEmployeeDialog.tsx b/apps/web/src/components/ImportEmployeeDialog.tsx
index 8a32c4dc..3702e491 100644
--- a/apps/web/src/components/ImportEmployeeDialog.tsx
+++ b/apps/web/src/components/ImportEmployeeDialog.tsx
@@ -1,3 +1,5 @@
+// 导入 Bot 模板 dialog (DialogImport artboard): upload a package, review the Server's quarantine check,
+// then confirm to create a new Bot with no computer authority and skills pending review.
 import type {
   Bot,
   EmployeeImportActivationResult,
diff --git a/apps/web/src/components/KnowledgeReviewPanel.tsx b/apps/web/src/components/KnowledgeReviewPanel.tsx
index 55015fe8..3abb7904 100644
--- a/apps/web/src/components/KnowledgeReviewPanel.tsx
+++ b/apps/web/src/components/KnowledgeReviewPanel.tsx
@@ -1,3 +1,4 @@
+// 候选经验 review in the memory panel: the Bot's knowledge proposals, each accepted or ignored.
 import type { KnowledgeProposal } from "@openbot/domain";
 import { useEffect, useId, useState } from "react";
 import { getKnowledgeProposals, reviewKnowledgeProposal } from "../api";
diff --git a/apps/web/src/components/LoginScreen.tsx b/apps/web/src/components/LoginScreen.tsx
index 5fc2eda8..a4101af7 100644
--- a/apps/web/src/components/LoginScreen.tsx
+++ b/apps/web/src/components/LoginScreen.tsx
@@ -1,3 +1,4 @@
+// 进入 OpenBot sign-in screen: the Owner's password, with first-run progress on Desktop.
 import { type FormEvent, useState } from "react";
 import { ApiError } from "../api";
 import { OnboardingFrame } from "./Onboarding";
diff --git a/apps/web/src/components/MessageActionBar.tsx b/apps/web/src/components/MessageActionBar.tsx
index cdbf4d2f..82150ae5 100644
--- a/apps/web/src/components/MessageActionBar.tsx
+++ b/apps/web/src/components/MessageActionBar.tsx
@@ -1,3 +1,4 @@
+// Hover actions beside a message bubble (MessageActions artboard): 回应 picker, 回复 and the 更多 menu.
 import {
   type Message,
   type MessageReaction,
diff --git a/apps/web/src/components/MessageAttachments.tsx b/apps/web/src/components/MessageAttachments.tsx
index c7852753..7236346e 100644
--- a/apps/web/src/components/MessageAttachments.tsx
+++ b/apps/web/src/components/MessageAttachments.tsx
@@ -1,3 +1,5 @@
+// A message's text plus its attachment cards; each card loads the file and shows a placeholder once
+// the file has been permanently deleted.
 import type { Bot } from "@openbot/domain";
 import { type ReactNode, useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/MessageReactions.tsx b/apps/web/src/components/MessageReactions.tsx
index f8e280b1..df9a59da 100644
--- a/apps/web/src/components/MessageReactions.tsx
+++ b/apps/web/src/components/MessageReactions.tsx
@@ -1,3 +1,4 @@
+// The Owner's saved reactions under a message bubble, and the emoji labels shared with the picker.
 import type { MessageReaction, ReactionEmoji } from "@openbot/domain";
 import { useState } from "react";
 import "./MessageReactions.css";
diff --git a/apps/web/src/components/ModelConnectionsDialog.tsx b/apps/web/src/components/ModelConnectionsDialog.tsx
index 269de7b6..78bf4b82 100644
--- a/apps/web/src/components/ModelConnectionsDialog.tsx
+++ b/apps/web/src/components/ModelConnectionsDialog.tsx
@@ -1,3 +1,5 @@
+// 连接模型服务 dialog (DialogModel artboard): add or edit a model connection, with a free key check
+// that only lists the provider's models. Also the provider tiles and labels used in Settings.
 import type {
   ModelConnection,
   ModelConnectionDependencies,
diff --git a/apps/web/src/components/ModelSelector.tsx b/apps/web/src/components/ModelSelector.tsx
index ef3ca68c..0432bd41 100644
--- a/apps/web/src/components/ModelSelector.tsx
+++ b/apps/web/src/components/ModelSelector.tsx
@@ -1,3 +1,5 @@
+// Model service and model picker for a Bot or the workspace default, plus the hook that loads the
+// Server's model connections. Used in onboarding, Settings and the Bot model editor.
 import type { ModelSelection, ModelServicesSnapshot } from "@openbot/domain";
 import { modelIdSchema } from "@openbot/protocol";
 import { useCallback, useEffect, useId, useRef, useState } from "react";
diff --git a/apps/web/src/components/ModelSettingsScreen.tsx b/apps/web/src/components/ModelSettingsScreen.tsx
index 48bbff82..2ff4b319 100644
--- a/apps/web/src/components/ModelSettingsScreen.tsx
+++ b/apps/web/src/components/ModelSettingsScreen.tsx
@@ -1,3 +1,5 @@
+// Model setup: connections plus the default model, as the onboarding step 给 Bot 选一个模型 or
+// embedded in Settings.
 import { useState } from "react";
 import { OnboardingFrame } from "./Onboarding";
 import { OwnerPreferenceSettings } from "./SettingsGeneral";
diff --git a/apps/web/src/components/NativeTaskScopeForm.tsx b/apps/web/src/components/NativeTaskScopeForm.tsx
index 220216d1..5a2220db 100644
--- a/apps/web/src/components/NativeTaskScopeForm.tsx
+++ b/apps/web/src/components/NativeTaskScopeForm.tsx
@@ -1,3 +1,5 @@
+// Scope form for a new 工作任务: Owner attachments (upload, process, delete) and opt-in extras such as
+// web, plugins, knowledge and collaborating Bots. Granted only as far as the Server allows.
 import type { Bot } from "@openbot/domain";
 import {
   ATTACHMENT_ACCEPT,
diff --git a/apps/web/src/components/NativeTaskScopeView.tsx b/apps/web/src/components/NativeTaskScopeView.tsx
index 7084e731..3b391c08 100644
--- a/apps/web/src/components/NativeTaskScopeView.tsx
+++ b/apps/web/src/components/NativeTaskScopeView.tsx
@@ -1,3 +1,4 @@
+// Read-only 已提交的任务范围 for a submitted 工作任务, read back from the Server.
 import { useEffect, useState } from "react";
 import { getNativeTaskScope, type NativeTaskScope } from "../native-task-api";
 
diff --git a/apps/web/src/components/NewBotSetupCard.tsx b/apps/web/src/components/NewBotSetupCard.tsx
index 2895be38..e1938ecf 100644
--- a/apps/web/src/components/NewBotSetupCard.tsx
+++ b/apps/web/src/components/NewBotSetupCard.tsx
@@ -1,3 +1,4 @@
+// 你最想让我先帮你做什么？ card (NewBotChat artboard) in a new Bot's empty 单聊; the answer sets its role.
 import type { Bot } from "@openbot/domain";
 import { type FormEvent, useState } from "react";
 import { RobotAvatar } from "./RobotAvatar";
diff --git a/apps/web/src/components/NewChatScreen.tsx b/apps/web/src/components/NewChatScreen.tsx
index 045a42b1..de27cfef 100644
--- a/apps/web/src/components/NewChatScreen.tsx
+++ b/apps/web/src/components/NewChatScreen.tsx
@@ -1,3 +1,5 @@
+// 新建聊天 screen (New and NewGroup artboards): pick recipients and write the first message; one Bot
+// opens a 单聊, several a 频道. Nothing is created before the message is sent.
 import type { Bot } from "@openbot/domain";
 import {
   Fragment,
diff --git a/apps/web/src/components/NodeManagerDialog.tsx b/apps/web/src/components/NodeManagerDialog.tsx
index 64ef6be8..9d2860a5 100644
--- a/apps/web/src/components/NodeManagerDialog.tsx
+++ b/apps/web/src/components/NodeManagerDialog.tsx
@@ -1,3 +1,5 @@
+// 配对一台工作电脑 dialog (DialogPairHost artboard): issue a one-time pairing token and list paired
+// work computers. Also the shared host-enrollment hook used by Settings → 工作主机.
 import type { ExecutionNode, NodeEnrollmentToken, NodeIdentitySummary } from "@openbot/domain";
 import { useCallback, useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/Onboarding.tsx b/apps/web/src/components/Onboarding.tsx
index 35e4dfbb..b31cf0cf 100644
--- a/apps/web/src/components/Onboarding.tsx
+++ b/apps/web/src/components/Onboarding.tsx
@@ -1,3 +1,5 @@
+// Launch screen and the shared first-run frame (Launch, Welcome, Install, Connect, Login,
+// ModelSetup and WorkerSetup artboards) used by every start-up step.
 import type { Bot, BotAppearance } from "@openbot/domain";
 import { type ReactNode, useEffect, useState } from "react";
 import { RobotAvatar } from "./RobotAvatar";
diff --git a/apps/web/src/components/PluginAppFrame.tsx b/apps/web/src/components/PluginAppFrame.tsx
index 01bf5ff1..6547d067 100644
--- a/apps/web/src/components/PluginAppFrame.tsx
+++ b/apps/web/src/components/PluginAppFrame.tsx
@@ -1,3 +1,5 @@
+// Sandboxed iframe that runs a plugin's own UI (MCP Apps) through AppBridge; every host capability
+// is denied unless wired explicitly here.
 import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { useEffect, useRef, useState } from "react";
 import { isBoundedPluginMessage, pluginProxyUrl } from "../plugin-app-sandbox";
diff --git a/apps/web/src/components/PluginCallApprovals.tsx b/apps/web/src/components/PluginCallApprovals.tsx
index 96cbfd3c..1980c7d0 100644
--- a/apps/web/src/components/PluginCallApprovals.tsx
+++ b/apps/web/src/components/PluginCallApprovals.tsx
@@ -1,3 +1,4 @@
+// 插件操作确认 in a channel: polls the plugin calls waiting for the Owner and approves or rejects each.
 import type { Bot } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import { ApiError } from "../api";
diff --git a/apps/web/src/components/PluginGrantEditor.tsx b/apps/web/src/components/PluginGrantEditor.tsx
index 53940dff..c1803798 100644
--- a/apps/web/src/components/PluginGrantEditor.tsx
+++ b/apps/web/src/components/PluginGrantEditor.tsx
@@ -1,3 +1,5 @@
+// Per-Bot grant for one plugin in Settings → 插件: 不授权, confirm each call, or allow read-only calls.
+// Shows 已保存 only once the Server's snapshot confirms the write.
 import type { Bot } from "@openbot/domain";
 import { useRef, useState } from "react";
 import type { Plugin, PluginGrant } from "../plugin-api";
diff --git a/apps/web/src/components/PluginInstallForm.tsx b/apps/web/src/components/PluginInstallForm.tsx
index 13e738f7..232c2284 100644
--- a/apps/web/src/components/PluginInstallForm.tsx
+++ b/apps/web/src/components/PluginInstallForm.tsx
@@ -1,3 +1,4 @@
+// 添加工具插件 form: preview an MCP endpoint's declared tools, then install it. Installing grants no Bot.
 import { type FormEvent, useState } from "react";
 import { type PluginManifest, pluginError, pluginRequest } from "../plugin-api";
 import { PluginContentDeclarations } from "./PluginPlatformPanels";
diff --git a/apps/web/src/components/PluginManagerPanel.tsx b/apps/web/src/components/PluginManagerPanel.tsx
index 91515124..309c611c 100644
--- a/apps/web/src/components/PluginManagerPanel.tsx
+++ b/apps/web/src/components/PluginManagerPanel.tsx
@@ -1,3 +1,5 @@
+// Plugin list shared by Settings → 插件 (SettingsPlugins artboard) and the Plugins dialog: search,
+// install, update, uninstall and per-Bot grants.
 import type { Bot, ReviewedPluginCatalog } from "@openbot/domain";
 import { Fragment, type MutableRefObject, useEffect, useRef, useState } from "react";
 import { getPluginCatalog } from "../api";
diff --git a/apps/web/src/components/PluginPlatformPanels.tsx b/apps/web/src/components/PluginPlatformPanels.tsx
index f5437cf8..327c8c51 100644
--- a/apps/web/src/components/PluginPlatformPanels.tsx
+++ b/apps/web/src/components/PluginPlatformPanels.tsx
@@ -1,3 +1,5 @@
+// Plugin detail panels: declared tools, prompts and resources, update review with a declaration
+// diff, the plugin's own UI and resources, and links to the plugin catalogue docs.
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
   type Plugin,
diff --git a/apps/web/src/components/PluginToolList.tsx b/apps/web/src/components/PluginToolList.tsx
index 1ce7cab9..b6775874 100644
--- a/apps/web/src/components/PluginToolList.tsx
+++ b/apps/web/src/components/PluginToolList.tsx
@@ -1,3 +1,4 @@
+// Expandable list of a plugin's tools with their input schema and self-reported annotations.
 import type { PluginTool } from "../plugin-api";
 
 export function PluginToolList({ tools }: { tools: PluginTool[] }) {
diff --git a/apps/web/src/components/PluginsDialog.tsx b/apps/web/src/components/PluginsDialog.tsx
index 043253da..b895e34c 100644
--- a/apps/web/src/components/PluginsDialog.tsx
+++ b/apps/web/src/components/PluginsDialog.tsx
@@ -1,3 +1,4 @@
+// Plugins dialog (Plugins artboard) over the workspace: choose which Bots use each plugin.
 import type { Bot } from "@openbot/domain";
 import type { PluginContentScope } from "../plugin-api";
 import { CloseIcon } from "./Icons";
diff --git a/apps/web/src/components/PortableEmployeeReview.tsx b/apps/web/src/components/PortableEmployeeReview.tsx
index 3ff25ffe..b26fccec 100644
--- a/apps/web/src/components/PortableEmployeeReview.tsx
+++ b/apps/web/src/components/PortableEmployeeReview.tsx
@@ -1,3 +1,4 @@
+// Profile summary and skill list of a Bot template, shown when exporting or importing it.
 import type { PortableEmployeeProfileSummary, PortableEmployeeSkillSummary } from "@openbot/domain";
 import "./PortableEmployeeReview.css";
 
diff --git a/apps/web/src/components/PrimaryBotSetting.tsx b/apps/web/src/components/PrimaryBotSetting.tsx
index 8397f074..b7189991 100644
--- a/apps/web/src/components/PrimaryBotSetting.tsx
+++ b/apps/web/src/components/PrimaryBotSetting.tsx
@@ -1,3 +1,4 @@
+// Settings row for the workspace's 主 Bot; a save tells the workspace to re-read so the crown moves.
 import type { WorkspacePrimaryBot } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import { ApiError, setWorkspacePrimaryBot } from "../api";
diff --git a/apps/web/src/components/RichMessage.tsx b/apps/web/src/components/RichMessage.tsx
index f2cc5f38..ebb1f152 100644
--- a/apps/web/src/components/RichMessage.tsx
+++ b/apps/web/src/components/RichMessage.tsx
@@ -1,3 +1,5 @@
+// Safe message text renderer: `code`, **bold**, https links and the 频道's Bot names as tags. Model
+// text never becomes markup.
 import type { Bot } from "@openbot/domain";
 import type { CSSProperties, ReactNode } from "react";
 import { getOpenBotDesktopBridge } from "../desktop-runtime";
diff --git a/apps/web/src/components/RobotAvatar.tsx b/apps/web/src/components/RobotAvatar.tsx
index 48d826dc..7453b67f 100644
--- a/apps/web/src/components/RobotAvatar.tsx
+++ b/apps/web/src/components/RobotAvatar.tsx
@@ -1,3 +1,5 @@
+// Bot head avatar (Avatars artboard v3): head shape, jaw colour, status dot and working motion,
+// plus the birth and restyle animations. Also the appearance defaults and the eight jaw colours.
 import type {
   Bot,
   BotAccessory,
diff --git a/apps/web/src/components/RunCollaboration.tsx b/apps/web/src/components/RunCollaboration.tsx
index 0c2facf2..6709bde9 100644
--- a/apps/web/src/components/RunCollaboration.tsx
+++ b/apps/web/src/components/RunCollaboration.tsx
@@ -1,3 +1,5 @@
+// Bot-to-Bot delegation in a conversation: links child runs to their parent from Server records and
+// shows the 参与协作 list, delegation notices and the delegated reply's context.
 import type { Bot, Message, Run } from "@openbot/domain";
 import { runStatusLabel, runStatusSummary, runTitle } from "../run-state";
 import { RobotAvatar } from "./RobotAvatar";
diff --git a/apps/web/src/components/SettingsAccount.tsx b/apps/web/src/components/SettingsAccount.tsx
index 6df1a3f9..87fe92bf 100644
--- a/apps/web/src/components/SettingsAccount.tsx
+++ b/apps/web/src/components/SettingsAccount.tsx
@@ -1,3 +1,5 @@
+// Settings → 账户与安全 (SettingsAccount artboard): Owner password change, signed-in devices, and
+// summaries of the security rules and audit log.
 import type { OwnerSessionDevice } from "@openbot/domain";
 import { type FormEvent, useCallback, useEffect, useId, useState } from "react";
 import { ApiError, changeOwnerPassword, listOwnerSessions, revokeOtherOwnerSessions } from "../api";
diff --git a/apps/web/src/components/SettingsApprovals.tsx b/apps/web/src/components/SettingsApprovals.tsx
index bd1f7a3a..f0a07fbc 100644
--- a/apps/web/src/components/SettingsApprovals.tsx
+++ b/apps/web/src/components/SettingsApprovals.tsx
@@ -1,3 +1,5 @@
+// Settings → 审批与权限 (SettingsApprovals artboard): extra confirmations for reads and their exact
+// Bot/target exceptions, saved against the Server's revision.
 import type { ApprovalException, ApprovalSettings, Bot, Channel } from "@openbot/domain";
 import { useCallback, useEffect, useState } from "react";
 import { ApiError, getApprovalSettings, saveApprovalSettings } from "../api";
diff --git a/apps/web/src/components/SettingsBrowser.tsx b/apps/web/src/components/SettingsBrowser.tsx
index 744113a5..5d815d8b 100644
--- a/apps/web/src/components/SettingsBrowser.tsx
+++ b/apps/web/src/components/SettingsBrowser.tsx
@@ -1,3 +1,5 @@
+// Settings → 员工浏览器 (SettingsBrowser artboard): each Docker Bot's browser status, with open,
+// restart and clear.
 import type { Bot, BrowserMaintenanceResult } from "@openbot/domain";
 import { useState } from "react";
 import { ApiError, maintainEmployeeBrowser } from "../api";
diff --git a/apps/web/src/components/SettingsGeneral.tsx b/apps/web/src/components/SettingsGeneral.tsx
index a9804b75..450ffc79 100644
--- a/apps/web/src/components/SettingsGeneral.tsx
+++ b/apps/web/src/components/SettingsGeneral.tsx
@@ -1,3 +1,5 @@
+// Rows of Settings → 通用 and 通知: Desktop start-up options, the Dock badge, and the Owner's time
+// zone and default model for new Bots.
 import type {
   DesktopPlatformPreferences,
   DesktopPlatformState,
diff --git a/apps/web/src/components/SettingsHeaderAction.tsx b/apps/web/src/components/SettingsHeaderAction.tsx
index 894bc2a9..76e89e06 100644
--- a/apps/web/src/components/SettingsHeaderAction.tsx
+++ b/apps/web/src/components/SettingsHeaderAction.tsx
@@ -1,3 +1,4 @@
+// Portal slot that puts a settings section's primary action in the dialog header.
 import { createContext, type ReactNode, useContext } from "react";
 import { createPortal } from "react-dom";
 
diff --git a/apps/web/src/components/SettingsHosts.tsx b/apps/web/src/components/SettingsHosts.tsx
index 1883e1a1..e259c19f 100644
--- a/apps/web/src/components/SettingsHosts.tsx
+++ b/apps/web/src/components/SettingsHosts.tsx
@@ -1,3 +1,4 @@
+// Settings → 工作主机 (SettingsHosts artboard): paired work computers, their live state, and pairing.
 import type { ExecutionNode } from "@openbot/domain";
 import { type ReactNode, useEffect, useState } from "react";
 import { getWorkspace } from "../api";
diff --git a/apps/web/src/components/SettingsMemory.tsx b/apps/web/src/components/SettingsMemory.tsx
index 6da4bf04..4379cc4f 100644
--- a/apps/web/src/components/SettingsMemory.tsx
+++ b/apps/web/src/components/SettingsMemory.tsx
@@ -1,3 +1,4 @@
+// Settings → 记忆 (SettingsMemory artboard): pick a Bot and manage its memory panel.
 import type { Bot, EmployeeProfile } from "@openbot/domain";
 import { useCallback, useEffect, useState } from "react";
 import { getEmployeeProfile } from "../api";
diff --git a/apps/web/src/components/SettingsModelServices.tsx b/apps/web/src/components/SettingsModelServices.tsx
index 8c7e3920..31ad71a2 100644
--- a/apps/web/src/components/SettingsModelServices.tsx
+++ b/apps/web/src/components/SettingsModelServices.tsx
@@ -1,3 +1,4 @@
+// Settings → 模型服务: connected model services with enable switches, then the provider catalogue.
 import type { ModelConnection } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import { ApiError, getWorkspace, updateModelConnection } from "../api";
diff --git a/apps/web/src/components/SettingsSearch.tsx b/apps/web/src/components/SettingsSearch.tsx
index c5a94fce..10bacfcc 100644
--- a/apps/web/src/components/SettingsSearch.tsx
+++ b/apps/web/src/components/SettingsSearch.tsx
@@ -1,3 +1,4 @@
+// Search box for long settings lists, shown once a list passes 20 entries (LongLists rule).
 import { useState } from "react";
 
 /** LongLists: a settings list gets a search box once it holds more than 20 entries. */
diff --git a/apps/web/src/components/SettingsSections.tsx b/apps/web/src/components/SettingsSections.tsx
index f006edbc..e55355f2 100644
--- a/apps/web/src/components/SettingsSections.tsx
+++ b/apps/web/src/components/SettingsSections.tsx
@@ -1,3 +1,5 @@
+// Shared settings building blocks (group, row, workspace loader) and small sections: the approval
+// rules summary, the audit log with CSV export, and the 例行任务 entry.
 import type { WorkspaceSnapshot } from "@openbot/domain";
 import { type ReactNode, useCallback, useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/SettingsSkills.tsx b/apps/web/src/components/SettingsSkills.tsx
index 42df7f12..65feead6 100644
--- a/apps/web/src/components/SettingsSkills.tsx
+++ b/apps/web/src/components/SettingsSkills.tsx
@@ -1,3 +1,4 @@
+// Settings → 技能 (SettingsSkills artboard): every Bot's skills in one list, with review and install.
 import type { Bot, EmployeeProfile, EmployeeSkill } from "@openbot/domain";
 import { useCallback, useEffect, useState } from "react";
 import { getEmployeeProfile } from "../api";
diff --git a/apps/web/src/components/SettingsStorage.tsx b/apps/web/src/components/SettingsStorage.tsx
index c89a08d5..69bad3f8 100644
--- a/apps/web/src/components/SettingsStorage.tsx
+++ b/apps/web/src/components/SettingsStorage.tsx
@@ -1,3 +1,5 @@
+// Settings → 存储空间 (SettingsStorage artboard): server disk use by category and channel, 回收站
+// cleanup, and each Bot's browser data measured on request.
 import type { Bot } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/SettingsTransfer.tsx b/apps/web/src/components/SettingsTransfer.tsx
index a96dce34..6be7296d 100644
--- a/apps/web/src/components/SettingsTransfer.tsx
+++ b/apps/web/src/components/SettingsTransfer.tsx
@@ -1,3 +1,4 @@
+// Settings → 导入与导出 (SettingsTransfer artboard): opens the Bot template import and export dialogs.
 import type { Bot } from "@openbot/domain";
 import { useState } from "react";
 import { useEmployeeProfiles } from "../use-employee-profiles";
diff --git a/apps/web/src/components/ShareConversationDialog.tsx b/apps/web/src/components/ShareConversationDialog.tsx
index 25c64018..10fc31cc 100644
--- a/apps/web/src/components/ShareConversationDialog.tsx
+++ b/apps/web/src/components/ShareConversationDialog.tsx
@@ -1,3 +1,5 @@
+// 分享 dialog (DialogShare artboard): save a 频道's outputs or pack one of its Bots as a template.
+// Produces files for the Owner only; nothing is sent or published.
 import type { Artifact, Bot, Channel, Run } from "@openbot/domain";
 import { useEffect, useRef, useState } from "react";
 import { extensionOf } from "../channel-attachment-client";
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 2f329e0d..2542fed5 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -1,3 +1,5 @@
+// Left sidebar (Sidebar artboard): search, 「+」, 主 Bot, pinned and grouped conversations with unread
+// and activity, the plugins row and the 「我」 account menu.
 import type { Bot, Channel, ChannelMessagePreview, Run } from "@openbot/domain";
 import {
   type KeyboardEvent,
diff --git a/apps/web/src/components/SidebarItemMenu.tsx b/apps/web/src/components/SidebarItemMenu.tsx
index e1230941..e10e6fbc 100644
--- a/apps/web/src/components/SidebarItemMenu.tsx
+++ b/apps/web/src/components/SidebarItemMenu.tsx
@@ -1,3 +1,5 @@
+// Right-click menus for sidebar rows and groups (ContextMenu artboard). Pin, group, mute, hide and
+// unread are per device; rename, delete and add-Bot are Server writes passed in by the caller.
 import type { Bot } from "@openbot/domain";
 import {
   type KeyboardEvent,
diff --git a/apps/web/src/components/TaskActions.tsx b/apps/web/src/components/TaskActions.tsx
index ea049704..a42de787 100644
--- a/apps/web/src/components/TaskActions.tsx
+++ b/apps/web/src/components/TaskActions.tsx
@@ -1,3 +1,5 @@
+// Task controls shared by the task card and 任务详情: stop, resubmit and 补充指令 for tasks the
+// server computer runs itself.
 import type { Run } from "@openbot/domain";
 import { useState } from "react";
 import { ApiError, cancelNativeRun, createMessage, steerRun } from "../api";
diff --git a/apps/web/src/components/TaskCard.tsx b/apps/web/src/components/TaskCard.tsx
index 9af50934..c3eb6fb2 100644
--- a/apps/web/src/components/TaskCard.tsx
+++ b/apps/web/src/components/TaskCard.tsx
@@ -1,3 +1,5 @@
+// Task card in the conversation (TaskCards artboard): status, step count, latest progress, outputs,
+// approvals and collaborators, updated in place as the Server reports progress.
 import type {
   Approval,
   ApprovalDecision,
diff --git a/apps/web/src/components/TaskSheet.tsx b/apps/web/src/components/TaskSheet.tsx
index c7205b3b..1a8547c5 100644
--- a/apps/web/src/components/TaskSheet.tsx
+++ b/apps/web/src/components/TaskSheet.tsx
@@ -1,3 +1,5 @@
+// 任务详情 sheet (TaskInspector artboard): a task's status, computer frame, 分工, steps, outputs and
+// model use, opened from a task card.
 import type { Artifact, Bot, ExecutionNode, Run, RunFrame, RunProgress } from "@openbot/domain";
 import { useEffect, useRef, useState } from "react";
 import { runStatusLabel, runStatusSummary, runTitle } from "../run-state";
diff --git a/apps/web/src/components/TaskSteps.tsx b/apps/web/src/components/TaskSteps.tsx
index b2a63655..7440c388 100644
--- a/apps/web/src/components/TaskSteps.tsx
+++ b/apps/web/src/components/TaskSteps.tsx
@@ -1,3 +1,4 @@
+// Step list in 任务详情: the Server's exact step count and stage names, folding the middle past 12.
 import type { Run, RunProgress, RunProgressDetails } from "@openbot/domain";
 import { type ReactNode, useEffect, useState } from "react";
 import { getRunProgress } from "../api";
diff --git a/apps/web/src/components/TranscriptionConnectionSetting.tsx b/apps/web/src/components/TranscriptionConnectionSetting.tsx
index d114d2b2..30935214 100644
--- a/apps/web/src/components/TranscriptionConnectionSetting.tsx
+++ b/apps/web/src/components/TranscriptionConnectionSetting.tsx
@@ -1,3 +1,4 @@
+// 语音转写 setting under Settings → 模型服务: which OpenAI connection transcribes voice attachments.
 import type { ModelConnection } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import {
diff --git a/apps/web/src/components/VoiceRecorder.tsx b/apps/web/src/components/VoiceRecorder.tsx
index 3de8e3aa..0fac3962 100644
--- a/apps/web/src/components/VoiceRecorder.tsx
+++ b/apps/web/src/components/VoiceRecorder.tsx
@@ -1,3 +1,5 @@
+// Composer voice recorder: record, review, re-record or discard an audio attachment. The microphone
+// opens only on an explicit click.
 import { useEffect, useRef, useState } from "react";
 import {
   type ComposerAttachment,
diff --git a/apps/web/src/components/WorkTasksEntry.tsx b/apps/web/src/components/WorkTasksEntry.tsx
index 6a31d9f5..8bc86372 100644
--- a/apps/web/src/components/WorkTasksEntry.tsx
+++ b/apps/web/src/components/WorkTasksEntry.tsx
@@ -1,3 +1,4 @@
+// Standalone 任务监督 page at #/tasks: loads the Bots from /bots and hosts WorkTasksScreen.
 import { useEffect, useState } from "react";
 import { listWorkBots } from "../work-api";
 import { WorkTasksScreen } from "./WorkTasksScreen";
diff --git a/apps/web/src/components/WorkTasksScreen.tsx b/apps/web/src/components/WorkTasksScreen.tsx
index f0e139d6..bb091093 100644
--- a/apps/web/src/components/WorkTasksScreen.tsx
+++ b/apps/web/src/components/WorkTasksScreen.tsx
@@ -1,3 +1,5 @@
+// 任务监督 (WorkSupervision artboard): create a Work task for a Bot, look one up by ID, follow its
+// current step and request cancellation. Talks to work-api.
 import type { Bot } from "@openbot/domain";
 import { type FormEvent, useCallback, useEffect, useRef, useState } from "react";
 import { ApiError } from "../api";
diff --git a/apps/web/src/components/WorkspaceHeader.tsx b/apps/web/src/components/WorkspaceHeader.tsx
index c85faa24..46f057d4 100644
--- a/apps/web/src/components/WorkspaceHeader.tsx
+++ b/apps/web/src/components/WorkspaceHeader.tsx
@@ -1,3 +1,5 @@
+// Main column header (Main artboard): title pill that opens the right rail, avatar, 分享 and the
+// reopen-sidebar button.
 import type { Bot } from "@openbot/domain";
 import type { RealtimeConnectionState } from "../api";
 import { shortcutLabel } from "../desktop-shortcuts";
diff --git a/apps/web/src/components/useListScroll.ts b/apps/web/src/components/useListScroll.ts
index e00796ce..ce930d3b 100644
--- a/apps/web/src/components/useListScroll.ts
+++ b/apps/web/src/components/useListScroll.ts
@@ -1,3 +1,5 @@
+// Hook for popover lists past eight rows: scroll inside, fade edges with hidden rows, and keep the
+// keyboard selection in view (LongLists rule).
 import { useEffect, useLayoutEffect, useState } from "react";
 
 /**
diff --git a/apps/web/src/components/useModalDialog.ts b/apps/web/src/components/useModalDialog.ts
index 92879248..4950e5ce 100644
--- a/apps/web/src/components/useModalDialog.ts
+++ b/apps/web/src/components/useModalDialog.ts
@@ -1,3 +1,4 @@
+// Hook that opens a native modal <dialog> and reports its close or cancel back to React state.
 import { useCallback, useEffect, useRef } from "react";
 
 /**
diff --git a/apps/web/src/composer-context.ts b/apps/web/src/composer-context.ts
index 7594b18b..cbfa0acc 100644
--- a/apps/web/src/composer-context.ts
+++ b/apps/web/src/composer-context.ts
@@ -1,3 +1,5 @@
+// Composer attachment and skill model: file type and size checks, upload to the channel, and the
+// task text that lists requested skills and attachment markers.
 import {
   ATTACHMENT_ACCEPT,
   ATTACHMENT_EXTENSIONS,
diff --git a/apps/web/src/conversation-session.ts b/apps/web/src/conversation-session.ts
index 70b0850f..4597dd65 100644
--- a/apps/web/src/conversation-session.ts
+++ b/apps/web/src/conversation-session.ts
@@ -1,3 +1,5 @@
+// In-memory per-channel cache for the workspace session: drafts, loaded message pages, scroll
+// position and older-page cursors. Holds no authority and writes nothing to disk.
 import type { CreateMessageInput, Message, Run, SubmitTaskResult } from "@openbot/domain";
 import { type ComposerAttachment, type ComposerSkill, composeTaskText } from "./composer-context";
 import { selectedRecipientIds } from "./recipient-utils";
diff --git a/apps/web/src/demo/Demo.tsx b/apps/web/src/demo/Demo.tsx
index 7e2e7fca..747c125c 100644
--- a/apps/web/src/demo/Demo.tsx
+++ b/apps/web/src/demo/Demo.tsx
@@ -1,3 +1,5 @@
+// Website demo (demo.html): the real sidebar, conversation and 任务详情 driven by a scripted run,
+// with play/pause controls.
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { ChannelWorkspace } from "../components/ChannelWorkspace";
 import { RobotAvatar } from "../components/RobotAvatar";
diff --git a/apps/web/src/demo/adapter.ts b/apps/web/src/demo/adapter.ts
index dcbbc5d2..fa2527e6 100644
--- a/apps/web/src/demo/adapter.ts
+++ b/apps/web/src/demo/adapter.ts
@@ -1,3 +1,5 @@
+// Scripted fake Server for the website demo: answers fetch and event-stream calls from fixed
+// fixtures and plays the demo run step by step. Never reaches a real Server.
 import {
   type Artifact,
   type ChannelRealtimeEvent,
diff --git a/apps/web/src/demo/fixtures.ts b/apps/web/src/demo/fixtures.ts
index a3ef2e25..c719bce0 100644
--- a/apps/web/src/demo/fixtures.ts
+++ b/apps/web/src/demo/fixtures.ts
@@ -1,3 +1,4 @@
+// Fixed Bots, channel, prompt, report and messages for the website demo; synthetic data only.
 import type { Artifact, Bot, Channel, Message, Run } from "@openbot/domain";
 
 export const demoTime = "2026-09-10T01:30:00.000Z";
diff --git a/apps/web/src/demo/install.ts b/apps/web/src/demo/install.ts
index 29129a3e..262ea0ac 100644
--- a/apps/web/src/demo/install.ts
+++ b/apps/web/src/demo/install.ts
@@ -1,3 +1,4 @@
+// Swaps fetch, EventSource, storage and downloads for the demo adapter before any product UI loads.
 import type { DemoAdapter } from "./adapter";
 
 /** Called only by demo.html, before importing any product UI module. */
diff --git a/apps/web/src/demo/main.tsx b/apps/web/src/demo/main.tsx
index a52c8928..1f688c2a 100644
--- a/apps/web/src/demo/main.tsx
+++ b/apps/web/src/demo/main.tsx
@@ -1,3 +1,4 @@
+// Entry point of demo.html (`npm run build:demo`): installs the demo transport, then renders Demo.
 import { DemoAdapter } from "./adapter";
 import { installDemoTransport } from "./install";
 import "../global-styles";
diff --git a/apps/web/src/desktop-runtime.ts b/apps/web/src/desktop-runtime.ts
index 734af4ba..54a21ffb 100644
--- a/apps/web/src/desktop-runtime.ts
+++ b/apps/web/src/desktop-runtime.ts
@@ -1,3 +1,4 @@
+// Typed access to the Desktop preload bridge (window.openbotDesktop); undefined in a plain browser.
 import type {
   OpenBotDesktopBridge as DesktopBridge,
   DesktopRuntimeInfo,
diff --git a/apps/web/src/desktop-shortcuts.ts b/apps/web/src/desktop-shortcuts.ts
index fbf20686..538bf216 100644
--- a/apps/web/src/desktop-shortcuts.ts
+++ b/apps/web/src/desktop-shortcuts.ts
@@ -1,3 +1,4 @@
+// Display label for a Desktop keyboard shortcut (⌘ on macOS, Ctrl elsewhere); display only.
 import { getOpenBotDesktopBridge } from "./desktop-runtime";
 
 /** This is display metadata only; command authority remains in the native menu. */
diff --git a/apps/web/src/destination-api.ts b/apps/web/src/destination-api.ts
index f0d0e9a5..56c54875 100644
--- a/apps/web/src/destination-api.ts
+++ b/apps/web/src/destination-api.ts
@@ -1,3 +1,4 @@
+// Client for the Server's automation routes (例行任务): list, create, enable or pause, delete.
 import type { Automation, CreateAutomationInput } from "@openbot/protocol";
 import { ApiError } from "./api";
 
diff --git a/apps/web/src/employee-template-delivery.ts b/apps/web/src/employee-template-delivery.ts
index 3c422a3c..fe66269b 100644
--- a/apps/web/src/employee-template-delivery.ts
+++ b/apps/web/src/employee-template-delivery.ts
@@ -1,3 +1,4 @@
+// Saves a reviewed Bot template package: through the Desktop save dialog, else a browser download.
 import type { EmployeeExportPreview } from "@openbot/domain";
 import { ApiError, fetchEmployeeTemplate } from "./api";
 import { getOpenBotDesktopBridge } from "./desktop-runtime";
diff --git a/apps/web/src/event-stream.ts b/apps/web/src/event-stream.ts
index ee3dddb5..63775885 100644
--- a/apps/web/src/event-stream.ts
+++ b/apps/web/src/event-stream.ts
@@ -1,3 +1,5 @@
+// One EventSource subscription with reconnect, watchdog and cleanup, used by api.ts for realtime
+// updates. Callers parse and validate the events.
 export type RealtimeConnectionState = "connecting" | "live" | "retrying";
 export type EventStreamSession = {
   /** Records valid activity; false if the stream is no longer active afterwards. */
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 9329b6d1..577263cb 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -1,3 +1,5 @@
+// Entry point of the Web app (index.html): installs global styles, favicon and colour scheme, then
+// renders App.
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { App } from "./App.tsx";
diff --git a/apps/web/src/mention-query.ts b/apps/web/src/mention-query.ts
index d50273b4..5e65f3be 100644
--- a/apps/web/src/mention-query.ts
+++ b/apps/web/src/mention-query.ts
@@ -1,3 +1,4 @@
+// Finds and removes the `@name` fragment at the composer caret, which opens the @ recipient list.
 export interface MentionQuery {
   start: number;
   query: string;
diff --git a/apps/web/src/native-task-api.ts b/apps/web/src/native-task-api.ts
index 9ab0a7b8..29c6fa71 100644
--- a/apps/web/src/native-task-api.ts
+++ b/apps/web/src/native-task-api.ts
@@ -1,3 +1,5 @@
+// Client for Work task resources: a task's submitted scope and the Owner's task attachments
+// (list, upload, process, delete).
 import {
   type AttachmentOperation,
   nativeTaskScopeSchema,
diff --git a/apps/web/src/plugin-api.ts b/apps/web/src/plugin-api.ts
index 5e849b3e..0860d643 100644
--- a/apps/web/src/plugin-api.ts
+++ b/apps/web/src/plugin-api.ts
@@ -1,3 +1,5 @@
+// Client for the Server's plugin routes: request helper, plugin list, content paths and the
+// Chinese error messages shown for each failure status.
 import type {
   PluginContentScope,
   PluginContentResultHttp,
diff --git a/apps/web/src/preview/AvatarSpecimens.tsx b/apps/web/src/preview/AvatarSpecimens.tsx
index 717c3d1f..cd825cc7 100644
--- a/apps/web/src/preview/AvatarSpecimens.tsx
+++ b/apps/web/src/preview/AvatarSpecimens.tsx
@@ -1,3 +1,4 @@
+// Design preview specimen sheets for the Avatars and GroupAvatars artboards, using real avatars.
 import type { Bot, BotAppearance, BotStatus, RunStatus } from "@openbot/domain";
 import { GroupAvatar } from "../components/GroupAvatar";
 import { RobotAvatar } from "../components/RobotAvatar";
diff --git a/apps/web/src/preview/ReadmeBanner.tsx b/apps/web/src/preview/ReadmeBanner.tsx
index 9f29e6c3..28c90b52 100644
--- a/apps/web/src/preview/ReadmeBanner.tsx
+++ b/apps/web/src/preview/ReadmeBanner.tsx
@@ -1,3 +1,4 @@
+// Design preview scene that draws the README banner with the product avatars (`?scene=banner`).
 import type { Bot, BotAppearance } from "@openbot/domain";
 import { RobotAvatar } from "../components/RobotAvatar";
 
diff --git a/apps/web/src/preview/main.tsx b/apps/web/src/preview/main.tsx
index 2a040f8c..3a9c9531 100644
--- a/apps/web/src/preview/main.tsx
+++ b/apps/web/src/preview/main.tsx
@@ -1,3 +1,5 @@
+// Entry point of the design preview (preview.html, dev only): the scene table and the page that
+// renders one scene on synthetic data for comparison with its artboard.
 import { installPreviewTransport } from "./transport";
 import { createWorld } from "./world";
 import "../global-styles";
diff --git a/apps/web/src/preview/scenes.tsx b/apps/web/src/preview/scenes.tsx
index c9ff70c6..97db2a31 100644
--- a/apps/web/src/preview/scenes.tsx
+++ b/apps/web/src/preview/scenes.tsx
@@ -1,3 +1,5 @@
+// Design preview renderers: the whole App for app scenes, single screens and dialogs for component
+// scenes, and the scene index. Actions stay pending; nothing is submitted.
 import type { Artifact, Bot, Channel, ExecutionNode, Run } from "@openbot/domain";
 import type { ReactElement } from "react";
 import { App } from "../App";
diff --git a/apps/web/src/preview/transport.ts b/apps/web/src/preview/transport.ts
index e7395283..3ba8c76a 100644
--- a/apps/web/src/preview/transport.ts
+++ b/apps/web/src/preview/transport.ts
@@ -1,3 +1,5 @@
+// Design preview fake Server (dev only): replaces fetch, EventSource and storage and answers every
+// route from the synthetic world. Fails closed and never touches the network.
 import { modelProviderPresets } from "@openbot/domain";
 import {
   attachmentsFor,
diff --git a/apps/web/src/quick-bot.ts b/apps/web/src/quick-bot.ts
index 39bc4376..c8140480 100644
--- a/apps/web/src/quick-bot.ts
+++ b/apps/web/src/quick-bot.ts
@@ -1,3 +1,5 @@
+// 创建新 Bot helpers: the quick-created Bot's placeholder role, a fresh random look, and the failure
+// notice. The Server allocates the name and opens its 单聊.
 import type { Bot, BotAppearance } from "@openbot/domain";
 
 /*
diff --git a/apps/web/src/recipient-utils.ts b/apps/web/src/recipient-utils.ts
index d31104f2..53bdd0fa 100644
--- a/apps/web/src/recipient-utils.ts
+++ b/apps/web/src/recipient-utils.ts
@@ -1,3 +1,4 @@
+// Composer recipient selection: add, remove or select everyone, up to six Bots per message.
 export const MAX_MESSAGE_RECIPIENTS = 6;
 
 export interface RecipientSelection {
diff --git a/apps/web/src/run-output-state.ts b/apps/web/src/run-output-state.ts
index 1878a51c..2ac8acb5 100644
--- a/apps/web/src/run-output-state.ts
+++ b/apps/web/src/run-output-state.ts
@@ -1,3 +1,5 @@
+// Merges a streamed reply draft into the channel's live drafts, keeping only the newest sequence
+// for a running model-only task of this channel.
 import type { Run, RunOutput } from "@openbot/domain";
 import { isRunOutputProjection } from "./api";
 
diff --git a/apps/web/src/sidebar-organization.ts b/apps/web/src/sidebar-organization.ts
index cd2af626..0537892d 100644
--- a/apps/web/src/sidebar-organization.ts
+++ b/apps/web/src/sidebar-organization.ts
@@ -1,3 +1,5 @@
+// Per-device sidebar arrangement in localStorage: pins, groups, folding, hidden rows, mute and
+// unread marks, plus the sort and search used by the sidebar. Never a Server write.
 import { useSyncExternalStore } from "react";
 
 /**
diff --git a/apps/web/src/slash-query.ts b/apps/web/src/slash-query.ts
index dc8136dc..84d6ecfa 100644
--- a/apps/web/src/slash-query.ts
+++ b/apps/web/src/slash-query.ts
@@ -1,3 +1,4 @@
+// Finds and removes the `/command` fragment at the composer caret, which opens the / skills menu.
 export interface SlashQuery {
   /** Index of the "/" that opened the command menu. */
   start: number;
diff --git a/apps/web/src/system-notifications.ts b/apps/web/src/system-notifications.ts
index 79f78912..f3a3b36c 100644
--- a/apps/web/src/system-notifications.ts
+++ b/apps/web/src/system-notifications.ts
@@ -1,3 +1,5 @@
+// Opt-in system notifications for new Bot replies and approvals, through Desktop or the browser
+// Notifications API. Notices name only the Bot and channel, never message text.
 import type { Approval, Bot, Channel } from "@openbot/domain";
 import { getOpenBotDesktopBridge } from "./desktop-runtime";
 
diff --git a/apps/web/src/textarea-caret.ts b/apps/web/src/textarea-caret.ts
index 27b722f2..f8573622 100644
--- a/apps/web/src/textarea-caret.ts
+++ b/apps/web/src/textarea-caret.ts
@@ -1,3 +1,4 @@
+// Measures the caret's x position in the composer textarea so the @ and / lists open at the caret.
 const mirrored = [
   "boxSizing",
   "width",
diff --git a/apps/web/src/use-desktop-navigation.ts b/apps/web/src/use-desktop-navigation.ts
index f896aba7..86422ef6 100644
--- a/apps/web/src/use-desktop-navigation.ts
+++ b/apps/web/src/use-desktop-navigation.ts
@@ -1,3 +1,5 @@
+// Wires Desktop menu commands and the matching Web keyboard shortcuts (new conversation, back,
+// forward, settings, panel toggles) to the workspace's navigation actions.
 import { useEffect, useRef } from "react";
 import { type DesktopNavigationCommand, getOpenBotDesktopBridge } from "./desktop-runtime";
 import { updatePreferences, useWorkspacePreferences } from "./workspace-preferences";
diff --git a/apps/web/src/use-employee-profile.ts b/apps/web/src/use-employee-profile.ts
index 677a42ff..b7a8a788 100644
--- a/apps/web/src/use-employee-profile.ts
+++ b/apps/web/src/use-employee-profile.ts
@@ -1,3 +1,4 @@
+// Hook that reads one Bot's employee profile, re-reading on events and reconnects, cancellably.
 import type { EmployeeProfile } from "@openbot/domain";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { getEmployeeProfile } from "./api";
diff --git a/apps/web/src/use-employee-profiles.ts b/apps/web/src/use-employee-profiles.ts
index bd5beca3..a9b7466e 100644
--- a/apps/web/src/use-employee-profiles.ts
+++ b/apps/web/src/use-employee-profiles.ts
@@ -1,3 +1,4 @@
+// Hook that reads several Bots' profiles, at most four requests at a time (Settings → 技能, 导入与导出).
 import type { EmployeeProfile } from "@openbot/domain";
 import { useEffect, useState } from "react";
 import { getEmployeeProfile } from "./api";
diff --git a/apps/web/src/use-settings-counts.ts b/apps/web/src/use-settings-counts.ts
index e9f42abd..ca234903 100644
--- a/apps/web/src/use-settings-counts.ts
+++ b/apps/web/src/use-settings-counts.ts
@@ -1,3 +1,4 @@
+// Hook for the settings nav badges (SettingsNav artboard): model, host, plugin and routine counts.
 import { useEffect, useState } from "react";
 import { getModelServices, listNodeIdentities } from "./api";
 import type { DesktopSettingsSection } from "./components/DesktopSettingsScreen";
diff --git a/apps/web/src/use-workspace-appearance.ts b/apps/web/src/use-workspace-appearance.ts
index d156d1d2..c9835ef4 100644
--- a/apps/web/src/use-workspace-appearance.ts
+++ b/apps/web/src/use-workspace-appearance.ts
@@ -1,3 +1,5 @@
+// Hook that applies density, font size, reduced motion and colour scheme to the page root, and
+// tracks the Desktop sidebar material.
 import { useEffect, useState } from "react";
 import {
   applyColorScheme,
diff --git a/apps/web/src/use-workspace-state.ts b/apps/web/src/use-workspace-state.ts
index ff8eb4c8..55a09d90 100644
--- a/apps/web/src/use-workspace-state.ts
+++ b/apps/web/src/use-workspace-state.ts
@@ -1,3 +1,5 @@
+// Hook holding the workspace snapshot from the Server: initial read, realtime event projections,
+// and re-reads after a disconnect without losing newer events.
 import type {
   Approval,
   Artifact,
diff --git a/apps/web/src/work-api.ts b/apps/web/src/work-api.ts
index b44424d5..fe220990 100644
--- a/apps/web/src/work-api.ts
+++ b/apps/web/src/work-api.ts
@@ -1,3 +1,4 @@
+// Client for the Work task routes used by 任务监督: list Bots, create, read and cancel a task.
 import {
   type CancelWorkInput,
   type CreateWorkInput,
diff --git a/apps/web/src/workspace-navigation.ts b/apps/web/src/workspace-navigation.ts
index 33f5fc22..7a0da72f 100644
--- a/apps/web/src/workspace-navigation.ts
+++ b/apps/web/src/workspace-navigation.ts
@@ -1,3 +1,5 @@
+// In-app back/forward history of workspace locations (home, new chat, a conversation, 任务监督),
+// plus the design preview's start-location seam.
 import { useCallback, useState } from "react";
 
 export type WorkspaceLocation =
diff --git a/apps/web/src/workspace-preferences.ts b/apps/web/src/workspace-preferences.ts
index 181785b9..736b2cb6 100644
--- a/apps/web/src/workspace-preferences.ts
+++ b/apps/web/src/workspace-preferences.ts
@@ -1,3 +1,5 @@
+// Per-device display preferences in localStorage (panels, density, font size, theme, send key,
+// notifications), validated on every read and write.
 import { useSyncExternalStore } from "react";
 
 export interface WorkspacePreferences {
diff --git a/scripts/hygiene-baseline.json b/scripts/hygiene-baseline.json
index b2e30673..b6b48c83 100644
--- a/scripts/hygiene-baseline.json
+++ b/scripts/hygiene-baseline.json
@@ -3,7 +3,7 @@
     "packages/protocol/AGENTS.md": 92
   },
   "undocumentedFiles": {
-    "apps/web": 129,
+    "apps/web": 0,
     "apps/server": 0,
     "apps/desktop": 33,
     "packages": 87,