docs(web): say what each Web source file is for

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 {

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,

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";

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. */

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;

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,

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";
 

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";

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";

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";

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";

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 {

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";

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 {

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";

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";

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,

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";

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,

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 {

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,

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";

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,

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";

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,

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 {

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,

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";
 

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";

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,

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";

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";
 

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,

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";

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";

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";

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 {

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,

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";

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";

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,

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 {

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";

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,

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";

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";

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,

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";
 

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";

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,

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 {

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";

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";

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";

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";

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";

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";

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,

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[] }) {

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";

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";
 

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";

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";

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,

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";

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";

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";