fix: add telegram timeout error

.agents/skills/add-provider-doc/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: add-provider-doc
-description: Add documentation for a new AI provider — usage docs, env vars, Docker config, image resources.
-disable-model-invocation: true
-argument-hint: '[provider-name]'
+description: Guide for adding new AI provider documentation. Use when adding documentation for a new AI provider (like OpenAI, Anthropic, etc.), including usage docs, environment variables, Docker config, and image resources. Triggers on provider documentation tasks.
 ---
 
 # Adding New AI Provider Documentation

.agents/skills/add-setting-env/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: add-setting-env
-description: Add server-side environment variables that control default values for user settings.
-disable-model-invocation: true
-argument-hint: '[setting-name]'
+description: Guide for adding environment variables to configure user settings. Use when implementing server-side environment variables that control default values for user settings. Triggers on env var configuration or setting default value tasks.
 ---
 
 # Adding Environment Variable for User Settings

.agents/skills/agent-runtime-hooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-runtime-hooks
-description: 'Agent runtime lifecycle hooks. Use for before/after tool or step hooks, tool mocks, human intervention, sub-agent calls, context compression, evals, tracing, callAgent, or lifecycle events.'
+description: "Agent runtime lifecycle hooks for observing and intercepting agent execution. Use when adding hooks to agent operations, mocking tool calls, logging step events, handling human intervention, sub-agent calls, context compression, or building eval/tracing integrations. Triggers on 'hooks', 'beforeToolCall', 'afterToolCall', 'beforeStep', 'afterStep', 'onComplete', 'onError', 'tool mock', 'agent lifecycle', 'human intervention', 'callAgent', 'compact'."
 user-invocable: false
 ---
 

.agents/skills/agent-signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-signal
-description: 'Build or extend LobeHub Agent Signal pipelines. Use for signal sources, signal/action types, policies, middleware, workflow handoff, dedupe, scope behavior, or observability.'
+description: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic signals, and action handlers. Use when adding a new Agent Signal source, signal or action type, policy, middleware handler, workflow handoff, dedupe or scope behavior, or observability around `src/server/services/agentSignal/**`, `packages/agent-signal`, or `packages/observability-otel/src/modules/agent-signal`.
 ---
 
 # Agent Signal

.agents/skills/agent-tracing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-tracing
-description: 'Agent tracing CLI for execution snapshots. Use for agent-tracing, traces, snapshots, LLM call inspection, context engine data, agent step analysis, or execution debugging.'
+description: "Agent tracing CLI for inspecting agent execution snapshots. Use when user mentions 'agent-tracing', 'trace', 'snapshot', wants to debug agent execution, inspect LLM calls, view context engine data, or analyze agent steps. Triggers on agent debugging, trace inspection, or execution analysis tasks."
 user-invocable: false
 ---
 
@@ -14,7 +14,7 @@ In `NODE_ENV=development`, `AgentRuntimeService.executeStep()` automatically rec
 
 **Data flow**: executeStep loop -> build `StepPresentationData` -> write partial snapshot to disk -> on completion, finalize to `.agent-tracing/{timestamp}_{traceId}.json`
 
-**Context engine capture**: In `RuntimeExecutors.ts`, the `call_llm` executor calls `ctx.tracingContextEngine(input, output)` after `serverMessagesEngine()` processes messages. `AgentRuntimeService.executeStep` buffers the call per step and forwards it to `OperationTraceRecorder.appendStep` as the typed `contextEngine` field. CE flows through this side channel rather than the `events` array so its heavy payload (agentDocuments, systemRole, …) never enters the Redis state pipeline (LOBE-9110).
+**Context engine capture**: In `RuntimeExecutors.ts`, the `call_llm` executor emits a `context_engine_result` event after `serverMessagesEngine()` processes messages. This event carries the full `contextEngineInput` (DB messages, systemRole, model, knowledge, tools, userMemory, etc.) and the processed `output` messages (the final LLM payload).
 
 ## Package Location
 
@@ -199,10 +199,9 @@ interface StepSnapshot {
   messages?: any[]; // DB messages before step
   context?: { phase: string; payload?: unknown; stepContext?: unknown };
   events?: Array<{ type: string; [key: string]: unknown }>;
-  contextEngine?: {
-    input?: unknown; // contextEngineInput minus messages + toolsConfig (reconstructible from baseline)
-    output?: unknown; // processed messages array (final LLM payload)
-  };
+  // context_engine_result event contains:
+  //   input: full contextEngineInput (messages, systemRole, model, knowledge, tools, userMemory, ...)
+  //   output: processed messages array (final LLM payload)
 }
 ```
 
@@ -217,5 +216,5 @@ When using `--messages`, the output shows three sections (if context engine data
 ## Integration Points
 
 - **Recording**: `src/server/services/agentRuntime/AgentRuntimeService.ts` — in the `executeStep()` method, after building `stepPresentationData`, writes partial snapshot in dev mode
-- **Context engine capture**: `src/server/modules/AgentRuntime/RuntimeExecutors.ts` — in `call_llm` executor, after `serverMessagesEngine()` returns, calls `ctx.tracingContextEngine(input, output)`. `AgentRuntimeService.executeStep` buffers it per step and passes it to `traceRecorder.appendStep` as the typed `contextEngine` field (kept off the `events` array to stay out of Redis state).
+- **Context engine event**: `src/server/modules/AgentRuntime/RuntimeExecutors.ts` — in `call_llm` executor, after `serverMessagesEngine()` returns, emits `context_engine_result` event
 - **Store**: `FileSnapshotStore` reads/writes to `.agent-tracing/` relative to `process.cwd()`

.agents/skills/bot/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: bot
+description: 'Bot platform architecture (Discord, Slack, Telegram, Feishu/Lark, QQ, WeChat). Use when working on inbound webhooks, Chat SDK message routing, agent execution from chat platforms, queue-mode callbacks, gateway lifecycle (websocket/polling), bot provider CRUD/credentials, or platform-specific clients/adapters/schemas. Triggers on bot, channel, webhook, mention, Chat SDK, agent bot provider, gateway, bot-callback, qstash bot.'
+---
+
+# Bot System
+
+> **Last updated: 2026-04-08.** Implementation evolves quickly — this doc is a map, not the source of truth. Always read the key files below to verify behavior, especially per-platform quirks. Update this doc when the architecture changes.
+
+LobeChat agents can answer inside external chat platforms. Inbound messages flow through the Chat SDK (`chat` npm package), get routed to the right agent by `(platform, applicationId)`, executed via `AiAgentService`, and replied back through a per-platform `PlatformClient`. There are **two execution modes** (in-memory vs queue/QStash) and **three connection modes** (`webhook`, `websocket`, `polling`).
+
+## Supported Platforms
+
+| Platform | id         | Default mode                    | Markdown          | Edit   | Notes                                                                                  |
+| -------- | ---------- | ------------------------------- | ----------------- | ------ | -------------------------------------------------------------------------------------- |
+| Discord  | `discord`  | `websocket`                     | yes               | yes    | Persistent gateway via Chat SDK adapter; reaction-thread quirks; native slash commands |
+| Slack    | `slack`    | `websocket` (Socket Mode)       | yes (mrkdwn)      | yes    | Multi-mode — user can pick `webhook` per provider                                      |
+| Telegram | `telegram` | `webhook`                       | yes (HTML)        | yes    | `setMyCommands` menu via `registerBotCommands`                                         |
+| Feishu   | `feishu`   | `websocket` (Lark SDK WSClient) | **no** (stripped) | yes    | Multi-mode; shared client with Lark                                                    |
+| Lark     | `lark`     | `websocket`                     | **no**            | yes    | Same client/schema as Feishu, different domain                                         |
+| QQ       | `qq`       | `websocket`                     | **no**            | **no** | All replies are final-only                                                             |
+| WeChat   | `wechat`   | `polling` (iLink long-poll)     | **no**            | **no** | 10-minute gateway window                                                               |
+
+`supportsMarkdown=false` ⇒ outbound markdown is stripped to plain text via `stripMarkdown` and the AI is told not to use markdown. `supportsMessageEdit=false` ⇒ no progress edits — only the final reply is sent.
+
+**Multi-mode connection** — Slack/Feishu/Lark/QQ ship as websocket but support `webhook` per-provider via `settings.connectionMode`. The runtime always merges schema defaults into stored settings before resolving the mode (`resolveBotProviderConfig` / `resolveConnectionMode` in `platforms/utils.ts`), so the schema's `field.default` is the source of truth — set it correctly when adding a new multi-mode platform.
+
+## Inbound Flow (one webhook → reply)
+
+```
+Platform server
+   │  POST /api/agent/webhooks/[platform]/[appId]
+   ▼
+route.ts ── catch-all `[[...appId]]` route
+   │
+   ▼
+BotMessageRouter (singleton)
+   │  • lazy-loads bot per `platform:applicationId`
+   │  • merges schema defaults + provider.settings (mergeWithDefaults)
+   │  • builds Chat SDK Chat<any> with createIoRedisState (if Redis available)
+   │  • registerHandlers: onNewMention / onSubscribedMessage / onNewMessage(/.dm)
+   │  • registerCommands: /new (reset topic), /stop (interrupt)
+   │
+   ▼
+chatBot.webhooks[platform](req)   ← Chat SDK parses → fires events
+   │
+   ▼
+AgentBridgeService.handleMention / handleSubscribedMessage
+   │  • activeThreads guard (no duplicate runs per thread)
+   │  • adds 👀 reaction (eyes), startTyping
+   │  • merges debounced/queued skipped messages (mergeSkippedMessages)
+   │  • extractFiles (buffer → fetchData → url)
+   │  • formatPrompt (sanitize mention + speaker tag + referenced_message)
+   │
+   ├── In-memory mode ──► AiAgentService.execAgent({ stepCallbacks })
+   │       → onAfterStep edits progress message live
+   │       → onComplete edits final reply, splits via splitMessage(charLimit)
+   │
+   └── Queue mode (isQueueAgentRuntimeEnabled) ──► execAgent({ stepWebhook, completionWebhook, webhookDelivery: 'qstash' })
+           → returns immediately, callbacks land at /api/agent/webhooks/bot-callback
+```
+
+The router caches loaded bots in memory. Cache is **invalidated** by `BotMessageRouter.invalidateBot(platform, appId)` whenever the TRPC `update`/`delete` mutations run, so new credentials/settings take effect on the next webhook.
+
+## Execution Modes
+
+### In-memory (default)
+
+`AgentBridgeService.executeWithInMemoryCallbacks` wraps `execAgent` with `stepCallbacks`. Lives in one process — Promise-based wait, 30-min timeout, edits the same `progressMessage` after every step. Topic title is summarized inline via `SystemAgentService`.
+
+### Queue (`isQueueAgentRuntimeEnabled`)
+
+`AgentBridgeService.executeWithWebhooks`:
+
+1. Posts the `renderStart` placeholder, captures `progressMessageId`.
+2. Calls `execAgent` with `stepWebhook` and `completionWebhook` pointing at `${INTERNAL_APP_URL ?? APP_URL}/api/agent/webhooks/bot-callback`, plus `webhookDelivery: 'qstash'`.
+3. Returns immediately; the bridge `finally` block keeps the active-thread marker held until the `completion` callback fires.
+
+`POST /api/agent/webhooks/bot-callback` (`src/server/agent-hono/handlers/botCallback.ts`) verifies the QStash signature via the `qstashAuth` middleware and hands off to `BotCallbackService.handleCallback`:
+
+- `type: 'step'` → `handleStep` re-renders `renderStepProgress`, edits `progressMessageId` (skipped if `displayToolCalls=false` or platform `supportsMessageEdit=false`).
+- `type: 'completion'` → `handleCompletion` writes the final reply (or error/interrupted message), removes the 👀 reaction, clears active-thread tracker, fires async `summarizeTopicTitle`.
+
+`BotCallbackService.createMessenger` reloads provider + credentials from DB and rebuilds a `PlatformClient` per call (no in-memory state).
+
+## Commands
+
+Defined in `BotMessageRouter.buildCommands` and registered via two paths:
+
+- **Native slash commands** (Slack/Discord): `bot.onSlashCommand('/<name>', ...)`
+- **Text-based fallback** (Telegram/Feishu/QQ/Lark/WeChat): `bot.onNewMessage(/^\/(new|stop)(\s|$|@)/, ...)` plus a per-mention `tryDispatch` so commands work even before subscribe.
+
+Built-in commands:
+
+- `/new` — clears `topicId` in thread state, next message starts a fresh topic.
+- `/stop` — interrupts the active execution (calls `AiAgentService.interruptTask` if `operationId` is known; otherwise queues a deferred stop via `requestStop`/`pendingStopThreads`, also aborts the startup phase via `startupControllers`).
+
+To add a command, append to `buildCommands` — it auto-registers everywhere; on Telegram it also surfaces in the `/` menu via `client.registerBotCommands` → `setMyCommands`.
+
+## Active-thread State (statics on `AgentBridgeService`)
+
+- `activeThreads: Set<threadId>` — prevents duplicate runs per thread (must guard before stale-topic check, otherwise concurrent messages can drop).
+- `activeOperations: Map<threadId, operationId>` — needed by `/stop` once `execAgent` returns.
+- `startupControllers: Map<threadId, AbortController>` — cancels pre-`operationId` work (topic/tool prep).
+- `pendingStopThreads: Set<threadId>` — `/stop` arrived before `operationId` existed; consumed once available.
+
+In **queue mode**, the bridge `finally` skips cleanup so the marker persists until `BotCallbackService.handleCompletion` calls `clearActiveThread`.
+
+## Topic Lifecycle in Threads
+
+- `handleMention` always treats the message as the start of a new conversation.
+- `handleSubscribedMessage` reads `topicId` from `thread.state`. If the topic is stale (`> 4 hours` since `updatedAt`), state is cleared and it retries as a fresh mention.
+- If `execAgent` fails with a Postgres FK violation on `topic_id` (cached topic was deleted), the bridge clears state and retries as a mention.
+- `subscribe()` is gated by `client.shouldSubscribe(threadId)` — Discord top-level channels return `false` so we don't follow up there.
+
+## Attachments
+
+`AgentBridgeService.extractFiles` resolves attachments in priority order:
+
+1. `att.buffer` — already downloaded by the adapter (WeChat/Feishu inbound).
+2. `att.fetchData()` — adapter-provided lazy download with auth (Telegram, Slack, Feishu history). **Required** when URLs are token-protected — naive `fetch(url)` later in `ingestAttachment.ts` has no credentials.
+3. `att.url` — public CDN fallback (Discord, public QQ).
+
+`inferMimeType` / `inferName` patch Telegram-style `photo` payloads (no `mimeType`/`name` from Bot API → defaults to `image/jpeg`) so vision models actually see them. Quoted-message attachments are also pulled from `raw.referenced_message.attachments` (Discord).
+
+## Concurrency
+
+`settings.concurrency` is `'queue'` or `'debounce'`:
+
+- `debounce` → Chat SDK debounces inbound messages by `debounceMs`; `mergeSkippedMessages` joins skipped texts/attachments into the current message before handing to the agent.
+- `queue` → Chat SDK serializes per-thread; the bridge's own `activeThreads` set is still required because in queue mode the SDK lock releases before the agent finishes.
+
+## Gateway (persistent platforms)
+
+Webhook platforms run fine in serverless functions. Persistent platforms (`websocket`, `polling`) need a long-running listener — that's the **gateway**.
+
+**`GatewayService.startClient(platform, appId, userId)`** (`src/server/services/gateway/index.ts`):
+
+- On Vercel + persistent mode → `BotConnectQueue.push` (Redis hash) and mark runtime status `queued`. The cron picks it up.
+- On Vercel + webhook mode → start the client inline (one HTTP call).
+- Off-Vercel → `GatewayManager` singleton holds long-lived clients in process.
+
+**`GET /api/agent/gateway`** (`src/server/agent-hono/handlers/gatewayCron.ts`, cron, `Bearer ${CRON_SECRET}`):
+
+- Iterates registered platforms and starts every enabled persistent provider with `durationMs = 10min`, then in `after(...)` polls `BotConnectQueue` every 30s for new connect requests, until the window expires.
+- `getEffectiveConnectionMode(platform, settings)` is the only place that resolves per-provider mode — respect it everywhere.
+
+**`POST /api/agent/gateway/start`** (`src/server/agent-hono/handlers/gatewayStart.ts`) is the non-Vercel `ensureRunning` entry point (`Bearer ${KEY_VAULTS_SECRET}`).
+
+**Runtime status** is stored in Redis at `bot:runtime-status:platform:appId` with TTL ≈ `durationMs + 60s`. States: `starting | connected | disconnected | failed | queued`. Updated by each `PlatformClient.start/stop` and by the gateway service.
+
+## Platform Definitions
+
+Each platform exposes a `PlatformDefinition` registered in `platforms/index.ts`:
+
+```ts
+{
+  id: 'discord',
+  name: 'Discord',
+  connectionMode: 'websocket',          // recommended default
+  schema: FieldSchema[],                 // applicationId + credentials + settings
+  clientFactory: new DiscordClientFactory(),
+  supportsMarkdown?: boolean,            // default true
+  supportsMessageEdit?: boolean,         // default true
+  documentation?: { portalUrl, setupGuideUrl },
+}
+```
+
+`schema` drives both server validation (`mergeWithDefaults`, `extractDefaults`) **and** the auto-generated UI form. Top-level keys `applicationId` / `credentials` / `settings` map to DB columns. Common settings fields live in `platforms/const.ts` (`displayToolCallsField`, `makeServerIdField(platform?)`, `makeUserIdField(platform?)`). The `serverId` / `userId` factories take a platform identifier so the field's hint can render platform-specific "how to find this ID" guidance (Discord Developer Mode, Telegram @userinfobot, etc.); pass no argument to fall back to generic copy.
+
+Each platform implements `PlatformClient` (see `platforms/types.ts`):
+
+- Lifecycle: `start(opts?)`, `stop()`
+- Inbound: `createAdapter()` → Chat SDK adapter map
+- Outbound: `getMessenger(platformThreadId)` → `{ createMessage, editMessage, removeReaction, triggerTyping, updateThreadName? }`
+- Formatting: `formatMarkdown?`, `formatReply?` (usage-stats footer when `showUsageStats`)
+- Helpers: `extractChatId`, `parseMessageId`, `sanitizeUserInput`, `shouldSubscribe`, `resolveReactionThreadId`
+- Optional patches: `applyChatPatches(chatBot)` (Discord uses this for `forwardedInteractions` + `threadRecovery`)
+- Optional menu: `registerBotCommands(commands)` (Telegram `setMyCommands`)
+
+`ClientFactory.validateCredentials` is called from the TRPC `testConnection` mutation — implement it to hit the platform API and return useful per-field errors.
+
+## Database
+
+**Schema** (`packages/database/src/schemas/agentBotProvider.ts`):
+
+```ts
+agent_bot_providers (
+  id uuid pk,
+  agent_id text fk → agents.id (cascade),
+  user_id text fk → users.id (cascade),
+  platform varchar(50),                  // 'discord' | 'slack' | …
+  application_id varchar(255),
+  credentials text,                      // KeyVaults-encrypted JSON
+  settings jsonb default '{}',
+  enabled boolean default true,
+  …timestamps
+)
+unique (platform, application_id)
+```
+
+**Model** (`packages/database/src/models/agentBotProvider.ts`):
+
+- User-scoped: `create / update / delete / query / findById / findByAgentId / findEnabledByApplicationId`. Credentials are encrypted/decrypted via the injected `KeyVaultsGateKeeper`.
+- Static (system-wide): `findByPlatformAndAppId`, `findEnabledByPlatform` — used by webhook routing & gateway sync, since they don't have a user context yet.
+
+**TRPC router** (`src/server/routers/lambda/agentBotProvider.ts`):
+
+| Procedure                                    | Notes                                                                                       |              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------ |
+| `listPlatforms`                              | Returns `SerializedPlatformDefinition[]` (no `clientFactory`)                               |              |
+| `create` / `update` / `delete`               | Calls `BotMessageRouter.invalidateBot` + `GatewayService.stopClient` so changes take effect |              |
+| `list` / `getByAgentId` / `getRuntimeStatus` | Decorate rows with Redis runtime status                                                     |              |
+| `connectBot`                                 | Returns \`{ status: 'started'                                                               | 'queued' }\` |
+| `testConnection`                             | Calls `clientFactory.validateCredentials`                                                   |              |
+| `wechatGetQrCode` / `wechatPollQrStatus`     | iLink onboarding flow                                                                       |              |
+
+Client service: `src/services/agentBotProvider.ts`. Store actions: `src/store/agent/slices/bot/action.ts`. UI: `src/routes/(main)/agent/channel/{list,detail}` — settings form is auto-generated from each platform's `schema`.
+
+## Reply Templates
+
+`src/server/services/bot/replyTemplate.ts` exports `renderStart`, `renderStepProgress`, `renderFinalReply`, `renderError`, `renderStopped`, `splitMessage`. Step progress carries elapsed time, last LLM content, last tools, totals; final reply uses `client.formatMarkdown` then `client.formatReply` (which optionally appends `formatUsageStats`). `splitMessage(text, charLimit)` chunks at paragraph → line → hard cut.
+
+`src/server/services/bot/ackPhrases/` provides randomized ack phrases.
+
+## Key Files
+
+```plaintext
+Webhook routes (mounted via `src/app/(backend)/api/agent/[[...route]]/route.ts` → `src/server/agent-hono`):
+  src/server/agent-hono/handlers/platformWebhook.ts  — inbound catch-all (POST /webhooks/:platform/:appId?)
+  src/server/agent-hono/handlers/botCallback.ts      — qstash bot callback
+  src/server/agent-hono/handlers/gatewayCron.ts      — cron gateway (10min window)
+  src/server/agent-hono/handlers/gatewayStart.ts     — non-Vercel ensureRunning
+
+Bot service:
+  src/server/services/bot/index.ts                          — barrel
+  src/server/services/bot/BotMessageRouter.ts               — lazy bot loading + handler registration + commands
+  src/server/services/bot/AgentBridgeService.ts             — Chat SDK ↔ AiAgentService bridge, both exec modes
+  src/server/services/bot/BotCallbackService.ts             — qstash callback handler
+  src/server/services/bot/formatPrompt.ts                   — speaker tag + referenced_message + sanitize
+  src/server/services/bot/replyTemplate.ts                  — render*/splitMessage
+  src/server/services/bot/ackPhrases/                       — randomized acks
+  src/server/services/bot/__tests__/                        — unit tests for the above
+
+Platform abstraction:
+  src/server/services/bot/platforms/index.ts                — registry singleton + exports
+  src/server/services/bot/platforms/types.ts                — PlatformClient/Definition/FieldSchema/ClientFactory
+  src/server/services/bot/platforms/registry.ts             — PlatformRegistry class
+  src/server/services/bot/platforms/utils.ts                — mergeWithDefaults, getEffectiveConnectionMode, formatUsageStats, runtimeKey
+  src/server/services/bot/platforms/const.ts                — shared FieldSchema fragments (displayToolCalls, serverId, userId)
+  src/server/services/bot/platforms/stripMarkdown.ts        — used by no-markdown platforms
+
+Per-platform (each ships definition.ts, schema.ts, client.ts, const.ts, protocol-spec.md):
+  src/server/services/bot/platforms/discord/                — websocket gateway + chat patches
+  src/server/services/bot/platforms/slack/                  — multi-mode (Socket Mode / webhook), markdownToMrkdwn
+  src/server/services/bot/platforms/telegram/               — webhook, markdownToHTML, registerBotCommands
+  src/server/services/bot/platforms/feishu/                 — feishu + lark share client/schema (definitions/{feishu,lark,shared}.ts)
+  src/server/services/bot/platforms/qq/                     — websocket, no markdown, no edit
+  src/server/services/bot/platforms/wechat/                 — long-poll, no markdown, no edit
+
+Gateway:
+  src/server/services/gateway/index.ts                      — GatewayService (Vercel-aware startClient/stopClient)
+  src/server/services/gateway/GatewayManager.ts             — long-running client registry (non-Vercel)
+  src/server/services/gateway/botConnectQueue.ts            — Redis hash queue with TTL
+  src/server/services/gateway/runtimeStatus.ts              — Redis bot:runtime-status keys
+
+Database:
+  packages/database/src/schemas/agentBotProvider.ts         — agent_bot_providers table
+  packages/database/src/models/agentBotProvider.ts          — encrypted CRUD + system-wide finders
+
+TRPC + client:
+  src/server/routers/lambda/agentBotProvider.ts             — TRPC router
+  src/services/agentBotProvider.ts                          — client wrapper
+  src/store/agent/slices/bot/action.ts                      — Zustand actions
+
+UI:
+  src/routes/(main)/agent/channel/list.tsx                  — channel list
+  src/routes/(main)/agent/channel/detail/                   — auto-generated form (Header/Body/Footer)
+  src/routes/(main)/agent/channel/const.ts                  — platform icons
+
+Types & runtime status:
+  src/types/botRuntimeStatus.ts                             — BOT_RUNTIME_STATUSES enum + snapshot type
+```
+
+## Adding a New Platform
+
+1. Create `src/server/services/bot/platforms/<id>/`:
+   - `definition.ts` — `PlatformDefinition` registered in `platforms/index.ts`
+   - `schema.ts` — `FieldSchema[]` (`applicationId` + `credentials` + `settings`); reuse fragments from `../const.ts`
+   - `client.ts` — `class XClientFactory extends ClientFactory` returning a `PlatformClient` (lifecycle + adapter + messenger + helpers)
+   - `const.ts` — `DEFAULT_X_CONNECTION_MODE`, history limits, etc.
+   - `protocol-spec.md` — protocol notes (every existing platform has one)
+2. Pick the right `connectionMode` — webhook is much simpler if the platform supports it.
+3. If the platform can't render markdown, set `supportsMarkdown: false` and implement `formatMarkdown` via `stripMarkdown`.
+4. If it can't edit messages, set `supportsMessageEdit: false` — `BotCallbackService` will skip step edits and only send the final reply.
+5. Implement `validateCredentials` so the UI's "Test connection" button gives useful errors.
+6. Add the platform icon in `src/routes/(main)/agent/channel/const.ts` and register the platform in `src/server/services/bot/platforms/index.ts`.
+7. Add i18n keys under `channel.*` in `src/locales/default/setting.ts` (or wherever the channel namespace lives) — the schema's `label`/`description`/`placeholder`/`enumLabels` are i18n keys.

.agents/skills/builtin-tool/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: builtin-tool
-description: 'Build LobeHub builtin tool packages. Use when adding agent-callable tools, manifests, executors, runtimes, inspectors, renders, placeholders, streaming, interventions, portals, or tool registries.'
+description: Build a new builtin tool package under `packages/builtin-tool-<name>/`. Use when adding a new agent-callable toolset, designing its API surface (manifest / ApiName / Params / State), implementing the Executor + ExecutionRuntime, building the Inspector / Render / Placeholder / Streaming / Intervention / Portal UI, or wiring a tool into the central registries (`packages/builtin-tools/src/{index,identifiers,inspectors,renders,placeholders,streamings,interventions,portals}.ts` and `src/store/tool/slices/builtin/executors/index.ts`). Triggers on "new builtin tool", "add a tool", "tool inspector", "tool render", "tool placeholder", "tool streaming", "tool intervention", "BuiltinToolManifest", "BaseExecutor", "ExecutionRuntime".
 ---
 
 # Builtin Tool Authoring Guide
@@ -19,11 +19,11 @@ A builtin tool is a package the agent runtime can call. It ships **five faces**:
 
 ## Read These First
 
-| Question                                                                             | Doc                                           |
-| ------------------------------------------------------------------------------------ | --------------------------------------------- |
-| Where do files live? What does each face do? Wiring?                                 | [architecture.md](references/architecture.md) |
-| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md)   |
-| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui/](references/ui/README.md)                |
+| Question                                                                             | Doc                                |
+| ------------------------------------------------------------------------------------ | ---------------------------------- |
+| Where do files live? What does each face do? Wiring?                                 | [architecture.md](architecture.md) |
+| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](tool-design.md)   |
+| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](ui.md)                     |
 
 ---
 
@@ -109,7 +109,7 @@ Before opening the PR:
 - [ ] Placeholder added if the API has a perceivable execution lag (search, list, crawl).
 - [ ] Streaming added for APIs that emit incremental output (run command, write file, code execution).
 - [ ] Intervention added if `humanIntervention` is set in the manifest.
-- [ ] All registry files updated (see [architecture.md → Registry wiring](references/architecture.md#registry-wiring)).
+- [ ] All registry files updated (see [architecture.md → Registry wiring](architecture.md#registry-wiring)).
 - [ ] i18n keys in `src/locales/default/plugin.ts` plus dev seeds in `en-US`/`zh-CN`.
 - [ ] `bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>'` passes.
 - [ ] `bun run type-check` passes.

.agents/skills/builtin-tool/architecture.md

@@ -213,7 +213,7 @@ The runtime hands every executor method an optional `BuiltinToolContext` as the
 | `operationId`                 | Operation lineage (use for cancellation, tracing)              |
 | `scope`                       | `'task' \| 'agent' \| …` — toggles default behaviors           |
 | `signal: AbortSignal`         | Honor for long-running ops                                     |
-| `stepContext`                 | Cross-message runtime state (lobe-agent todos, etc.)           |
+| `stepContext`                 | Cross-message runtime state (GTD todos, etc.)                  |
 | `registerAfterCompletion(cb)` | Defer side-effects past message-update race                    |
 | `groupOrchestration`          | Group orchestration callbacks                                  |
 

.agents/skills/builtin-tool/references/ui/README.md

@@ -1,36 +0,0 @@
-# Tool UI Surfaces
-
-A builtin tool can ship up to **six client-side surfaces**, each with a different role in the chat UI. Only `Inspector` is required; the other five are added on demand and registered in their own central files.
-
-| Surface      | Required? | When the chat shows it                                                | Registered in                                 |
-| ------------ | --------- | --------------------------------------------------------------------- | --------------------------------------------- |
-| Inspector    | ✅ Always | Header strip of every tool call (one-line chip)                       | `packages/builtin-tools/src/inspectors.ts`    |
-| Render       | Optional  | Rich result card below the header, after the call returns             | `packages/builtin-tools/src/renders.ts`       |
-| Placeholder  | Optional  | Skeleton between "args streaming complete" and "result arrives"       | `packages/builtin-tools/src/placeholders.ts`  |
-| Streaming    | Optional  | Live output during execution (e.g. command stdout)                    | `packages/builtin-tools/src/streamings.ts`    |
-| Intervention | Optional  | Approval / edit-before-run dialog (when `humanIntervention` triggers) | `packages/builtin-tools/src/interventions.ts` |
-| Portal       | Optional  | Full-screen detail view (right-side or modal)                         | `packages/builtin-tools/src/portals.ts`       |
-
-The two reference tools to read end-to-end:
-
-- **`builtin-tool-web-browsing/src/client/`** — Inspector + Render + Placeholder + Portal (no Intervention/Streaming).
-- **`builtin-tool-local-system/src/client/`** — all six surfaces, including `components/` for shared building blocks.
-
----
-
-## Files in this folder
-
-Read **principles** and **shared-rules** first — they apply to every surface. Then jump to the surface you're building.
-
-| File                               | What it covers                                                          |
-| ---------------------------------- | ----------------------------------------------------------------------- |
-| [principles.md](principles.md)     | Design principles — when each surface exists and how far to take it     |
-| [shared-rules.md](shared-rules.md) | Cross-surface rules: component skeleton, styling, single-layer surfaces |
-| [inspector.md](inspector.md)       | Inspector — header chip (required)                                      |
-| [render.md](render.md)             | Render — rich result card                                               |
-| [placeholder.md](placeholder.md)   | Placeholder — skeleton between args and result                          |
-| [streaming.md](streaming.md)       | Streaming — live output during execution                                |
-| [intervention.md](intervention.md) | Intervention — approval / edit-before-run                               |
-| [portal.md](portal.md)             | Portal — full-screen detail view                                        |
-| [composition.md](composition.md)   | Shared subcomponents (`client/components/`) + package public API        |
-| [diagnostics.md](diagnostics.md)   | Symptom → surface quick-lookup                                          |

.agents/skills/builtin-tool/references/ui/composition.md

@@ -1,51 +0,0 @@
-# Composition — Shared Components & Package API
-
-## `client/components/` — Shared Subcomponents
-
-Cross-cutting building blocks used by multiple surfaces live here, not duplicated in each surface folder.
-
-Examples from `web-browsing/src/client/components/`:
-
-- `CategoryAvatar.tsx` — search category icon
-- `EngineAvatar.tsx` — search engine logo (used in Inspector chip + Render list + Portal header)
-- `SearchBar.tsx` — editable query bar (used in Render and Portal)
-
-Examples from `local-system/src/client/components/`:
-
-- `FileItem.tsx` — single file row (used in ListFiles Render, SearchFiles Render, MoveLocalFiles Render)
-- `FilePathDisplay.tsx` — path with truncation (used everywhere)
-
-### Rules
-
-- Live under `client/components/`, exported via `client/components/index.ts`.
-- Re-export from `client/index.ts` only if other packages need them; otherwise keep internal.
-- Keep them dumb — props in, JSX out, no store reads. The store reads belong in the surface that composes them.
-
----
-
-## `client/index.ts` — Package Public API
-
-Re-exports everything the registries need plus useful types/manifest:
-
-```ts
-// Inspector — required
-export { TaskInspectors } from './Inspector';
-
-// Render — only if any API has one
-export { TaskRenders, CreateTaskRender, RunTasksRender } from './Render';
-
-// Placeholder / Streaming / Intervention — only if used
-export { LocalSystemListFilesPlaceholder, LocalSystemSearchFilesPlaceholder } from './Placeholder';
-export { LocalSystemStreamings } from './Streaming';
-export { LocalSystemInterventions } from './Intervention';
-
-// Portal — single export per tool
-export { default as WebBrowsingPortal } from './Portal';
-
-// Reusable components if other packages need them
-export { CategoryAvatar, EngineAvatar, SearchBar } from './components';
-
-// Re-export manifest, identifier, types for convenience
-export { TaskManifest, TaskIdentifier } from '../manifest';
-export * from '../types';
-```

.agents/skills/builtin-tool/references/ui/diagnostics.md

@@ -1,15 +0,0 @@
-# Diagnostic Quick-Lookup
-
-| Symptom                                         | Surface to check                                                                                                                      |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| No header at all on the tool call               | Inspector missing from `client/Inspector/index.ts` registry                                                                           |
-| Header shows the API name but no chips          | Inspector missing `args?.X \|\| partialArgs?.X` fallback                                                                              |
-| Header doesn't pulse during loading             | Missing `shinyTextStyles.shinyText` on `isArgumentsStreaming \|\| isLoading`                                                          |
-| Empty result card under header                  | Render returned `<div />` instead of `null` when no data                                                                              |
-| Render looks "complex" / card-in-card           | Filled container (`colorFillQuaternary`) wrapping more filled boxes — flatten to single-layer, see [shared-rules.md](shared-rules.md) |
-| Layout jump when result arrives                 | Placeholder dimensions don't match Render dimensions                                                                                  |
-| Approval dialog never appears                   | Manifest missing `humanIntervention`, or Intervention not in registry                                                                 |
-| Approval click doesn't wait for inline edit     | Missing `registerBeforeApprove(id, flushFn)`                                                                                          |
-| Portal opens but blank                          | Switch in `Portal/index.tsx` doesn't cover the apiName                                                                                |
-| Strings show as `builtins.lobe-foo.apiName.bar` | Missing i18n key in `src/locales/default/plugin.ts` (or not seeded in dev locale files)                                               |
-| Wrong color shade on `<Text type="secondary">`  | `type='secondary'` is lighter than `colorTextSecondary` — pass via `style={{ color: cssVar.colorTextSecondary }}`                     |

.agents/skills/builtin-tool/references/ui/inspector.md

@@ -1,118 +0,0 @@
-# Inspector — Header Chip (required)
-
-**Lifecycle:** Inspector renders for **every phase** of a tool call: while args are streaming in, while the executor is running, and after results come back. It's the only surface that's always visible.
-
-**Goal:** keep it to a single line. Show what's happening with as much context as is currently available.
-
-## Props (`BuiltinInspectorProps<Args, State>`)
-
-```ts
-interface BuiltinInspectorProps<Arguments = any, State = any> {
-  apiName: string;
-  args: Arguments; // final args (only after the assistant stops streaming)
-  identifier: string;
-  isArgumentsStreaming?: boolean; // args still arriving
-  isLoading?: boolean; // args complete, executor running
-  partialArgs?: Arguments; // partial JSON during streaming
-  pluginState?: State; // executor's `state` after success
-  result?: { content: string | null; error?: any };
-}
-```
-
-## State machine
-
-| Phase                               | What's available                                           | What to show                                               |
-| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
-| Args streaming, no useful field yet | `isArgumentsStreaming === true`, `partialArgs.X` undefined | Just the API title with `shinyTextStyles.shinyText`        |
-| Args streaming, key field arrived   | `partialArgs.X` populated                                  | Title + key field chip, still pulse-animated               |
-| Args complete, executor running     | `args` populated, `isLoading === true`                     | Same as above, still pulse-animated                        |
-| Result arrived                      | `pluginState` populated, `isLoading === false`             | Title + chips + result summary (count, identifier, status) |
-
-## Canonical example — Search
-
-`packages/builtin-tool-web-browsing/src/client/Inspector/Search/index.tsx`:
-
-```tsx
-'use client';
-
-import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
-import { Text } from '@lobehub/ui';
-import { cssVar, cx } from 'antd-style';
-import { memo } from 'react';
-import { useTranslation } from 'react-i18next';
-
-import { highlightTextStyles, inspectorTextStyles, shinyTextStyles } from '@/styles';
-
-export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
-  ({ args, partialArgs, isArgumentsStreaming, isLoading, pluginState }) => {
-    const { t } = useTranslation('plugin');
-
-    const query = args?.query || partialArgs?.query || '';
-    const resultCount = pluginState?.results?.length ?? 0;
-    const hasResults = resultCount > 0;
-
-    if (isArgumentsStreaming && !query) {
-      return (
-        <div className={cx(inspectorTextStyles.root, shinyTextStyles.shinyText)}>
-          <span>{t('builtins.lobe-web-browsing.apiName.search')}</span>
-        </div>
-      );
-    }
-
-    return (
-      <div
-        className={cx(
-          inspectorTextStyles.root,
-          (isArgumentsStreaming || isLoading) && shinyTextStyles.shinyText,
-        )}
-      >
-        <span>{t('builtins.lobe-web-browsing.apiName.search')}:&nbsp;</span>
-        {query && <span className={highlightTextStyles.primary}>{query}</span>}
-        {!isLoading &&
-          !isArgumentsStreaming &&
-          pluginState?.results &&
-          (hasResults ? (
-            <span style={{ marginInlineStart: 4 }}>({resultCount})</span>
-          ) : (
-            <Text as="span" color={cssVar.colorTextDescription} fontSize={12}>
-              ({t('builtins.lobe-web-browsing.inspector.noResults')})
-            </Text>
-          ))}
-      </div>
-    );
-  },
-);
-SearchInspector.displayName = 'SearchInspector';
-export default SearchInspector;
-```
-
-## Inspector rules
-
-- Wrap the whole row with `inspectorTextStyles.root` (provides correct flex / line-height baseline).
-- Pulse with `shinyTextStyles.shinyText` whenever `isArgumentsStreaming || isLoading`.
-- Show the i18n title first so the row is non-empty during the earliest streaming phase.
-- Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
-- Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
-- Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
-- **Switch copy by phase.** If the verb implies an ongoing action ("Creating", "Searching", "Listing"), define `<api>.loading` and `<api>.completed` keys and select via `isArgumentsStreaming || isLoading ? loadingKey : completedKey`. Inspector chips persist in chat history — leaving "Creating task" frozen on a finished call reads as if the tool is still running. Read-only labels that are already noun-form ("View task") can keep a single key. See `CallSubAgentInspector` for the canonical two-key pattern.
-
-## Inspector registry — `client/Inspector/index.ts`
-
-```ts
-import type { BuiltinInspector } from '@lobechat/types';
-
-import { TaskApiName } from '../../types';
-import { CreateTaskInspector } from './CreateTask';
-import { ListTasksInspector } from './ListTasks';
-/* … */
-
-export const TaskInspectors: Record<string, BuiltinInspector> = {
-  [TaskApiName.createTask]: CreateTaskInspector as BuiltinInspector,
-  [TaskApiName.listTasks]: ListTasksInspector as BuiltinInspector,
-  /* one entry per ApiName */
-};
-
-export { CreateTaskInspector } from './CreateTask';
-export { ListTasksInspector } from './ListTasks';
-/* re-export each */
-```

.agents/skills/builtin-tool/references/ui/intervention.md

@@ -1,88 +0,0 @@
-# Intervention — Approval / Edit-Before-Run (optional)
-
-**Lifecycle:** rendered **before the executor runs** for APIs whose manifest sets `humanIntervention`. The user sees a preview of the args, can edit them, then approves or skips/cancels.
-
-**Add for** destructive or sensitive ops: shell commands, file writes, file moves, payments, message broadcasts.
-
-## Props (`BuiltinInterventionProps<Args>`)
-
-```ts
-interface BuiltinInterventionProps<Arguments = any> {
-  apiName?: string;
-  args: Arguments;
-  identifier?: string;
-  interactionMode?: 'approval' | 'custom';
-  messageId: string;
-
-  /** Called when the user edits the args; the approve action awaits this. */
-  onArgsChange?: (args: Arguments) => void | Promise<void>;
-
-  /** Called on approve / skip / cancel. */
-  onInteractionAction?: (
-    action:
-      | { type: 'submit'; payload: Record<string, unknown> }
-      | { type: 'skip'; payload?: Record<string, unknown>; reason?: string }
-      | { type: 'cancel'; payload?: Record<string, unknown> },
-  ) => Promise<void>;
-
-  /** Register a callback to flush pending saves before approval. Returns cleanup. */
-  registerBeforeApprove?: (id: string, callback: () => void | Promise<void>) => () => void;
-}
-```
-
-## Canonical example — RunCommand Intervention
-
-`packages/builtin-tool-local-system/src/client/Intervention/RunCommand/index.tsx`:
-
-```tsx
-import type { RunCommandParams } from '@lobechat/electron-client-ipc';
-import type { BuiltinInterventionProps } from '@lobechat/types';
-import { Flexbox, Highlighter, Text } from '@lobehub/ui';
-import { memo } from 'react';
-
-const RunCommand = memo<BuiltinInterventionProps<RunCommandParams>>(({ args }) => {
-  const { description, command, timeout } = args;
-  return (
-    <Flexbox gap={8}>
-      <Flexbox horizontal justify="space-between">
-        {description && <Text>{description}</Text>}
-        {timeout && (
-          <Text style={{ fontSize: 12 }} type="secondary">
-            timeout: {formatTimeout(timeout)}
-          </Text>
-        )}
-      </Flexbox>
-      {command && (
-        <Highlighter wrap language="sh" showLanguage={false} variant="outlined">
-          {command}
-        </Highlighter>
-      )}
-    </Flexbox>
-  );
-});
-export default RunCommand;
-```
-
-## Intervention rules
-
-- **Show a preview, not a form by default.** Editing UI is opt-in via `onArgsChange` and is usually inline (click to edit a code block, etc.).
-- For args with debounced edit state (text fields), use `registerBeforeApprove(id, flushFn)` so the approve action waits for the debounce to flush. Always return the cleanup function.
-- Call `onInteractionAction({ type: 'submit', payload })` when the user approves; `'skip'` if they skip with a reason; `'cancel'` if they cancel the whole turn.
-- Add a corresponding `interventionAudit.ts` in the package root if the tool needs scope/path validation before approval (see `local-system/src/interventionAudit.ts`).
-
-## Intervention registry — `client/Intervention/index.ts`
-
-```ts
-import { LocalSystemApiName } from '../..';
-import EditLocalFile from './EditLocalFile';
-import RunCommand from './RunCommand';
-import WriteFile from './WriteFile';
-/* … */
-
-export const LocalSystemInterventions = {
-  [LocalSystemApiName.editLocalFile]: EditLocalFile,
-  [LocalSystemApiName.runCommand]: RunCommand,
-  [LocalSystemApiName.writeLocalFile]: WriteFile,
-  /* one entry per API that needs approval */
-};
-```

.agents/skills/builtin-tool/references/ui/placeholder.md

@@ -1,93 +0,0 @@
-# Placeholder — Skeleton Between Args and Result (optional)
-
-**Lifecycle:** rendered when the args have finished streaming but the executor hasn't returned yet. Disappears when `pluginState` arrives. Bridges the moment of perceived lag.
-
-**Add for** APIs with noticeable execution time: web search, network crawl, file list, large grep. **Skip for** instant ops (status flips, calculator).
-
-## Props (`BuiltinPlaceholderProps<Args>`)
-
-```ts
-interface BuiltinPlaceholderProps<T extends Record<string, any> = any> {
-  apiName: string;
-  args?: T;
-  identifier: string;
-}
-```
-
-No `pluginState` — Placeholder lives entirely in the "executing" gap.
-
-## Canonical example — Search Placeholder
-
-`packages/builtin-tool-web-browsing/src/client/Placeholder/Search.tsx`:
-
-```tsx
-import type { BuiltinPlaceholderProps, SearchQuery } from '@lobechat/types';
-import { Flexbox, Icon, Skeleton } from '@lobehub/ui';
-import { createStaticStyles, cx } from 'antd-style';
-import { SearchIcon } from 'lucide-react';
-import { memo } from 'react';
-
-import { useIsMobile } from '@/hooks/useIsMobile';
-import { shinyTextStyles } from '@/styles';
-
-const styles = createStaticStyles(({ css, cssVar }) => ({
-  query: cx(
-    css`
-      padding: 4px 8px;
-      border-radius: 8px;
-      font-size: 12px;
-      color: ${cssVar.colorTextSecondary};
-      &:hover {
-        background: ${cssVar.colorFillTertiary};
-      }
-    `,
-    shinyTextStyles.shinyText,
-  ),
-}));
-
-export const Search = memo<BuiltinPlaceholderProps<SearchQuery>>(({ args }) => {
-  const { query } = args || {};
-  const isMobile = useIsMobile();
-
-  return (
-    <Flexbox gap={8}>
-      <Flexbox horizontal={!isMobile} gap={isMobile ? 8 : 40}>
-        <Flexbox horizontal align="center" className={styles.query} gap={8}>
-          <Icon icon={SearchIcon} />
-          {query ? query : <Skeleton.Block active style={{ height: 20, width: 40 }} />}
-        </Flexbox>
-        <Skeleton.Block active style={{ height: 20, width: 40 }} />
-      </Flexbox>
-      <Flexbox horizontal gap={12}>
-        {[1, 2, 3, 4, 5].map((id) => (
-          <Skeleton.Button active key={id} style={{ borderRadius: 8, height: 80, width: 160 }} />
-        ))}
-      </Flexbox>
-    </Flexbox>
-  );
-});
-```
-
-## Placeholder rules
-
-- **Mirror the eventual Render's layout.** When the result arrives the Placeholder unmounts and the Render mounts; if they share dimensions, the chat doesn't jump.
-- Use `Skeleton.Block` / `Skeleton.Button` from `@lobehub/ui` for placeholder shapes.
-- Embed any args you have (e.g. the query text) — context helps the user know what's loading.
-- Pulse with `shinyTextStyles.shinyText` if the Placeholder includes literal text.
-
-## Placeholder registry — `client/Placeholder/index.ts`
-
-```ts
-import { WebBrowsingApiName } from '../../types';
-import CrawlMultiPages from './CrawlMultiPages';
-import CrawlSinglePage from './CrawlSinglePage';
-import { Search } from './Search';
-
-export const WebBrowsingPlaceholders = {
-  [WebBrowsingApiName.crawlMultiPages]: CrawlMultiPages,
-  [WebBrowsingApiName.crawlSinglePage]: CrawlSinglePage,
-  [WebBrowsingApiName.search]: Search,
-};
-
-export { CrawlMultiPages, CrawlSinglePage, Search };
-```

.agents/skills/builtin-tool/references/ui/portal.md

@@ -1,71 +0,0 @@
-# Portal — Full-Screen Detail View (optional)
-
-**Lifecycle:** rendered when the user opens the tool message in a side panel or full-screen modal. One Portal per **tool**, not per API — the Portal switches on `apiName` internally.
-
-**Add for** tools whose results deserve a deep-dive view: search results with editable filters, page content with reader mode, code interpreter sessions.
-
-## Props (`BuiltinPortalProps<Args, State>`)
-
-```ts
-interface BuiltinPortalProps<Arguments = Record<string, any>, State = any> {
-  apiName?: string;
-  arguments: Arguments;
-  identifier: string;
-  messageId: string;
-  state: State;
-}
-```
-
-## Canonical example — Web-Browsing Portal
-
-`packages/builtin-tool-web-browsing/src/client/Portal/index.tsx`:
-
-```tsx
-import type { BuiltinPortalProps, CrawlPluginState, SearchQuery } from '@lobechat/types';
-import { memo } from 'react';
-
-import { WebBrowsingApiName } from '../../types';
-import PageContent from './PageContent';
-import PageContents from './PageContents';
-import Search from './Search';
-
-const Portal = memo<BuiltinPortalProps>(({ arguments: args, messageId, state, apiName }) => {
-  switch (apiName) {
-    case WebBrowsingApiName.search:
-      return <Search messageId={messageId} query={args as SearchQuery} response={state} />;
-
-    case WebBrowsingApiName.crawlSinglePage: {
-      const result = (state as CrawlPluginState).results.find((r) => r.originalUrl === args.url);
-      return <PageContent messageId={messageId} result={result} />;
-    }
-
-    case WebBrowsingApiName.crawlMultiPages:
-      return (
-        <PageContents
-          messageId={messageId}
-          results={(state as CrawlPluginState).results}
-          urls={args.urls}
-        />
-      );
-  }
-  return null;
-});
-export default Portal;
-```
-
-## Portal rules
-
-- One Portal per tool — the file is the routing layer, subcomponents implement each API's view.
-- Portals can read the chat store directly to detect "still streaming" and render a Skeleton internally (see `Search/index.tsx:20-46`).
-- Layout assumes more space than the Render — use `Flexbox` with `height={'100%'}` and structure for a side panel viewport.
-
-## Portal registry — `packages/builtin-tools/src/portals.ts`
-
-```ts
-import { WebBrowsingManifest, WebBrowsingPortal } from '@lobechat/builtin-tool-web-browsing/client';
-import { type BuiltinPortal } from '@lobechat/types';
-
-export const BuiltinToolsPortals: Record<string, BuiltinPortal> = {
-  [WebBrowsingManifest.identifier]: WebBrowsingPortal as BuiltinPortal,
-};
-```

.agents/skills/builtin-tool/references/ui/principles.md

@@ -1,19 +0,0 @@
-# Tool Render 设计原则（中文草案）
-
-这些原则用于判断一个 builtin tool 的 Inspector / Render / Placeholder / Streaming / Intervention / Portal 应该做什么，以及做到什么程度。
-
-1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
-2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
-3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
-4. **文案要随状态切换时态。** 同一个动作在 loading 与 completed 两个阶段必须用不同的措辞：执行中用现在进行时（“正在创建任务 / Creating task / 正在搜索”），执行完成后切到完成态（“已创建任务 / Task created / 已找到 N 条”）。Inspector chip 会一直留在聊天记录里 —— 如果一直挂着 “正在 xxx”，几小时后回看历史时会读起来像还在跑。约定的 i18n 形式是 `<api>.loading` / `<api>.completed` 一对键（见 `lobe-agent.apiName.callSubAgent.{loading,completed}` 与 `lobe-claude-code.task.{create,list,update,get}.{loading,completed}`），渲染时按 `isArgumentsStreaming || isLoading` 决定取哪一个。只读 / 查询类（“查看任务” 这种本来就是名词性的）可以共用一个键。
-5. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
-6. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
-7. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
-8. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
-9. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
-10. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
-11. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
-12. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
-13. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。具体的样式约定见 [shared-rules.md](shared-rules.md)。
-14. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
-15. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。

.agents/skills/builtin-tool/references/ui/render.md

@@ -1,101 +0,0 @@
-# Render — Rich Result Card (optional)
-
-**Lifecycle:** rendered **once the result arrives** (after Placeholder/Streaming hand off). Sits below the Inspector header.
-
-**Skip if** the API is read-only or the result is just text — the framework already shows the executor's `content` string. Add a Render only when there's a structured artifact worth seeing: a card, a chart, a diff, a list of files.
-
-## Props (`BuiltinRenderProps<Args, State, Content>`)
-
-```ts
-interface BuiltinRenderProps<Arguments = any, State = any, Content = any> {
-  apiName?: string;
-  args: Arguments; // final params from the LLM
-  content: Content; // executor's content string (or parsed)
-  identifier?: string;
-  messageId: string; // for store lookups
-  pluginError?: any; // from BuiltinToolResult.error
-  pluginState?: State; // executor's state
-  toolCallId?: string;
-}
-```
-
-## Two patterns
-
-**Pattern A — Single-file Render** (web-browsing CrawlSinglePage):
-
-```tsx
-// client/Render/CrawlSinglePage.tsx
-import type { BuiltinRenderProps, CrawlPluginState, CrawlSinglePageQuery } from '@lobechat/types';
-import { memo } from 'react';
-
-import PageContent from './PageContent';
-
-const CrawlSinglePage = memo<BuiltinRenderProps<CrawlSinglePageQuery, CrawlPluginState>>(
-  ({ messageId, pluginState, args }) => (
-    <PageContent messageId={messageId} results={pluginState?.results} urls={[args?.url]} />
-  ),
-);
-export default CrawlSinglePage;
-```
-
-**Pattern B — Folder with subcomponents** (web-browsing Search):
-
-```
-client/Render/Search/
-├── index.tsx           # composes the subcomponents, handles error states
-├── ConfigForm.tsx      # appears when pluginError.type === 'PluginSettingsInvalid'
-├── SearchQuery.tsx     # editable query header
-└── SearchResult.tsx    # result list
-```
-
-Use Pattern B when the Render has internal state (editing mode, expanded items), error variants, or is large enough to benefit from splitting.
-
-## Error handling in Render
-
-Renders are the canonical place to surface `pluginError` because the chat doesn't auto-render typed errors:
-
-```tsx
-if (pluginError) {
-  if (pluginError?.type === 'PluginSettingsInvalid') {
-    return <ConfigForm id={messageId} provider={pluginError.body?.provider} />;
-  }
-  return (
-    <Alert
-      title={pluginError?.message}
-      type="error"
-      extra={<Highlighter language="json">{JSON.stringify(pluginError.body, null, 2)}</Highlighter>}
-    />
-  );
-}
-```
-
-## Render rules
-
-- **Return `null`** if there's nothing useful to draw yet (avoids empty cards during stream).
-- Use `pluginState` for server-truth (ids, counts, server-assigned status) and `args` for what the LLM asked. **Combine — neither alone is enough.**
-- For lists, summarize with a header line and show top N items with a "+N more" tail rather than rendering everything.
-- **Keep the Render single-layer** — the tool card is already your surface, so don't open with your own filled container and then nest more filled boxes inside it. See [shared-rules.md](shared-rules.md) → "Stay single-layer".
-- For modals from a Render, use `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
-
-## Render registry — `client/Render/index.ts`
-
-```ts
-import type { BuiltinRender } from '@lobechat/types';
-
-import { TaskApiName } from '../../types';
-import CreateTaskRender from './CreateTask';
-import RunTasksRender from './RunTasks';
-
-export const TaskRenders: Record<string, BuiltinRender> = {
-  [TaskApiName.createTask]: CreateTaskRender as BuiltinRender,
-  [TaskApiName.runTasks]: RunTasksRender as BuiltinRender,
-  /* only the APIs with rich result UI — others fall back to text content */
-};
-
-export { default as CreateTaskRender } from './CreateTask';
-export { default as RunTasksRender } from './RunTasks';
-```
-
-## Render display control (rare)
-
-If the Render should hide for certain results (e.g. ClaudeCode's TodoWrite hides when the agent is mid-stream), add a `RenderDisplayControl` to `packages/builtin-tools/src/displayControls.ts`. See `ClaudeCodeRenderDisplayControls` for the pattern.

.agents/skills/builtin-tool/references/ui/shared-rules.md

@@ -1,89 +0,0 @@
-# Shared Style Rules
-
-These apply across every surface.
-
-## The component skeleton
-
-Every surface file is the same shape, so internalize it once instead of re-deriving it per rule. The skeleton below bakes in five mechanical conventions — copy it and fill the body:
-
-```tsx
-'use client'; // (a) leaves of the chat tree must not block server rendering
-
-import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
-import { memo } from 'react';
-import { useTranslation } from 'react-i18next';
-
-// (b) type with BuiltinXProps<Args, State> — never widen to `any`.
-//     Args = the JSON Schema params, State = the executor's `state` field;
-//     they should match <Name>Params / <Name>State from types.ts.
-export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
-  ({ args, pluginState }) => {
-    const { t } = useTranslation('plugin'); // (c) all strings from the `plugin` namespace
-
-    // (d) cross-cutting state (loading, streaming buffer) comes from the store,
-    //     not props — props only carry args/state/messageId.
-    // const buffer = useChatStore((s) => chatToolSelectors.streamingBuffer(messageId)(s));
-
-    return <span>{t('builtins.<identifier>.apiName.search')}</span>;
-  },
-);
-SearchInspector.displayName = 'SearchInspector'; // (e) always memo + displayName
-export default SearchInspector;
-```
-
-- **(c)** Default an Inspector to `t('builtins.<identifier>.apiName.<api>')` so the row is non-empty while args stream in.
-- **(d)** Read the store via Zustand selectors inside the component; see [streaming.md](streaming.md) for the buffer selector.
-
-## Styling: `createStaticStyles + cssVar.*`, `@lobehub/ui` over `antd`
-
-Zero-runtime CSS-in-JS — styles compile once and read CSS variables at runtime:
-
-```tsx
-import { createStaticStyles, cssVar } from 'antd-style';
-
-const styles = createStaticStyles(({ css, cssVar }) => ({
-  chip: css`
-    padding-block: 2px;
-    padding-inline: 8px;
-    border-radius: 999px;
-    color: ${cssVar.colorText};
-    background: ${cssVar.colorFillTertiary};
-  `,
-}));
-```
-
-- Fall back to `createStyles + token` only when you need runtime token computation (rare). Inline `style={{ color: cssVar.colorTextSecondary }}` is fine for one-off dynamic values.
-- Components come from `@lobehub/ui` (`Block`, `Text`, `Flexbox`, `Highlighter`, `Alert`, `Tooltip`, `Skeleton`), not raw `antd`. Modals come from `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
-- Note: `<Text type='secondary'>` is a lighter shade than `colorTextSecondary`. For that exact token color, write `<Text style={{ color: cssVar.colorTextSecondary }}>`.
-
-## Stay single-layer — don't nest filled cards
-
-The framework already wraps every Render / Intervention in a tool card, so that card **is** your surface. A Render that opens with its own `background: ${cssVar.colorFillQuaternary}` container is already one card deep; put another filled box inside it (`colorBgContainer` / `colorFillTertiary`) and you get the card-in-card look that reads as "complex" — two or three stacked fills for what is really a flat list of fields.
-
-- **The outermost wrapper carries no fill.** Use a flat container with only `padding-block: 4px` for breathing room; let the tool card provide the card. (See `Agent/index.tsx`'s `container`.)
-- **At most one filled box, and only to delineate real content** — a Markdown preview, a diff, a code/result block. Labels, key–value fields, question/answer text, chips: render flat on the surface, separated by spacing or a hairline divider (`height: 1px; background: ${cssVar.colorFillSecondary}`), not by wrapping each in its own box.
-- **A box on a flat surface needs a visible fill.** Once the outer fill is gone, an inner `colorBgContainer` box can vanish against the tool card (same color). Use `colorFillTertiary` for the one content box so it still reads as delineated.
-- Don't wrap a single value in a box just to give it padding — that's the redundant-nesting smell (a `detailCard` around a `value` box around one string).
-
-```tsx
-// ❌ card-in-card: filled container wrapping a filled preview box
-container: css`
-  padding: 12px;
-  background: ${cssVar.colorFillQuaternary};
-`,
-previewBox: css`
-  background: ${cssVar.colorBgContainer};
-`,
-
-// ✅ single-layer: flat container, one visible content box
-container: css`
-  padding-block: 4px;
-`,
-previewBox: css`
-  background: ${cssVar.colorFillTertiary};
-`,
-```
-
-For the common "icon + file/title header, then one content box" shape, reuse `ToolResultCard` from `@lobechat/shared-tool-ui/components` instead of rebuilding it — it's already single-layer (flat wrapper, one `colorFillTertiary` content box) and is what CC `Read` / `Grep` / `Glob` / `Write` / `WebSearch` / `WebFetch` render through.
-
-The exception is a deliberate **panel** pattern — an `<Block variant="outlined">` with a header bar + list rows (CC `TodoWrite` / `Task`). There the single outlined block is the panel and the header fill is a header bar, not a nested card. One structured panel is fine; stacked decorative fills are not.

.agents/skills/builtin-tool/references/ui/streaming.md

@@ -1,83 +0,0 @@
-# Streaming — Live Output During Execution (optional)
-
-**Lifecycle:** rendered **while the executor is still running** for APIs that emit incremental output. The component is responsible for fetching the in-flight stream from the chat store and rendering it.
-
-**Add for** long-running ops with continuous output: shell command execution (stdout/stderr), file write progress, code interpreter cells.
-
-## Props (`BuiltinStreamingProps<Args>`)
-
-```ts
-interface BuiltinStreamingProps<Arguments = any> {
-  apiName: string;
-  args: Arguments;
-  identifier: string;
-  messageId: string; // use to fetch the streaming buffer from store
-  toolCallId: string;
-}
-```
-
-Note there's **no `state` or `result` prop** — the Streaming component is for the in-flight phase. It pulls the live buffer from the store itself (typically via `chatToolSelectors.streamingContent(messageId)` or similar).
-
-## Canonical example — RunCommandStreaming
-
-`packages/builtin-tool-local-system/src/client/Streaming/RunCommand/index.tsx`:
-
-```tsx
-'use client';
-
-import type { BuiltinStreamingProps } from '@lobechat/types';
-import { Highlighter } from '@lobehub/ui';
-import { memo } from 'react';
-
-interface RunCommandParams {
-  command?: string;
-  description?: string;
-  timeout?: number;
-}
-
-export const RunCommandStreaming = memo<BuiltinStreamingProps<RunCommandParams>>(({ args }) => {
-  const { command } = args || {};
-  if (!command) return null;
-
-  return (
-    <Highlighter
-      animated
-      wrap
-      language="sh"
-      showLanguage={false}
-      style={{ padding: '4px 8px' }}
-      variant="outlined"
-    >
-      {command}
-    </Highlighter>
-  );
-});
-RunCommandStreaming.displayName = 'RunCommandStreaming';
-```
-
-For real-time output beyond just the command (stderr/stdout streaming), pull from the chat store:
-
-```tsx
-const buffer = useChatStore((state) =>
-  chatToolSelectors.streamingBuffer(messageId, toolCallId)(state),
-);
-```
-
-## Streaming rules
-
-- Render `null` until you have something to display (avoids flash).
-- For terminal-style output, use `Highlighter` with `animated` to show typing-like effect.
-- The Streaming component must **unmount cleanly** when execution ends — typically the framework swaps it out for the Render automatically.
-
-## Streaming registry — `client/Streaming/index.ts`
-
-```ts
-import { LocalSystemApiName } from '../..';
-import { RunCommandStreaming } from './RunCommand';
-import { WriteFileStreaming } from './WriteFile';
-
-export const LocalSystemStreamings = {
-  [LocalSystemApiName.runCommand]: RunCommandStreaming,
-  [LocalSystemApiName.writeLocalFile]: WriteFileStreaming,
-};
-```

.agents/skills/builtin-tool/tool-design.md

@@ -2,7 +2,7 @@
 
 This doc covers everything that **isn't UI**: the tool's identifier, API surface, manifest, types, system prompt, ExecutionRuntime, and the executor that wires it into the frontend.
 
-For UI surfaces (Inspector / Render / Placeholder / Streaming / Intervention / Portal), see [ui/](ui/README.md).
+For UI surfaces (Inspector / Render / Placeholder / Streaming / Intervention / Portal), see [ui.md](ui.md).
 For where files live and how registries work, see [architecture.md](architecture.md).
 
 ---
@@ -156,7 +156,7 @@ export const TaskManifest: BuiltinToolManifest = {
   executors: ['client', 'server'],
 
   /* Default human intervention policy for all APIs that don't specify one.
-     Pair with an Intervention component (see ui/intervention.md). */
+     Pair with an Intervention component (see ui.md). */
   humanIntervention: 'never' | 'always' | { /* extended config */ },
 }
 ```

.agents/skills/builtin-tool/ui.md

@@ -0,0 +1,721 @@
+# Tool UI Surfaces
+
+A builtin tool can ship up to **six client-side surfaces**, each with a different role in the chat UI. Only `Inspector` is required; the other five are added on demand and registered in their own central files.
+
+| Surface      | Required? | When the chat shows it                                                | Registered in                                 |
+| ------------ | --------- | --------------------------------------------------------------------- | --------------------------------------------- |
+| Inspector    | ✅ Always | Header strip of every tool call (one-line chip)                       | `packages/builtin-tools/src/inspectors.ts`    |
+| Render       | Optional  | Rich result card below the header, after the call returns             | `packages/builtin-tools/src/renders.ts`       |
+| Placeholder  | Optional  | Skeleton between "args streaming complete" and "result arrives"       | `packages/builtin-tools/src/placeholders.ts`  |
+| Streaming    | Optional  | Live output during execution (e.g. command stdout)                    | `packages/builtin-tools/src/streamings.ts`    |
+| Intervention | Optional  | Approval / edit-before-run dialog (when `humanIntervention` triggers) | `packages/builtin-tools/src/interventions.ts` |
+| Portal       | Optional  | Full-screen detail view (right-side or modal)                         | `packages/builtin-tools/src/portals.ts`       |
+
+The two reference tools to read end-to-end:
+
+- **`builtin-tool-web-browsing/src/client/`** — Inspector + Render + Placeholder + Portal (no Intervention/Streaming).
+- **`builtin-tool-local-system/src/client/`** — all six surfaces, including `components/` for shared building blocks.
+
+---
+
+## 0. Shared Style Rules
+
+These apply across every surface.
+
+### 0.1 Use `'use client'` at the top of every component file
+
+Tool surfaces are leaves in the chat tree and must not block server rendering.
+
+### 0.2 Prefer `createStaticStyles + cssVar.*`
+
+Zero-runtime CSS-in-JS — the styles compile once and read CSS variables at runtime.
+
+```tsx
+import { createStaticStyles, cssVar } from 'antd-style';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  chip: css`
+    padding-block: 2px;
+    padding-inline: 8px;
+    border-radius: 999px;
+    color: ${cssVar.colorText};
+    background: ${cssVar.colorFillTertiary};
+  `,
+}));
+```
+
+Fall back to `createStyles + token` only when you need runtime token computation (rare). Inline `style={{ color: cssVar.colorTextSecondary }}` is fine for one-off dynamic values.
+
+### 0.3 Use `@lobehub/ui`, not raw `antd`
+
+`Block`, `Text`, `Flexbox`, `Highlighter`, `Alert`, `Tooltip`, `Skeleton` all come from `@lobehub/ui`. Modals come from `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+
+Memory note: `@lobehub/ui`'s `<Text type='secondary'>` is a lighter shade than `colorTextSecondary`. If you need that exact token color, write `<Text style={{ color: cssVar.colorTextSecondary }}>`.
+
+### 0.4 Always `memo` and set `displayName`
+
+```tsx
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args /* … */ }) => {
+    /* … */
+  },
+);
+SearchInspector.displayName = 'SearchInspector';
+export default SearchInspector;
+```
+
+### 0.5 Always type with `BuiltinXProps<Args, State>` generics
+
+Don't widen to `any`. The Args generic is the JSON Schema params, the State generic is the executor's `state` field. The two should match `<Name>Params` and `<Name>State` from `types.ts`.
+
+### 0.6 Pull strings from `t('plugin')`
+
+```tsx
+const { t } = useTranslation('plugin');
+t('builtins.<identifier>.apiName.<api>');
+```
+
+Every Inspector should default to `t('builtins.<identifier>.apiName.<api>')` so it shows something while args stream in.
+
+### 0.7 Read store state from `@/store/chat`, not props
+
+Tool surfaces sometimes need cross-cutting state (loading, streaming buffer). Read it inside the component via Zustand selectors, not from props — props only carry args/state/messageId.
+
+---
+
+## 1. Inspector — Header Chip (required)
+
+**Lifecycle:** Inspector renders for **every phase** of a tool call: while args are streaming in, while the executor is running, and after results come back. It's the only surface that's always visible.
+
+**Goal:** keep it to a single line. Show what's happening with as much context as is currently available.
+
+### Props (`BuiltinInspectorProps<Args, State>`)
+
+```ts
+interface BuiltinInspectorProps<Arguments = any, State = any> {
+  apiName: string;
+  args: Arguments; // final args (only after the assistant stops streaming)
+  identifier: string;
+  isArgumentsStreaming?: boolean; // args still arriving
+  isLoading?: boolean; // args complete, executor running
+  partialArgs?: Arguments; // partial JSON during streaming
+  pluginState?: State; // executor's `state` after success
+  result?: { content: string | null; error?: any };
+}
+```
+
+### State machine
+
+| Phase                               | What's available                                           | What to show                                               |
+| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| Args streaming, no useful field yet | `isArgumentsStreaming === true`, `partialArgs.X` undefined | Just the API title with `shinyTextStyles.shinyText`        |
+| Args streaming, key field arrived   | `partialArgs.X` populated                                  | Title + key field chip, still pulse-animated               |
+| Args complete, executor running     | `args` populated, `isLoading === true`                     | Same as above, still pulse-animated                        |
+| Result arrived                      | `pluginState` populated, `isLoading === false`             | Title + chips + result summary (count, identifier, status) |
+
+### Canonical example — Search
+
+`packages/builtin-tool-web-browsing/src/client/Inspector/Search/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
+import { Text } from '@lobehub/ui';
+import { cssVar, cx } from 'antd-style';
+import { memo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { highlightTextStyles, inspectorTextStyles, shinyTextStyles } from '@/styles';
+
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args, partialArgs, isArgumentsStreaming, isLoading, pluginState }) => {
+    const { t } = useTranslation('plugin');
+
+    const query = args?.query || partialArgs?.query || '';
+    const resultCount = pluginState?.results?.length ?? 0;
+    const hasResults = resultCount > 0;
+
+    if (isArgumentsStreaming && !query) {
+      return (
+        <div className={cx(inspectorTextStyles.root, shinyTextStyles.shinyText)}>
+          <span>{t('builtins.lobe-web-browsing.apiName.search')}</span>
+        </div>
+      );
+    }
+
+    return (
+      <div
+        className={cx(
+          inspectorTextStyles.root,
+          (isArgumentsStreaming || isLoading) && shinyTextStyles.shinyText,
+        )}
+      >
+        <span>{t('builtins.lobe-web-browsing.apiName.search')}:&nbsp;</span>
+        {query && <span className={highlightTextStyles.primary}>{query}</span>}
+        {!isLoading &&
+          !isArgumentsStreaming &&
+          pluginState?.results &&
+          (hasResults ? (
+            <span style={{ marginInlineStart: 4 }}>({resultCount})</span>
+          ) : (
+            <Text as="span" color={cssVar.colorTextDescription} fontSize={12}>
+              ({t('builtins.lobe-web-browsing.inspector.noResults')})
+            </Text>
+          ))}
+      </div>
+    );
+  },
+);
+SearchInspector.displayName = 'SearchInspector';
+export default SearchInspector;
+```
+
+### Inspector rules
+
+- Wrap the whole row with `inspectorTextStyles.root` (provides correct flex / line-height baseline).
+- Pulse with `shinyTextStyles.shinyText` whenever `isArgumentsStreaming || isLoading`.
+- Show the i18n title first so the row is non-empty during the earliest streaming phase.
+- Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
+- Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
+- Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
+
+### Inspector registry — `client/Inspector/index.ts`
+
+```ts
+import type { BuiltinInspector } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import { CreateTaskInspector } from './CreateTask';
+import { ListTasksInspector } from './ListTasks';
+/* … */
+
+export const TaskInspectors: Record<string, BuiltinInspector> = {
+  [TaskApiName.createTask]: CreateTaskInspector as BuiltinInspector,
+  [TaskApiName.listTasks]: ListTasksInspector as BuiltinInspector,
+  /* one entry per ApiName */
+};
+
+export { CreateTaskInspector } from './CreateTask';
+export { ListTasksInspector } from './ListTasks';
+/* re-export each */
+```
+
+---
+
+## 2. Render — Rich Result Card (optional)
+
+**Lifecycle:** rendered **once the result arrives** (after Placeholder/Streaming hand off). Sits below the Inspector header.
+
+**Skip if** the API is read-only or the result is just text — the framework already shows the executor's `content` string. Add a Render only when there's a structured artifact worth seeing: a card, a chart, a diff, a list of files.
+
+### Props (`BuiltinRenderProps<Args, State, Content>`)
+
+```ts
+interface BuiltinRenderProps<Arguments = any, State = any, Content = any> {
+  apiName?: string;
+  args: Arguments; // final params from the LLM
+  content: Content; // executor's content string (or parsed)
+  identifier?: string;
+  messageId: string; // for store lookups
+  pluginError?: any; // from BuiltinToolResult.error
+  pluginState?: State; // executor's state
+  toolCallId?: string;
+}
+```
+
+### Two patterns
+
+**Pattern A — Single-file Render** (web-browsing CrawlSinglePage):
+
+```tsx
+// client/Render/CrawlSinglePage.tsx
+import type { BuiltinRenderProps, CrawlPluginState, CrawlSinglePageQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import PageContent from './PageContent';
+
+const CrawlSinglePage = memo<BuiltinRenderProps<CrawlSinglePageQuery, CrawlPluginState>>(
+  ({ messageId, pluginState, args }) => (
+    <PageContent messageId={messageId} results={pluginState?.results} urls={[args?.url]} />
+  ),
+);
+export default CrawlSinglePage;
+```
+
+**Pattern B — Folder with subcomponents** (web-browsing Search):
+
+```
+client/Render/Search/
+├── index.tsx           # composes the subcomponents, handles error states
+├── ConfigForm.tsx      # appears when pluginError.type === 'PluginSettingsInvalid'
+├── SearchQuery.tsx     # editable query header
+└── SearchResult.tsx    # result list
+```
+
+Use Pattern B when the Render has internal state (editing mode, expanded items), error variants, or is large enough to benefit from splitting.
+
+### Error handling in Render
+
+Renders are the canonical place to surface `pluginError` because the chat doesn't auto-render typed errors:
+
+```tsx
+if (pluginError) {
+  if (pluginError?.type === 'PluginSettingsInvalid') {
+    return <ConfigForm id={messageId} provider={pluginError.body?.provider} />;
+  }
+  return (
+    <Alert
+      title={pluginError?.message}
+      type="error"
+      extra={<Highlighter language="json">{JSON.stringify(pluginError.body, null, 2)}</Highlighter>}
+    />
+  );
+}
+```
+
+### Render rules
+
+- **Return `null`** if there's nothing useful to draw yet (avoids empty cards during stream).
+- Use `pluginState` for server-truth (ids, counts, server-assigned status) and `args` for what the LLM asked. **Combine — neither alone is enough.**
+- For lists, summarize with a header line and show top N items with a "+N more" tail rather than rendering everything.
+- For modals from a Render, use `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+
+### Render registry — `client/Render/index.ts`
+
+```ts
+import type { BuiltinRender } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import CreateTaskRender from './CreateTask';
+import RunTasksRender from './RunTasks';
+
+export const TaskRenders: Record<string, BuiltinRender> = {
+  [TaskApiName.createTask]: CreateTaskRender as BuiltinRender,
+  [TaskApiName.runTasks]: RunTasksRender as BuiltinRender,
+  /* only the APIs with rich result UI — others fall back to text content */
+};
+
+export { default as CreateTaskRender } from './CreateTask';
+export { default as RunTasksRender } from './RunTasks';
+```
+
+### Render display control (rare)
+
+If the Render should hide for certain results (e.g. ClaudeCode's TodoWrite hides when the agent is mid-stream), add a `RenderDisplayControl` to `packages/builtin-tools/src/displayControls.ts`. See `ClaudeCodeRenderDisplayControls` for the pattern.
+
+---
+
+## 3. Placeholder — Skeleton Between Args and Result (optional)
+
+**Lifecycle:** rendered when the args have finished streaming but the executor hasn't returned yet. Disappears when `pluginState` arrives. Bridges the moment of perceived lag.
+
+**Add for** APIs with noticeable execution time: web search, network crawl, file list, large grep. **Skip for** instant ops (status flips, calculator).
+
+### Props (`BuiltinPlaceholderProps<Args>`)
+
+```ts
+interface BuiltinPlaceholderProps<T extends Record<string, any> = any> {
+  apiName: string;
+  args?: T;
+  identifier: string;
+}
+```
+
+No `pluginState` — Placeholder lives entirely in the "executing" gap.
+
+### Canonical example — Search Placeholder
+
+`packages/builtin-tool-web-browsing/src/client/Placeholder/Search.tsx`:
+
+```tsx
+import type { BuiltinPlaceholderProps, SearchQuery } from '@lobechat/types';
+import { Flexbox, Icon, Skeleton } from '@lobehub/ui';
+import { createStaticStyles, cx } from 'antd-style';
+import { SearchIcon } from 'lucide-react';
+import { memo } from 'react';
+
+import { useIsMobile } from '@/hooks/useIsMobile';
+import { shinyTextStyles } from '@/styles';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  query: cx(
+    css`
+      padding: 4px 8px;
+      border-radius: 8px;
+      font-size: 12px;
+      color: ${cssVar.colorTextSecondary};
+      &:hover {
+        background: ${cssVar.colorFillTertiary};
+      }
+    `,
+    shinyTextStyles.shinyText,
+  ),
+}));
+
+export const Search = memo<BuiltinPlaceholderProps<SearchQuery>>(({ args }) => {
+  const { query } = args || {};
+  const isMobile = useIsMobile();
+
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal={!isMobile} gap={isMobile ? 8 : 40}>
+        <Flexbox horizontal align="center" className={styles.query} gap={8}>
+          <Icon icon={SearchIcon} />
+          {query ? query : <Skeleton.Block active style={{ height: 20, width: 40 }} />}
+        </Flexbox>
+        <Skeleton.Block active style={{ height: 20, width: 40 }} />
+      </Flexbox>
+      <Flexbox horizontal gap={12}>
+        {[1, 2, 3, 4, 5].map((id) => (
+          <Skeleton.Button active key={id} style={{ borderRadius: 8, height: 80, width: 160 }} />
+        ))}
+      </Flexbox>
+    </Flexbox>
+  );
+});
+```
+
+### Placeholder rules
+
+- **Mirror the eventual Render's layout.** When the result arrives the Placeholder unmounts and the Render mounts; if they share dimensions, the chat doesn't jump.
+- Use `Skeleton.Block` / `Skeleton.Button` from `@lobehub/ui` for placeholder shapes.
+- Embed any args you have (e.g. the query text) — context helps the user know what's loading.
+- Pulse with `shinyTextStyles.shinyText` if the Placeholder includes literal text.
+
+### Placeholder registry — `client/Placeholder/index.ts`
+
+```ts
+import { WebBrowsingApiName } from '../../types';
+import CrawlMultiPages from './CrawlMultiPages';
+import CrawlSinglePage from './CrawlSinglePage';
+import { Search } from './Search';
+
+export const WebBrowsingPlaceholders = {
+  [WebBrowsingApiName.crawlMultiPages]: CrawlMultiPages,
+  [WebBrowsingApiName.crawlSinglePage]: CrawlSinglePage,
+  [WebBrowsingApiName.search]: Search,
+};
+
+export { CrawlMultiPages, CrawlSinglePage, Search };
+```
+
+---
+
+## 4. Streaming — Live Output During Execution (optional)
+
+**Lifecycle:** rendered **while the executor is still running** for APIs that emit incremental output. The component is responsible for fetching the in-flight stream from the chat store and rendering it.
+
+**Add for** long-running ops with continuous output: shell command execution (stdout/stderr), file write progress, code interpreter cells.
+
+### Props (`BuiltinStreamingProps<Args>`)
+
+```ts
+interface BuiltinStreamingProps<Arguments = any> {
+  apiName: string;
+  args: Arguments;
+  identifier: string;
+  messageId: string; // use to fetch the streaming buffer from store
+  toolCallId: string;
+}
+```
+
+Note there's **no `state` or `result` prop** — the Streaming component is for the in-flight phase. It pulls the live buffer from the store itself (typically via `chatToolSelectors.streamingContent(messageId)` or similar).
+
+### Canonical example — RunCommandStreaming
+
+`packages/builtin-tool-local-system/src/client/Streaming/RunCommand/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinStreamingProps } from '@lobechat/types';
+import { Highlighter } from '@lobehub/ui';
+import { memo } from 'react';
+
+interface RunCommandParams {
+  command?: string;
+  description?: string;
+  timeout?: number;
+}
+
+export const RunCommandStreaming = memo<BuiltinStreamingProps<RunCommandParams>>(({ args }) => {
+  const { command } = args || {};
+  if (!command) return null;
+
+  return (
+    <Highlighter
+      animated
+      wrap
+      language="sh"
+      showLanguage={false}
+      style={{ padding: '4px 8px' }}
+      variant="outlined"
+    >
+      {command}
+    </Highlighter>
+  );
+});
+RunCommandStreaming.displayName = 'RunCommandStreaming';
+```
+
+For real-time output beyond just the command (stderr/stdout streaming), pull from the chat store:
+
+```tsx
+const buffer = useChatStore((state) =>
+  chatToolSelectors.streamingBuffer(messageId, toolCallId)(state),
+);
+```
+
+### Streaming rules
+
+- Render `null` until you have something to display (avoids flash).
+- For terminal-style output, use `Highlighter` with `animated` to show typing-like effect.
+- The Streaming component must **unmount cleanly** when execution ends — typically the framework swaps it out for the Render automatically.
+
+### Streaming registry — `client/Streaming/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import { RunCommandStreaming } from './RunCommand';
+import { WriteFileStreaming } from './WriteFile';
+
+export const LocalSystemStreamings = {
+  [LocalSystemApiName.runCommand]: RunCommandStreaming,
+  [LocalSystemApiName.writeLocalFile]: WriteFileStreaming,
+};
+```
+
+---
+
+## 5. Intervention — Approval / Edit-Before-Run (optional)
+
+**Lifecycle:** rendered **before the executor runs** for APIs whose manifest sets `humanIntervention`. The user sees a preview of the args, can edit them, then approves or skips/cancels.
+
+**Add for** destructive or sensitive ops: shell commands, file writes, file moves, payments, message broadcasts.
+
+### Props (`BuiltinInterventionProps<Args>`)
+
+```ts
+interface BuiltinInterventionProps<Arguments = any> {
+  apiName?: string;
+  args: Arguments;
+  identifier?: string;
+  interactionMode?: 'approval' | 'custom';
+  messageId: string;
+
+  /** Called when the user edits the args; the approve action awaits this. */
+  onArgsChange?: (args: Arguments) => void | Promise<void>;
+
+  /** Called on approve / skip / cancel. */
+  onInteractionAction?: (
+    action:
+      | { type: 'submit'; payload: Record<string, unknown> }
+      | { type: 'skip'; payload?: Record<string, unknown>; reason?: string }
+      | { type: 'cancel'; payload?: Record<string, unknown> },
+  ) => Promise<void>;
+
+  /** Register a callback to flush pending saves before approval. Returns cleanup. */
+  registerBeforeApprove?: (id: string, callback: () => void | Promise<void>) => () => void;
+}
+```
+
+### Canonical example — RunCommand Intervention
+
+`packages/builtin-tool-local-system/src/client/Intervention/RunCommand/index.tsx`:
+
+```tsx
+import type { RunCommandParams } from '@lobechat/electron-client-ipc';
+import type { BuiltinInterventionProps } from '@lobechat/types';
+import { Flexbox, Highlighter, Text } from '@lobehub/ui';
+import { memo } from 'react';
+
+const RunCommand = memo<BuiltinInterventionProps<RunCommandParams>>(({ args }) => {
+  const { description, command, timeout } = args;
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal justify="space-between">
+        {description && <Text>{description}</Text>}
+        {timeout && (
+          <Text style={{ fontSize: 12 }} type="secondary">
+            timeout: {formatTimeout(timeout)}
+          </Text>
+        )}
+      </Flexbox>
+      {command && (
+        <Highlighter wrap language="sh" showLanguage={false} variant="outlined">
+          {command}
+        </Highlighter>
+      )}
+    </Flexbox>
+  );
+});
+export default RunCommand;
+```
+
+### Intervention rules
+
+- **Show a preview, not a form by default.** Editing UI is opt-in via `onArgsChange` and is usually inline (click to edit a code block, etc.).
+- For args with debounced edit state (text fields), use `registerBeforeApprove(id, flushFn)` so the approve action waits for the debounce to flush. Always return the cleanup function.
+- Call `onInteractionAction({ type: 'submit', payload })` when the user approves; `'skip'` if they skip with a reason; `'cancel'` if they cancel the whole turn.
+- Add a corresponding `interventionAudit.ts` in the package root if the tool needs scope/path validation before approval (see `local-system/src/interventionAudit.ts`).
+
+### Intervention registry — `client/Intervention/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import EditLocalFile from './EditLocalFile';
+import RunCommand from './RunCommand';
+import WriteFile from './WriteFile';
+/* … */
+
+export const LocalSystemInterventions = {
+  [LocalSystemApiName.editLocalFile]: EditLocalFile,
+  [LocalSystemApiName.runCommand]: RunCommand,
+  [LocalSystemApiName.writeLocalFile]: WriteFile,
+  /* one entry per API that needs approval */
+};
+```
+
+---
+
+## 6. Portal — Full-Screen Detail View (optional)
+
+**Lifecycle:** rendered when the user opens the tool message in a side panel or full-screen modal. One Portal per **tool**, not per API — the Portal switches on `apiName` internally.
+
+**Add for** tools whose results deserve a deep-dive view: search results with editable filters, page content with reader mode, code interpreter sessions.
+
+### Props (`BuiltinPortalProps<Args, State>`)
+
+```ts
+interface BuiltinPortalProps<Arguments = Record<string, any>, State = any> {
+  apiName?: string;
+  arguments: Arguments;
+  identifier: string;
+  messageId: string;
+  state: State;
+}
+```
+
+### Canonical example — Web-Browsing Portal
+
+`packages/builtin-tool-web-browsing/src/client/Portal/index.tsx`:
+
+```tsx
+import type { BuiltinPortalProps, CrawlPluginState, SearchQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import { WebBrowsingApiName } from '../../types';
+import PageContent from './PageContent';
+import PageContents from './PageContents';
+import Search from './Search';
+
+const Portal = memo<BuiltinPortalProps>(({ arguments: args, messageId, state, apiName }) => {
+  switch (apiName) {
+    case WebBrowsingApiName.search:
+      return <Search messageId={messageId} query={args as SearchQuery} response={state} />;
+
+    case WebBrowsingApiName.crawlSinglePage: {
+      const result = (state as CrawlPluginState).results.find((r) => r.originalUrl === args.url);
+      return <PageContent messageId={messageId} result={result} />;
+    }
+
+    case WebBrowsingApiName.crawlMultiPages:
+      return (
+        <PageContents
+          messageId={messageId}
+          results={(state as CrawlPluginState).results}
+          urls={args.urls}
+        />
+      );
+  }
+  return null;
+});
+export default Portal;
+```
+
+### Portal rules
+
+- One Portal per tool — the file is the routing layer, subcomponents implement each API's view.
+- Portals can read the chat store directly to detect "still streaming" and render a Skeleton internally (see `Search/index.tsx:20-46`).
+- Layout assumes more space than the Render — use `Flexbox` with `height={'100%'}` and structure for a side panel viewport.
+
+### Portal registry — `packages/builtin-tools/src/portals.ts`
+
+```ts
+import { WebBrowsingManifest, WebBrowsingPortal } from '@lobechat/builtin-tool-web-browsing/client';
+import { type BuiltinPortal } from '@lobechat/types';
+
+export const BuiltinToolsPortals: Record<string, BuiltinPortal> = {
+  [WebBrowsingManifest.identifier]: WebBrowsingPortal as BuiltinPortal,
+};
+```
+
+---
+
+## 7. `client/components/` — Shared Subcomponents
+
+Cross-cutting building blocks used by multiple surfaces live here, not duplicated in each surface folder.
+
+Examples from `web-browsing/src/client/components/`:
+
+- `CategoryAvatar.tsx` — search category icon
+- `EngineAvatar.tsx` — search engine logo (used in Inspector chip + Render list + Portal header)
+- `SearchBar.tsx` — editable query bar (used in Render and Portal)
+
+Examples from `local-system/src/client/components/`:
+
+- `FileItem.tsx` — single file row (used in ListFiles Render, SearchFiles Render, MoveLocalFiles Render)
+- `FilePathDisplay.tsx` — path with truncation (used everywhere)
+
+### Rules
+
+- Live under `client/components/`, exported via `client/components/index.ts`.
+- Re-export from `client/index.ts` only if other packages need them; otherwise keep internal.
+- Keep them dumb — props in, JSX out, no store reads. The store reads belong in the surface that composes them.
+
+---
+
+## 8. `client/index.ts` — Package Public API
+
+Re-exports everything the registries need plus useful types/manifest:
+
+```ts
+// Inspector — required
+export { TaskInspectors } from './Inspector';
+
+// Render — only if any API has one
+export { TaskRenders, CreateTaskRender, RunTasksRender } from './Render';
+
+// Placeholder / Streaming / Intervention — only if used
+export { LocalSystemListFilesPlaceholder, LocalSystemSearchFilesPlaceholder } from './Placeholder';
+export { LocalSystemStreamings } from './Streaming';
+export { LocalSystemInterventions } from './Intervention';
+
+// Portal — single export per tool
+export { default as WebBrowsingPortal } from './Portal';
+
+// Reusable components if other packages need them
+export { CategoryAvatar, EngineAvatar, SearchBar } from './components';
+
+// Re-export manifest, identifier, types for convenience
+export { TaskManifest, TaskIdentifier } from '../manifest';
+export * from '../types';
+```
+
+---
+
+## 9. Diagnostic Quick-Lookup
+
+| Symptom                                         | Surface to check                                                                                                  |     |                           |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --- | ------------------------- |
+| No header at all on the tool call               | Inspector missing from `client/Inspector/index.ts` registry                                                       |     |                           |
+| Header shows the API name but no chips          | Inspector missing \`args?.X                                                                                       |     | partialArgs?.X\` fallback |
+| Header doesn't pulse during loading             | Missing `shinyTextStyles.shinyText` on `isArgumentsStreaming \|\| isLoading`                                      |     |                           |
+| Empty result card under header                  | Render returned `<div />` instead of `null` when no data                                                          |     |                           |
+| Layout jump when result arrives                 | Placeholder dimensions don't match Render dimensions                                                              |     |                           |
+| Approval dialog never appears                   | Manifest missing `humanIntervention`, or Intervention not in registry                                             |     |                           |
+| Approval click doesn't wait for inline edit     | Missing `registerBeforeApprove(id, flushFn)`                                                                      |     |                           |
+| Portal opens but blank                          | Switch in `Portal/index.tsx` doesn't cover the apiName                                                            |     |                           |
+| Strings show as `builtins.lobe-foo.apiName.bar` | Missing i18n key in `src/locales/default/plugin.ts` (or not seeded in dev locale files)                           |     |                           |
+| Wrong color shade on `<Text type="secondary">`  | `type='secondary'` is lighter than `colorTextSecondary` — pass via `style={{ color: cssVar.colorTextSecondary }}` |     |                           |

.agents/skills/chat-sdk/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: chat-sdk
-description: 'Build multi-platform chat bots with the chat SDK. Use for Slack, Teams, Google Chat, Discord, GitHub, Linear bots, webhooks, mentions, slash commands, cards, modals, or streaming responses.'
-user-invocable: false
+description: >
+  Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to
+  (1) Build a Slack, Teams, Google Chat, Discord, GitHub, or Linear bot,
+  (2) Use the Chat SDK to handle mentions, messages, reactions, slash commands, cards, modals, or streaming,
+  (3) Set up webhook handlers for chat platforms,
+  (4) Send interactive cards or stream AI responses to chat platforms.
+  Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "discord bot", "@chat-adapter",
+  building bots that work across multiple chat platforms.
 ---
 
 # Chat SDK

.agents/skills/cli-backend-testing/SKILL.md

@@ -29,9 +29,10 @@ Standard workflow for verifying backend changes using the LobeHub CLI (`lh`) aga
 
 ## Quick Reference
 
-All CLI dev commands run from `lobehub/apps/cli/`. Subsequent examples use `$CLI`:
+All CLI dev commands run from `lobehub/apps/cli/`:
 
 ```bash
+# Shorthand for all commands below
 CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"
 ```
 
@@ -39,14 +40,17 @@ CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"
 
 ### Step 1: Ensure Dev Server is Running
 
+Check if the dev server is already running:
+
 ```bash
 curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null
 ```
 
-- **If reachable**: skip to Step 2.
-- **If unreachable**: start from cloud repo root:
+- **If reachable** (returns any HTTP status): server is running. Skip to Step 2.
+- **If unreachable**: start the server:
 
 ```bash
+# From cloud repo root
 pnpm run dev:next
 ```
 
@@ -61,33 +65,37 @@ pnpm run dev:next
 
 ### Step 2: Check CLI Authentication
 
+Check if dev credentials already exist:
+
 ```bash
 cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null
 ```
 
-- **If file exists and contains `"serverUrl": "http://localhost:3011"`**: skip to Step 3.
-- **If missing or wrong server**: ask the user to run:
+- **If file exists and contains `"serverUrl": "http://localhost:3011"`**: already authenticated. Skip to Step 3.
+- **If file missing or points to wrong server**: login is needed. Ask the user to run:
 
 ```bash
 ! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011
 ```
 
-> Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via `!` prefix. Credentials persist in `lobehub/apps/cli/.lobehub-dev/`.
+> Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via `!` prefix. After login, credentials are saved to `lobehub/apps/cli/.lobehub-dev/` and persist across sessions.
 
 ### Step 3: Test with CLI Commands
 
-CLI runs from source, so CLI-side code changes take effect immediately without rebuilding.
+CLI runs from source (`bun src/index.ts`), so CLI-side code changes take effect immediately without rebuilding.
 
 ```bash
 cd lobehub/apps/cli
-$CLI <command>
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
 ```
 
 ### Step 4: Clean Up Test Data
 
+Delete any test data created during verification:
+
 ```bash
-$CLI task delete < id > -y
-$CLI agent delete < id > -y
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts task delete < id > -y
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y
 ```
 
 ## Common Testing Patterns
@@ -95,30 +103,51 @@ $CLI agent delete < id > -y
 ### Task System
 
 ```bash
+# List tasks
 $CLI task list
+
+# Create test data with nesting
 $CLI task create -n "Root Task" -i "Test instruction"
 $CLI task create -n "Child Task" -i "Sub instruction" --parent T-1
+
+# View task detail (tests getTaskDetail service)
 $CLI task view T-1
+
+# View task tree
 $CLI task tree T-1
+
+# Test lifecycle
 $CLI task edit T-1 --status running
 $CLI task comment T-1 -m "Test comment"
+
+# Clean up
 $CLI task delete T-1 -y
 ```
 
 ### Agent System
 
 ```bash
+# List agents
 $CLI agent list
+
+# View agent detail
 $CLI agent view <agent-id>
+
+# Run agent (tests agent execution pipeline)
 $CLI agent run <agent-id> -m "Test prompt"
 ```
 
 ### Document & Knowledge Base
 
 ```bash
+# List documents
 $CLI doc list
+
+# Create and view
 $CLI doc create -t "Test Doc" -c "Content here"
 $CLI doc view <doc-id>
+
+# Knowledge base
 $CLI kb list
 $CLI kb tree <kb-id>
 ```
@@ -126,13 +155,18 @@ $CLI kb tree <kb-id>
 ### Model & Provider
 
 ```bash
+# List models and providers
 $CLI model list
 $CLI provider list
+
+# Test provider connectivity
 $CLI provider test <provider-id>
 ```
 
 ## Dev-Test Cycle
 
+The standard cycle for backend development:
+
 ```
 1. Make code changes (service/model/router/type)
          |
@@ -143,7 +177,7 @@ $CLI provider test <provider-id>
    lsof -ti:3011 | xargs kill && pnpm run dev:next
          |
 4. CLI verification (end-to-end)
-   $CLI <command>
+   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
          |
 5. Clean up test data
 ```
@@ -159,6 +193,10 @@ $CLI provider test <provider-id>
 | `lobehub/apps/cli/` (CLI code)            | No       |
 | `src/` (cloud overrides)                  | Yes      |
 
+### When Server Restart is NOT Needed
+
+CLI runs from source via `bun src/index.ts`, so any changes to `lobehub/apps/cli/src/` take effect immediately on next command invocation.
+
 ## Troubleshooting
 
 | Issue                       | Solution                                                              |
@@ -169,3 +207,12 @@ $CLI provider test <provider-id>
 | CLI shows old data/behavior | Server needs restart to pick up code changes                          |
 | `EADDRINUSE` on port 3011   | Server already running; kill with `lsof -ti:3011 \| xargs kill`       |
 | Login opens wrong server    | Must use `--server http://localhost:3011` flag (env var doesn't work) |
+
+## Credential Isolation
+
+| Mode       | Credential Dir                   | Server            |
+| ---------- | -------------------------------- | ----------------- |
+| Dev        | `lobehub/apps/cli/.lobehub-dev/` | `localhost:3011`  |
+| Production | `~/.lobehub/`                    | `app.lobehub.com` |
+
+The two environments are completely isolated. Dev mode credentials are gitignored.

.agents/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli
-description: LobeHub CLI (@lobehub/cli) development guide — commands, subcommands, architecture.
+description: LobeHub CLI (@lobehub/cli) development guide. Use when working on CLI commands, adding new subcommands, fixing CLI bugs, or understanding CLI architecture. Triggers on CLI development, command implementation, or `lh` command questions.
 disable-model-invocation: true
 ---
 

.agents/skills/data-fetching-architecture/SKILL.md

@@ -1,614 +0,0 @@
----
-name: data-fetching-architecture
-description: 'LobeHub data-fetching pipeline guide. Use for service layer, Zustand store, SWR, lambdaClient, useClientDataSWR, useFetchXxx hooks, or migrating useEffect fetches.'
-user-invocable: false
----
-
-# LobeHub Data Fetching Architecture
-
-> **Related:** `store-data-structures` covers List vs Detail data shape rationale (Map vs Array).
-
-## Architecture Overview
-
-```text
-┌─────────────┐
-│  Component  │
-└──────┬──────┘
-       │ 1. Call useFetchXxx hook from store
-       ↓
-┌──────────────────┐
-│  Zustand Store   │
-│  (State + Hook)  │
-└──────┬───────────┘
-       │ 2. useClientDataSWR calls service
-       ↓
-┌──────────────────┐
-│  Service Layer   │
-│  (xxxService)    │
-└──────┬───────────┘
-       │ 3. Call lambdaClient
-       ↓
-┌──────────────────┐
-│  lambdaClient    │
-│  (TRPC Client)   │
-└──────────────────┘
-```
-
-## Core Principles
-
-### ✅ DO
-
-1. **Use Service Layer** for all API calls
-2. **Use Store SWR Hooks** for data fetching (not useEffect)
-3. **Use proper data structures** — see `store-data-structures` skill for List vs Detail patterns
-4. **Use lambdaClient.mutate** for write operations (create/update/delete)
-5. **Use lambdaClient.query** only inside service methods
-6. **Naming convention** — read hooks are `useFetchXxx`, cache invalidation helpers are `refreshXxx` (e.g. `useFetchBenchmarks` / `refreshBenchmarks`). Mutations then chain `refreshXxx()` after the service call.
-
-### ❌ DON'T
-
-1. **Never use useEffect** for data fetching
-2. **Never call lambdaClient** directly in components or stores
-3. **Never use useState** for server data
-4. **Never mix data structure patterns** — follow `store-data-structures` skill
-
----
-
-## Layer 1: Service Layer
-
-### Purpose
-
-- Encapsulate all API calls to lambdaClient
-- Provide clean, typed interfaces
-- Single source of truth for API operations
-
-### Service Structure
-
-```typescript
-// src/services/agentEval.ts
-class AgentEvalService {
-  // Query methods - READ operations
-  async listBenchmarks() {
-    return lambdaClient.agentEval.listBenchmarks.query();
-  }
-
-  async getBenchmark(id: string) {
-    return lambdaClient.agentEval.getBenchmark.query({ id });
-  }
-
-  // Mutation methods - WRITE operations
-  async createBenchmark(params: CreateBenchmarkParams) {
-    return lambdaClient.agentEval.createBenchmark.mutate(params);
-  }
-
-  async updateBenchmark(params: UpdateBenchmarkParams) {
-    return lambdaClient.agentEval.updateBenchmark.mutate(params);
-  }
-
-  async deleteBenchmark(id: string) {
-    return lambdaClient.agentEval.deleteBenchmark.mutate({ id });
-  }
-}
-
-export const agentEvalService = new AgentEvalService();
-```
-
-### Service Guidelines
-
-1. **One service per domain** (e.g., agentEval, ragEval, aiAgent)
-2. **Export singleton instance** (`export const xxxService = new XxxService()`)
-3. **Method names match operations** (list, get, create, update, delete)
-4. **Clear parameter types** (use interfaces for complex params)
-
----
-
-## Layer 2: Store with SWR Hooks
-
-### Purpose
-
-- Manage client-side state
-- Provide SWR hooks for data fetching
-- Handle cache invalidation
-
-### State Structure
-
-```typescript
-// src/store/eval/slices/benchmark/initialState.ts
-export interface BenchmarkSliceState {
-  // List data - simple array
-  benchmarkList: AgentEvalBenchmarkListItem[];
-  benchmarkListInit: boolean;
-
-  // Detail data - map for caching
-  benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
-  loadingBenchmarkDetailIds: string[];
-
-  // Mutation states
-  isCreatingBenchmark: boolean;
-  isUpdatingBenchmark: boolean;
-  isDeletingBenchmark: boolean;
-}
-```
-
-> For complete initialState, reducer, and internal dispatch patterns, see the `store-data-structures` skill.
-
-### Actions
-
-```typescript
-// src/store/eval/slices/benchmark/action.ts
-const FETCH_BENCHMARKS_KEY = 'FETCH_BENCHMARKS';
-const FETCH_BENCHMARK_DETAIL_KEY = 'FETCH_BENCHMARK_DETAIL';
-
-export interface BenchmarkAction {
-  // SWR Hooks - for data fetching
-  useFetchBenchmarks: () => SWRResponse;
-  useFetchBenchmarkDetail: (id?: string) => SWRResponse;
-
-  // Refresh methods - for cache invalidation
-  refreshBenchmarks: () => Promise<void>;
-  refreshBenchmarkDetail: (id: string) => Promise<void>;
-
-  // Mutation actions
-  createBenchmark: (params: CreateParams) => Promise<any>;
-  updateBenchmark: (params: UpdateParams) => Promise<void>;
-  deleteBenchmark: (id: string) => Promise<void>;
-
-  // Internal methods - not for direct UI use
-  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
-  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
-}
-
-export const createBenchmarkSlice: StateCreator<EvalStore, any, [], BenchmarkAction> = (
-  set,
-  get,
-) => ({
-  // Fetch list — simple array stored in benchmarkList
-  useFetchBenchmarks: () =>
-    useClientDataSWR(FETCH_BENCHMARKS_KEY, () => agentEvalService.listBenchmarks(), {
-      onSuccess: (data) => {
-        set({ benchmarkList: data, benchmarkListInit: true }, false, 'useFetchBenchmarks/success');
-      },
-    }),
-
-  // Fetch detail — null key disables the request when id is missing
-  useFetchBenchmarkDetail: (id) =>
-    useClientDataSWR(
-      id ? [FETCH_BENCHMARK_DETAIL_KEY, id] : null,
-      () => agentEvalService.getBenchmark(id!),
-      {
-        onSuccess: (data) => {
-          get().internal_dispatchBenchmarkDetail({
-            type: 'setBenchmarkDetail',
-            id: id!,
-            value: data,
-          });
-          get().internal_updateBenchmarkDetailLoading(id!, false);
-        },
-      },
-    ),
-
-  // Refresh methods
-  refreshBenchmarks: () => mutate(FETCH_BENCHMARKS_KEY),
-  refreshBenchmarkDetail: (id) => mutate([FETCH_BENCHMARK_DETAIL_KEY, id]),
-
-  // CREATE — refresh list after creation
-  createBenchmark: async (params) => {
-    set({ isCreatingBenchmark: true }, false, 'createBenchmark/start');
-    try {
-      const result = await agentEvalService.createBenchmark(params);
-      await get().refreshBenchmarks();
-      return result;
-    } finally {
-      set({ isCreatingBenchmark: false }, false, 'createBenchmark/end');
-    }
-  },
-
-  // UPDATE — optimistic update + refresh
-  updateBenchmark: async (params) => {
-    const { id } = params;
-
-    // 1. Optimistic update
-    get().internal_dispatchBenchmarkDetail({
-      type: 'updateBenchmarkDetail',
-      id,
-      value: params,
-    });
-    // 2. Set loading
-    get().internal_updateBenchmarkDetailLoading(id, true);
-
-    try {
-      // 3. Call service
-      await agentEvalService.updateBenchmark(params);
-      // 4. Refresh from server
-      await get().refreshBenchmarks();
-      await get().refreshBenchmarkDetail(id);
-    } finally {
-      get().internal_updateBenchmarkDetailLoading(id, false);
-    }
-  },
-
-  // DELETE — optimistic update + refresh
-  deleteBenchmark: async (id) => {
-    get().internal_dispatchBenchmarkDetail({ type: 'deleteBenchmarkDetail', id });
-    get().internal_updateBenchmarkDetailLoading(id, true);
-
-    try {
-      await agentEvalService.deleteBenchmark(id);
-      await get().refreshBenchmarks();
-    } finally {
-      get().internal_updateBenchmarkDetailLoading(id, false);
-    }
-  },
-
-  // Internal — dispatch to reducer (for detail map)
-  internal_dispatchBenchmarkDetail: (payload) => {
-    const currentMap = get().benchmarkDetailMap;
-    const nextMap = benchmarkDetailReducer(currentMap, payload);
-
-    // Skip set when nothing changed — avoids unnecessary re-renders
-    if (isEqual(nextMap, currentMap)) return;
-    set({ benchmarkDetailMap: nextMap }, false, `dispatchBenchmarkDetail/${payload.type}`);
-  },
-
-  // Internal — update loading state for specific detail
-  internal_updateBenchmarkDetailLoading: (id, loading) => {
-    set(
-      (state) => ({
-        loadingBenchmarkDetailIds: loading
-          ? [...state.loadingBenchmarkDetailIds, id]
-          : state.loadingBenchmarkDetailIds.filter((i) => i !== id),
-      }),
-      false,
-      'updateBenchmarkDetailLoading',
-    );
-  },
-});
-```
-
-### Store Guidelines
-
-1. **SWR keys as constants** at top of file
-2. **useClientDataSWR** for all data fetching (never useEffect)
-3. **onSuccess callback** updates store state
-4. **Refresh methods** use `mutate()` to invalidate cache
-5. **Loading states** in initialState, updated in onSuccess
-6. **Mutations** call service, then refresh relevant cache
-
----
-
-## Layer 3: Component Usage
-
-### Fetching List Data
-
-```tsx
-// ✅ CORRECT
-const BenchmarkList = () => {
-  // 1. Get the hook from store
-  const useFetchBenchmarks = useEvalStore((s) => s.useFetchBenchmarks);
-
-  // 2. Get list data
-  const benchmarks = useEvalStore((s) => s.benchmarkList);
-  const isInit = useEvalStore((s) => s.benchmarkListInit);
-
-  // 3. Call the hook (SWR handles the data fetching)
-  useFetchBenchmarks();
-
-  // 4. Use the data
-  if (!isInit) return <Loading />;
-  return (
-    <div>
-      <h2>Total: {benchmarks.length}</h2>
-      {benchmarks.map((b) => (
-        <BenchmarkCard key={b.id} {...b} />
-      ))}
-    </div>
-  );
-};
-```
-
-### Fetching Detail Data
-
-```tsx
-// ✅ CORRECT
-const BenchmarkDetail = () => {
-  const { benchmarkId } = useParams<{ benchmarkId: string }>();
-
-  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);
-
-  // Detail from map
-  const benchmark = useEvalStore((s) =>
-    benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
-  );
-
-  // Per-item loading
-  const isLoading = useEvalStore((s) =>
-    benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
-  );
-
-  useFetchBenchmarkDetail(benchmarkId);
-
-  if (!benchmark) return <Loading />;
-  return (
-    <div>
-      <h1>{benchmark.name}</h1>
-      <p>{benchmark.description}</p>
-      {isLoading && <Spinner />}
-    </div>
-  );
-};
-```
-
-### Using Selectors (Recommended)
-
-```typescript
-// src/store/eval/slices/benchmark/selectors.ts
-export const benchmarkSelectors = {
-  getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
-  isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
-    s.loadingBenchmarkDetailIds.includes(id),
-};
-
-// Component with selectors
-const BenchmarkDetail = () => {
-  const { benchmarkId } = useParams();
-  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);
-  const benchmark = useEvalStore(benchmarkSelectors.getBenchmarkDetail(benchmarkId!));
-
-  useFetchBenchmarkDetail(benchmarkId);
-
-  return <div>{benchmark && <h1>{benchmark.name}</h1>}</div>;
-};
-```
-
-### Anti-pattern
-
-```tsx
-// ❌ WRONG — Don't use useEffect for data fetching
-const BenchmarkList = () => {
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    setLoading(true);
-    lambdaClient.agentEval.listBenchmarks
-      .query()
-      .then(setData)
-      .finally(() => setLoading(false));
-  }, []);
-
-  return <div>...</div>;
-};
-```
-
-### Mutations in Components
-
-```tsx
-// Create — global mutation flag drives form loading
-const CreateBenchmarkModal = () => {
-  const createBenchmark = useEvalStore((s) => s.createBenchmark);
-  const isCreating = useEvalStore((s) => s.isCreatingBenchmark);
-
-  const handleSubmit = async (values) => {
-    try {
-      // Optimistic update + refresh happen inside createBenchmark
-      await createBenchmark(values);
-      message.success('Created successfully');
-      onClose();
-    } catch (error) {
-      message.error('Failed to create');
-    }
-  };
-
-  return (
-    <Form onSubmit={handleSubmit} loading={isCreating}>
-      ...
-    </Form>
-  );
-};
-
-// Update / delete — per-item loading so only the row being mutated spins
-const BenchmarkItem = ({ id }: { id: string }) => {
-  const updateBenchmark = useEvalStore((s) => s.updateBenchmark);
-  const deleteBenchmark = useEvalStore((s) => s.deleteBenchmark);
-  const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(id));
-
-  const handleUpdate = async (data) => {
-    await updateBenchmark({ id, ...data });
-  };
-
-  const handleDelete = async () => {
-    await deleteBenchmark(id);
-  };
-
-  return (
-    <div>
-      {isLoading && <Spinner />}
-      <button onClick={handleUpdate}>Update</button>
-      <button onClick={handleDelete}>Delete</button>
-    </div>
-  );
-};
-```
-
-**Why two patterns:** create has no id yet, so a single `isCreatingXxx` flag is enough. Update/delete target a specific row, so global flags would freeze unrelated rows — keep per-item state in `loadingXxxIds`.
-
----
-
-## Need a fuller worked example?
-
-The canonical `Benchmark` example above is the one to copy for a flat list + detail map. If you need to maintain a list **keyed by a parent id** (e.g. `datasetMap[benchmarkId]` because the same shape appears under multiple parents), read [`references/walkthrough.md`](./references/walkthrough.md) — it walks through the full 6 steps (service → reducer → slice → store wiring → selectors → component) for that variant.
-
----
-
-## Common Patterns
-
-### Pattern 1: Pagination
-
-Cache key array must include every parameter that should trigger a refetch.
-
-```typescript
-useFetchTestCases: (params: { datasetId: string; limit: number; offset: number }) =>
-  useClientDataSWR(
-    params.datasetId ? [FETCH_TEST_CASES_KEY, params.datasetId, params.limit, params.offset] : null,
-    () => agentEvalService.listTestCases(params),
-    {
-      onSuccess: (data) =>
-        set({
-          testCaseList: data.data,
-          testCaseTotal: data.total,
-          isLoadingTestCases: false,
-        }),
-    },
-  );
-```
-
-### Pattern 2: Dependent Fetching
-
-Both hooks run in parallel — SWR dedupes, no manual sequencing needed.
-
-```tsx
-const BenchmarkDetail = () => {
-  const { benchmarkId } = useParams();
-  const useFetchBenchmarkDetail = useEvalStore((s) => s.useFetchBenchmarkDetail);
-  const useFetchDatasets = useEvalStore((s) => s.useFetchDatasets);
-
-  useFetchBenchmarkDetail(benchmarkId);
-  useFetchDatasets(benchmarkId);
-
-  return <div>...</div>;
-};
-```
-
-### Pattern 3: Conditional Fetching
-
-Pass `undefined` to disable the hook entirely.
-
-```tsx
-// only fetch when modal is open AND id present
-useFetchDatasetDetail(open && datasetId ? datasetId : undefined);
-```
-
-### Pattern 4: Cross-domain Refresh
-
-```typescript
-deleteBenchmark: async (id) => {
-  await agentEvalService.deleteBenchmark(id);
-  await get().refreshBenchmarks();
-  await get().refreshDatasets(id); // related cache invalidated too
-};
-```
-
----
-
-## Migration Guide: useEffect → Store SWR
-
-### Before (❌ Wrong)
-
-```tsx
-const TestCaseList = ({ datasetId }: Props) => {
-  const [data, setData] = useState<any[]>([]);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    setLoading(true);
-    lambdaClient.agentEval.listTestCases
-      .query({ datasetId })
-      .then((r) => setData(r.data))
-      .finally(() => setLoading(false));
-  }, [datasetId]);
-
-  return <Table data={data} loading={loading} />;
-};
-```
-
-### After (✅ Correct)
-
-```typescript
-// 1. Add service method
-class AgentEvalService {
-  async listTestCases(params: { datasetId: string }) {
-    return lambdaClient.agentEval.listTestCases.query(params);
-  }
-}
-
-// 2. Add store slice hook
-export const createTestCaseSlice: StateCreator<...> = (set) => ({
-  useFetchTestCases: (params) =>
-    useClientDataSWR(
-      params.datasetId ? [FETCH_TEST_CASES_KEY, params.datasetId] : null,
-      () => agentEvalService.listTestCases(params),
-      {
-        onSuccess: (data) =>
-          set({ testCaseList: data.data, isLoadingTestCases: false }),
-      },
-    ),
-});
-
-// 3. Component reads from store
-const TestCaseList = ({ datasetId }: Props) => {
-  const useFetchTestCases = useEvalStore((s) => s.useFetchTestCases);
-  const data = useEvalStore((s) => s.testCaseList);
-  const loading = useEvalStore((s) => s.isLoadingTestCases);
-
-  useFetchTestCases({ datasetId });
-
-  return <Table data={data} loading={loading} />;
-};
-```
-
----
-
-## Troubleshooting
-
-| Symptom                     | Check                                                               |
-| --------------------------- | ------------------------------------------------------------------- |
-| Data never loads            | Hook called? Key not `null`/`undefined`? Network tab shows request? |
-| Stale data after mutation   | Did `refreshXxx` run? Cache key matches what the hook uses?         |
-| Loading state stuck `true`  | `onSuccess` writes loading=false? Promise rejected silently?        |
-| Detail map missing an entry | Reducer dispatch ran? `isEqual` short-circuited on stale data?      |
-
----
-
-## Summary Checklist
-
-When adding new data fetching:
-
-### Step 1: Types & State
-
-See `store-data-structures` for details.
-
-- [ ] Define types in `@lobechat/types`: Detail type + List item type
-- [ ] State structure: `xxxList: XxxListItem[]`, `xxxDetailMap: Record<string, Xxx>`, `loadingXxxDetailIds: string[]`
-- [ ] Reducer if optimistic updates are needed
-
-### Step 2: Service Layer
-
-- [ ] Create service in `src/services/xxxService.ts`
-- [ ] Methods: `listXxx()`, `getXxx(id)`, `createXxx()`, `updateXxx()`, `deleteXxx()`
-
-### Step 3: Store Actions
-
-- [ ] `initialState.ts` with state structure
-- [ ] `action.ts` with:
-  - [ ] `useFetchXxxList()`, `useFetchXxxDetail(id)` — SWR hooks
-  - [ ] `refreshXxxList()`, `refreshXxxDetail(id)` — cache invalidation
-  - [ ] CRUD methods calling service
-  - [ ] `internal_dispatch`, `internal_updateLoading` if using reducer
-- [ ] `selectors.ts` (optional but recommended)
-- [ ] Integrate slice into main store + initialState
-
-### Step 4: Component Usage
-
-- [ ] Use store hooks (NOT useEffect)
-- [ ] List pages: access `xxxList` array
-- [ ] Detail pages: access `xxxDetailMap[id]`
-- [ ] Use loading states for UI feedback
-
-**Mental model:** Types → Service → Reducer → Slice → Component 🎯
-
----
-
-## Related Skills
-
-- **`store-data-structures`** — How to structure List and Detail data in stores
-- **`zustand`** — General Zustand patterns and best practices

.agents/skills/data-fetching-architecture/references/walkthrough.md

@@ -1,244 +0,0 @@
-# Walkthrough: Adding a New Feature End-to-End
-
-This is a worked example of the canonical 6-step recipe applied to a new entity (`Dataset`), showing a variant of the main skill's pattern: **a list keyed by a parent id** (`datasetMap[benchmarkId]`), useful when the same shape appears under different parents.
-
-If you only need the canonical (single-array) pattern, the main `SKILL.md` already shows it for `Benchmark`. Read this file when you need the parent-keyed Map variant, or when you want a checklist-style walkthrough.
-
-## Step 1: Add Service methods
-
-```typescript
-class AgentEvalService {
-  async listDatasets(benchmarkId: string) {
-    return lambdaClient.agentEval.listDatasets.query({ benchmarkId });
-  }
-  async getDataset(id: string) {
-    return lambdaClient.agentEval.getDataset.query({ id });
-  }
-  async createDataset(params: CreateDatasetParams) {
-    return lambdaClient.agentEval.createDataset.mutate(params);
-  }
-  // updateDataset / deleteDataset follow the same shape
-}
-```
-
-## Step 2: Reducer (optimistic updates)
-
-```typescript
-// src/store/eval/slices/dataset/reducer.ts
-export type DatasetDispatch =
-  | { type: 'addDataset'; value: Dataset }
-  | { type: 'updateDataset'; id: string; value: Partial<Dataset> }
-  | { type: 'deleteDataset'; id: string };
-
-export const datasetReducer = (state: Dataset[] = [], payload: DatasetDispatch): Dataset[] =>
-  produce(state, (draft) => {
-    switch (payload.type) {
-      case 'addDataset':
-        draft.unshift(payload.value);
-        break;
-      case 'updateDataset': {
-        const i = draft.findIndex((item) => item.id === payload.id);
-        if (i !== -1) draft[i] = { ...draft[i], ...payload.value };
-        break;
-      }
-      case 'deleteDataset': {
-        const i = draft.findIndex((item) => item.id === payload.id);
-        if (i !== -1) draft.splice(i, 1);
-        break;
-      }
-    }
-  });
-```
-
-## Step 3: Store slice
-
-```typescript
-// src/store/eval/slices/dataset/initialState.ts
-export interface DatasetData {
-  currentPage: number;
-  hasMore: boolean;
-  isLoading: boolean;
-  items: Dataset[];
-  pageSize: number;
-  total: number;
-}
-
-export interface DatasetSliceState {
-  // Map keyed by benchmarkId — multiple parent contexts share the slice
-  datasetMap: Record<string, DatasetData>;
-  // Single item for modal display
-  datasetDetail: Dataset | null;
-  isLoadingDatasetDetail: boolean;
-  loadingDatasetIds: string[];
-}
-
-export const datasetInitialState: DatasetSliceState = {
-  datasetMap: {},
-  datasetDetail: null,
-  isLoadingDatasetDetail: false,
-  loadingDatasetIds: [],
-};
-```
-
-```typescript
-// src/store/eval/slices/dataset/action.ts
-const FETCH_DATASETS_KEY = 'FETCH_DATASETS';
-const FETCH_DATASET_DETAIL_KEY = 'FETCH_DATASET_DETAIL';
-
-export const createDatasetSlice: StateCreator<EvalStore, any, [], DatasetAction> = (set, get) => ({
-  // Cache key includes benchmarkId so each parent has its own SWR entry
-  useFetchDatasets: (benchmarkId) =>
-    useClientDataSWR(
-      benchmarkId ? [FETCH_DATASETS_KEY, benchmarkId] : null,
-      () => agentEvalService.listDatasets(benchmarkId!),
-      {
-        onSuccess: (data) => {
-          set({
-            datasetMap: {
-              ...get().datasetMap,
-              [benchmarkId!]: {
-                currentPage: 1,
-                hasMore: false,
-                isLoading: false,
-                items: data,
-                pageSize: data.length,
-                total: data.length,
-              },
-            },
-          });
-        },
-      },
-    ),
-
-  useFetchDatasetDetail: (id) =>
-    useClientDataSWR(
-      id ? [FETCH_DATASET_DETAIL_KEY, id] : null,
-      () => agentEvalService.getDataset(id!),
-      {
-        onSuccess: (data) => set({ datasetDetail: data, isLoadingDatasetDetail: false }),
-      },
-    ),
-
-  refreshDatasets: (benchmarkId) => mutate([FETCH_DATASETS_KEY, benchmarkId]),
-  refreshDatasetDetail: (id) => mutate([FETCH_DATASET_DETAIL_KEY, id]),
-
-  // CREATE with optimistic update — note the temp id pattern
-  createDataset: async (params) => {
-    const tmpId = Date.now().toString();
-    const { benchmarkId } = params;
-
-    get().internal_dispatchDataset(
-      { type: 'addDataset', value: { ...params, id: tmpId, createdAt: Date.now() } as any },
-      benchmarkId,
-    );
-    get().internal_updateDatasetLoading(tmpId, true);
-
-    try {
-      const result = await agentEvalService.createDataset(params);
-      await get().refreshDatasets(benchmarkId);
-      return result;
-    } finally {
-      get().internal_updateDatasetLoading(tmpId, false);
-    }
-  },
-
-  // UPDATE / DELETE follow the same optimistic + refresh pattern as BenchmarkSlice
-  // (see the main SKILL.md)
-
-  // Internal — dispatch reducer scoped to a parent
-  internal_dispatchDataset: (payload, benchmarkId) => {
-    const currentData = get().datasetMap[benchmarkId];
-    const nextItems = datasetReducer(currentData?.items, payload);
-
-    // Skip set when nothing changed — avoids unnecessary re-renders
-    if (isEqual(nextItems, currentData?.items)) return;
-
-    set({
-      datasetMap: {
-        ...get().datasetMap,
-        [benchmarkId]: {
-          ...currentData,
-          currentPage: currentData?.currentPage ?? 1,
-          hasMore: currentData?.hasMore ?? false,
-          isLoading: false,
-          items: nextItems,
-          pageSize: currentData?.pageSize ?? nextItems.length,
-          total: currentData?.total ?? nextItems.length,
-        },
-      },
-    });
-  },
-
-  internal_updateDatasetLoading: (id, loading) => {
-    set((state) => ({
-      loadingDatasetIds: loading
-        ? [...state.loadingDatasetIds, id]
-        : state.loadingDatasetIds.filter((i) => i !== id),
-    }));
-  },
-});
-```
-
-## Step 4: Wire into the store
-
-```typescript
-// src/store/eval/store.ts
-export type EvalStore = EvalStoreState & BenchmarkAction & DatasetAction & RunAction;
-
-const createStore: StateCreator<EvalStore, [['zustand/devtools', never]]> = (set, get, store) => ({
-  ...initialState,
-  ...createBenchmarkSlice(set, get, store),
-  ...createDatasetSlice(set, get, store),
-  ...createRunSlice(set, get, store),
-});
-
-// src/store/eval/initialState.ts
-export const initialState: EvalStoreState = {
-  ...benchmarkInitialState,
-  ...datasetInitialState,
-  ...runInitialState,
-};
-```
-
-## Step 5: Selectors (optional but recommended)
-
-```typescript
-export const datasetSelectors = {
-  getDatasetData: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId],
-  getDatasets: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId]?.items ?? [],
-  isLoadingDataset: (id: string) => (s: EvalStore) => s.loadingDatasetIds.includes(id),
-};
-```
-
-## Step 6: Use in component
-
-```tsx
-// List scoped to a parent
-const DatasetList = ({ benchmarkId }: { benchmarkId: string }) => {
-  const useFetchDatasets = useEvalStore((s) => s.useFetchDatasets);
-  const datasets = useEvalStore(datasetSelectors.getDatasets(benchmarkId));
-  const datasetData = useEvalStore(datasetSelectors.getDatasetData(benchmarkId));
-
-  useFetchDatasets(benchmarkId);
-
-  if (datasetData?.isLoading) return <Loading />;
-  return (
-    <div>
-      <h2>Total: {datasetData?.total ?? 0}</h2>
-      <List data={datasets} />
-    </div>
-  );
-};
-
-// Single item for modal — conditional fetching pattern
-const DatasetImportModal = ({ open, datasetId }: Props) => {
-  const useFetchDatasetDetail = useEvalStore((s) => s.useFetchDatasetDetail);
-  const dataset = useEvalStore((s) => s.datasetDetail);
-  const isLoading = useEvalStore((s) => s.isLoadingDatasetDetail);
-
-  // Only fetch when modal is open AND id present
-  useFetchDatasetDetail(open && datasetId ? datasetId : undefined);
-
-  return <Modal open={open}>{isLoading ? <Loading /> : <div>{dataset?.name}</div>}</Modal>;
-};
-```

.agents/skills/db-migrations/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: db-migrations
-description: 'Use for Drizzle migrations: schema/table/column changes, migration generation or regeneration, sequence conflicts after rebase, idempotent SQL review, or migration renames.'
-user-invocable: false
+description: 'Use when generating or regenerating Drizzle migration files, changing database schema tables or columns, resolving migration sequence conflicts after rebase, reviewing migration SQL for idempotent patterns, or renaming migration files.'
 ---
 
 # Database Migrations Guide

.agents/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: debug-package
-description: 'LobeHub debug package and log namespace guide. Use when adding debug() logging, choosing lobe-* namespaces, troubleshooting DEBUG output, localStorage.debug, or log format specifiers.'
+name: debug
+description: Debug package usage guide. Use when adding debug logging, understanding log namespaces, or implementing debugging features. Triggers on debug logging requests or logging implementation.
 user-invocable: false
 ---
 

.agents/skills/desktop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: desktop
-description: Electron desktop development guide — IPC handlers, controllers, preload scripts, window/menu management.
+description: Electron desktop development guide. Use when implementing desktop features, IPC handlers, controllers, preload scripts, window management, menu configuration, or Electron-specific functionality. Triggers on desktop app development, Electron IPC, or desktop local tools implementation.
 disable-model-invocation: true
 ---
 

.agents/skills/docs-changelog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-changelog
-description: 'Write website changelog pages under docs/changelog/*.mdx. Use for EN/ZH product update posts, changelog posts, update-log copy, or docs changelog edits; not GitHub Release notes.'
+description: 'Writing guide for website changelog pages under docs/changelog/*.mdx. Use when creating or editing product update posts in EN/ZH. Not for GitHub Release notes.'
 ---
 
 # Docs Changelog Writing Guide

.agents/skills/drizzle/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: drizzle
-description: 'LobeHub Drizzle ORM schema and query style. Use for pgTable schemas, indexes, joins, inferred types, db.select/db.query, schema fields, foreign keys, junction tables, or postgres query patterns.'
-user-invocable: false
+description: Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.
 ---
 
 # Drizzle ORM Schema Style Guide
@@ -9,13 +8,13 @@ user-invocable: false
 ## Configuration
 
 - Config: `drizzle.config.ts`
-- Schemas: `packages/database/src/schemas/`
-- Migrations: `packages/database/migrations/`
+- Schemas: `src/database/schemas/`
+- Migrations: `src/database/migrations/`
 - Dialect: `postgresql` with `strict: true`
 
 ## Helper Functions
 
-Location: `packages/database/src/schemas/_helpers.ts`
+Location: `src/database/schemas/_helpers.ts`
 
 - `timestamptz(name)`: Timestamp with timezone
 - `createdAt()`, `updatedAt()`, `accessedAt()`: Standard timestamp columns
@@ -126,7 +125,11 @@ The relational API generates complex lateral joins with `json_build_array` that
 
 ```typescript
 // ✅ Good
-const [result] = await this.db.select().from(agents).where(eq(agents.id, id)).limit(1);
+const [result] = await this.db
+  .select()
+  .from(agents)
+  .where(eq(agents.id, id))
+  .limit(1);
 return result;
 
 // ❌ Bad: relational API
@@ -174,94 +177,6 @@ const rows = await this.db
   .groupBy(agentEvalDatasets.id);
 ```
 
-### Raw SQL and Advanced Queries
-
-Prefer Drizzle builders whenever the query can be expressed clearly with `select`,
-`insert().select()`, `update().from()`, joins, CTEs, `groupBy`, and typed selected
-columns. This keeps table and column references tied to schema definitions, so
-schema changes are more likely to surface as TypeScript errors.
-
-Expression-level `sql<T>` is fine inside a Drizzle builder for PostgreSQL features
-that do not have a dedicated helper, such as JSON path extraction, casts, aggregate
-expressions, `CASE`, `NOW()`, or advisory locks. Row locks are query clauses, not
-expressions; use the select builder's `.for('update')` instead of raw
-`FOR UPDATE` SQL fragments.
-
-When refactoring raw SQL:
-
-- Preserve the original query shape for latency-sensitive paths. If raw SQL is one
-  database roundtrip, do not replace it with multiple depth-based queries just to
-  remove `execute`.
-- Use `$with(...)` plus `insert().select()` / `update().from()` for multi-step
-  single-roundtrip writes when Drizzle can express the data flow.
-- Avoid generic `execute<MyRow>(sql...)` as the main safety mechanism. It types the
-  returned rows, but it does not keep selected columns in sync with schema changes.
-- If the only clean implementation is a PostgreSQL feature that Drizzle cannot
-  express well, keep the raw SQL and tighten it instead: use schema references in
-  interpolations, explicit user scope, a narrow row interface, and regression tests.
-
-Recursive CTEs are a special case: current Drizzle usage in this repo does not have
-a clean `WITH RECURSIVE` builder pattern. Keep recursive CTE raw SQL when replacing
-it would add extra database roundtrips or materially worsen performance.
-
-Example: convert an aggregate query when Drizzle can preserve one roundtrip:
-
-```typescript
-// ✅ Good: builder owns table and column references; sql<T> stays expression-level.
-const rows = await trx
-  .select({
-    model: messages.model,
-    provider: messages.provider,
-    totalCost: sql<string | null>`sum((${messages.metadata}->'usage'->>'cost')::numeric)`.as(
-      'totalCost',
-    ),
-  })
-  .from(messages)
-  .where(
-    and(
-      eq(messages.topicId, topicId),
-      eq(messages.userId, userId),
-      eq(messages.role, 'assistant'),
-      sql`${messages.metadata} ? 'usage'`,
-    ),
-  )
-  .groupBy(messages.provider, messages.model);
-```
-
-Example: use the select lock builder for row locks:
-
-```typescript
-const [user] = await trx.select().from(users).where(eq(users.id, userId)).for('update');
-```
-
-Example: keep a recursive CTE raw when replacing it would add depth-based DB
-roundtrips:
-
-```typescript
-interface TaskTreeRow {
-  id: string;
-  parent_task_id: string | null;
-}
-
-// execute<T> is acceptable here only because Drizzle has no clean WITH RECURSIVE
-// builder; a builder rewrite would add depth-based roundtrips. Keep schema refs in
-// the interpolations and scope every leg to the user.
-const { rows } = await db.execute<TaskTreeRow>(sql`
-  WITH RECURSIVE task_tree AS (
-    SELECT ${tasks.id}, ${tasks.parentTaskId}
-    FROM ${tasks}
-    WHERE ${tasks.id} = ${rootTaskId}
-      AND ${tasks.createdByUserId} = ${userId}
-    UNION ALL
-    SELECT ${tasks.id}, ${tasks.parentTaskId}
-    FROM ${tasks}
-    JOIN task_tree ON ${tasks.parentTaskId} = task_tree.id
-    WHERE ${tasks.createdByUserId} = ${userId}
-  )
-  SELECT * FROM task_tree
-`);
-```
-
 ### One-to-Many (Separate Queries)
 
 When you need a parent record with its children, use two queries instead of relational `with:`:

.agents/skills/heterogeneous-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: heterogeneous-agent
-description: 'Implement or debug LobeHub heterogeneous agents. Use for Claude Code/Codex adapters, external CLI agents, event mapping, IPC, persistence, tool-call chains, sessions, traces, or adapter bugs.'
+description: Guide for implementing and debugging LobeHub heterogeneous agent integrations such as Claude Code, Codex, and future external CLI agents. Use when working on adapter event mapping, Electron IPC transport, renderer persistence, tool-call chaining, subagent threads, resume/session handling, or regressions like mixed multi-tool messages, broken step boundaries, stuck tool loading, and orphan tool messages. Triggers on 'heterogeneous agent', 'hetero agent', '异构 agent', 'claude code adapter', 'codex adapter', 'external agent CLI', '孤立 tool 消息', 'raw Codex trace', or adapter/executor bugs.
 ---
 
 # Heterogeneous Agent Development

.agents/skills/hotkey/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: hotkey
-description: 'Add or edit LobeHub keyboard shortcuts. Use for HotkeyEnum, HOTKEYS_REGISTRATION, combineKeys, useHotkeyById, tooltip hotkeys, shortcut scope, conflicts, or Cmd/Ctrl key combos.'
-user-invocable: false
+description: Guide for adding keyboard shortcuts. Use when implementing new hotkeys, registering shortcuts, or working with keyboard interactions. Triggers on hotkey implementation or keyboard shortcut tasks.
 ---
 
 # Adding Keyboard Shortcuts Guide

.agents/skills/i18n/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: i18n
-description: 'LobeHub i18n with react-i18next. Use for user-facing strings, locale keys, namespaces, useTranslation, t(), interpolation, zh-CN/en-US previews, hardcoded UI copy, or pnpm i18n.'
-user-invocable: false
+description: Internationalization guide using react-i18next. Use when adding translations, creating i18n keys, or working with localized text in React components (.tsx files). Triggers on translation tasks, locale management, or i18n implementation.
 ---
 
 # LobeHub Internationalization Guide

.agents/skills/linear/SKILL.md

@@ -1,55 +1,55 @@
 ---
 name: linear
-description: 'Linear issue management. Use for LOBE-xxx issues, Linear links, PRs referencing Linear, retrieving issues, updating status, completion comments, or sub-issue trees.'
-user-invocable: false
+description: "Linear issue management. MUST USE when: (1) user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), (2) user says 'linear', 'linear issue', 'link linear', (3) creating PRs that reference Linear issues. Provides workflows for retrieving issues, updating status, and adding comments."
 ---
 
 # Linear Issue Management
 
 Before using Linear workflows, search for `linear` MCP tools. If not found, treat as not installed.
 
-## PR Creation with Linear Issues
+## ⚠️ CRITICAL: PR Creation with Linear Issues
 
-A PR that fixes a Linear issue has **two separate jobs to do**, and both matter:
+**When creating a PR that references Linear issues (LOBE-xxx), you MUST:**
 
-1. **`Fixes LOBE-xxx` in the PR body** — Linear watches GitHub for these magic keywords and auto-links the PR and auto-closes the issue on merge. This is the machine-readable side.
-2. **A completion comment on the Linear issue** — gives the reviewer/PM/teammate landing in Linear a human-readable summary of what changed and why, without forcing them to click through to GitHub and read a diff.
+1. Create the PR with magic keywords (`Fixes LOBE-xxx`)
+2. **IMMEDIATELY after PR creation**, add completion comments to ALL referenced Linear issues
+3. Do NOT consider the task complete until Linear comments are added
 
-If you only do step 1, Linear watchers (often non-engineers) hit the issue and see no context. So pair PR creation with the Linear comment as part of the same task — finish both before considering the work done.
+This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
 
 ## Workflow
 
 1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
-2. **Read images** — issue descriptions often contain screenshots with critical context (mockups, error states, before/after). Use `mcp__linear-server__extract_images` so you actually see them; reading raw markdown alone misses what the reporter was looking at.
-3. **Check for sub-issues**: `mcp__linear-server__list_issues` with `parentId` filter
-4. **Mark as In Progress** at the moment you start planning or implementing — this signals to teammates the issue is owned, so they don't double-pick it up.
+2. **Read images**: If the issue description contains images, MUST use `mcp__linear-server__extract_images` to read image content for full context
+3. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
+4. **Mark as In Progress**: When starting to plan or implement an issue, immediately update status to **"In Progress"** via `mcp__linear-server__update_issue`
 5. **Update issue status** when completing: `mcp__linear-server__update_issue`
-6. **Add completion comment** (see [format below](#completion-comment-format))
+6. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
 
 ## Creating Issues
 
-When creating issues with `mcp__linear-server__create_issue`, add the `claude code` label. Reason: the label is how the team filters/audits AI-generated issues; without it those issues vanish into the general backlog and the team loses visibility into AI contribution patterns.
+When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.
 
 ## Language
 
-Match the issue language to the conversation that produced it — if you're discussing in 中文，write the issue in 中文；if discussing in English, write it in English. Reason: the issue is a continuation of the conversation, and forcing a language switch creates translation friction for the collaborator who started the thread.
+Issue titles, descriptions, and comments **MUST follow the language of the current conversation**, not default to English.
 
-Specifics:
-
-- 中文 conversation → 中文 body; technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
-- English conversation → English body.
+- Conversation in 中文 → issue body in 中文；technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
+- Conversation in English → issue body in English.
 - Code blocks, file paths, and quoted strings always stay in their original form regardless of surrounding language.
-- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; don't switch the issue language mid-refactor.
+- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; do not switch the issue language during a refactor (Chinese → English or vice versa).
+
+Rationale: the issue is a continuation of the conversation. Forcing English when the discussion is in Chinese creates translation friction for the collaborator who came from that thread.
 
 ## Creating Sub-issue Trees
 
 When breaking a parent issue into a tree of sub-issues (e.g., task decomposition for LOBE-xxx), follow these rules — they work around real limitations of the Linear MCP tools.
 
-### 1. Prefix titles with an ordering index
+### 1. ALWAYS prefix titles with an ordering index
 
-The Linear Sub-issues panel orders children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation produces the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you can't set order at create time.
+The Linear Sub-issues panel displays children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation will produce the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you cannot set order at create time.
 
-Workaround: encode execution order in the title itself:
+**Workaround**: encode execution order in the title itself:
 
 ```plaintext
 [1]     [db]       add schema fields
@@ -100,7 +100,7 @@ The implementer may open only the sub-issue, not the parent — don't rely on co
 
 ## Completion Comment Format
 
-Each completed issue gets a comment summarizing the work, so reviewers and future readers don't have to reconstruct it from the PR diff:
+Every completed issue MUST have a comment summarizing work done:
 
 ```markdown
 ## Changes Summary
@@ -116,28 +116,34 @@ Each completed issue gets a comment summarizing the work, so reviewers and futur
 - ...
 ```
 
-This gives team visibility, code-review context, and a paper trail for future reference.
+This is critical for:
 
-## PR Association
+- Team visibility
+- Code review context
+- Future reference
 
-When creating PRs for Linear issues, include magic keywords in the PR body:
+## PR Association (REQUIRED)
+
+When creating PRs for Linear issues, include magic keywords in PR body:
 
 - `Fixes LOBE-123`
 - `Closes LOBE-123`
 - `Resolves LOBE-123`
 
-These trigger Linear's auto-link + auto-close on merge.
-
 ## Per-Issue Completion Rule
 
-When working on multiple issues, close out **each one before starting the next** — don't batch all the Linear updates to the end. Batching is where comments get forgotten and issues stay stuck in "In Progress" days after the PR shipped.
-
-For each issue:
+When working on multiple issues, update EACH issue IMMEDIATELY after completing it:
 
 1. Complete implementation
 2. Run `bun run type-check`
 3. Run related tests
 4. Create PR if needed
-5. Update status to **"In Review"** (not "Done" — "Done" is for after the PR merges)
-6. Add the completion comment
-7. Move to the next issue
+5. Update status to **"In Review"** (NOT "Done")
+6. **Add completion comment immediately**
+7. Move to next issue
+
+**Note:** Status → "In Review" when PR created. "Done" only after PR merged.
+
+**❌ Wrong:** Complete all → Create PR → Forget Linear comments
+
+**✅ Correct:** Complete → Create PR → Add Linear comments → Task done

.agents/skills/local-testing/SKILL.md

@@ -397,60 +397,35 @@ The pattern is the same for every platform:
 
 Pick the file for your target platform — each contains activation, navigation, send-message, and verification snippets specific to that app:
 
-Each channel has its own folder under `bot/<channel>/` containing an `index.md`
-(activation, navigation, send-message, and verification snippets specific to
-that app) and its test script:
+| Platform      | Reference                                          | Quick switcher |
+| ------------- | -------------------------------------------------- | -------------- |
+| Discord       | [references/discord.md](./references/discord.md)   | `Cmd+K`        |
+| Slack         | [references/slack.md](./references/slack.md)       | `Cmd+K`        |
+| Telegram      | [references/telegram.md](./references/telegram.md) | `Cmd+F`        |
+| WeChat / 微信 | [references/wechat.md](./references/wechat.md)     | `Cmd+F`        |
+| Lark / 飞书   | [references/lark.md](./references/lark.md)         | `Cmd+K`        |
+| QQ            | [references/qq.md](./references/qq.md)             | `Cmd+F`        |
 
-| Platform      | Reference                                        | Quick switcher |
-| ------------- | ------------------------------------------------ | -------------- |
-| Discord       | [bot/discord/index.md](./bot/discord/index.md)   | `Cmd+K`        |
-| Slack         | [bot/slack/index.md](./bot/slack/index.md)       | `Cmd+K`        |
-| Telegram      | [bot/telegram/index.md](./bot/telegram/index.md) | `Cmd+F`        |
-| WeChat / 微信 | [bot/wechat/index.md](./bot/wechat/index.md)     | `Cmd+F`        |
-| Lark / 飞书   | [bot/lark/index.md](./bot/lark/index.md)         | `Cmd+K`        |
-| QQ            | [bot/qq/index.md](./bot/qq/index.md)             | `Cmd+F`        |
-
-For **shared osascript patterns** (activate, type, paste, screenshot, read accessibility, common workflow template, gotchas), see [bot/osascript-common.md](./bot/osascript-common.md). Read this first if you're new to osascript automation.
-
-## Bridge-based channels (no native app)
-
-Some channels have no native app to drive with osascript — they connect through
-a local bridge inside the Desktop app. These are tested with agent-browser
-(IPC + UI) plus the bridge's own HTTP/REST endpoints, not osascript:
-
-| Channel  | Reference                                        | What it drives                                           |
-| -------- | ------------------------------------------------ | -------------------------------------------------------- |
-| iMessage | [bot/imessage/index.md](./bot/imessage/index.md) | `imessageBridge.*` IPC + local bridge + BlueBubbles REST |
-
-For iMessage there is a one-shot regression script — see `test-imessage-bridge.sh` below.
+For **shared osascript patterns** (activate, type, paste, screenshot, read accessibility, common workflow template, gotchas), see [references/osascript-common.md](./references/osascript-common.md). Read this first if you're new to osascript automation.
 
 ---
 
 # Scripts
 
-**App / recording scripts** in `.agents/skills/local-testing/scripts/`:
+Ready-to-use scripts in `.agents/skills/local-testing/scripts/`:
 
 | Script                    | Usage                                               |
 | ------------------------- | --------------------------------------------------- |
 | `electron-dev.sh`         | Manage Electron dev env (start/stop/status/restart) |
+| `capture-app-window.sh`   | Capture screenshot of a specific app window         |
 | `record-electron-demo.sh` | Record Electron app demo with ffmpeg                |
 | `record-app-screen.sh`    | Record app screen (video + screenshots, start/stop) |
-
-**Bot scripts** live under `.agents/skills/local-testing/bot/`, one folder per
-channel (alongside that channel's `index.md`). The shared
-`capture-app-window.sh` sits at the `bot/` root:
-
-| Script                             | Usage                                                               |
-| ---------------------------------- | ------------------------------------------------------------------- |
-| `capture-app-window.sh`            | Capture screenshot of a specific app window (used by bot tests)     |
-| `discord/test-discord-bot.sh`      | Send message to Discord bot via osascript                           |
-| `slack/test-slack-bot.sh`          | Send message to Slack bot via osascript                             |
-| `telegram/test-telegram-bot.sh`    | Send message to Telegram bot via osascript                          |
-| `wechat/test-wechat-bot.sh`        | Send message to WeChat bot via osascript                            |
-| `lark/test-lark-bot.sh`            | Send message to Lark / 飞书 bot via osascript                       |
-| `qq/test-qq-bot.sh`                | Send message to QQ bot via osascript                                |
-| `imessage/test-imessage-bridge.sh` | Regression-test the iMessage BlueBubbles bridge (IPC + HTTP)        |
-| `imessage/send-imessage-test.sh`   | Send one real iMessage (desktop → BB → iMessage) and verify it sent |
+| `test-discord-bot.sh`     | Send message to Discord bot via osascript           |
+| `test-slack-bot.sh`       | Send message to Slack bot via osascript             |
+| `test-telegram-bot.sh`    | Send message to Telegram bot via osascript          |
+| `test-wechat-bot.sh`      | Send message to WeChat bot via osascript            |
+| `test-lark-bot.sh`        | Send message to Lark / 飞书 bot via osascript       |
+| `test-qq-bot.sh`          | Send message to QQ bot via osascript                |
 
 ### Window Screenshot Utility
 
@@ -458,9 +433,9 @@ channel (alongside that channel's `index.md`). The shared
 
 ```bash
 # Standalone usage
-./.agents/skills/local-testing/bot/capture-app-window.sh "Discord" /tmp/discord.png
-./.agents/skills/local-testing/bot/capture-app-window.sh "Slack" /tmp/slack.png
-./.agents/skills/local-testing/bot/capture-app-window.sh "WeChat" /tmp/wechat.png
+./.agents/skills/local-testing/scripts/capture-app-window.sh "Discord" /tmp/discord.png
+./.agents/skills/local-testing/scripts/capture-app-window.sh "Slack" /tmp/slack.png
+./.agents/skills/local-testing/scripts/capture-app-window.sh "WeChat" /tmp/wechat.png
 ```
 
 All bot test scripts use this utility automatically for their screenshots.
@@ -477,48 +452,32 @@ Examples:
 
 ```bash
 # Discord — test a bot in #bot-testing channel
-./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "!ping"
-./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "!ping"
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
 
 # Slack — test a bot in #bot-testing channel
-./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "@mybot hello"
-./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
 
 # Telegram — test a bot by username
-./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "MyTestBot" "/start"
-./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "GPTBot" "Hello" 60
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
 
 # WeChat — test a bot or send to a contact
-./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "文件传输助手" "test message" 5
-./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
 
 # Lark/飞书 — test a bot in a group chat
-./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "@MyBot hello"
-./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "Help me with this" 30
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "@MyBot hello"
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "Help me with this" 30
 
 # QQ — test a bot in a group or direct chat
-./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "bot-testing" "Hello bot" 15
-./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "MyBot" "/help" 10
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "bot-testing" "Hello bot" 15
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "MyBot" "/help" 10
 ```
 
 Each script: activates the app, navigates to the channel/contact, pastes the message via clipboard, sends, waits, and takes a screenshot. Use the `Read` tool on the screenshot for visual verification.
 
-### iMessage bridge regression script
-
-`test-imessage-bridge.sh` does **not** follow the osascript bot interface — it
-drives the Desktop bridge's IPC + HTTP layers and asserts the result, then
-self-cleans. Needs BlueBubbles running and Electron up with CDP.
-
-```bash
-./.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh '<bluebubbles_password>' [bb_url] [cdp_port]
-# defaults: bb_url=http://127.0.0.1:1234  cdp_port=9222 — exit 0 = all green
-```
-
-It guards the connect/configure flow (testConfig happy + reject paths, first-time
-`upsertConfig` save, bridge running + webhook registered, local-server secret
-enforcement). See [bot/imessage/index.md](./bot/imessage/index.md)
-for the full manual UI flow and known bugs.
-
 ---
 
 # Screen Recording
@@ -558,4 +517,4 @@ Outputs to `.records/` directory (gitignored): `<name>.mp4` (video) + `<name>/`
 
 ### osascript
 
-See [bot/osascript-common.md](./bot/osascript-common.md#gotchas) for the full osascript gotchas list (accessibility permissions, `keystroke` non-ASCII issues, locale-specific app names, rate limiting, etc.).
+See [references/osascript-common.md](./references/osascript-common.md#gotchas) for the full osascript gotchas list (accessibility permissions, `keystroke` non-ASCII issues, locale-specific app names, rate limiting, etc.).

.agents/skills/local-testing/bot/imessage/index.md

@@ -1,232 +0,0 @@
-# iMessage Desktop bridge regression test
-
-The iMessage channel is different from the other bot platforms: there is **no
-native app to drive with osascript**. Instead the Desktop app runs a local
-**BlueBubbles bridge** — a small HTTP server in the Electron main process that
-registers a webhook on a local [BlueBubbles](https://bluebubbles.app/) server,
-receives iMessage events, and forwards them to LobeHub Cloud.
-
-So the test surface is three layers:
-
-1. **Electron main IPC** — `imessageBridge.*` handlers (`getStatus`,
-   `testConfig`, `upsertConfig`, `removeConfig`, `start`, `stop`)
-2. **Local bridge HTTP server** — `http://127.0.0.1:<port>/webhooks/bluebubbles/<appId>?secret=<secret>`
-3. **BlueBubbles REST API** — `http://127.0.0.1:1234/api/v1/*` (webhook + server/info)
-
-## Prerequisites
-
-- A running **BlueBubbles server** (macOS, default `http://127.0.0.1:1234`) with
-  a known password. Sanity check:
-  ```bash
-  curl -sS -m4 -o /dev/null -w '%{http_code}\n' \
-    "http://127.0.0.1:1234/api/v1/server/info?password=<PW>" # expect 200
-  ```
-- **Electron dev running with CDP**: `./.agents/skills/local-testing/scripts/electron-dev.sh start`
-- The **iMessage Desktop branch** checked out (the `imessageBridge` IPC group
-  and `@lobechat/chat-adapter-imessage` must be compiled into the main bundle).
-  Run `pnpm install --ignore-scripts` at the repo root **and** in `apps/desktop/`
-  after switching branches — the new workspace package must be linked or the
-  main build fails to resolve `@lobechat/chat-adapter-imessage`.
-
-## Fast path: automated script
-
-```bash
-./.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh '<bluebubbles_password>' [bb_url] [cdp_port]
-```
-
-Asserts the whole flow and self-cleans (unique `applicationId` per run, removes
-its bridge config + BlueBubbles webhook on exit). Exit 0 = all green. It covers:
-
-- BlueBubbles reachable + password valid; Electron CDP reachable; IPC available
-- `testConfig` happy path → success
-- `testConfig` wrong password → rejected; unreachable URL → rejected
-- `upsertConfig` **first-time save → success** (Bug #1 regression guard, below)
-- `getStatus` → `running:true`, config persisted, password redacted (`blueBubblesPasswordSet`)
-- BlueBubbles webhook actually registered for the appId
-- Local bridge HTTP server: wrong secret → 401; valid secret → past auth
-
-The password is passed as argv (visible in `ps`) — local dev only, don't use a
-real secret on a shared machine.
-
-## Layer 1 — IPC probes (no UI)
-
-The renderer exposes the main-process handlers via `window.electronAPI.invoke`.
-This is the quickest way to exercise the bridge without clicking:
-
-```bash
-# baseline
-agent-browser --cdp 9222 eval \
-  "(async()=>JSON.stringify(await window.electronAPI.invoke('imessageBridge.getStatus',{})))()"
-
-# test a connection (note: password as a JS string)
-agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
-(async function () {
-  try {
-    var r = await window.electronAPI.invoke('imessageBridge.testConfig', {
-      applicationId: 'probe',
-      blueBubblesServerUrl: 'http://127.0.0.1:1234',
-      blueBubblesPassword: 'PASTE_PW',
-      enabled: true,
-      webhookSecret: 'probe-secret',
-    });
-    return JSON.stringify(r);            // { success: true }
-  } catch (e) { return 'ERR: ' + (e.message || e); }
-})()
-EVALEOF
-```
-
-`upsertConfig` persists to the Electron store, starts the local HTTP server, and
-registers the BlueBubbles webhook. `removeConfig` + `stop` reverse it.
-
-## Layer 2 — full UI flow (agent-browser)
-
-The bridge settings only render in Desktop (`isDesktop` guard) under the agent's
-**Channel → iMessage** screen. The platform tile only appears as a real (non
-"Coming Soon") entry once the server registers `imessage` **and** the frontend
-drops it from `COMING_SOON_PLATFORMS` (`src/routes/(main)/agent/channel/const.ts`).
-
-```bash
-agent-browser --cdp 9222 open "http://localhost:5173/agent/<aid>/channel"
-agent-browser --cdp 9222 wait --load networkidle && agent-browser --cdp 9222 wait 1500
-
-# confirm the remote backend lists imessage (it must be registered + deployed)
-agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
-(async function(){
-  var url='lobe-backend://lobe/trpc/lambda/agentBotProvider.listPlatforms?input='+encodeURIComponent('{"json":null,"meta":{"values":["undefined"],"v":1}}');
-  var d=await (await fetch(url,{credentials:'include'})).json();
-  var p=d.result?.data?.json||d;
-  return JSON.stringify(p.map(function(x){return x.id;}));
-})()
-EVALEOF
-
-# click the iMessage tile, then fill the form by ref
-agent-browser --cdp 9222 eval "(()=>{var b=[...document.querySelectorAll('aside button')].find(x=>/imessage/i.test(x.textContent));b&&b.click();})()"
-agent-browser --cdp 9222 wait 1500
-agent-browser --cdp 9222 snapshot -i | grep -iE "127.0.0.1:1234|Application ID|Webhook Secret|Test BlueBubbles|Save Bridge"
-```
-
-Field refs (from the snapshot): Application ID, Webhook Secret, BlueBubbles
-Server URL (`placeholder="http://127.0.0.1:1234"`), and a **nested** textbox right
-under the URL one is the BlueBubbles Password. Fill with `fill` (real input
-events — `eval`-setting React inputs won't fire onChange), click **Test
-BlueBubbles**, then **Save Bridge**. Read the antd toast immediately (it
-auto-dismisses):
-
-```bash
-agent-browser --cdp 9222 eval \
-  "JSON.stringify([...new Set([...document.querySelectorAll('.ant-message-custom-content')].map(n=>n.textContent.trim()))])"
-# Test  → "BlueBubbles connection passed"
-# Save  → "iMessage Desktop bridge saved"
-```
-
-Verify the end state via BlueBubbles + IPC:
-
-```bash
-curl -sS "http://127.0.0.1:1234/api/v1/webhook?password=<PW>" # webhook for the appId present
-agent-browser --cdp 9222 eval "(async()=>JSON.stringify(await window.electronAPI.invoke('imessageBridge.getStatus',{})))()"
-# running:true, serverUrl: http://127.0.0.1:33270, configs[].blueBubblesPasswordSet:true
-```
-
-Cleanup: `removeConfig` + `stop` via IPC, then `DELETE /api/v1/webhook/<id>` on
-BlueBubbles.
-
-## Outbound send test (desktop → BlueBubbles → iMessage)
-
-Verifies the leg the bridge uses to _reply_: `BlueBubblesApiClient.sendText`
-→ `POST /api/v1/message/text`. Run the helper against your own number:
-
-```bash
-./.agents/skills/local-testing/bot/imessage/send-imessage-test.sh '<bb_password>' '+<E164>' # e.g. +15551234567
-```
-
-**Gotcha that bites everyone:** with `method=apple-script` and a _new_
-conversation, the HTTP POST often **times out** even though the message is
-sent. Never judge success by the HTTP response. Instead poll
-`POST /api/v1/message/query` and read the matching `isFromMe:true` row's
-`error` field:
-
-- `error: 0` (or null) → sent OK
-- non-zero `error` → real send failure
-
-The script does exactly this: fires the send, ignores the timeout, then matches
-its marker text in the message store and asserts `error == 0`.
-
-Two more notes:
-
-- Use a full E.164 handle (`iMessage;-;+<countrycode><number>`) or an Apple ID
-  email. Looking the chat up by guid afterwards may 404 if BB filed the message
-  under a differently-formatted guid — that's a lookup quirk, not a send failure.
-- Sending to _your own_ number round-trips: BB records both the outgoing
-  (`fromMe:true`) and an incoming copy (`fromMe:false`).
-
-## Inbound e2e test (iMessage → cloud agent → reply)
-
-Full inbound chain: a message arrives → BlueBubbles fires its `new-message`
-webhook → local bridge (`:33270`) → `forwardWebhook` POSTs to
-`<remote>/api/agent/webhooks/imessage/<appId>?secret=…` → cloud agent → reply
-flows back via Device Gateway → BB `sendText`.
-
-Prerequisites:
-
-- A cloud bot provider for the same `applicationId` exists and is **connected**
-  (Save Configuration + the device gateway connected — a _disconnected_ gateway
-  yields `DEVICE_NOT_FOUND` on connect and blocks the reply leg).
-- The `imessage` Labs toggle is on (otherwise the channel is gated to "Coming
-  Soon"), and `webhookSecret` matches on both ends (auto-generated on save).
-
-Two ways to drive it:
-
-1. **Second device / Apple ID (recommended).** Have _another_ Apple ID message
-   the BB-hosted number (e.g. "please reply pong"). The bot replies; you see it
-   on the other device. **No loop risk** — the reply goes to the other party,
-   not back to itself.
-2. **Send to your own number (quick, loop-aware).** `sendText` to the hosted
-   number; the loopback _incoming_ copy (`isFromMe:false`) triggers the bot.
-   Watch the reply land in `message/query` as a `fromMe:true` row.
-
-**Loop guard — why a self-send doesn't spin forever:** the Chat SDK adapter
-drops any `isFromMe` message before dispatch
-(`packages/chat-adapter-imessage/src/adapter.ts`: `if (message.isFromMe) return`).
-The bot's own reply (`isFromMe:true`) is never re-processed, so in the normal
-case (someone else → bot → reply to them) there is no loop. The self-send case
-is a **test-only edge**: the bot's reply also round-trips to your number, and
-only the adapter's `isFromMe` check stops a second pass. Keep the prompt
-conversational (so the bot doesn't keep finding something to answer), and
-**turn the `imessage` lab off / remove the config when done** — never leave a
-self-send bot running unattended.
-
-Watch the chain live:
-
-```bash
-tail -f /tmp/electron-dev.log | grep -iE "imessage|bridge|forward|Message API"
-# the agent reply shows up as a fromMe:true row with the bot's text:
-curl -sS -X POST "http://127.0.0.1:1234/api/v1/message/query?password=<PW>" \
-  -H 'Content-Type: application/json' -d '{"limit":5,"sort":"DESC"}'
-```
-
-`startTyping` will log a Private-API error unless BlueBubbles has the Private
-API helper set up (needs a jailbroken / SIP-disabled Mac) — it's logged and
-ignored; text replies still work.
-
-## Known bugs / gotchas
-
-- **Bug #1 — first-time save (fixed; guarded by the script).** BlueBubbles'
-  `GET /api/v1/webhook?url=<unregistered>` returns **HTTP 500**
-  (`Cannot read properties of null (reading 'events')`). The bridge must list
-  **all** webhooks and match client-side, never pass the `?url=` filter. If you
-  see `upsertConfig` fail with "An unhandled error has occurred!" originating in
-  `listWebhooks`, this regressed.
-- **Save leaves a half-state on webhook failure.** `upsertConfig` writes the
-  config + starts the HTTP server _before_ registering the webhook, so a webhook
-  failure still reports `running:true` with the config persisted but no
-  BlueBubbles webhook. Always assert the BlueBubbles webhook list, not just IPC
-  status.
-- **Unknown appId / forward failure → 500.** Posting to the local bridge for an
-  unknown appId, or when no cloud bot is bound, returns 500 (BlueBubbles retries
-  on 5xx). Auth (wrong secret → 401) is enforced before that.
-- **Backend deploy lag.** Desktop dev proxies tRPC through `lobe-backend://` to
-  the _remote_ server. iMessage only appears in `listPlatforms` once the server
-  registration is deployed there, regardless of local branch.
-- **Restart to load main-process fixes.** Editing `imessageBridgeSrv.ts` /
-  `@lobechat/chat-adapter-imessage` needs `electron-dev.sh restart` — main isn't
-  hot-replaced. On restart, enabled configs auto-register their webhook again.

.agents/skills/local-testing/bot/imessage/send-imessage-test.sh

@@ -1,81 +0,0 @@
-#!/usr/bin/env bash
-#
-# send-imessage-test.sh — Verify the outbound leg: desktop → BlueBubbles → iMessage
-#
-# Sends one real iMessage via the same REST call the Desktop bridge uses
-# (`POST /api/v1/message/text`, which BlueBubblesApiClient.sendText wraps) and
-# confirms it actually went out.
-#
-# KEY GOTCHA: with method=apple-script and a NEW conversation, the HTTP request
-# often TIMES OUT even though the message is sent. Do NOT treat the timeout as a
-# failure — instead poll `POST /api/v1/message/query` and check the message's
-# `error` field (0 = sent OK). This script does that for you.
-#
-# This sends a REAL message, so it has side effects. Target your own number.
-#
-# Usage:
-#   ./send-imessage-test.sh <bb_password> <target_e164> [message] [bb_url]
-#
-# Example (send to your own phone, E.164 with country code):
-#   ./send-imessage-test.sh 'my-bb-pass' '+15551234567'
-#
-set -euo pipefail
-
-BB_PASS="${1:?Usage: $0 <bb_password> <target_e164(+countrycode)> [message] [bb_url]}"
-TARGET="${2:?Need a target handle in E.164, e.g. +15551234567 (or an Apple ID email)}"
-MARKER="lobe-imsg-test-$(date +%s)"
-MESSAGE="${3:-[${MARKER}] desktop bridge → BlueBubbles → iMessage outbound check}"
-BB_URL="${4:-http://127.0.0.1:1234}"
-
-CHAT_GUID="iMessage;-;${TARGET}"
-
-echo "[send-test] target=${TARGET}  marker=${MARKER}"
-
-# 1) Fire the send. apple-script on a new chat may hang the HTTP response, so we
-#    cap it short and ignore a timeout — step 2 is the source of truth.
-python3 - "$BB_PASS" "$BB_URL" "$CHAT_GUID" "$MESSAGE" <<'PY' || true
-import json,sys,urllib.request,urllib.parse,uuid
-pw,base,guid,msg=sys.argv[1:5]
-url=base+"/api/v1/message/text?password="+urllib.parse.quote(pw)
-body={"chatGuid":guid,"message":msg,"method":"apple-script","tempGuid":str(uuid.uuid4())}
-req=urllib.request.Request(url,data=json.dumps(body).encode("utf-8"),
-    headers={"Content-Type":"application/json"},method="POST")
-try:
-    r=urllib.request.urlopen(req,timeout=8)
-    print("[send-test] HTTP",r.status,"(immediate response)")
-except urllib.error.HTTPError as e:
-    print("[send-test] HTTP",e.code,e.read().decode()[:200])
-except Exception as e:
-    print("[send-test] HTTP request returned no body (likely apple-script delay):",type(e).__name__)
-PY
-
-# 2) Source of truth: find our marker in the message store and read its error.
-echo "[send-test] verifying via message/query (the HTTP timeout above is expected)…"
-sleep 3
-python3 - "$BB_PASS" "$BB_URL" "$MARKER" <<'PY'
-import json,sys,time,urllib.request,urllib.parse
-pw,base,marker=sys.argv[1:4]
-url=base+"/api/v1/message/query?password="+urllib.parse.quote(pw)
-def query():
-    body={"limit":15,"offset":0,"with":["chats"],"sort":"DESC"}
-    req=urllib.request.Request(url,data=json.dumps(body).encode(),
-        headers={"Content-Type":"application/json"},method="POST")
-    return json.load(urllib.request.urlopen(req,timeout=12)).get("data") or []
-hit=None
-for _ in range(5):
-    for m in query():
-        if marker in (m.get("text") or "") and m.get("isFromMe"):
-            hit=m; break
-    if hit: break
-    time.sleep(2)
-if not hit:
-    print("[send-test] ✗ outbound message not found in BB store — send likely failed")
-    sys.exit(1)
-err=hit.get("error")
-if err in (0,None):
-    print("[send-test] ✓ outbound message sent (fromMe=True, error=%s)"%err)
-    print("[send-test]   → confirm it arrived in the Messages app on the target device")
-else:
-    print("[send-test] ✗ BlueBubbles reported send error=%s"%err)
-    sys.exit(1)
-PY

.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh

@@ -1,187 +0,0 @@
-#!/usr/bin/env bash
-#
-# test-imessage-bridge.sh — Regression test for the iMessage Desktop bridge
-#
-# Drives the Electron main-process `imessageBridge.*` IPC handlers plus the
-# local bridge HTTP server and the BlueBubbles server, asserting the full
-# connect/configure flow. Use it to regression-test PR work on the iMessage
-# channel (BlueBubbles bridge) without clicking through the UI every time.
-#
-# Prerequisites:
-#   1. BlueBubbles server running and reachable (default http://127.0.0.1:1234)
-#   2. Electron dev running with CDP — `electron-dev.sh start`
-#   3. `agent-browser` on PATH, connected to the same CDP port
-#
-# Usage:
-#   ./test-imessage-bridge.sh <bluebubbles_password> [bb_url] [cdp_port]
-#
-# Example:
-#   ./test-imessage-bridge.sh 'my-bb-password'
-#   ./test-imessage-bridge.sh 'my-bb-password' http://127.0.0.1:1234 9222
-#
-# Notes:
-#   - The password is passed as an argv, so it is visible in `ps`. This is a
-#     local dev tool; do not run it on shared machines with a real secret.
-#   - It uses a unique applicationId per run (imsg-regression-$$) and cleans up
-#     its own bridge config + BlueBubbles webhook on exit, so it is safe to
-#     re-run and does not disturb real configs.
-set -euo pipefail
-
-BB_PASS="${1:?Usage: $0 <bluebubbles_password> [bb_url] [cdp_port]}"
-BB_URL="${2:-http://127.0.0.1:1234}"
-CDP_PORT="${3:-9222}"
-
-APP_ID="imsg-regression-$$"
-SECRET="regression-secret-$$"
-
-PASS=0
-FAIL=0
-
-# ── Output helpers ───────────────────────────────────────────────────
-ok()   { echo "  ✓ $1"; PASS=$((PASS + 1)); }
-bad()  { echo "  ✗ $1 — $2"; FAIL=$((FAIL + 1)); }
-note() { echo "[imsg-test] $1"; }
-
-# ── BlueBubbles REST helpers ─────────────────────────────────────────
-bb_get_webhooks() {
-  curl -sS -m 8 "${BB_URL}/api/v1/webhook?password=${BB_PASS}"
-}
-
-# Delete every webhook whose URL mentions our APP_ID (cleanup is idempotent).
-bb_cleanup_webhooks() {
-  local ids
-  ids=$(bb_get_webhooks | python3 -c '
-import json,sys
-try: d=json.load(sys.stdin)
-except Exception: sys.exit(0)
-for w in (d.get("data") or []):
-    if "'"$APP_ID"'" in (w.get("url") or ""): print(w["id"])
-' 2>/dev/null || true)
-  for id in $ids; do
-    curl -sS -m 8 -X DELETE "${BB_URL}/api/v1/webhook/${id}?password=${BB_PASS}" >/dev/null 2>&1 || true
-  done
-}
-
-# ── IPC helper (drives the Electron renderer's electronAPI bridge) ───
-# Runs a JS snippet that returns a string token; prints the raw token.
-# The BlueBubbles password is base64-injected (atob) so special chars in the
-# secret never need shell/JS quoting.
-ipc_eval() {
-  local js="$1"
-  agent-browser --cdp "$CDP_PORT" eval -b "$(printf '%s' "$js" | base64)" 2>/dev/null
-}
-
-PASS_B64=$(printf '%s' "$BB_PASS" | base64)
-
-# Emit an inline JS object literal for the bridge config. $1 overrides the
-# password expression (defaults to atob of the real password); pass a JS string
-# literal like "'wrong'" to test the rejection path.
-ipc_config_js() {
-  local pwexpr="${1:-atob('${PASS_B64}')}"
-  printf "{applicationId:'%s',blueBubblesServerUrl:'%s',blueBubblesPassword:%s,enabled:true,webhookSecret:'%s'}" \
-    "$APP_ID" "$BB_URL" "$pwexpr" "$SECRET"
-}
-
-# ── Preflight ────────────────────────────────────────────────────────
-note "BlueBubbles: ${BB_URL}   CDP: ${CDP_PORT}   appId: ${APP_ID}"
-
-code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' \
-  "${BB_URL}/api/v1/server/info?password=${BB_PASS}" || echo 000)
-if [ "$code" = "200" ]; then ok "BlueBubbles reachable + password valid"; else
-  bad "BlueBubbles preflight" "HTTP $code (is BlueBubbles running on ${BB_URL}?)"
-  echo "Aborting — fix BlueBubbles first."; exit 1
-fi
-
-if ! curl -sf --max-time 3 "http://localhost:${CDP_PORT}/json/version" >/dev/null 2>&1; then
-  bad "Electron CDP preflight" "CDP ${CDP_PORT} unreachable — run electron-dev.sh start"
-  echo "Aborting."; exit 1
-fi
-ok "Electron CDP reachable"
-
-# Bridge must expose the IPC group (built from this branch's code).
-probe=$(ipc_eval "(async()=>{try{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});return 'OK:'+JSON.stringify(s);}catch(e){return 'ERR:'+(e.message||e);}})()")
-case "$probe" in
-  *OK:*) ok "imessageBridge IPC available" ;;
-  *) bad "imessageBridge IPC" "got: $probe (is the iMessage Desktop branch checked out?)"; echo "Aborting."; exit 1 ;;
-esac
-
-# Start clean: remove any leftover config for this appId + BB webhooks.
-ipc_eval "(async()=>{try{await window.electronAPI.invoke('imessageBridge.removeConfig',{applicationId:'${APP_ID}'});}catch(e){}return 'done';})()" >/dev/null
-bb_cleanup_webhooks
-
-# ── testConfig: happy path ───────────────────────────────────────────
-r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js);var x=await window.electronAPI.invoke('imessageBridge.testConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
-case "$r" in
-  *OK:*success*true*) ok "testConfig with valid password → success" ;;
-  *) bad "testConfig (valid)" "got: $r" ;;
-esac
-
-# ── testConfig: wrong password rejects ───────────────────────────────
-r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js "'definitely-wrong-password'");var x=await window.electronAPI.invoke('imessageBridge.testConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
-case "$r" in
-  *ERR:*) ok "testConfig with wrong password → rejected" ;;
-  *) bad "testConfig (wrong password)" "expected rejection, got: $r" ;;
-esac
-
-# ── testConfig: unreachable URL rejects ──────────────────────────────
-r=$(ipc_eval "(async()=>{try{var x=await window.electronAPI.invoke('imessageBridge.testConfig',{applicationId:'${APP_ID}',blueBubblesServerUrl:'http://127.0.0.1:65530',blueBubblesPassword:atob('${PASS_B64}'),enabled:true,webhookSecret:'${SECRET}'});return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
-case "$r" in
-  *ERR:*) ok "testConfig with unreachable URL → rejected" ;;
-  *) bad "testConfig (unreachable)" "expected rejection, got: $r" ;;
-esac
-
-# ── upsertConfig: FIRST-TIME registration (Bug #1 regression guard) ──
-# BlueBubbles' GET /webhook?url=<unregistered> returns HTTP 500. The bridge
-# must list ALL webhooks and match client-side, otherwise this first save
-# fails. This assertion guards that fix.
-r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js);var x=await window.electronAPI.invoke('imessageBridge.upsertConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
-case "$r" in
-  *OK:*success*true*) ok "upsertConfig first-time save → success (Bug #1 guard)" ;;
-  *) bad "upsertConfig (first-time)" "got: $r" ;;
-esac
-
-# ── getStatus: bridge running + config persisted ─────────────────────
-# Return a quote-free token so grep isn't tripped up by agent-browser's
-# JSON-string escaping of the eval result.
-r=$(ipc_eval "(async()=>{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});var c=(s.configs||[]).find(function(x){return x.applicationId==='${APP_ID}';});return 'RUN='+(s.running?'Y':'N')+' CFG='+(c?'Y':'N')+' PW='+((c&&c.blueBubblesPasswordSet)?'Y':'N');})()")
-echo "$r" | grep -q 'RUN=Y' && ok "bridge running" || bad "bridge running" "got: $r"
-echo "$r" | grep -q 'CFG=Y' && ok "config persisted" || bad "config persisted" "got: $r"
-echo "$r" | grep -q 'PW=Y'  && ok "password stored (redacted in status)" || bad "password stored" "got: $r"
-
-# ── BlueBubbles webhook actually registered ──────────────────────────
-if bb_get_webhooks | grep -q "${APP_ID}"; then
-  ok "BlueBubbles webhook registered for appId"
-else
-  bad "BlueBubbles webhook" "no webhook URL containing ${APP_ID}"
-fi
-
-# ── Local bridge HTTP server: secret enforcement ─────────────────────
-BRIDGE_URL=$(ipc_eval "(async()=>{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});return s.serverUrl||'';})()" | tr -d '"')
-if [ -n "$BRIDGE_URL" ]; then
-  # wrong secret → 401
-  code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' -X POST \
-    -H 'Content-Type: application/json' \
-    "${BRIDGE_URL}/webhooks/bluebubbles/${APP_ID}?secret=WRONG" \
-    -d '{"type":"new-message","data":{"guid":"x"}}' || echo 000)
-  [ "$code" = "401" ] && ok "local bridge rejects wrong secret (401)" || bad "local bridge wrong secret" "expected 401, got $code"
-
-  # right secret → passes auth (reaches forward; without a bound cloud bot it
-  # returns 5xx — that's fine, we're only asserting auth + routing here)
-  code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' -X POST \
-    -H 'Content-Type: application/json' \
-    "${BRIDGE_URL}/webhooks/bluebubbles/${APP_ID}?secret=${SECRET}" \
-    -d '{"type":"new-message","data":{"guid":"x","text":"hi"}}' || echo 000)
-  [ "$code" != "401" ] && ok "local bridge accepts valid secret (HTTP $code, past auth)" || bad "local bridge valid secret" "got 401 with correct secret"
-else
-  bad "local bridge URL" "getStatus returned no serverUrl"
-fi
-
-# ── Cleanup ──────────────────────────────────────────────────────────
-ipc_eval "(async()=>{try{await window.electronAPI.invoke('imessageBridge.removeConfig',{applicationId:'${APP_ID}'});await window.electronAPI.invoke('imessageBridge.stop',{});}catch(e){}return 'cleaned';})()" >/dev/null
-bb_cleanup_webhooks
-note "cleaned up config + BlueBubbles webhook for ${APP_ID}"
-
-# ── Summary ──────────────────────────────────────────────────────────
-echo ""
-echo "[imsg-test] PASS=${PASS}  FAIL=${FAIL}"
-[ "$FAIL" -eq 0 ] || exit 1

.agents/skills/local-testing/references/agent-gateway.md

@@ -1,93 +0,0 @@
-# LobeHub gateway streaming + tab-switch test harness
-
-Captures store + DOM state at 200ms intervals so we can prove or disprove
-claims like "切回 tab 后消息回到了很早以前". Built for gateway-mode chat but
-works for any LobeHub streaming session.
-
-## Files
-
-`scripts/agent-gateway/`
-
-| File            | Role                                                             |
-| --------------- | ---------------------------------------------------------------- |
-| `probe.js`      | Injects a 200ms sampler + `__PROBE_EVENT` marker + `__switchTab` |
-| `probe-dump.js` | Stops the sampler and returns `{events, samples}` as JSON string |
-| `tab-switch.js` | Runs N round-trip switches between two tabs, marks each step     |
-| `analyze.mjs`   | Node post-processor: timeline + regression detection             |
-
-## Standard workflow
-
-```bash
-# 1. Start Electron with CDP
-./.agents/skills/local-testing/scripts/electron-dev.sh start
-
-# 2. Navigate to a chat, switch runtime to Cloud Sandbox (gateway mode)
-
-# 3. Install the probe + helpers
-agent-browser --cdp 9222 eval --stdin \
-  < .agents/skills/local-testing/scripts/agent-gateway/probe.js
-
-# 4. Send a tool-call message — manually or via type+press
-agent-browser --cdp 9222 eval "window.__PROBE_EVENT('SENT')"
-
-# 5. Run the multi-switch driver (auto-picks active tab as BACK and the
-#    rightmost inactive tab as AWAY — edit ROUND_TRIPS / DWELL_MS in the
-#    file if you want different timing)
-agent-browser --cdp 9222 eval --stdin \
-  < .agents/skills/local-testing/scripts/agent-gateway/tab-switch.js
-
-# 6. Wait for streaming to finish, then dump
-agent-browser --cdp 9222 eval --stdin \
-  < .agents/skills/local-testing/scripts/agent-gateway/probe-dump.js \
-  > /tmp/probe.json
-
-# 7. Analyze
-node .agents/skills/local-testing/scripts/agent-gateway/analyze.mjs /tmp/probe.json
-```
-
-The analyzer prints three sections: EVENTS, TIMELINE, REGRESSIONS. If
-REGRESSIONS is non-empty it means content/reasoning/childN dropped on the
-same topic — the symptom users describe.
-
-## What the probe tracks (and why)
-
-`chat.messagesMap` only stores the top-level `assistantGroup` shell. The
-actual streamed content, reasoning, and tool calls live in
-`assistantGroup.children: AssistantContentBlock[]`. Any probe that only
-reads `m.content` / `m.reasoning` will see zeros throughout streaming and
-miss everything that matters. probe.js walks both levels and sums:
-
-- `cT` total content length
-- `rT` total reasoning length
-- `toolT` total tool-call count
-- `childN` number of content blocks
-
-Plus DOM-side signals (`domLen`, search/crawl indicator counts) so you can
-tell store-side regressions apart from render-side regressions.
-
-## Gotchas
-
-- **Optimistic new-topic state.** Before the first chunk lands, messages
-  live under the `<scope>_new` key with `tmp_*` ids and no `topicId` field.
-  probe.js falls back to those when `activeTopicId` is null.
-- **Reasoning resets to 0 are not bugs.** When the assistant finishes
-  thinking and starts tool-use or text, the streaming reasoning buffer
-  empties and the finalised reasoning gets sealed into a completed block.
-  Filter these out manually if needed.
-- **DOM length jitters by a handful of chars** because counters like "(10)"
-  in tool-call labels change as results arrive. analyze.mjs only flags
-  `domLen` drops greater than 100 chars to ignore that noise.
-- **Never identify tabs by innerText.** The active tab's text embeds a
-  ` · <agent name>` suffix, so a search like `'LobeHub Growth'` matches the
-  active tab when the active agent happens to be LobeHub Growth — and you
-  end up clicking the tab you're already on. probe.js uses the stable
-  `data-contextmenu-trigger` attribute (a React `useId()` value that's set
-  per-tab and survives focus changes) plus `data-active="true"` to mark
-  the active one. Helpers exposed:
-  `__listTabs()` / `__clickTabByKey(key)` / `__clickTabByIndex(i)` /
-  `__activeTabKey()`.
-- **`tab-switch.js` fires-and-forgets.** The IIFE kicks off an async loop
-  and returns immediately so the agent-browser CLI eval doesn't blow past
-  its default 25 s timeout. Wait on the `SWITCH_LOOP_DONE` event marker
-  before dumping. Re-running while a loop is in flight is refused — the
-  chaotic data from overlapping runs is not worth debugging.

.agents/skills/local-testing/references/discord.md

@@ -2,7 +2,7 @@
 
 **App name:** `Discord` | **Process name:** `Discord`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -92,6 +92,6 @@ echo "Screenshot saved to /tmp/discord-test-result.png"
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "!ping"
-./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "!ping"
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
 ```

.agents/skills/local-testing/references/lark.md

@@ -2,7 +2,7 @@
 
 **App name:** `Lark` or `飞书` | **Process name:** `Lark` or `飞书`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -56,6 +56,6 @@ screencapture /tmp/lark-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "@MyBot hello"
-./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "Help me with this" 30
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "@MyBot hello"
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "Help me with this" 30
 ```

.agents/skills/local-testing/references/qq.md

@@ -2,7 +2,7 @@
 
 **App name:** `QQ` | **Process name:** `QQ`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -57,6 +57,6 @@ screencapture /tmp/qq-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "bot-testing" "Hello bot" 15
-./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "MyBot" "/help" 10
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "bot-testing" "Hello bot" 15
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "MyBot" "/help" 10
 ```

.agents/skills/local-testing/references/slack.md

@@ -2,7 +2,7 @@
 
 **App name:** `Slack` | **Process name:** `Slack`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -68,6 +68,6 @@ screencapture /tmp/slack-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "@mybot hello"
-./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
 ```

.agents/skills/local-testing/references/telegram.md

@@ -2,7 +2,7 @@
 
 **App name:** `Telegram` | **Process name:** `Telegram`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -75,6 +75,6 @@ curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | j
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "MyTestBot" "/start"
-./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "GPTBot" "Hello" 60
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
 ```

.agents/skills/local-testing/references/wechat.md

@@ -2,7 +2,7 @@
 
 **App name:** `微信` or `WeChat` | **Process name:** `WeChat`
 
-See [osascript-common.md](../osascript-common.md) for shared patterns.
+See [osascript-common.md](./osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -76,6 +76,6 @@ screencapture /tmp/wechat-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "文件传输助手" "test message" 5
-./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
 ```

.agents/skills/local-testing/scripts/agent-gateway/analyze-events.ts

@@ -1,243 +0,0 @@
-// Analyzer for probe-events dumps. Reads a JSON file produced by `run.ts dump`
-// and prints a layered breakdown:
-//
-//   1. STREAM EVENTS — every non-chunk WS/SSE event in receipt order
-//   2. CHUNKS SUMMARY — collapsed per-step chunk counts (otherwise floods)
-//   3. ACTION CALLS — replaceMessages / refreshMessages / MARK:* with stack
-//   4. CORRELATION — calls ↔ nearest stream event within ±300ms
-//   5. PER-KEY ASSISTANT GROWTH — for each messagesMap key, when the leading
-//      assistant message's cLen / rLen actually moves (this is what reveals
-//      "chunks arrived but the message never grew" regressions)
-//   6. ROLLBACKS — msgN / childN / role drops in the active-topic timeline
-//
-// Usage:
-//   bun run .agents/skills/local-testing/scripts/agent-gateway/analyze-events.ts <dump.json>
-
-import { readFileSync } from 'node:fs';
-
-import type {
-  ProbeActionCall,
-  ProbeDump,
-  ProbeMessageSummary,
-  ProbeStreamEvent,
-  ProbeTimelineSample,
-} from './types';
-
-const file = process.argv[2];
-if (!file) {
-  console.error('usage: bun run analyze-events.ts <dump.json>');
-  process.exit(1);
-}
-
-const raw = readFileSync(file, 'utf8');
-// agent-browser eval --stdin wraps return values in quotes when the value is
-// a string — so the JSON file may be double-encoded depending on how it was
-// captured. Handle both.
-const parsedOnce = JSON.parse(raw) as ProbeDump | string;
-const dump: ProbeDump = typeof parsedOnce === 'string' ? JSON.parse(parsedOnce) : parsedOnce;
-
-const { streamEvents = [], actionCalls = [], timeline = [] } = dump;
-
-const pad = (v: unknown, n: number) => String(v).padStart(n);
-
-// ── META ───────────────────────────────────────────────────────────
-console.log('=== META ===');
-console.log(`  events:    ${streamEvents.length}`);
-console.log(`  calls:     ${actionCalls.length}`);
-console.log(`  timeline:  ${timeline.length}`);
-
-// ── 1. STREAM EVENTS (non-chunk) ───────────────────────────────────
-const nonChunkEvents = streamEvents.filter((e) => e.type !== 'stream_chunk');
-const chunkEvents = streamEvents.filter((e) => e.type === 'stream_chunk');
-
-console.log(
-  `\n=== STREAM EVENTS (${nonChunkEvents.length} non-chunk + ${chunkEvents.length} chunks elided) ===`,
-);
-for (const e of nonChunkEvents) {
-  const dataStr = e.dataKeys?.length ? ` [${e.dataKeys.join(',')}]` : '';
-  const data = e.data as Record<string, unknown> | undefined;
-  const uiHint = data?.uiMessagesPreview
-    ? ` uiPreview=${JSON.stringify(data.uiMessagesPreview)}`
-    : data?.uiMessagesTotal
-      ? ` uiTotal=${data.uiMessagesTotal}`
-      : '';
-  const phaseHint = data?.phase ? ` phase=${data.phase}` : '';
-  const extra = e.serverType ? ` serverType=${e.serverType}` : '';
-  console.log(
-    `  t=${pad(e.t, 7)}  [${(e.transport ?? '?').padEnd(3)}]  step=${pad(e.stepIndex ?? '-', 2)}  ` +
-      `type=${(e.type ?? '').padEnd(22)}  op=${e.opIdTail ?? '-'}${phaseHint}${uiHint}${extra}${dataStr}`,
-  );
-}
-
-// ── 2. CHUNK SUMMARY ───────────────────────────────────────────────
-console.log('\n=== CHUNKS SUMMARY (per step / chunkType) ===');
-const chunkBuckets = new Map<string, { count: number; firstT: number; lastT: number }>();
-for (const c of chunkEvents) {
-  const data = c.data as Record<string, unknown> | undefined;
-  const ct = (data?.chunkType as string | undefined) ?? '?';
-  const key = `step=${c.stepIndex ?? '-'}  chunkType=${ct.padEnd(8)}  op=${c.opIdTail}`;
-  const slot = chunkBuckets.get(key);
-  if (slot) {
-    slot.count += 1;
-    slot.lastT = c.t;
-  } else {
-    chunkBuckets.set(key, { count: 1, firstT: c.t, lastT: c.t });
-  }
-}
-for (const [k, v] of chunkBuckets) {
-  console.log(`  ${k}  count=${pad(v.count, 4)}  t=${pad(v.firstT, 7)}..${pad(v.lastT, 7)}`);
-}
-
-// ── 3. ACTION CALLS ───────────────────────────────────────────────
-console.log('\n=== ACTION CALLS (replace/refresh/MARK) ===');
-for (const c of actionCalls) {
-  if (c.name?.startsWith('MARK:')) {
-    console.log(`  t=${pad(c.t, 7)}  ${c.name}`);
-    continue;
-  }
-  const snapshot = (c.args as any)?.snapshot as
-    | Array<{ id: string; role: string; cLen: number; rLen: number }>
-    | undefined;
-  const snapStr = snapshot?.length
-    ? '  snapshot=' + snapshot.map((m) => `${m.id}:${m.role}/c${m.cLen}/r${m.rLen}`).join(' | ')
-    : '';
-  const summary =
-    c.name === 'replaceMessages'
-      ? `count=${c.args?.count} action=${(c.args?.params as any)?.action ?? '-'}${snapStr}`
-      : c.name === 'refreshMessages'
-        ? `ctx=${JSON.stringify(c.args?.context)}`
-        : c.error
-          ? `error=${c.error}`
-          : '';
-  console.log(`  t=${pad(c.t, 7)}  ${c.name.padEnd(20)} ${summary}`);
-  if (c.stack) {
-    const frames = c.stack
-      .split(' ← ')
-      .filter((f) => !!f && !f.includes('Object.<anonymous>'))
-      .slice(0, 3);
-    for (const f of frames) console.log(`             ↳ ${f}`);
-  }
-}
-
-// ── 4. CORRELATION ────────────────────────────────────────────────
-function nearestEventForCall(
-  call: ProbeActionCall,
-  windowMs = 300,
-): { event: ProbeStreamEvent; delta: number } | null {
-  let best: ProbeStreamEvent | null = null;
-  let bestDelta = Infinity;
-  for (const e of streamEvents) {
-    const d = Math.abs(e.t - call.t);
-    if (d < bestDelta && d <= windowMs) {
-      bestDelta = d;
-      best = e;
-    }
-  }
-  return best ? { event: best, delta: bestDelta } : null;
-}
-
-console.log('\n=== CORRELATION (replace/refresh ↔ nearest event within ±300ms) ===');
-for (const c of actionCalls) {
-  if (c.name !== 'refreshMessages' && c.name !== 'replaceMessages') continue;
-  const hit = nearestEventForCall(c);
-  if (hit) {
-    const phase = (hit.event.data as Record<string, unknown> | undefined)?.phase;
-    console.log(
-      `  t=${pad(c.t, 7)}  ${c.name.padEnd(16)} ← Δ${pad(hit.delta, 4)}ms ${hit.event.type}` +
-        (phase ? ` phase=${phase}` : ''),
-    );
-  } else {
-    console.log(`  t=${pad(c.t, 7)}  ${c.name.padEnd(16)} ← (no event nearby — external trigger)`);
-  }
-}
-
-// ── 5. PER-KEY ASSISTANT GROWTH ───────────────────────────────────
-// For each messagesMap key, find the trailing assistant message and report
-// the points in time where its cLen / rLen actually changed. If the timeline
-// shows chunks arriving but the assistant cLen never moves, that's the
-// signature of "dispatch queue blocked / messageId mismatch".
-console.log('\n=== PER-KEY ASSISTANT GROWTH ===');
-const keysEverSeen = new Set<string>();
-for (const s of timeline) for (const k of Object.keys(s.byKey ?? {})) keysEverSeen.add(k);
-
-for (const key of keysEverSeen) {
-  console.log(`\n  key=${key}`);
-  let lastSig: string | null = null;
-  for (const s of timeline) {
-    const slot = s.byKey?.[key];
-    if (!slot) continue;
-    const last = slot.msgs.at(-1) as ProbeMessageSummary | undefined;
-    if (!last) continue;
-    const sig = `${last.id}|c${last.cLen}|r${last.rLen}|n${slot.n}`;
-    if (sig === lastSig) continue;
-    lastSig = sig;
-    console.log(
-      `    t=${pad(s.t, 7)}  msgN=${pad(slot.n, 3)}  ` +
-        `lastAssistant=${last.id}  cLen=${pad(last.cLen, 5)}  rLen=${pad(last.rLen, 5)}` +
-        `  runOps=${s.runOps}`,
-    );
-  }
-}
-
-// ── 6. ROLLBACKS (active-topic msgN / childN / role drops) ─────────
-console.log('\n=== ROLLBACKS (active-topic msgN / childN / role drops) ===');
-let prev: ProbeTimelineSample | null = null;
-const rollbacks: Array<{ t: number; topic: string | null; drops: string[] }> = [];
-
-const flatten = (s: ProbeTimelineSample) => {
-  if (!s.activeTopic) return [];
-  return Object.entries(s.byKey ?? {})
-    .filter(([k]) => k.includes(s.activeTopic!))
-    .flatMap(([, v]) => v.msgs);
-};
-
-for (const s of timeline) {
-  if (s.err) {
-    prev = null;
-    continue;
-  }
-  if (!prev || prev.activeTopic !== s.activeTopic) {
-    prev = s;
-    continue;
-  }
-  const prevMsgs = flatten(prev);
-  const curMsgs = flatten(s);
-  const drops: string[] = [];
-
-  if (curMsgs.length < prevMsgs.length) drops.push(`msgN ${prevMsgs.length}→${curMsgs.length}`);
-
-  let prevChild = 0;
-  let curChild = 0;
-  for (const m of prevMsgs) prevChild += m.chN ?? 0;
-  for (const m of curMsgs) curChild += m.chN ?? 0;
-  if (curChild < prevChild) drops.push(`childN ${prevChild}→${curChild}`);
-
-  const prevById = new Map(prevMsgs.map((m) => [m.id, m]));
-  for (const m of curMsgs) {
-    const pr = prevById.get(m.id);
-    if (!pr) continue;
-    if (m.cLen < pr.cLen) drops.push(`cLen[${m.id}] ${pr.cLen}→${m.cLen}`);
-    if (m.rLen < pr.rLen) drops.push(`rLen[${m.id}] ${pr.rLen}→${m.rLen}`);
-  }
-
-  if (drops.length) rollbacks.push({ t: s.t, topic: s.activeTopic, drops });
-  prev = s;
-}
-
-if (rollbacks.length === 0) {
-  console.log('  (none)');
-} else {
-  for (const r of rollbacks) {
-    const nearEvent = streamEvents
-      .filter((e) => Math.abs(e.t - r.t) <= 300)
-      .map((e) => `${e.type}${(e.data as any)?.phase ? ':' + (e.data as any).phase : ''}`);
-    const nearCall = actionCalls
-      .filter((c) => Math.abs(c.t - r.t) <= 300 && !c.name?.startsWith('MARK:'))
-      .map((c) => c.name);
-    console.log(
-      `  t=${pad(r.t, 7)}  topic=${r.topic}  ${r.drops.join(' | ')}` +
-        (nearEvent.length ? `  near-event:[${nearEvent.join(',')}]` : '') +
-        (nearCall.length ? `  near-call:[${nearCall.join(',')}]` : ''),
-    );
-  }
-}

.agents/skills/local-testing/scripts/agent-gateway/analyze.mjs

@@ -1,119 +0,0 @@
-#!/usr/bin/env node
-// Analyze a probe dump captured by probe.js + probe-dump.js.
-//
-//   node analyze.mjs /tmp/probe.json
-//
-// Prints:
-//   1. EVENTS — user-action markers with their relative timestamps
-//   2. TIMELINE — periodic samples (~1 per second + event-adjacent samples)
-//      showing every interesting field; columns:
-//        t(ms) | runOps | msgN | childN | content | reasoning | tools | domLen | search | crawl | topic | event
-//   3. REGRESSIONS — every place a tracked counter *dropped* on the same
-//      topic between adjacent samples. A "true" UI rollback shows up as a
-//      drop in content/reasoning/tools/childN/domLen without a topic change.
-//
-// Whitelisted transitions (not flagged):
-//   - topic change → all drops expected (focus moved away)
-//   - reasoning length 0 after content starts → reasoning gets sealed into a
-//     completed sub-block; the parent's running reasoning resets to ''.
-//   - msgN drop when topic transitions from `_new` placeholder to a real id.
-
-import fs from 'node:fs';
-
-const file = process.argv[2];
-if (!file) {
-  console.error('usage: node analyze.mjs <probe.json>');
-  process.exit(1);
-}
-
-const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
-// probe-dump.js wraps the payload in JSON.stringify so agent-browser returns
-// it as a single quoted string. Unwrap.
-const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
-const { events, samples } = data;
-
-const fmt = {
-  pad(v, n) {
-    return String(v).padStart(n);
-  },
-};
-
-console.log('=== EVENTS ===');
-for (const e of events) console.log(`  t=${fmt.pad(e.t, 7)}  ${e.name}`);
-
-console.log(
-  '\n=== TIMELINE (~1s cadence, plus event-adjacent samples) ===\n' +
-    '  t(ms)   runOps  msgN childN  content reasoning tools  domLen  search crawl  topic     event',
-);
-
-let lastSampledAt = -1e9;
-const eventBuckets = events.map((e) => e.t);
-for (let i = 0; i < samples.length; i++) {
-  const s = samples[i];
-  const nearEvent = eventBuckets.some((et) => Math.abs(et - s.t) < 110);
-  if (!nearEvent && s.t - lastSampledAt < 1000) continue;
-  lastSampledAt = s.t;
-
-  const ev = events.find((e) => Math.abs(e.t - s.t) < 110);
-  const evMarker = ev ? `  ◀ ${ev.name}` : '';
-  const topicSuffix = s.topicId ? s.topicId.slice(-6) : '(none)';
-  const search = s.ind?.search ?? 0;
-  const crawl = s.ind?.crawl ?? 0;
-  console.log(
-    `  ${fmt.pad(s.t, 6)} ` +
-      `${fmt.pad(s.runOps, 6)}  ` +
-      `${fmt.pad(s.msgN, 4)}  ` +
-      `${fmt.pad(s.childN ?? 0, 5)} ` +
-      `${fmt.pad(s.cT ?? 0, 8)} ` +
-      `${fmt.pad(s.rT ?? 0, 9)} ` +
-      `${fmt.pad(s.toolT ?? 0, 5)} ` +
-      `${fmt.pad(s.domLen ?? 0, 7)} ` +
-      `${fmt.pad(search, 6)} ` +
-      `${fmt.pad(crawl, 5)}  ` +
-      `${topicSuffix.padEnd(8)}${evMarker}`,
-  );
-}
-
-console.log('\n=== REGRESSIONS (same topic, value dropped) ===');
-const regressions = [];
-for (let i = 1; i < samples.length; i++) {
-  const prev = samples[i - 1];
-  const cur = samples[i];
-  if (!cur.topicId || prev.topicId !== cur.topicId) continue;
-
-  const drops = [];
-  if (cur.msgN < prev.msgN) drops.push(`msgN: ${prev.msgN}→${cur.msgN}`);
-  if ((cur.childN ?? 0) < (prev.childN ?? 0)) drops.push(`childN: ${prev.childN}→${cur.childN}`);
-  if ((cur.cT ?? 0) < (prev.cT ?? 0)) drops.push(`content: ${prev.cT}→${cur.cT}`);
-  if ((cur.rT ?? 0) < (prev.rT ?? 0)) drops.push(`reasoning: ${prev.rT}→${cur.rT}`);
-  if ((cur.toolT ?? 0) < (prev.toolT ?? 0)) drops.push(`tools: ${prev.toolT}→${cur.toolT}`);
-  // domLen jitters by a few chars from counter labels — only flag big drops.
-  if ((cur.domLen ?? 0) < (prev.domLen ?? 0) - 100) {
-    drops.push(`domLen: ${prev.domLen}→${cur.domLen}`);
-  }
-  if (drops.length === 0) continue;
-
-  const nearbyEv = events.filter((e) => Math.abs(e.t - cur.t) < 600).map((e) => e.name);
-  regressions.push({ t: cur.t, topic: cur.topicId.slice(-6), drops, nearbyEv });
-}
-
-if (regressions.length === 0) {
-  console.log('  (none)');
-} else {
-  for (const r of regressions) {
-    const evStr = r.nearbyEv.length ? `  near:[${r.nearbyEv.join(',')}]` : '';
-    console.log(`  t=${fmt.pad(r.t, 7)}  topic=${r.topic}  ${r.drops.join(' | ')}${evStr}`);
-  }
-}
-
-console.log(`\n=== SUMMARY ===`);
-console.log(`  samples: ${samples.length}`);
-console.log(`  events:  ${events.length}`);
-console.log(`  regressions: ${regressions.length}`);
-if (samples.length) {
-  const last = samples.at(-1);
-  console.log(
-    `  final: msgN=${last.msgN} childN=${last.childN ?? 0} content=${last.cT ?? 0} ` +
-      `reasoning=${last.rT ?? 0} tools=${last.toolT ?? 0} runOps=${last.runOps}`,
-  );
-}

.agents/skills/local-testing/scripts/agent-gateway/probe-dump.js

@@ -1,17 +0,0 @@
-// Stop the probe and serialize collected data.
-//
-//   agent-browser --cdp 9222 eval --stdin < probe-dump.js > /tmp/probe.json
-//
-// The whole thing is wrapped in a JSON.stringify so agent-browser returns it
-// as a single quoted string — the analyzer double-parses to handle that.
-
-(function () {
-  if (window.__PROBE_TIMER) {
-    clearInterval(window.__PROBE_TIMER);
-    window.__PROBE_TIMER = null;
-  }
-  return JSON.stringify({
-    events: window.__PROBE_EVENTS || [],
-    samples: window.__PROBE_SAMPLES || [],
-  });
-})();

.agents/skills/local-testing/scripts/agent-gateway/probe-dump.ts

@@ -1,37 +0,0 @@
-// Stops the events-probe timeline timer and stashes the full capture as a
-// JSON string on `window.__PROBE_LAST_DUMP_JSON`. `run.ts` wraps the bundle
-// in an IIFE that returns that global, which `agent-browser eval` prints to
-// stdout — the runner then persists it under `.agent-gateway/`.
-
-import type { ProbeDump } from './types';
-
-declare global {
-  interface Window {
-    __PROBE_LAST_DUMP_JSON?: string;
-  }
-}
-
-const w = window;
-
-if (w.__PROBE_TIMELINE_TIMER) {
-  clearInterval(w.__PROBE_TIMELINE_TIMER);
-  w.__PROBE_TIMELINE_TIMER = null;
-}
-
-const mutations = w.__PROBE_MUTATIONS ?? [];
-
-const dump: ProbeDump & { mutations: typeof mutations } = {
-  meta: {
-    t0: w.__PROBE_T0 ?? 0,
-    collectedAt: Date.now(),
-    sampleCount: (w.__PROBE_MSG_TIMELINE ?? []).length,
-    eventCount: (w.__PROBE_STREAM_EVENTS ?? []).length,
-    callCount: (w.__PROBE_ACTION_CALLS ?? []).length,
-  },
-  streamEvents: w.__PROBE_STREAM_EVENTS ?? [],
-  actionCalls: w.__PROBE_ACTION_CALLS ?? [],
-  timeline: w.__PROBE_MSG_TIMELINE ?? [],
-  mutations,
-};
-
-w.__PROBE_LAST_DUMP_JSON = JSON.stringify(dump);

.agents/skills/local-testing/scripts/agent-gateway/probe-events.ts

@@ -1,637 +0,0 @@
-// LobeHub gateway raw-event-stream probe.
-//
-// Gateway-mode chats subscribe via WebSocket — NOT via the `/api/agent/stream`
-// SSE endpoint (that one belongs to the direct/client durable-agent runtime).
-// `AgentStreamClient` (`packages/agent-gateway-client/src/client.ts`) opens
-// `new WebSocket('wss://.../ws?operationId=...')`, then parses JSON frames in
-// its `onmessage` handler and re-emits `agent_event.event` objects to the
-// chat store.
-//
-// To capture the RAW gateway events before the store touches them, we wrap
-// `window.WebSocket` so that for any socket whose URL contains `operationId=`
-// we intercept the `onmessage` handler / `addEventListener('message')` and
-// log every `agent_event` frame.
-//
-// We *also* keep the `window.fetch` hook for `/api/agent/stream` so this
-// probe still works for direct-mode runs — but gateway-mode events come
-// through the WebSocket path.
-//
-// Buffers (read via `dump`):
-//   __PROBE_STREAM_EVENTS  — raw events parsed off the wire
-//   __PROBE_ACTION_CALLS   — replaceMessages / refreshMessages calls (best-effort)
-//   __PROBE_MSG_TIMELINE   — 200ms snapshots of every messagesMap key
-
-import type {
-  ProbeActionCall,
-  ProbeMessageSummary,
-  ProbeStreamEvent,
-  ProbeTimelineSample,
-} from './types';
-
-// Bundled by esbuild as an IIFE. Top-level code runs once on injection.
-
-const w = window;
-
-// ── Buffers ─────────────────────────────────────────────────────────
-
-declare global {
-  interface Window {
-    __PROBE_MUTATIONS?: Array<{
-      t: number;
-      key: string;
-      n: number;
-      last?: { id: string; role: string; cLen: number; rLen: number; updatedAt?: unknown };
-      prevLast?: { id: string; role: string; cLen: number; rLen: number };
-      delta?: string;
-    }>;
-    __PROBE_STORE_UNSUB?: () => void;
-  }
-}
-
-const events: ProbeStreamEvent[] = (w.__PROBE_STREAM_EVENTS ??= []);
-const calls: ProbeActionCall[] = (w.__PROBE_ACTION_CALLS ??= []);
-const timeline: ProbeTimelineSample[] = (w.__PROBE_MSG_TIMELINE ??= []);
-const mutations = (w.__PROBE_MUTATIONS ??= []);
-events.length = 0;
-calls.length = 0;
-timeline.length = 0;
-mutations.length = 0;
-
-const t0 = Date.now();
-w.__PROBE_T0 = t0;
-const now = (): number => Date.now() - t0;
-
-// ── Helpers ─────────────────────────────────────────────────────────
-
-function summarizeData(data: unknown): Record<string, unknown> | unknown {
-  if (!data || typeof data !== 'object') return data;
-  const src = data as Record<string, unknown>;
-  const out: Record<string, unknown> = {};
-  for (const k of Object.keys(src)) {
-    const v = src[k];
-    if (v == null) {
-      out[k] = v;
-    } else if (Array.isArray(v)) {
-      out[k] = `Array(${v.length})`;
-      if (k === 'uiMessages') {
-        out.uiMessagesPreview = v.slice(0, 5).map((m: any) => ({
-          id: (m.id ?? '').slice(-8),
-          role: m.role,
-          cLen: (m.content ?? '').length,
-          children: (m.children ?? []).length,
-          tools: (m.tools ?? []).length,
-          reasoning: (m.reasoning?.content ?? '').length,
-        }));
-        out.uiMessagesTotal = v.length;
-      }
-    } else if (typeof v === 'object') {
-      const obj = v as Record<string, unknown>;
-      out[k] =
-        'Object{' +
-        Object.keys(obj)
-          .slice(0, 6)
-          .map((kk) => kk + (typeof obj[kk] === 'string' ? `=${(obj[kk] as string).length}ch` : ''))
-          .join(',') +
-        '}';
-    } else if (typeof v === 'string') {
-      out[k] = v.length > 100 ? v.slice(0, 100) + `…(${v.length})` : v;
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-function summarizeMessages(msgs: any[]): ProbeMessageSummary[] {
-  return (msgs ?? []).slice(0, 80).map((m) => ({
-    id: (m.id ?? '').slice(-8),
-    role: m.role,
-    cLen: (m.content ?? '').length,
-    rLen: (m.reasoning?.content ?? '').length,
-    tools: (m.tools ?? []).length,
-    chN: (m.children ?? []).length,
-  }));
-}
-
-function shortStack(): string {
-  const raw = new Error('probe-stack').stack ?? '';
-  return raw
-    .split('\n')
-    .slice(3)
-    .filter((l) => !l.includes('probe-events') && !l.includes('node_modules'))
-    .map((l) => l.trim().replace(/^at\s+/, ''))
-    .slice(0, 6)
-    .join(' ← ');
-}
-
-function recordAgentEvent(args: {
-  transport: 'ws' | 'sse';
-  opId: string | null;
-  agentEvent: any;
-  eventId?: string | null;
-  rawLen?: number;
-}): void {
-  const { transport, opId, agentEvent, eventId, rawLen } = args;
-  if (!agentEvent || typeof agentEvent !== 'object') return;
-  events.push({
-    t: now(),
-    transport,
-    opIdTail: (opId ?? '').slice(-10),
-    eventId: eventId ?? null,
-    type: agentEvent.type,
-    stepIndex: agentEvent.stepIndex,
-    dataKeys: agentEvent.data ? Object.keys(agentEvent.data) : [],
-    data: summarizeData(agentEvent.data) as Record<string, unknown>,
-    rawLen,
-  });
-}
-
-// ── 1. Patch window.WebSocket for gateway WS events ────────────────
-
-if (!w.__PROBE_ORIG_WEBSOCKET) w.__PROBE_ORIG_WEBSOCKET = w.WebSocket;
-const OrigWS = w.__PROBE_ORIG_WEBSOCKET;
-
-function extractOpIdFromWsUrl(url: string | URL): string | null {
-  const m = String(url ?? '').match(/operationId=([^&]+)/);
-  return m ? decodeURIComponent(m[1]) : null;
-}
-
-function isGatewayWs(url: string | URL): boolean {
-  return String(url ?? '').includes('operationId=');
-}
-
-function handleWsFrame(rawData: unknown, opId: string | null): void {
-  const rawLen = typeof rawData === 'string' ? rawData.length : -1;
-  let parsed: any;
-  try {
-    parsed = typeof rawData === 'string' ? JSON.parse(rawData) : null;
-  } catch {
-    events.push({
-      t: now(),
-      transport: 'ws',
-      opIdTail: (opId ?? '').slice(-10),
-      type: '_PARSE_ERROR_',
-      raw: typeof rawData === 'string' && rawData.length < 400 ? rawData : '(non-string or large)',
-    });
-    return;
-  }
-  if (!parsed) return;
-
-  if (parsed.type === 'agent_event') {
-    recordAgentEvent({
-      transport: 'ws',
-      opId,
-      agentEvent: parsed.event,
-      eventId: parsed.id,
-      rawLen,
-    });
-  } else {
-    events.push({
-      t: now(),
-      transport: 'ws',
-      opIdTail: (opId ?? '').slice(-10),
-      type: '_SERVER_MSG_',
-      serverType: parsed.type,
-      rawLen,
-    });
-  }
-}
-
-// Wrap the constructor. Instance `constructor` will still reflect OrigWS
-// (we share prototypes), so use the `_WS_OPEN_` sentinel events to confirm
-// the patch is firing.
-function PatchedWebSocket(this: WebSocket, url: string | URL, protocols?: string | string[]) {
-  const ws: WebSocket = protocols == null ? new OrigWS(url) : new OrigWS(url, protocols);
-  const opId = extractOpIdFromWsUrl(url);
-  if (!isGatewayWs(url)) return ws;
-
-  events.push({
-    t: now(),
-    transport: 'ws',
-    opIdTail: (opId ?? '').slice(-10),
-    type: '_WS_OPEN_',
-    url: String(url),
-  });
-
-  // One observer listener that always fires, regardless of how the consumer
-  // (AgentStreamClient uses `ws.onmessage = …`) subscribes.
-  ws.addEventListener('message', (e) => {
-    try {
-      handleWsFrame((e as MessageEvent).data, opId);
-    } catch {
-      /* swallow */
-    }
-  });
-
-  ws.addEventListener('close', () => {
-    events.push({
-      t: now(),
-      transport: 'ws',
-      opIdTail: (opId ?? '').slice(-10),
-      type: '_WS_CLOSE_',
-    });
-  });
-
-  return ws;
-}
-
-// Preserve prototype + static fields so `instanceof WebSocket` and
-// `WebSocket.OPEN` constants still work.
-(PatchedWebSocket as unknown as { prototype: WebSocket }).prototype = OrigWS.prototype;
-for (const k of Object.keys(OrigWS) as Array<keyof typeof OrigWS>) {
-  try {
-    (PatchedWebSocket as any)[k] = (OrigWS as any)[k];
-  } catch {
-    /* readonly */
-  }
-}
-(['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'] as const).forEach((k) => {
-  (PatchedWebSocket as any)[k] = (OrigWS as any)[k];
-});
-w.WebSocket = PatchedWebSocket as unknown as typeof WebSocket;
-
-// ── 2. Patch window.fetch for `/api/agent/stream` (direct-mode SSE) ─
-
-if (!w.__PROBE_ORIG_FETCH) w.__PROBE_ORIG_FETCH = w.fetch.bind(w);
-const origFetch = w.__PROBE_ORIG_FETCH;
-
-function isAgentStreamUrl(input: RequestInfo | URL): boolean {
-  let url = '';
-  if (typeof input === 'string') url = input;
-  else if (input instanceof URL) url = input.toString();
-  else if (input && typeof (input as Request).url === 'string') url = (input as Request).url;
-  return url.includes('/api/agent/stream');
-}
-
-function extractOpIdFromHttpUrl(input: RequestInfo | URL): string | null {
-  const url = typeof input === 'string' ? input : (input as Request | URL).toString();
-  const m = url.match(/operationId=([^&]+)/);
-  return m ? decodeURIComponent(m[1]) : null;
-}
-
-function pushFromSSEFrame(rawFrame: string, opId: string | null): void {
-  const lines = rawFrame.split('\n');
-  let dataJson = '';
-  let evtName = 'message';
-  for (const line of lines) {
-    if (line.startsWith('event:')) evtName = line.slice(6).trim();
-    else if (line.startsWith('data:')) dataJson += line.slice(5).trim();
-  }
-  if (!dataJson) return;
-  let parsed: any;
-  try {
-    parsed = JSON.parse(dataJson);
-  } catch {
-    events.push({
-      t: now(),
-      transport: 'sse',
-      opIdTail: (opId ?? '').slice(-10),
-      type: '_PARSE_ERROR_',
-      sseEvent: evtName,
-      raw: dataJson.length > 400 ? dataJson.slice(0, 400) + '…' : dataJson,
-    });
-    return;
-  }
-  recordAgentEvent({
-    transport: 'sse',
-    opId,
-    agentEvent: parsed,
-    eventId: null,
-    rawLen: dataJson.length,
-  });
-}
-
-async function teeAndDrain(response: Response, opId: string | null): Promise<Response> {
-  if (!response.body) return response;
-  const [a, b] = response.body.tee();
-
-  void (async () => {
-    const reader = b.getReader();
-    const decoder = new TextDecoder();
-    let buf = '';
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        let idx: number;
-
-        while ((idx = buf.indexOf('\n\n')) !== -1) {
-          const frame = buf.slice(0, idx);
-          buf = buf.slice(idx + 2);
-          if (frame.trim()) pushFromSSEFrame(frame, opId);
-        }
-      }
-      if (buf.trim()) pushFromSSEFrame(buf, opId);
-    } catch (e: any) {
-      events.push({
-        t: now(),
-        transport: 'sse',
-        opIdTail: (opId ?? '').slice(-10),
-        type: '_TEE_ERROR_',
-        message: String(e?.message ?? e),
-      });
-    }
-  })();
-
-  return new Response(a, {
-    headers: response.headers,
-    status: response.status,
-    statusText: response.statusText,
-  });
-}
-
-w.fetch = async function patchedFetch(input: RequestInfo | URL, init?: RequestInit) {
-  const response = await origFetch(input as any, init);
-  if (!isAgentStreamUrl(input)) return response;
-  const opId = extractOpIdFromHttpUrl(input);
-  const url =
-    typeof input === 'string'
-      ? input.split('?')[0]
-      : (input as Request | URL).toString().split('?')[0];
-  events.push({
-    t: now(),
-    transport: 'sse',
-    opIdTail: (opId ?? '').slice(-10),
-    type: '_CONNECTED_',
-    url,
-    status: response.status,
-  });
-  return teeAndDrain(response, opId);
-} as typeof fetch;
-
-// ── 3. Wrap store actions (best-effort for "who called replace") ────
-
-// Side-global stash for the original chat-store actions. Re-installs ALWAYS
-// rewrap from the originals so updates to the probe body take effect
-// without a page reload — using only a `__probeWrapped` flag on the chat
-// state object would freeze the first-installed wrapper across re-installs.
-declare global {
-  interface Window {
-    __PROBE_ORIG_REFRESH_MESSAGES?: any;
-    __PROBE_ORIG_REPLACE_MESSAGES?: any;
-  }
-}
-
-try {
-  const chat = w.__LOBE_STORES?.chat?.();
-  if (chat) {
-    // First-time install: cache the originals. Re-install: restore from
-    // the cached originals before wrapping again.
-    if (!w.__PROBE_ORIG_REFRESH_MESSAGES) w.__PROBE_ORIG_REFRESH_MESSAGES = chat.refreshMessages;
-    if (!w.__PROBE_ORIG_REPLACE_MESSAGES) w.__PROBE_ORIG_REPLACE_MESSAGES = chat.replaceMessages;
-    const origRefresh = w.__PROBE_ORIG_REFRESH_MESSAGES;
-    const origReplace = w.__PROBE_ORIG_REPLACE_MESSAGES;
-    chat.refreshMessages = origRefresh;
-    chat.replaceMessages = origReplace;
-
-    chat.refreshMessages = async function probeRefresh(this: unknown, ...args: any[]) {
-      calls.push({
-        t: now(),
-        name: 'refreshMessages',
-        args: { context: args[0] ?? null },
-        stack: shortStack(),
-      });
-      return origRefresh.apply(this, args);
-    };
-    chat.replaceMessages = function probeReplace(this: unknown, ...args: any[]) {
-      const msgs = (args[0] as any[]) ?? [];
-      const snapshot = msgs.slice(-2).map((m) => ({
-        id: (m.id ?? '').slice(-8),
-        role: m.role,
-        cLen: (m.content ?? '').length,
-        rLen: (m.reasoning?.content ?? '').length,
-        updatedAt: m.updatedAt,
-      }));
-      calls.push({
-        t: now(),
-        name: 'replaceMessages',
-        args: { count: msgs.length, params: args[1] ?? null, snapshot } as any,
-        stack: shortStack(),
-      });
-
-      // Pair the call with a mutation row so the analyzer can build a
-      // single ordered timeline across replaceMessages + dispatchMessage.
-      const stackTop = shortStack().split(' ← ')[0]?.slice(0, 80);
-      const last = msgs.at(-1);
-      const lastSum = last
-        ? {
-            id: (last.id ?? '').slice(-8),
-            role: last.role,
-            cLen: (last.content ?? '').length,
-            rLen: (last.reasoning?.content ?? '').length,
-            updatedAt: last.updatedAt,
-          }
-        : undefined;
-      const params: any = args[1] ?? {};
-      const ctxKey = params.context
-        ? `main_${params.context.agentId ?? '?'}_${
-            params.context.topicId ? 'tpc_' + params.context.topicId : 'new'
-          }`.replace('main_tpc_', 'main_') // crude key inference
-        : '(no-ctx)';
-      mutations.push({
-        t: now(),
-        key: ctxKey,
-        n: msgs.length,
-        last: lastSum,
-        delta: `replaceMessages(action=${params.action ?? '-'})  src=${stackTop ?? '-'}`,
-      });
-
-      return origReplace.apply(this, args);
-    };
-  }
-} catch (e: any) {
-  calls.push({ t: now(), name: '_WRAP_ERROR_', error: String(e?.message ?? e) });
-}
-
-// ── 3.5. Mutation log — wrap the TWO ChatStore writers (replaceMessages,
-// internal_dispatchMessage) to record EVERY dbMessagesMap[key] reference
-// change with a one-line "before/after last assistant message" delta. This
-// reveals dispatchMessage-driven collapses that the replaceMessages wrap
-// alone cannot see.
-
-declare global {
-  interface Window {
-    __PROBE_ORIG_DISPATCH_MESSAGE?: any;
-  }
-}
-
-try {
-  const chat = w.__LOBE_STORES?.chat?.();
-  if (chat?.internal_dispatchMessage) {
-    if (!w.__PROBE_ORIG_DISPATCH_MESSAGE)
-      w.__PROBE_ORIG_DISPATCH_MESSAGE = chat.internal_dispatchMessage;
-    const origDispatch = w.__PROBE_ORIG_DISPATCH_MESSAGE;
-    chat.internal_dispatchMessage = origDispatch;
-
-    chat.internal_dispatchMessage = function probeDispatch(this: unknown, payload: any, ctx?: any) {
-      // Snapshot BEFORE — read the would-be target key + last message.
-      const before = (() => {
-        try {
-          const state = w.__LOBE_STORES?.chat?.();
-          if (!state) return null;
-          // Replicate state.internal_getConversationContext logic enough to
-          // resolve a key — but most callers pass operationId on ctx, and
-          // operationId-keyed lookup needs store internals. Easiest: snapshot
-          // ALL keys' last-assistant cLen and compare BEFORE vs AFTER below.
-          const map = state.dbMessagesMap ?? {};
-          const out: Record<string, any> = {};
-          for (const k of Object.keys(map)) {
-            const last = (map[k] ?? []).at(-1);
-            out[k] = last
-              ? {
-                  id: (last.id ?? '').slice(-8),
-                  cLen: (last.content ?? '').length,
-                  rLen: (last.reasoning?.content ?? '').length,
-                  n: map[k].length,
-                }
-              : { n: 0 };
-          }
-          return out;
-        } catch {
-          return null;
-        }
-      })();
-
-      const result = origDispatch.apply(this, [payload, ctx]);
-
-      // Snapshot AFTER — find which key(s) actually changed.
-      try {
-        const state = w.__LOBE_STORES?.chat?.();
-        if (state && before) {
-          const map = state.dbMessagesMap ?? {};
-          for (const k of Object.keys(map)) {
-            const last = (map[k] ?? []).at(-1);
-            const beforeSnap = before[k];
-            const afterSnap = last
-              ? {
-                  id: (last.id ?? '').slice(-8),
-                  cLen: (last.content ?? '').length,
-                  rLen: (last.reasoning?.content ?? '').length,
-                  n: map[k].length,
-                }
-              : { n: 0 };
-            const changed =
-              !beforeSnap ||
-              beforeSnap.n !== afterSnap.n ||
-              beforeSnap.id !== (afterSnap as any).id ||
-              beforeSnap.cLen !== (afterSnap as any).cLen ||
-              beforeSnap.rLen !== (afterSnap as any).rLen;
-            if (!changed) continue;
-            let delta = '';
-            if (beforeSnap?.id !== undefined && beforeSnap.id !== (afterSnap as any).id)
-              delta += `id:${beforeSnap.id}→${(afterSnap as any).id};`;
-            if (
-              beforeSnap?.cLen !== undefined &&
-              (afterSnap as any).cLen !== undefined &&
-              (afterSnap as any).cLen < beforeSnap.cLen
-            )
-              delta += `cLen↓${beforeSnap.cLen}→${(afterSnap as any).cLen};`;
-            if (
-              beforeSnap?.rLen !== undefined &&
-              (afterSnap as any).rLen !== undefined &&
-              (afterSnap as any).rLen < beforeSnap.rLen
-            )
-              delta += `rLen↓${beforeSnap.rLen}→${(afterSnap as any).rLen};`;
-            if (beforeSnap?.n !== undefined && afterSnap.n < beforeSnap.n)
-              delta += `n↓${beforeSnap.n}→${afterSnap.n};`;
-            mutations.push({
-              t: now(),
-              key: k,
-              n: afterSnap.n,
-              last: (afterSnap as any).id ? (afterSnap as any) : undefined,
-              prevLast: beforeSnap?.id ? beforeSnap : undefined,
-              delta: delta || `dispatch:${payload?.type}`,
-            });
-          }
-        }
-      } catch (e: any) {
-        mutations.push({
-          t: now(),
-          key: '_DISPATCH_PROBE_ERROR_',
-          n: -1,
-          delta: String(e?.message ?? e),
-        });
-      }
-      return result;
-    };
-  }
-} catch (e: any) {
-  calls.push({ t: now(), name: '_DISPATCH_WRAP_ERROR_', error: String(e?.message ?? e) });
-}
-
-// ── 4. Periodic per-key timeline snapshots ─────────────────────────
-
-function captureTimeline(): void {
-  try {
-    const c = w.__LOBE_STORES?.chat?.();
-    if (!c) return;
-    const msgsMap = (c.messagesMap ?? {}) as Record<string, any[]>;
-    const dbMap = (c.dbMessagesMap ?? {}) as Record<string, any[]>;
-    const byKey: ProbeTimelineSample['byKey'] = {};
-    for (const k of Object.keys(msgsMap)) {
-      const display = msgsMap[k] ?? [];
-      const db = dbMap[k] ?? [];
-      if (display.length === 0 && db.length === 0) continue;
-      byKey[k] = {
-        n: display.length,
-        dbN: db.length,
-        msgs: summarizeMessages(display),
-      };
-    }
-    const ops = Object.values((c.operations ?? {}) as Record<string, any>);
-    timeline.push({
-      t: now(),
-      activeTopic: ((c.activeTopicId as string | null) ?? '').slice(-10) || null,
-      keys: Object.keys(byKey),
-      byKey,
-      runOps: ops.filter((o: any) => o.status === 'running').length,
-    });
-  } catch (e: any) {
-    timeline.push({
-      t: now(),
-      activeTopic: null,
-      keys: [],
-      byKey: {},
-      runOps: 0,
-      err: e?.message ?? String(e),
-    });
-  }
-}
-captureTimeline();
-if (w.__PROBE_TIMELINE_TIMER) clearInterval(w.__PROBE_TIMELINE_TIMER);
-w.__PROBE_TIMELINE_TIMER = setInterval(captureTimeline, 200);
-
-// ── 5. Tab-switch helpers ──────────────────────────────────────────
-
-function listTopBarTabs(): HTMLElement[] {
-  return Array.from(
-    document.querySelectorAll<HTMLElement>(
-      '[data-insp-path*="TabItem.tsx"][data-contextmenu-trigger]',
-    ),
-  ).filter((t) => t.getBoundingClientRect().top < 30);
-}
-
-w.__listTabs = () =>
-  listTopBarTabs().map((t, i) => ({
-    i,
-    key: t.getAttribute('data-contextmenu-trigger'),
-    active: t.getAttribute('data-active') === 'true',
-    title: (t.innerText ?? '').slice(0, 60),
-  }));
-
-w.__clickTabByKey = (key: string) => {
-  const tab = listTopBarTabs().find((t) => t.getAttribute('data-contextmenu-trigger') === key);
-  if (!tab) return 'not found: ' + key;
-  if (tab.getAttribute('data-active') === 'true') return 'already active: ' + key;
-  tab.click();
-  return 'clicked key=' + key;
-};
-
-w.__PROBE_EVENT = (name: string) => {
-  calls.push({ t: now(), name: 'MARK:' + name });
-};
-
-// `run.ts` wraps the bundle in an IIFE and appends a `return <confirmation>`
-// after the bundle body — agent-browser then prints the confirmation back to
-// the operator. Nothing to do here at the end of the module body.

.agents/skills/local-testing/scripts/agent-gateway/probe.js

@@ -1,204 +0,0 @@
-// LobeHub chat streaming time-series probe.
-//
-// Inject into the renderer (via agent-browser eval) to record store + DOM
-// snapshots every 200ms during a streaming session. Designed to surface
-// "UI rolled back to an earlier state" symptoms — especially around
-// gateway-mode tab switches that happen while the assistant is still writing.
-//
-// Usage:
-//   agent-browser --cdp 9222 eval --stdin < probe.js
-//   # ...do test interactions, call window.__PROBE_EVENT('LABEL') to mark moments...
-//   agent-browser --cdp 9222 eval --stdin < probe-dump.js > /tmp/probe.json
-//   node analyze.mjs /tmp/probe.json
-//
-// What it captures per sample:
-//   - activeTopicId
-//   - msgN: top-level messages in chat.messagesMap for this topic
-//   - childN: total assistantGroup.children blocks across all msgs (THIS is
-//     where streaming content actually lives — top-level assistantGroup stays empty)
-//   - cT / rT / toolT: totals across messages AND their children
-//                       (content, reasoning, tool-call count)
-//   - perMsg: per-message breakdown so regressions can be located precisely
-//   - runOps: number of running operations (execServerAgentRuntime etc.)
-//   - domLen: total innerText length of the rendered chat list area
-//   - ind: visible UI indicators (Search pages, Crawled pages, Deeply Thought, Sending)
-//
-// Event markers: window.__PROBE_EVENT('NAME') records {t, name} into
-// __PROBE_EVENTS, used by the analyzer to align state changes with
-// user-driven actions (SENT, AWAY_1, BACK_1, ...).
-
-(function () {
-  if (window.__PROBE_TIMER) clearInterval(window.__PROBE_TIMER);
-  window.__PROBE_SAMPLES = [];
-  window.__PROBE_EVENTS = [];
-  const t0 = Date.now();
-
-  function snapshot() {
-    try {
-      const chat = window.__LOBE_STORES.chat();
-      const topicId = chat.activeTopicId;
-      const idTail = topicId ? topicId.replace('tpc_', '') : null;
-      const keys = Object.keys(chat.messagesMap || {});
-
-      // Collect messages for the active topic. Before a topic is committed,
-      // optimistic messages live under the `<agentScope>_new` key — fall
-      // back to those when no topic is active yet.
-      let msgs = [];
-      if (idTail) {
-        keys.forEach((k) => {
-          if (k.includes(idTail)) msgs = msgs.concat(chat.messagesMap[k] || []);
-        });
-      } else {
-        keys
-          .filter((k) => k.endsWith('_new'))
-          .forEach((k) => {
-            msgs = msgs.concat(chat.messagesMap[k] || []);
-          });
-      }
-
-      // Walk top-level + assistantGroup.children. children carry the actual
-      // streamed content / reasoning / tool calls; the parent assistantGroup
-      // remains a placeholder (cLen=0, rLen=0) for its whole lifetime.
-      let totalContent = 0;
-      let totalReason = 0;
-      let totalTools = 0;
-      let childCount = 0;
-      const perMsg = msgs.map((m) => {
-        const cLen = (m.content || '').length;
-        const rLen = ((m.reasoning && m.reasoning.content) || '').length;
-        const tools = (m.tools || []).length;
-        totalContent += cLen;
-        totalReason += rLen;
-        totalTools += tools;
-
-        const children = m.children || [];
-        let chC = 0;
-        let chR = 0;
-        let chT = 0;
-        children.forEach((c) => {
-          chC += (c.content || '').length;
-          chR += ((c.reasoning && c.reasoning.content) || '').length;
-          chT += (c.tools || []).length;
-        });
-        totalContent += chC;
-        totalReason += chR;
-        totalTools += chT;
-        childCount += children.length;
-
-        return {
-          id: (m.id || '').slice(-8),
-          role: m.role,
-          cLen,
-          rLen,
-          tools,
-          chCount: children.length,
-          chC,
-          chR,
-          chT,
-        };
-      });
-
-      const ops = Object.values(chat.operations || {});
-      const runningOps = ops.filter((o) => o.status === 'running');
-
-      // DOM probe: total rendered text in the chat scroll area (proxy for
-      // "how much is actually visible to the user").
-      const convScroll =
-        document.querySelector(
-          '[data-chat-list], [class*="ChatList"], [class*="ConversationList"]',
-        ) ||
-        document.querySelector('main [class*="scroll"]') ||
-        document.querySelector('main');
-      const domTxt = convScroll ? convScroll.innerText || '' : '';
-
-      const bodyTxt = document.body.innerText || '';
-      const searchMatches = (bodyTxt.match(/Search pages?:|Searched the web/g) || []).length;
-      const crawlMatches = (bodyTxt.match(/Crawl(ed|ing) pages?/g) || []).length;
-
-      window.__PROBE_SAMPLES.push({
-        t: Date.now() - t0,
-        topicId,
-        msgN: msgs.length,
-        childN: childCount,
-        cT: totalContent,
-        rT: totalReason,
-        toolT: totalTools,
-        perMsg,
-        runOps: runningOps.length,
-        runOpTypes: runningOps.map((o) => o.type),
-        domLen: domTxt.length,
-        ind: {
-          search: searchMatches,
-          crawl: crawlMatches,
-          sending: bodyTxt.includes('Sending message'),
-          deeplyThinking: bodyTxt.includes('Deeply Thinking'),
-          deeplyThought: bodyTxt.includes('Deeply Thought'),
-        },
-      });
-    } catch (e) {
-      window.__PROBE_SAMPLES.push({ t: Date.now() - t0, err: e.message });
-    }
-  }
-
-  snapshot();
-  window.__PROBE_TIMER = setInterval(snapshot, 200);
-  window.__PROBE_EVENT = function (name) {
-    window.__PROBE_EVENTS.push({ t: Date.now() - t0, name });
-  };
-
-  // Tab-switch helpers installed alongside the probe.
-  //
-  // The Electron tab bar mounts each tab as a div with data-insp-path
-  // ending in `TabItem.tsx:...`. The active tab is marked with
-  // data-active="true". DO NOT search by innerText — the active tab's text
-  // includes a ` · <agent name>` suffix that produces false matches when
-  // your search string happens to overlap with the agent name.
-  function listTabs() {
-    return Array.from(
-      document.querySelectorAll('[data-insp-path*="TabItem.tsx"][data-contextmenu-trigger]'),
-    ).filter((t) => t.getBoundingClientRect().top < 30);
-  }
-  function tabKey(el) {
-    // Stable for the tab's lifetime; survives focus changes.
-    return el.getAttribute('data-contextmenu-trigger');
-  }
-  function findActiveTab() {
-    return listTabs().find((t) => t.getAttribute('data-active') === 'true') || null;
-  }
-
-  // Click by stable key captured earlier (preferred for round-trips).
-  window.__clickTabByKey = function (key) {
-    const tab = listTabs().find((t) => tabKey(t) === key);
-    if (!tab) return 'not found: key=' + key;
-    if (tab.getAttribute('data-active') === 'true') return 'already active: ' + key;
-    tab.click();
-    return 'clicked key=' + key;
-  };
-
-  // Click by index in the tab strip (0-based, left-to-right).
-  window.__clickTabByIndex = function (i) {
-    const tabs = listTabs();
-    if (i < 0 || i >= tabs.length) return 'index out of range: ' + i + '/' + tabs.length;
-    const t = tabs[i];
-    if (t.getAttribute('data-active') === 'true') return 'already active: i=' + i;
-    t.click();
-    return 'clicked i=' + i + ' key=' + tabKey(t);
-  };
-
-  // Snapshot all tabs in order: [{key, active, title (first 60 chars of innerText)}]
-  window.__listTabs = function () {
-    return listTabs().map((t, i) => ({
-      i,
-      key: tabKey(t),
-      active: t.getAttribute('data-active') === 'true',
-      title: (t.innerText || '').slice(0, 60),
-    }));
-  };
-
-  window.__activeTabKey = function () {
-    const a = findActiveTab();
-    return a ? tabKey(a) : null;
-  };
-
-  return 'probe installed';
-})();

.agents/skills/local-testing/scripts/agent-gateway/run.ts

@@ -1,211 +0,0 @@
-// CLI for the agent-gateway probe.
-//
-// Bundles the TS probes with esbuild, pipes them into `agent-browser eval`,
-// and persists dumps under `.agent-gateway/` (gitignored) for later use as
-// streaming-replay test fixtures.
-//
-// Commands:
-//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts install
-//       Bundle probe-events.ts and inject into the CDP-attached browser.
-//       Re-installing clears all buffers and re-patches WebSocket / fetch.
-//
-//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts dump [name]
-//       Stop the timeline timer, fetch the capture as JSON, write it to
-//       `.agent-gateway/<name>-<YYYYMMDD-HHmmss>.json`. `name` defaults to
-//       `dump`. Prints the absolute path written.
-//
-//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts analyze [path]
-//       Run analyze-events.ts on the dump. `path` defaults to the most
-//       recently modified file in `.agent-gateway/`.
-//
-// Optional flags:
-//   --cdp <port>     CDP port (default 9222)
-//   --browser <bin>  agent-browser binary (default 'agent-browser')
-
-import { spawn } from 'node:child_process';
-import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-// .agents/skills/local-testing/scripts/agent-gateway/ → 5 levels up
-const PROJECT_ROOT = path.resolve(SCRIPT_DIR, '../../../../..');
-const DUMP_DIR = path.join(PROJECT_ROOT, '.agent-gateway');
-
-interface Flags {
-  browser: string;
-  cdp: string;
-  positional: string[];
-}
-
-function parseFlags(argv: string[]): Flags {
-  const out: Flags = { cdp: '9222', browser: 'agent-browser', positional: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--cdp') out.cdp = argv[++i] ?? out.cdp;
-    else if (a === '--browser') out.browser = argv[++i] ?? out.browser;
-    else out.positional.push(a);
-  }
-  return out;
-}
-
-async function bundle(entry: string): Promise<string> {
-  // Bun.build is built into the Bun runtime — no external dep needed.
-  const r = await Bun.build({
-    entrypoints: [path.join(SCRIPT_DIR, entry)],
-    target: 'browser',
-    format: 'esm',
-    minify: false,
-  });
-  if (!r.success) {
-    const msgs = r.logs.map((l) => `${l.level}: ${l.message}`).join('\n');
-    throw new Error(`bundle failed for ${entry}:\n${msgs}`);
-  }
-  return await r.outputs[0].text();
-}
-
-function wrapIife(body: string, returnExpr: string): string {
-  // Wrap as an IIFE that swallows the bundled top-level (top-level `const`
-  // declarations get scoped to the IIFE, so re-injection doesn't conflict)
-  // and returns the configured expression — which `agent-browser eval`
-  // captures and prints to stdout.
-  return `(() => {\n${body}\n;return ${returnExpr};\n})()`;
-}
-
-function runAgentBrowserEval(flags: Flags, script: string): Promise<string> {
-  return new Promise((resolveP, rejectP) => {
-    const child = spawn(flags.browser, ['--cdp', flags.cdp, 'eval', '--stdin'], {
-      stdio: ['pipe', 'pipe', 'inherit'],
-    });
-    let stdout = '';
-    child.stdout.on('data', (chunk: Buffer) => {
-      stdout += chunk.toString('utf8');
-    });
-    child.on('error', rejectP);
-    child.on('close', (code) => {
-      if (code === 0) resolveP(stdout);
-      else rejectP(new Error(`agent-browser exited ${code}`));
-    });
-    child.stdin.write(script);
-    child.stdin.end();
-  });
-}
-
-// agent-browser prints eval results as JSON (string values are quoted).
-function unquoteAgentBrowserResult(raw: string): string {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
-    try {
-      return JSON.parse(trimmed) as string;
-    } catch {
-      /* fall through */
-    }
-  }
-  return trimmed;
-}
-
-function isoStamp(): string {
-  const d = new Date();
-  const yyyy = d.getFullYear();
-  const mm = String(d.getMonth() + 1).padStart(2, '0');
-  const dd = String(d.getDate()).padStart(2, '0');
-  const hh = String(d.getHours()).padStart(2, '0');
-  const mi = String(d.getMinutes()).padStart(2, '0');
-  const ss = String(d.getSeconds()).padStart(2, '0');
-  return `${yyyy}${mm}${dd}-${hh}${mi}${ss}`;
-}
-
-function ensureDumpDir(): void {
-  mkdirSync(DUMP_DIR, { recursive: true });
-}
-
-function latestDump(): string | null {
-  ensureDumpDir();
-  const entries = readdirSync(DUMP_DIR)
-    .filter((f) => f.endsWith('.json'))
-    .map((f) => ({ f, mtime: statSync(path.join(DUMP_DIR, f)).mtimeMs }))
-    .sort((a, b) => b.mtime - a.mtime);
-  return entries[0] ? path.join(DUMP_DIR, entries[0].f) : null;
-}
-
-// ── Commands ────────────────────────────────────────────────────────
-
-async function cmdInstall(flags: Flags): Promise<void> {
-  const body = await bundle('probe-events.ts');
-  const installMsg = JSON.stringify(
-    'events probe installed: WebSocket+fetch interception. ' +
-      'WS captures operationId= sockets (gateway), fetch captures /api/agent/stream (direct).',
-  );
-  const script = wrapIife(body, installMsg);
-  const out = await runAgentBrowserEval(flags, script);
-  console.log(unquoteAgentBrowserResult(out));
-}
-
-async function cmdDump(flags: Flags): Promise<void> {
-  const name = flags.positional[1] ?? 'dump';
-  const body = await bundle('probe-dump.ts');
-  const script = wrapIife(body, 'window.__PROBE_LAST_DUMP_JSON');
-  const raw = await runAgentBrowserEval(flags, script);
-  const json = unquoteAgentBrowserResult(raw);
-  ensureDumpDir();
-  const filename = `${name}-${isoStamp()}.json`;
-  const dumpPath = path.join(DUMP_DIR, filename);
-  writeFileSync(dumpPath, json, 'utf8');
-  // Validate by parsing the meta header so we error early on bad capture
-  try {
-    const parsed = JSON.parse(json) as {
-      meta?: { eventCount?: number; callCount?: number; sampleCount?: number };
-    };
-    const meta = parsed.meta ?? {};
-    console.log(
-      `wrote ${dumpPath}  (${json.length} bytes  events=${meta.eventCount ?? '?'}  ` +
-        `calls=${meta.callCount ?? '?'}  samples=${meta.sampleCount ?? '?'})`,
-    );
-  } catch {
-    console.log(`wrote ${dumpPath}  (${json.length} bytes — JSON.parse failed; see file)`);
-  }
-}
-
-async function cmdAnalyze(flags: Flags): Promise<void> {
-  const target = flags.positional[1] ?? latestDump();
-  if (!target) {
-    console.error('no dump file found. run `dump` first or pass a path.');
-    process.exit(1);
-  }
-  const child = spawn('bun', ['run', path.join(SCRIPT_DIR, 'analyze-events.ts'), target], {
-    stdio: 'inherit',
-  });
-  await new Promise<void>((resolveP, rejectP) => {
-    child.on('error', rejectP);
-    child.on('close', (code) => (code === 0 ? resolveP() : rejectP(new Error(`exit ${code}`))));
-  });
-}
-
-// ── Entry point ─────────────────────────────────────────────────────
-
-const flags = parseFlags(process.argv.slice(2));
-const cmd = flags.positional[0];
-
-const usage = `usage:
-  bun run run.ts install [--cdp 9222]
-  bun run run.ts dump [name] [--cdp 9222]
-  bun run run.ts analyze [path]
-`;
-
-if (!cmd) {
-  console.error(usage);
-  process.exit(1);
-}
-
-try {
-  if (cmd === 'install') await cmdInstall(flags);
-  else if (cmd === 'dump') await cmdDump(flags);
-  else if (cmd === 'analyze') await cmdAnalyze(flags);
-  else {
-    console.error(`unknown command: ${cmd}\n\n${usage}`);
-    process.exit(1);
-  }
-} catch (e: any) {
-  console.error(e?.stack ?? e);
-  process.exit(1);
-}

.agents/skills/local-testing/scripts/agent-gateway/tab-switch.js

@@ -1,72 +0,0 @@
-// Run N round-trip tab switches with event markers timed against the probe.
-//
-//   agent-browser --cdp 9222 eval --stdin < tab-switch.js
-//
-// Captures the currently-active tab as the BACK target and the rightmost
-// inactive tab as the AWAY target. Both are addressed by their stable
-// data-contextmenu-trigger key (NOT by visible title — the active tab's
-// innerText embeds a ` · <agent name>` suffix that breaks text matching).
-//
-// Fires the loop in the background and returns immediately so the
-// agent-browser eval doesn't have to await the full ROUND_TRIPS × DWELL_MS
-// duration. Wait on the `SWITCH_LOOP_DONE` event before dumping.
-//
-// Refuses to launch if a previous loop is still in flight.
-//
-// Requires probe.js to have been installed first (provides
-// window.__PROBE_EVENT / __listTabs / __clickTabByKey / __activeTabKey).
-
-(function () {
-  const ROUND_TRIPS = 4;
-  const DWELL_MS = 10_000;
-
-  if (!window.__PROBE_EVENT || !window.__listTabs || !window.__clickTabByKey) {
-    return 'probe not installed — eval probe.js first';
-  }
-  if (window.__SWITCH_LOOP_RUNNING) {
-    return 'switch loop already running — wait for SWITCH_LOOP_DONE first';
-  }
-
-  const tabs = window.__listTabs();
-  const activeTab = tabs.find((t) => t.active);
-  if (!activeTab) return 'no active tab — abort';
-
-  // Pick the first inactive tab as AWAY target. With multiple inactive tabs
-  // you'll usually want the one that's stable across the test — feel free
-  // to swap to tabs[tabs.length-1] if you want the rightmost.
-  const inactives = tabs.filter((t) => !t.active);
-  if (inactives.length === 0) return 'no inactive tab to switch to — abort';
-  const awayTab = inactives.at(-1); // rightmost inactive
-
-  const BACK_KEY = activeTab.key;
-  const AWAY_KEY = awayTab.key;
-
-  window.__SWITCH_LOOP_RUNNING = true;
-  window.__PROBE_EVENT('SWITCH_LOOP_CONFIG:back=' + BACK_KEY + ',away=' + AWAY_KEY);
-
-  (async function () {
-    function sleep(ms) {
-      return new Promise((r) => setTimeout(r, ms));
-    }
-
-    try {
-      window.__PROBE_EVENT('SWITCH_LOOP_START');
-      for (let i = 1; i <= ROUND_TRIPS; i++) {
-        window.__PROBE_EVENT('AWAY_' + i);
-        const awayResult = window.__clickTabByKey(AWAY_KEY);
-        window.__PROBE_EVENT('AWAY_' + i + '_RES:' + awayResult.slice(0, 50));
-        await sleep(DWELL_MS);
-
-        window.__PROBE_EVENT('BACK_' + i);
-        const backResult = window.__clickTabByKey(BACK_KEY);
-        window.__PROBE_EVENT('BACK_' + i + '_RES:' + backResult.slice(0, 50));
-        await sleep(DWELL_MS);
-      }
-      window.__PROBE_EVENT('SWITCH_LOOP_DONE');
-    } finally {
-      window.__SWITCH_LOOP_RUNNING = false;
-    }
-  })();
-
-  return 'switch loop kicked off (BACK=' + BACK_KEY + ', AWAY=' + AWAY_KEY + ')';
-})();

.agents/skills/local-testing/scripts/agent-gateway/types.ts

@@ -1,113 +0,0 @@
-// Shared types between the in-browser probe and the Node-side analyzer.
-// Kept tiny on purpose — anything the analyzer can re-derive is left off.
-
-export interface ProbeStreamEvent {
-  /** Summarized payload — long strings truncated, arrays printed as Array(N) */
-  data?: Record<string, unknown>;
-  /** Keys present on the event's `data` payload — useful at a glance */
-  dataKeys?: string[];
-  /** ServerMessage.id — gateway WS frames carry an event-id we may resume from */
-  eventId?: string | null;
-  message?: string;
-  /** Last 10 chars of the operationId (full id is excessively long) */
-  opIdTail: string;
-  raw?: string;
-  /** Raw frame byte length, when applicable */
-  rawLen?: number;
-  /** For non-agent_event server frames (auth_success, heartbeat_ack, …) */
-  serverType?: string;
-  sseEvent?: string;
-  status?: number;
-  stepIndex?: number;
-  /** Milliseconds since the probe's t0 (install time). */
-  t: number;
-  /** 'ws' for gateway WebSocket frames, 'sse' for direct /api/agent/stream */
-  transport: 'ws' | 'sse';
-  /** Either the AgentStreamEvent.type, or a probe sentinel like `_WS_OPEN_` */
-  type: string;
-  url?: string;
-}
-
-export interface ProbeActionCall {
-  args?: {
-    count?: number;
-    context?: unknown;
-    params?: unknown;
-  };
-  error?: string;
-  /** `replaceMessages` / `refreshMessages` / `MARK:<label>` / `_WRAP_ERROR_` */
-  name: string;
-  stack?: string;
-  t: number;
-}
-
-export interface ProbeMessageSummary {
-  /** children.length */
-  chN: number;
-  /** content.length */
-  cLen: number;
-  /** Last 8 chars of the message id */
-  id: string;
-  /** reasoning.content.length */
-  rLen: number;
-  role: string;
-  /** tools.length */
-  tools: number;
-}
-
-export interface ProbeTimelineSample {
-  /** Last 10 chars of activeTopicId, or null */
-  activeTopic: string | null;
-  /** Per-key breakdown: display count, db count, message summaries */
-  byKey: Record<
-    string,
-    {
-      n: number;
-      dbN: number;
-      msgs: ProbeMessageSummary[];
-    }
-  >;
-  err?: string;
-  /** All messagesMap keys that have content at this moment */
-  keys: string[];
-  /** Number of operations in 'running' status */
-  runOps: number;
-  t: number;
-}
-
-export interface ProbeDumpMeta {
-  callCount: number;
-  /** Date.now() at dump call */
-  collectedAt: number;
-  eventCount: number;
-  sampleCount: number;
-  /** Date.now() at probe install */
-  t0: number;
-}
-
-export interface ProbeDump {
-  actionCalls: ProbeActionCall[];
-  meta: ProbeDumpMeta;
-  streamEvents: ProbeStreamEvent[];
-  timeline: ProbeTimelineSample[];
-}
-
-/**
- * Globals the probe attaches to `window`. Keeps `as any` casts at the boundary
- * instead of sprinkling them through the probe body.
- */
-declare global {
-  interface Window {
-    __clickTabByKey?: (key: string) => string;
-    __listTabs?: () => Array<{ i: number; key: string | null; active: boolean; title: string }>;
-    __LOBE_STORES?: Record<string, () => any>;
-    __PROBE_ACTION_CALLS?: ProbeActionCall[];
-    __PROBE_EVENT?: (label: string) => void;
-    __PROBE_MSG_TIMELINE?: ProbeTimelineSample[];
-    __PROBE_ORIG_FETCH?: typeof fetch;
-    __PROBE_ORIG_WEBSOCKET?: typeof WebSocket;
-    __PROBE_STREAM_EVENTS?: ProbeStreamEvent[];
-    __PROBE_T0?: number;
-    __PROBE_TIMELINE_TIMER?: ReturnType<typeof setInterval> | null;
-  }
-}

.agents/skills/local-testing/scripts/electron-dev.sh

@@ -76,9 +76,7 @@ find_project_pids() {
   port_pid=$(lsof -ti tcp:"$CDP_PORT" -sTCP:LISTEN 2>/dev/null || true)
   pids="$pids $port_pid"
 
-  # `|| true` because `grep -v '^$'` exits 1 when input has no non-empty
-  # lines, which (with pipefail + set -e) silently kills the caller.
-  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true
+  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' '
 }
 
 # Wait for the CDP HTTP endpoint to respond, with a deadline + early bail-out
@@ -148,7 +146,7 @@ do_stop() {
   for pid in $seed_pids; do
     all_pids="$all_pids $(expand_descendants "$pid")"
   done
-  all_pids=$(echo "$all_pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true)
+  all_pids=$(echo "$all_pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ')
 
   if [ -z "$all_pids" ]; then
     echo "[electron-dev] No project Electron/vite processes found."
@@ -272,17 +270,10 @@ do_start() {
   # Launch in a new session (setsid) so the whole process tree shares a PGID
   # we can later signal in one shot. `setsid bash -c '... exec ...' &` keeps
   # the bash shell as the session leader; its PID is what we save.
-  # macOS doesn't ship setsid by default — fall back to plain bash; cleanup
-  # still works via `expand_descendants` walking the process tree.
-  local launch_cmd="
+  setsid bash -c "
     cd '$PROJECT_ROOT/apps/desktop'
     exec npx electron-vite dev -- --remote-debugging-port=$CDP_PORT
-  "
-  if command -v setsid >/dev/null 2>&1; then
-    setsid bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
-  else
-    bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
-  fi
+  " >> "$ELECTRON_LOG" 2>&1 < /dev/null &
   local launcher_pid=$!
   echo "$launcher_pid" > "$PIDFILE"
   echo "[electron-dev] Launcher PID (session leader): $launcher_pid"

.agents/skills/local-testing/scripts/test-discord-bot.sh

@@ -60,5 +60,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/scripts/test-lark-bot.sh

@@ -80,5 +80,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/scripts/test-qq-bot.sh

@@ -72,5 +72,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/scripts/test-slack-bot.sh

@@ -60,5 +60,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/scripts/test-telegram-bot.sh

@@ -75,5 +75,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/scripts/test-wechat-bot.sh

@@ -81,5 +81,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/microcopy/SKILL.md

@@ -1,16 +1,10 @@
 ---
 name: microcopy
-description: 'UI copy and microcopy guidelines. Use for user-facing copy, buttons, errors, empty states, onboarding, i18n wording, translation, or copy improvements in Chinese or English.'
-user-invocable: false
+description: UI copy and microcopy guidelines. Use when writing UI text, buttons, error messages, empty states, onboarding, or any user-facing copy. Triggers on i18n translation, UI text writing, or copy improvement tasks. Supports both Chinese and English.
 ---
 
 # LobeHub UI Microcopy Guidelines
 
-This file is the quick-reference summary. For full prompt-style guidelines with extensive examples (anti-patterns, tone matrices, scenario walk-throughs), load the language-specific reference:
-
-- **中文文案** — [`references/zh.md`](./references/zh.md)
-- **English copy** — [`references/en.md`](./references/en.md)
-
 Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not just "generation".
 
 ## Fixed Terminology

.agents/skills/modal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modal
-description: 'LobeHub imperative modal conventions. Use when creating or migrating modals, dialogs, popups, confirm flows, ModalHost wiring, createModal, confirmModal, useModalContext, or base-ui modal APIs.'
+description: MUST use when creating, editing, or writing modal dialogs or imperative modals. Prefer createModal / useModalContext / confirmModal from @lobehub/ui/base-ui; root @lobehub/ui is legacy (antd Modal). Covers patterns, ModalHost, and migration notes.
 user-invocable: false
 ---
 

.agents/skills/pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr
-description: "Create a PR for the current branch (targets `canary` by default), including splitting one cross-layer branch into ordered stacked PRs so a lower layer (db / shared package / server TRPC) merges before its callers (desktop / CLI / UI). Use when the user asks to create / submit a PR, or to split a branch because clients call a server contract that isn't on the trunk yet. Triggers on 'pr', 'create pr', 'submit pr', 'open a PR', 'pull request', 'split this PR', 'stacked PR', 'backend should merge first', '提 PR', '提个 PR', '新建 PR', '拆 PR', '后端先合', '分层合并'."
+description: "Create a PR for the current branch. Use when the user asks to create a pull request, submit PR, or says 'pr'."
 user-invocable: true
 ---
 
@@ -71,82 +71,3 @@ Use `.github/PULL_REQUEST_TEMPLATE.md` as the body structure. Key sections:
 
 - **Language**: All PR content must be in English
 - If a PR already exists for the branch, inform the user instead of creating a duplicate
-
----
-
-# Stacked PRs (cross-layer feature)
-
-The steps above create **one** PR for the current branch. When a single branch lands across layers — `packages/database` schema/model → a shared `packages/*` lib → `src/server` TRPC → `apps/desktop` + `apps/cli` callers → `src/features` UI — shipping it as one PR can't merge safely: the clients call an endpoint that doesn't exist on the trunk until the same PR merges, so any partial/rollback or independent review breaks. Split it into **ordered PRs**, lower layer first.
-
-## The ordering rule
-
-A PR may only merge **after** every layer it calls is already on the trunk.
-
-- The **server contract** (new TRPC procedure, changed return shape, new table/model) merges first.
-- The **callers** (desktop, CLI, UI) merge after — they invoke that contract.
-- Tie-break with one question: _"if this merged alone to `canary` right now, would it build and behave?"_ If no, it belongs in a later PR.
-
-## Which file goes in which PR
-
-The non-obvious calls:
-
-- **Frontend that adapts to a contract change goes WITH the server PR.** If you widen a TRPC return shape (e.g. `listDevices` now returns `platform: string | null`), the component consuming it must change in the _same_ PR — otherwise the server PR breaks the build on its own. Contract + its in-repo consumers ship together.
-- **A new shared package goes with its consumer**, not the server, unless the server imports it too. A `@lobechat/*` package imported only by desktop/CLI ships in the client PR. Don't carry an unused package in the lower PR.
-- **Workspace dep declarations** (`package.json` `workspace:*`, `pnpm-workspace.yaml`) travel with the code that imports the package.
-
-## The git recipe — split an existing full branch
-
-Starting point: one branch (`feat/x`) with a single commit `<FULL>` containing everything, already pushed (so it's also safe on the remote).
-
-```bash
-# 1. Safety nets — make the full work unloseable before rewriting anything
-git branch backup/x-full <FULL>          # local ref to the full commit
-git branch feat/x-clients <FULL>         # the higher-layer branch starts here
-
-# 2. Rewrite the lower-layer branch to lower-layer files only
-git checkout feat/x                      # this becomes the SERVER PR
-git reset --hard origin/canary
-git checkout <FULL> -- <server/db files…>   # stages just those paths
-git commit -m "✨ feat(...): <server half>"
-git push --force-with-lease origin feat/x   # never --force; never push to canary
-
-# 3. Build the higher-layer branch STACKED on the lower branch
-git checkout feat/x-clients
-git reset --hard feat/x                  # base = the just-rewritten server HEAD
-git checkout backup/x-full -- <client/ui files…>   # only the remaining paths
-git commit -m "✨ feat(...): <client half>"
-git push -u origin feat/x-clients
-```
-
-Then open the higher PR **based on the lower branch**, not the trunk:
-
-```bash
-gh pr create --base feat/x --head feat/x-clients --title "…" --body "…"
-```
-
-`--base feat/x` keeps the diff client-only (no server files leak in) and makes it physically impossible to merge the clients before the server. **After the server PR merges to `canary`, retarget the client PR's base to `canary`** (GitHub usually auto-retargets when the base branch merges; note it in the PR body so a human confirms).
-
-## Verify the dependency actually holds
-
-The whole point is the higher layer needs the lower one. Prove it: on the stacked higher branch, type-check the caller and confirm the symbol the lower layer introduced resolves.
-
-```bash
-cd apps/cli && bun run type-check 2>&1 | grep -iE "connect\.ts|device\.register"
-# empty (re: your change) = the stacked base supplies device.register ✓
-```
-
-Filter to your touched files — this repo's standalone type-check emits pre-existing env noise (`__ELECTRON__`, `@/types/llm`, unbuilt `@lobechat/types`) that isn't yours.
-
-## PR + Linear bookkeeping
-
-- **Each PR closes only its own layer's issues.** Server PR: `Closes LOBE-<server>`. Client PR: `Closes LOBE-<pkg> / <desktop> / <cli>`. Don't let one PR's body claim another layer's issue.
-- Both PRs are `Part of LOBE-<parent>`.
-- On PR creation, move each closed sub-issue to **In Review** (not Done) and add a completion comment — see the `linear` skill.
-
-## Gotchas
-
-- **Never push to `canary`.** A split branch cut with `git checkout -b feat/x origin/canary` _tracks_ `origin/canary`, so a bare `git push` targets canary. Always `git push origin feat/x` with the explicit branch name.
-- **`--force-with-lease`, not `--force`** when rewriting the lower branch — it aborts if the remote moved under you.
-- **Back up before `reset --hard`.** Step 1's `backup/x-full` + the pushed remote branch mean the full commit is referenced by ≥3 refs before you rewrite anything. Verify with `git branch --contains <FULL>`.
-- **Lockfiles:** this monorepo commits no root `pnpm-lock.yaml`, so a new `workspace:*` dep needs no lockfile churn. In a repo that _does_ commit one, regenerate it on each branch after the split.
-- **Don't over-split.** Two PRs (contract / callers) is usually enough. A UI page that only reads an existing endpoint can be its own later PR, but don't fragment a single layer across PRs for its own sake.

.agents/skills/project-overview/SKILL.md

@@ -1,25 +1,19 @@
 ---
 name: project-overview
-description: 'LobeHub open-source monorepo architecture map. Use when locating code layers, understanding apps/packages/src layout, business stubs, project structure, or onboarding to the repository.'
-user-invocable: false
+description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
 ---
 
 # LobeHub Project Overview
 
-> The directory listings below are a **curated map of key locations**, not an
-> exhaustive tree. `packages/`, `src/store/`, route groups etc. grow over time —
-> run `ls` against the real directory for the current set.
-
 ## Project Description
 
 Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
-This repo is the **open-source root** (`github.com/lobehub/lobehub`, package `@lobehub/lobehub`).
 
 **Supported platforms:**
 
 - Web desktop/mobile
-- Desktop (Electron) — `apps/desktop`
-- Mobile app (React Native) — **separate repo, already launched** (not in this monorepo)
+- Desktop (Electron)
+- Mobile app (React Native) - coming soon
 
 **Logo emoji:** 🤯
 
@@ -44,49 +38,123 @@ This repo is the **open-source root** (`github.com/lobehub/lobehub`, package `@l
 | Database      | Neon PostgreSQL + Drizzle ORM              |
 | Testing       | Vitest                                     |
 
-> Exact versions live in the root `package.json` — check there, not here.
+## Complete Project Structure
 
-## Monorepo Layout
-
-Flat layout — `apps/`, `packages/`, and `src/` all sit at the repo root. No
-git submodules.
+Monorepo using `@lobechat/` namespace for workspace packages.
 
 ```
-(repo root)
+lobehub/
 ├── apps/
-│   ├── cli/                  # LobeHub CLI
-│   ├── desktop/              # Electron desktop app
-│   └── device-gateway/       # Device gateway service
-├── docs/                     # changelog, development, self-hosting, usage
-├── locales/                  # en-US, zh-CN, ...
-├── packages/                 # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
-│   ├── agent-runtime/        # Agent runtime core
-│   ├── agent-signal/         # Agent Signal pipeline
-│   ├── agent-tracing/        # Tracing / snapshots
-│   ├── builtin-tool-*/       # Per-tool packages (calculator, web-browsing, claude-code, ...)
-│   ├── builtin-tools/        # Central registries that compose builtin-tool-*
+│   └── desktop/                 # Electron desktop app
+├── docs/
+│   ├── changelog/
+│   ├── development/
+│   ├── self-hosting/
+│   └── usage/
+├── locales/
+│   ├── en-US/
+│   └── zh-CN/
+├── packages/
+│   ├── agent-runtime/           # Agent runtime
+│   ├── builtin-agents/
+│   ├── builtin-tool-*/          # Builtin tool packages
+│   ├── business/                # Cloud-only business logic
+│   │   ├── config/
+│   │   ├── const/
+│   │   └── model-runtime/
+│   ├── config/
+│   ├── const/
 │   ├── context-engine/
-│   ├── database/             # src/{models,schemas,repositories}
-│   ├── model-bank/           # Model definitions & provider cards
-│   ├── model-runtime/        # src/{core,providers}
-│   ├── business/             # Open-source stubs (config, const, model-bank, model-runtime) — overridden by cloud
+│   ├── conversation-flow/
+│   ├── database/
+│   │   └── src/
+│   │       ├── models/
+│   │       ├── schemas/
+│   │       └── repositories/
+│   ├── desktop-bridge/
+│   ├── edge-config/
+│   ├── editor-runtime/
+│   ├── electron-client-ipc/
+│   ├── electron-server-ipc/
+│   ├── fetch-sse/
+│   ├── file-loaders/
+│   ├── memory-user-memory/
+│   ├── model-bank/
+│   ├── model-runtime/
+│   │   └── src/
+│   │       ├── core/
+│   │       └── providers/
+│   ├── observability-otel/
+│   ├── prompts/
+│   ├── python-interpreter/
+│   ├── ssrf-safe-fetch/
+│   ├── types/
+│   ├── utils/
+│   └── web-crawler/
+├── src/
+│   ├── app/
+│   │   ├── (backend)/
+│   │   │   ├── api/
+│   │   │   ├── f/
+│   │   │   ├── market/
+│   │   │   ├── middleware/
+│   │   │   ├── oidc/
+│   │   │   ├── trpc/
+│   │   │   └── webapi/
+│   │   ├── spa/                  # SPA HTML template service
+│   │   └── [variants]/
+│   │       └── (auth)/           # Auth pages (SSR required)
+│   ├── routes/                  # SPA page components (Vite)
+│   │   ├── (main)/
+│   │   ├── (mobile)/
+│   │   ├── (desktop)/
+│   │   ├── onboarding/
+│   │   └── share/
+│   ├── spa/                     # SPA entry points and router config
+│   │   ├── entry.web.tsx
+│   │   ├── entry.mobile.tsx
+│   │   ├── entry.desktop.tsx
+│   │   └── router/
+│   ├── business/                # Cloud-only (client/server)
+│   │   ├── client/
+│   │   ├── locales/
+│   │   └── server/
+│   ├── components/
+│   ├── config/
+│   ├── const/
+│   ├── envs/
+│   ├── features/
+│   ├── helpers/
+│   ├── hooks/
+│   ├── layout/
+│   │   ├── AuthProvider/
+│   │   └── GlobalProvider/
+│   ├── libs/
+│   │   ├── better-auth/
+│   │   ├── oidc-provider/
+│   │   └── trpc/
+│   ├── locales/
+│   │   └── default/
+│   ├── server/
+│   │   ├── featureFlags/
+│   │   ├── globalConfig/
+│   │   ├── modules/
+│   │   ├── routers/
+│   │   │   ├── async/
+│   │   │   ├── lambda/
+│   │   │   ├── mobile/
+│   │   │   └── tools/
+│   │   └── services/
+│   ├── services/
+│   ├── store/
+│   │   ├── agent/
+│   │   ├── chat/
+│   │   └── user/
+│   ├── styles/
+│   ├── tools/
 │   ├── types/
 │   └── utils/
-└── src/
-    ├── app/
-    │   ├── (backend)/        # api, f, market, middleware, oidc, trpc, webapi
-    │   ├── spa/              # SPA HTML template service
-    │   └── [variants]/(auth)/ # Auth pages (SSR required)
-    ├── routes/               # SPA page segments (thin — delegate to features/)
-    │   └── (main)/ (mobile)/ (desktop)/ (popup)/ onboarding/ share/
-    ├── spa/                  # SPA entries + router config
-    │   ├── entry.{web,mobile,desktop,popup}.tsx
-    │   └── router/
-    ├── business/             # Open-source stubs (client/server) — cloud repo provides real impls
-    ├── features/             # Domain business components
-    ├── store/                # ~30 zustand stores — `ls` for the full set
-    ├── server/               # featureFlags, globalConfig, modules, routers, services, workflows, agent-hono
-    └── ...                   # components, hooks, layout, libs, locales, services, types, utils
+└── e2e/                         # E2E tests (Cucumber + Playwright)
 ```
 
 ## Architecture Map
@@ -109,27 +177,11 @@ git submodules.
 | DB Model         | `packages/database/src/models`                      |
 | DB Repository    | `packages/database/src/repositories`                |
 | Third-party      | `src/libs` (analytics, oidc, etc.)                  |
-| Builtin Tools    | `packages/builtin-tool-*`, `packages/builtin-tools` |
-| Open-source stub | `src/business/*`, `packages/business/*` (this repo) |
+| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`              |
+| Cloud-only       | `src/business/*`, `packages/business/*`             |
 
 ## Data Flow
 
 ```
 React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
 ```
-
-## Note: Relationship to the Cloud Repo
-
-This open-source repo is consumed by a **separate, private cloud (SaaS) repo**
-as a git submodule mounted at `lobehub/`. The cloud repo provides:
-
-- **`src/business/{client,server}`** and **`packages/business/*`** implementations
-  that override the stubs shipped here.
-- Cloud-only routes (e.g. `(cloud)/`, `embed/`), cloud-only stores (e.g.
-  `subscription/`), cloud-only TRPC routers (billing, budget, risk control, …),
-  and Vercel cron routes under `src/app/(backend)/cron/`.
-- File-resolution order in cloud: `@/store/x` → cloud `src/store/x` first, then
-  `lobehub/packages/store/src/x`, then `lobehub/src/store/x`. **Cloud override wins.**
-
-When working in this repo alone, ignore the cloud layer — the stubs in
-`src/business/` and `packages/business/` are the source of truth here.

.agents/skills/react/SKILL.md

@@ -1,122 +1,94 @@
 ---
 name: react
-description: 'LobeHub React component conventions. Use when editing TSX UI, choosing base-ui vs @lobehub/ui vs antd, styling with antd-style, routing, desktop variants, layouts, or component state.'
-user-invocable: false
+description: React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.
 ---
 
 # React Component Writing Guide
 
-## Styling
+- Use antd-style for complex styles; for simple cases, use inline `style` attribute
+  - **Prefer `createStaticStyles` with `cssVar.*`** (zero-runtime) — module-level, no hook call required
+  - Only fall back to `createStyles` + `token` when styles genuinely need runtime computation (dynamic props, JS color fns like `readableColor`/`chroma`)
+  - See `.cursor/docs/createStaticStyles_migration_guide.md` for full pattern
+- Use `Flexbox` and `Center` from `@lobehub/ui` for layouts (see `references/layout-kit.md`)
+- Component priority: `src/components` > `@lobehub/ui/base-ui` > `@lobehub/ui` > custom implementation
+  - Always prefer `@lobehub/ui/base-ui` primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…) over antd equivalents
+  - Fall back to `@lobehub/ui` higher-level components when base-ui has no match
+  - Only implement a custom component as a last resort — never reach for antd directly
+- Use selectors to access zustand store data
 
-| Scenario                                                   | Approach                                                       |
-| ---------------------------------------------------------- | -------------------------------------------------------------- |
-| Most cases                                                 | `createStaticStyles` + `cssVar.*` (zero-runtime, module-level) |
-| Simple one-off                                             | Inline `style` attribute                                       |
-| Truly dynamic (JS color fns like `readableColor`/`chroma`) | `createStyles` + `token` — **last resort**                     |
+## @lobehub/ui Components
 
-## Component Priority
+If unsure about component usage, search existing code in this project. Most components extend antd with additional props.
 
-1. **`src/components`** — project-specific reusable components
-2. **`@lobehub/ui/base-ui`** — headless primitives. **If the component lives here, use it. Do NOT import the same-named root export.**
-3. **`@lobehub/ui`** — higher-level / antd-wrapping components (only when no base-ui equivalent)
-4. **antd** — only when neither base-ui nor `@lobehub/ui` root provides it
-5. **Custom implementation** — true last resort
+Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
 
-If unsure about available components, search existing code or check `node_modules/@lobehub/ui/es/index.mjs` and `node_modules/@lobehub/ui/es/base-ui/`.
+**Common Components:**
 
-### `@lobehub/ui/base-ui` — always prefer for these
-
-| Component                                  | Import                                                                                                  |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `Select` (+ `SelectProps`, `SelectOption`) | `import { Select } from '@lobehub/ui/base-ui';`                                                         |
-| `Modal` (imperative API)                   | `import { createModal, confirmModal, useModalContext, type ModalInstance } from '@lobehub/ui/base-ui';` |
-| `DropdownMenu`                             | `import { DropdownMenu } from '@lobehub/ui/base-ui';`                                                   |
-| `ContextMenu`                              | `import { ContextMenu } from '@lobehub/ui/base-ui';`                                                    |
-| `Popover`                                  | `import { Popover } from '@lobehub/ui/base-ui';`                                                        |
-| `ScrollArea`                               | `import { ScrollArea } from '@lobehub/ui/base-ui';`                                                     |
-| `Switch`                                   | `import { Switch } from '@lobehub/ui/base-ui';`                                                         |
-| `Toast`                                    | `import { Toast } from '@lobehub/ui/base-ui';`                                                          |
-| `FloatingSheet`                            | `import { FloatingSheet } from '@lobehub/ui/base-ui';`                                                  |
-
-For Modal specifically, see the dedicated **modal** skill — use the imperative `createModal({ content: … })` pattern over the legacy `<Modal open … />` declarative pattern. base-ui has its own `ModalHost` already mounted in `SPAGlobalProvider`.
-
-> Common slip: `import { Select } from '@lobehub/ui'` looks fine but it's the antd-backed Select. Use base-ui Select. Same for `Modal`, `DropdownMenu`, etc.
-
-### `@lobehub/ui` root — use when base-ui has no equivalent
-
-| Category     | Components                                                                            |
-| ------------ | ------------------------------------------------------------------------------------- |
-| General      | ActionIcon, ActionIconGroup, Block, Button, Icon                                      |
-| Data Display | Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip                          |
-| Data Entry   | CodeEditor, CopyButton, EditableText, Form, Input, InputPassword, SearchBar, TextArea |
-| Feedback     | Alert, Drawer                                                                         |
-| Layout       | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow                             |
-| Navigation   | Burger, Menu, SideNav, Tabs                                                           |
-
-## State
-
-When a feature component manages more than 3 pieces of state (`useState`/`useReducer`/derived state), extract the logic into a custom hook (e.g. `useXxx`). Keep the component focused on rendering — the hook holds state and handlers, so logic can be unit-tested without rendering the component.
-
-## Layout
-
-Use `Flexbox` and `Center` from `@lobehub/ui`. See `references/layout-kit.md` for full props and examples.
-
-- Use `gap` instead of `margin` for spacing between flex children
-- Use `flex={1}` to fill available space
-- Nest Flexbox for complex layouts; set `overflow: 'auto'` for scrollable regions
-
-## Navigation
-
-**For SPA pages, use `react-router-dom`, NOT `next/link`.**
-
-```tsx
-// ❌ Wrong
-import Link from 'next/link';
-
-// ✅ Correct
-import { Link, useNavigate } from 'react-router-dom';
-```
-
-Access navigate from stores: `useGlobalStore.getState().navigate?.('/settings');`
-
-## Desktop File Sync Rule
-
-Files with a `.desktop.ts(x)` variant must be edited **in sync**. Drift causes blank pages in Electron.
-
-| Base file (web)            | Desktop file (Electron)            |
-| -------------------------- | ---------------------------------- |
-| `desktopRouter.config.tsx` | `desktopRouter.config.desktop.tsx` |
-| `componentMap.ts`          | `componentMap.desktop.ts`          |
-
-**After editing any `.ts`/`.tsx`:** glob for `<filename>.desktop.{ts,tsx}` in the same directory. If found, apply the equivalent sync-import change.
+- General: ActionIcon, ActionIconGroup, Block, Button, Icon
+- Data Display: Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
+- Data Entry: CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select
+- Feedback: Alert, Drawer, Modal
+- Layout: Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow
+- Navigation: Burger, Dropdown, Menu, SideNav, Tabs
 
 ## Routing Architecture
 
-| Route Type         | Use Case   | Implementation                                     |
-| ------------------ | ---------- | -------------------------------------------------- |
-| Next.js App Router | Auth pages | `src/app/[variants]/(auth)/`                       |
-| React Router DOM   | Main SPA   | `desktopRouter.config.tsx` + `.desktop.tsx` (pair) |
+Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).
 
-Router utilities:
+| Route Type         | Use Case                          | Implementation                                                               |
+| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
+| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/`                                                 |
+| React Router DOM   | Main SPA (chat, settings)         | `desktopRouter.config.tsx` + `desktopRouter.config.desktop.tsx` (must match) |
+
+### Key Files
+
+- Entry: `src/spa/entry.web.tsx` (web), `src/spa/entry.mobile.tsx`, `src/spa/entry.desktop.tsx`
+- Desktop router (pair — **always edit both** when changing routes): `src/spa/router/desktopRouter.config.tsx` (dynamic imports) and `src/spa/router/desktopRouter.config.desktop.tsx` (sync imports). Drift can cause unregistered routes / blank screen.
+- Mobile router: `src/spa/router/mobileRouter.config.tsx`
+- Router utilities: `src/utils/router.tsx`
+
+### `.desktop.{ts,tsx}` File Sync Rule
+
+**CRITICAL**: Some files have a `.desktop.ts(x)` variant that Electron uses instead of the base file. When editing a base file, **always check** if a `.desktop` counterpart exists and update it in sync. Drift causes blank pages or missing features in Electron.
+
+Known pairs that must stay in sync:
+
+| Base file (web, dynamic imports)                      | Desktop file (Electron, sync imports)                         |
+| ----------------------------------------------------- | ------------------------------------------------------------- |
+| `src/spa/router/desktopRouter.config.tsx`             | `src/spa/router/desktopRouter.config.desktop.tsx`             |
+| `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` |
+
+**How to check**: After editing any `.ts` / `.tsx` file, run `Glob` for `<filename>.desktop.{ts,tsx}` in the same directory. If a match exists, update it with the equivalent sync-import change.
+
+### Router Utilities
 
 ```tsx
 import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
+
 element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
 element: redirectElement('/settings/profile');
 errorElement: <ErrorBoundary />;
 ```
 
-## Common Mistakes
+### Navigation
 
-| Mistake                                                            | Fix                                                                         |
-| ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
-| Using `next/link` in SPA                                           | Use `react-router-dom` `Link`                                               |
-| Using antd directly                                                | Use `@lobehub/ui/base-ui` first, then `@lobehub/ui`                         |
-| `import { Select } from '@lobehub/ui'`                             | `import { Select } from '@lobehub/ui/base-ui'`                              |
-| `import { Modal } from '@lobehub/ui'` + `<Modal open>` declarative | `createModal` / `confirmModal` from `@lobehub/ui/base-ui` (see modal skill) |
-| `import { DropdownMenu/Popover/Switch } from '@lobehub/ui'`        | Import same name from `@lobehub/ui/base-ui` instead                         |
-| `createStyles` for static styles                                   | Use `createStaticStyles` + `cssVar`                                         |
-| Editing only `desktopRouter.config.tsx`                            | Must edit both `.tsx` and `.desktop.tsx`                                    |
-| Using `margin` for flex spacing                                    | Use `gap` prop on Flexbox                                                   |
-| Accessing zustand store without selector                           | Use selectors to access store data (see zustand skill)                      |
-| Text or icon-text actions built with `Flexbox`/`Text` + `onClick`  | Use `Button type={'text'} size={'small'}` with `icon` when needed           |
+**Important**: For SPA pages, use `Link` from `react-router-dom`, NOT `next/link`.
+
+```tsx
+// ❌ Wrong
+import Link from 'next/link';
+<Link href="/">Home</Link>;
+
+// ✅ Correct
+import { Link } from 'react-router-dom';
+<Link to="/">Home</Link>;
+
+// In components
+import { useNavigate } from 'react-router-dom';
+const navigate = useNavigate();
+navigate('/chat');
+
+// From stores
+const navigate = useGlobalStore.getState().navigate;
+navigate?.('/settings');
+```

.agents/skills/response-compliance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-compliance
-description: 'OpenResponses API compliance testing. Use for Response API endpoint tests, compliance runs, schema debugging, response api test, or openresponses test tasks.'
+description: OpenResponses API compliance testing. Use when testing the Response API endpoint, running compliance tests, or debugging Response API schema issues. Triggers on 'compliance', 'response api test', 'openresponses test'.
 ---
 
 # OpenResponses Compliance Test

.agents/skills/review-checklist/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: review-checklist
-description: 'LobeHub code review checklist. Use when reviewing a PR, diff, or branch for console leftovers, return await, secrets, i18n, desktop router drift, UI imports, migrations, or cloud impact.'
-user-invocable: false
+description: 'Common recurring mistakes in LobeHub code review — console leftovers, missing return await, hardcoded secrets, hardcoded i18n strings, desktop router pair drift, antd vs @lobehub/ui, non-idempotent migrations, cloud impact red flags. Use as a quick checklist when reviewing PRs, diffs, or branch changes.'
 ---
 
 # Review Checklist

.agents/skills/skills-audit/SKILL.md

@@ -1,142 +0,0 @@
----
-name: skills-audit
-description: 'Audit .agents/skills SKILL.md files. Use for recurring checks of duplicate, overlapping, stale, inconsistent, or broken skills and merge/delete candidates.'
-disable-model-invocation: true
-argument-hint: '[--verbose | --apply]'
----
-
-# Skills Audit
-
-Periodic review of the project-local skill set under `.agents/skills/`. The goal is to catch drift before the catalog becomes confusing — too many skills, overlapping triggers, descriptions that no longer match the body, references to skills that were renamed/deleted.
-
-**Recommended cadence:** weekly, or after any week where >1 skill was added/renamed.
-
-## Procedure
-
-### 1 — Inventory
-
-Build a fresh census of all SKILL.md files. Do NOT trust any prior cached list.
-
-```bash
-find .agents/skills -name SKILL.md | wc -l                      # total count
-find .agents/skills -name SKILL.md -exec wc -l {} \; | sort -rn # by body length
-```
-
-Group by domain in a mental table (DB / state / UI / agent / testing / workflow / docs / etc.). Note new arrivals since last audit (`git log --since="1 week ago" -- .agents/skills/`).
-
-### 2 — Pull frontmatter for all skills
-
-```bash
-# Extract name + description for each SKILL.md
-for f in .agents/skills/*/SKILL.md; do
-  echo "=== $(basename $(dirname $f)) ==="
-  awk '/^---$/{c++; next} c==1' "$f" | head -20
-done
-```
-
-Read the description block of every skill. The body can stay unread unless step 4 flags it.
-
-### 3 — Detect overlap / redundancy
-
-For each pair within the same domain, ask:
-
-- **Same description**? → likely duplicate (one is probably a stale rename leftover, or a global-vs-local collision).
-- **Trigger keywords substantially overlap**? → either merge, OR tighten one description so the model can choose unambiguously.
-- **One skill's body says "see also: foo"**? → confirm `foo` still exists, AND confirm the cross-reference is still meaningful (the referenced skill may have absorbed the referrer's concerns).
-- **Skill duplicates content from `AGENTS.md`**? → fold into AGENTS.md or slim the skill to just the delta.
-
-Common false positives (do NOT merge):
-
-- `db-migrations` vs `drizzle` — distinct workflows (migration files vs schema authoring).
-- `microcopy` vs `i18n` — content vs mechanics.
-- `agent-runtime-hooks` vs `agent-tracing` vs `agent-signal` — different surfaces of the agent system.
-- `testing` vs `local-testing` vs `cli-backend-testing` — different test types.
-
-### 4 — Description format consistency
-
-Apply the **standard template**:
-
-```
-{Topic + key conventions or scope}. Use when {scenarios — verbs + nouns}. Triggers on {`code-symbols`, 'natural phrases', '中文'}.
-```
-
-Skills with `disable-model-invocation: true` (user-invoked only, slash commands) don't need `Triggers on` — they're never auto-routed.
-
-Flag descriptions that:
-
-- ❌ Have NO `Use when` clause (model can't decide when to load it).
-- ❌ Have NO `Triggers on` clause (and aren't `disable-model-invocation`).
-- ❌ Use weird formats (numbered lists `(1)(2)(3)`, `Triggers:` colon instead of `Triggers on`, `MUST use when ...` as opening word).
-- ❌ Are dramatically terse for a 200+ line body, or dramatically verbose for a 60-line body.
-- ❌ Reference deleted/renamed skills.
-
-### 5 — Stale-skill check
-
-For narrow domain skills (e.g. `response-compliance`, one-off CLI workflows):
-
-```bash
-# Confirm the referenced code surface still exists
-rg -l "response-compliance|openresponses" packages/ src/              # adjust per skill
-git log --since="3 months ago" -- .agents/skills/ < skill > /SKILL.md # is it being maintained?
-```
-
-If the underlying surface is gone and the skill hasn't been edited in 3+ months → flag for archival.
-
-### 6 — Cross-reference integrity
-
-Any skill body mentioning another skill by name:
-
-```bash
-# Scan all skill bodies for skill-name references
-rg -o '`[a-z][a-z0-9-]+`' .agents/skills/*/SKILL.md | grep -v ':\s*$' | sort -u
-```
-
-For each name extracted, confirm `.agents/skills/<name>/SKILL.md` exists. Broken references happen after renames — fix them in the same audit pass.
-
-### 7 — Output report
-
-Produce a markdown summary back to the user with the same structure as the original audit (this skill was created during one):
-
-```markdown
-## 📊 Inventory
-
-{count, domain breakdown}
-
-## 🎯 Recommendations
-
-### 🔴 High confidence
-
-- {action} — {reason}
-
-### 🟡 Medium confidence
-
-- {action} — {reason needs verification}
-
-### 🟢 Low confidence / no-op
-
-- {item considered but skipping because ...}
-
-## 📋 Suggested order
-
-{table of actions with risk + LOC estimate}
-```
-
-End by asking the user which actions to apply — do NOT auto-apply unless the user passed `--apply` and even then confirm destructive deletes individually.
-
-## Output rules
-
-- Be specific. "Skill X overlaps with Y" is useless without naming the overlapping triggers.
-- Cite line numbers when flagging description / body issues.
-- Don't recommend merges unless the call sites would actually load the merged skill in the same context.
-- Don't recommend deletes for skills that haven't been touched recently — "unused" can mean "stable", not "dead".
-
-## What NOT to do
-
-- ❌ Don't rename skill directories without checking for cross-references AND user memory entries that name the old slug.
-- ❌ Don't normalize a description by removing trigger keywords just to fit the template — the keywords are the routing signal.
-- ❌ Don't fold a heavy 200+ line skill into another just because they share a domain — large skills get loaded selectively and merging makes everything load.
-- ❌ Don't propose `.agents/skills/INDEX.md` or `<domain>-<skill>` prefix renames unless the user explicitly asks — costs > benefits for cosmetic reorgs.
-
-## Related history
-
-- First audit: `chore/skills-audit` branch (2026-05-25) — deleted `source-command-dedupe`, renamed `data-fetching` → `data-fetching-architecture`, normalized 9 descriptions, created this skill.

.agents/skills/source-command-dedupe/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: 'source-command-dedupe'
+description: 'Find duplicate GitHub issues'
+---
+
+# source-command-dedupe
+
+Use this skill when the user asks to run the migrated source command `dedupe`.
+
+## Command Template
+
+Find up to 3 likely duplicate issues for a given GitHub issue.
+
+To do this, follow these steps precisely:
+
+1. Use an agent to check if the Github issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.
+2. Use an agent to view a Github issue, and ask the agent to return a summary of the issue
+3. Then, launch 5 parallel agents to search Github for duplicates of this issue, using diverse keywords and search approaches, using the summary from #1
+4. Next, feed the results from #1 and #2 into another agent, so that it can filter out false positives, that are likely not actually duplicates of the original issue. If there are no duplicates remaining, do not proceed.
+5. Finally, comment back on the issue with a list of up to three duplicate issues (or zero, if there are no likely duplicates)
+
+Notes (be sure to tell this to your agents, too):
+
+- Use `gh` to interact with Github, rather than web fetch
+- Do not use other tools, beyond `gh` (eg. don't use other MCP servers, file edit, etc.)
+- Make a todo list first
+- For your comment, follow the following format precisely (assuming for this example that you found 3 suspected duplicates):
+
+---
+
+Found 3 possible duplicate issues:
+
+1. <link to issue>
+2. <link to issue>
+3. <link to issue>
+
+This issue will be automatically closed as a duplicate in 3 days.
+
+- If your issue is a duplicate, please close it and 👍 the existing issue instead
+- To prevent auto-closure, add a comment or 👎 this comment
+
+> 🤖 Generated with Codex
+
+---

.agents/skills/spa-routes/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: spa-routes
-description: 'LobeHub SPA route architecture. Use when editing src/routes, src/features delegation, desktop/mobile/popup router configs, .desktop variants, route segments, redirects, or new pages.'
-user-invocable: false
+description: MUST use when editing src/routes/ segments, src/spa/router/desktopRouter.config.tsx or desktopRouter.config.desktop.tsx (always change both together), mobileRouter.config.tsx, or when moving UI/logic between routes and src/features/.
 ---
 
 # SPA Routes and Features Guide
@@ -85,36 +84,15 @@ Each feature should:
 
 ## 3a. Desktop router pair (`desktopRouter.config` × 2)
 
-| File                               | Role                                                                                                                      |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `desktopRouter.config.tsx`         | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
-| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling.                 |
+| File | Role |
+|------|------|
+| `desktopRouter.config.tsx` | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
+| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling. |
 
 Anything that changes the tree (new segment, renamed `path`, moved layout, new child route) must be reflected in **both** files in one PR or commit. Remove routes from both when deleting.
 
 ---
 
-## 3b. Other `.desktop.{ts,tsx}` variants inside `src/routes/`
-
-The router pair is **not** the only `.desktop` variant pattern in this repo. Some route trees colocate a `<name>.desktop.{ts,tsx}` next to its base `<name>.{ts,tsx}` — Vite's resolver swaps in the `.desktop` file for Electron builds. Same drift risk as the router pair: editing only one side can break Electron silently.
-
-Known variants today:
-
-| Base file (web)                                       | Desktop file (Electron)                                       | Purpose                                                                                                                                    |
-| ----------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` | Settings tab → component map. Web uses dynamic `import()`; desktop uses sync imports. `componentMap.sync.test.ts` enforces identical keys. |
-| `src/routes/(main)/agent/index.tsx`                   | `src/routes/(main)/agent/index.desktop.tsx`                   | Page entry. Desktop variant overrides the web page wholesale (e.g. extra popup guards).                                                    |
-| `src/routes/(main)/group/index.tsx`                   | `src/routes/(main)/group/index.desktop.tsx`                   | Same pattern as agent.                                                                                                                     |
-
-**Rules:**
-
-1. After editing **any** `.ts`/`.tsx` under `src/routes/`, glob the same directory for a `<filename>.desktop.{ts,tsx}` sibling. If one exists, apply the equivalent change there in the same commit.
-2. When adding a new SettingsTab, register it in **both** `componentMap.ts` (with `dynamic(...)`) and `componentMap.desktop.ts` (with a sync `import`). `componentMap.sync.test.ts` will fail the build otherwise.
-3. When adding a new desktop-only page wholesale-override, prefer a single base file with platform-aware code over introducing a new `.desktop.tsx` variant — only add a new variant when the two trees genuinely diverge (different store wiring, different popup guards, etc.).
-4. When deleting, remove **both** files together.
-
----
-
 ## 4. How to Divide Files (route vs feature)
 
 | Question                                                 | Put in `src/routes/`                                     | Put in `src/features/`       |

.agents/skills/store-data-structures/SKILL.md

@@ -1,91 +1,257 @@
 ---
 name: store-data-structures
-description: 'LobeHub Zustand store data-shape patterns. Use when designing store state, list/detail splits, normalized maps, reducers, messagesMap, topicsMap, or choosing shared type sources.'
-user-invocable: false
+description: Zustand store data structure patterns for LobeHub. Covers List vs Detail data structures, Map + Reducer patterns, type definitions, and when to use each pattern. Use when designing store state, choosing data structures, or implementing list/detail pages.
 ---
 
 # LobeHub Store Data Structures
 
-How to structure data in Zustand stores for fast list rendering, multi-detail caching, and ergonomic optimistic updates.
+This guide covers how to structure data in Zustand stores for optimal performance and user experience.
 
 ## Core Principles
 
 ### ✅ DO
 
-1. **Separate List and Detail** — different structures for list pages and detail pages
-2. **Use Map for Details** — cache multiple detail pages with `Record<string, Detail>`
-3. **Use Array for Lists** — simple arrays for list display
-4. **Types from `@lobechat/types`** — never use `@lobechat/database` types in stores
-5. **Distinguish List and Detail types** — List types may have computed UI fields
+1. **Separate List and Detail** - Use different structures for list pages and detail pages
+2. **Use Map for Details** - Cache multiple detail pages with `Record<string, Detail>`
+3. **Use Array for Lists** - Simple arrays for list display
+4. **Types from @lobechat/types** - Never use `@lobechat/database` types in stores
+5. **Distinguish List and Detail types** - List types may have computed UI fields
 
 ### ❌ DON'T
 
-1. **Don't use a single detail object** — can't cache multiple pages
-2. **Don't mix List and Detail types** — they have different purposes
-3. **Don't use database types** — use types from `@lobechat/types`
-4. **Don't use Map for lists** — simple arrays are sufficient
+1. **Don't use single detail object** - Can't cache multiple pages
+2. **Don't mix List and Detail types** - They have different purposes
+3. **Don't use database types** - Use types from `@lobechat/types`
+4. **Don't use Map for lists** - Simple arrays are sufficient
 
 ---
 
 ## Type Definitions
 
-Each entity gets its own file under `@lobechat/types/`. Each file exports two types:
+Types should be organized by entity in separate files:
 
-- **Detail type** — full entity, including heavy fields (rubrics, content, editor state, …)
-- **List item type** — a **subset** that excludes heavy fields, may add computed UI fields (counts, timestamps formatted for display)
+```
+@lobechat/types/src/eval/
+├── benchmark.ts        # Benchmark types
+├── agentEvalDataset.ts # Dataset types
+├── agentEvalRun.ts     # Run types
+└── index.ts           # Re-exports
+```
 
-**Important:** the List type is a **subset**, not an `extends` of Detail. Extending pulls the heavy fields right back in.
+### Example: Benchmark Types
 
-> See [`references/types.md`](./references/types.md) for full worked examples (Benchmark, Document) and the heavy-field exclusion checklist.
+```typescript
+// packages/types/src/eval/benchmark.ts
+import type { EvalBenchmarkRubric } from './rubric';
+
+// ============================================
+// Detail Type - Full entity (for detail pages)
+// ============================================
+
+/**
+ * Full benchmark entity with all fields including heavy data
+ */
+export interface AgentEvalBenchmark {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  metadata?: Record<string, unknown> | null;
+  name: string;
+  referenceUrl?: string | null;
+  rubrics: EvalBenchmarkRubric[]; // Heavy field
+  updatedAt: Date;
+}
+
+// ============================================
+// List Type - Lightweight (for list display)
+// ============================================
+
+/**
+ * Lightweight benchmark item - excludes heavy fields
+ * May include computed statistics for UI
+ */
+export interface AgentEvalBenchmarkListItem {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  name: string;
+  // Note: rubrics NOT included (heavy field)
+
+  // Computed statistics for UI display
+  datasetCount?: number;
+  runCount?: number;
+  testCaseCount?: number;
+}
+```
+
+### Example: Document Types (with heavy content)
+
+```typescript
+// packages/types/src/document.ts
+
+/**
+ * Full document entity - includes heavy content fields
+ */
+export interface Document {
+  id: string;
+  title: string;
+  description?: string;
+  content: string; // Heavy field - full markdown content
+  editorData: any; // Heavy field - editor state
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight document item - excludes heavy content
+ */
+export interface DocumentListItem {
+  id: string;
+  title: string;
+  description?: string;
+  // Note: content and editorData NOT included
+  createdAt: Date;
+  updatedAt: Date;
+
+  // Computed statistics
+  wordCount?: number;
+  lastEditedBy?: string;
+}
+```
+
+**Key Points:**
+
+- **Detail types** include ALL fields from database (full entity)
+- **List types** are **subsets** that exclude heavy/large fields
+- List types may add computed statistics for UI (e.g., `testCaseCount`)
+- **Each entity gets its own file** (not mixed together)
+- **All types** exported from `@lobechat/types`, NOT `@lobechat/database`
+
+**Heavy fields to exclude from List:**
+
+- Large text content (`content`, `editorData`, `fullDescription`)
+- Complex objects (`rubrics`, `config`, `metrics`)
+- Binary data (`image`, `file`)
+- Large arrays (`messages`, `items`)
 
 ---
 
 ## When to Use Map vs Array
 
-### Use Map + Reducer — for Detail Data
+### Use Map + Reducer (for Detail Data)
 
-✅ Detail page data caching — multiple detail pages cached simultaneously
-✅ Optimistic updates — update UI before API responds
-✅ Per-item loading states — track which items are being updated
-✅ Multi-page navigation — user can switch between details without refetching
+✅ **Detail page data caching** - Cache multiple detail pages simultaneously
+✅ **Optimistic updates** - Update UI before API responds
+✅ **Per-item loading states** - Track which items are being updated
+✅ **Multiple pages open** - User can navigate between details without refetching
+
+**Structure:**
 
 ```typescript
 benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
 ```
 
-Examples: benchmark detail pages, dataset detail pages, user profiles.
+**Example:** Benchmark detail pages, Dataset detail pages, User profiles
 
-### Use Simple Array — for List Data
+### Use Simple Array (for List Data)
 
-✅ List display — lists, tables, cards
-✅ Refresh as a whole — entire list refreshes together
-✅ No per-item updates — no need to mutate individual rows in place
-✅ Simple data flow — fewer moving parts
+✅ **List display** - Lists, tables, cards
+✅ **Read-only or refresh-as-whole** - Entire list refreshes together
+✅ **No per-item updates** - No need to update individual items
+✅ **Simple data flow** - Easier to understand and maintain
+
+**Structure:**
 
 ```typescript
-benchmarkList: AgentEvalBenchmarkListItem[];
+benchmarkList: AgentEvalBenchmarkListItem[]
 ```
 
-Examples: benchmark list, dataset list, user list.
+**Example:** Benchmark list, Dataset list, User list
 
 ---
 
 ## State Structure Pattern
 
+### Complete Example
+
+```typescript
+// packages/types/src/eval/benchmark.ts
+import type { EvalBenchmarkRubric } from './rubric';
+
+/**
+ * Full benchmark entity (for detail pages)
+ */
+export interface AgentEvalBenchmark {
+  id: string;
+  name: string;
+  description?: string | null;
+  identifier: string;
+  rubrics: EvalBenchmarkRubric[]; // Heavy field
+  metadata?: Record<string, unknown> | null;
+  isSystem: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight benchmark (for list display)
+ * Excludes heavy fields like rubrics
+ */
+export interface AgentEvalBenchmarkListItem {
+  id: string;
+  name: string;
+  description?: string | null;
+  identifier: string;
+  isSystem: boolean;
+  createdAt: Date;
+  // Note: rubrics excluded
+
+  // Computed statistics
+  testCaseCount?: number;
+  datasetCount?: number;
+  runCount?: number;
+}
+```
+
 ```typescript
 // src/store/eval/slices/benchmark/initialState.ts
 import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
 
 export interface BenchmarkSliceState {
-  // List — simple array
+  // ============================================
+  // List Data - Simple Array
+  // ============================================
+  /**
+   * List of benchmarks for list page display
+   * May include computed fields like testCaseCount
+   */
   benchmarkList: AgentEvalBenchmarkListItem[];
   benchmarkListInit: boolean;
 
-  // Detail — map for multi-entity caching
+  // ============================================
+  // Detail Data - Map for Caching
+  // ============================================
+  /**
+   * Map of benchmark details keyed by ID
+   * Caches detail page data for multiple benchmarks
+   * Enables optimistic updates and per-item loading
+   */
   benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
-  loadingBenchmarkDetailIds: string[]; // per-item loading
 
-  // Mutation states (drive form-level UI)
+  /**
+   * Track which benchmark details are being loaded/updated
+   * For showing spinners on specific items
+   */
+  loadingBenchmarkDetailIds: string[];
+
+  // ============================================
+  // Mutation States
+  // ============================================
   isCreatingBenchmark: boolean;
   isUpdatingBenchmark: boolean;
   isDeletingBenchmark: boolean;
@@ -106,51 +272,180 @@ export const benchmarkInitialState: BenchmarkSliceState = {
 
 ## Reducer Pattern (for Detail Map)
 
-When the Detail Map needs optimistic updates (i.e. the user edits a row and the UI should reflect it before the server confirms), wire a typed reducer instead of inlining `set` calls. This keeps mutations testable and the dispatch surface small.
+### Why Use Reducer?
 
-> See [`references/reducer.md`](./references/reducer.md) for the full discriminated-union action types, the `produce`-based reducer, and the `internal_dispatch*` slice methods that connect them to Zustand.
+- **Immutable updates** - Immer ensures immutability
+- **Type-safe actions** - TypeScript discriminated unions
+- **Testable** - Pure functions easy to test
+- **Reusable** - Same reducer for optimistic updates and server data
+
+### Reducer Structure
+
+```typescript
+// src/store/eval/slices/benchmark/reducer.ts
+import { produce } from 'immer';
+import type { AgentEvalBenchmark } from '@lobechat/types';
+
+// ============================================
+// Action Types
+// ============================================
+
+type SetBenchmarkDetailAction = {
+  id: string;
+  type: 'setBenchmarkDetail';
+  value: AgentEvalBenchmark;
+};
+
+type UpdateBenchmarkDetailAction = {
+  id: string;
+  type: 'updateBenchmarkDetail';
+  value: Partial<AgentEvalBenchmark>;
+};
+
+type DeleteBenchmarkDetailAction = {
+  id: string;
+  type: 'deleteBenchmarkDetail';
+};
+
+export type BenchmarkDetailDispatch =
+  | SetBenchmarkDetailAction
+  | UpdateBenchmarkDetailAction
+  | DeleteBenchmarkDetailAction;
+
+// ============================================
+// Reducer Function
+// ============================================
+
+export const benchmarkDetailReducer = (
+  state: Record<string, AgentEvalBenchmark> = {},
+  payload: BenchmarkDetailDispatch,
+): Record<string, AgentEvalBenchmark> => {
+  switch (payload.type) {
+    case 'setBenchmarkDetail': {
+      return produce(state, (draft) => {
+        draft[payload.id] = payload.value;
+      });
+    }
+
+    case 'updateBenchmarkDetail': {
+      return produce(state, (draft) => {
+        if (draft[payload.id]) {
+          draft[payload.id] = { ...draft[payload.id], ...payload.value };
+        }
+      });
+    }
+
+    case 'deleteBenchmarkDetail': {
+      return produce(state, (draft) => {
+        delete draft[payload.id];
+      });
+    }
+
+    default:
+      return state;
+  }
+};
+```
+
+### Internal Dispatch Methods
+
+```typescript
+// In action.ts
+export interface BenchmarkAction {
+  // ... other methods ...
+
+  // Internal methods - not for direct UI use
+  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
+  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
+}
+
+export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
+  // ... other methods ...
+
+  // Internal - Dispatch to reducer
+  internal_dispatchBenchmarkDetail: (payload) => {
+    const currentMap = get().benchmarkDetailMap;
+    const nextMap = benchmarkDetailReducer(currentMap, payload);
+
+    // Only update if changed
+    if (isEqual(nextMap, currentMap)) return;
+
+    set(
+      { benchmarkDetailMap: nextMap },
+      false,
+      `dispatchBenchmarkDetail/${payload.type}`,
+    );
+  },
+
+  // Internal - Update loading state
+  internal_updateBenchmarkDetailLoading: (id, loading) => {
+    set(
+      (state) => {
+        if (loading) {
+          return { loadingBenchmarkDetailIds: [...state.loadingBenchmarkDetailIds, id] };
+        }
+        return {
+          loadingBenchmarkDetailIds: state.loadingBenchmarkDetailIds.filter((i) => i !== id),
+        };
+      },
+      false,
+      'updateBenchmarkDetailLoading',
+    );
+  },
+});
+```
 
 ---
 
 ## Data Structure Comparison
 
-### ❌ WRONG — Single Detail Object
+### ❌ WRONG - Single Detail Object
 
 ```typescript
 interface BenchmarkSliceState {
+  // ❌ Can only cache one detail
   benchmarkDetail: AgentEvalBenchmark | null;
+
+  // ❌ Global loading state
   isLoadingBenchmarkDetail: boolean;
 }
 ```
 
-Problems:
+**Problems:**
 
 - Can only cache one detail page at a time
-- Switching between details forces refetch
+- Switching between details causes unnecessary refetches
 - No optimistic updates
 - No per-item loading states
 
-### ✅ CORRECT — Separate List and Detail
+### ✅ CORRECT - Separate List and Detail
 
 ```typescript
+import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
+
 interface BenchmarkSliceState {
+  // ✅ List data - simple array
   benchmarkList: AgentEvalBenchmarkListItem[];
   benchmarkListInit: boolean;
 
+  // ✅ Detail data - map for caching
   benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
+
+  // ✅ Per-item loading
   loadingBenchmarkDetailIds: string[];
 
+  // ✅ Mutation states
   isCreatingBenchmark: boolean;
   isUpdatingBenchmark: boolean;
   isDeletingBenchmark: boolean;
 }
 ```
 
-Benefits:
+**Benefits:**
 
 - Cache multiple detail pages
 - Fast navigation between cached details
-- Optimistic updates via reducer
+- Optimistic updates with reducer
 - Per-item loading states
 - Clear separation of concerns
 
@@ -160,16 +455,22 @@ Benefits:
 
 ### Accessing List Data
 
-```tsx
+```typescript
 const BenchmarkList = () => {
+  // Simple array access
   const benchmarks = useEvalStore((s) => s.benchmarkList);
   const isInit = useEvalStore((s) => s.benchmarkListInit);
 
   if (!isInit) return <Loading />;
+
   return (
     <div>
-      {benchmarks.map((b) => (
-        <BenchmarkCard key={b.id} name={b.name} testCaseCount={b.testCaseCount} />
+      {benchmarks.map(b => (
+        <BenchmarkCard
+          key={b.id}
+          name={b.name}
+          testCaseCount={b.testCaseCount} // Computed field
+        />
       ))}
     </div>
   );
@@ -178,18 +479,22 @@ const BenchmarkList = () => {
 
 ### Accessing Detail Data
 
-```tsx
+```typescript
 const BenchmarkDetail = () => {
   const { benchmarkId } = useParams<{ benchmarkId: string }>();
 
+  // Get from map
   const benchmark = useEvalStore((s) =>
     benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
   );
+
+  // Check loading
   const isLoading = useEvalStore((s) =>
     benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
   );
 
   if (!benchmark) return <Loading />;
+
   return (
     <div>
       <h1>{benchmark.name}</h1>
@@ -205,6 +510,7 @@ const BenchmarkDetail = () => {
 // src/store/eval/slices/benchmark/selectors.ts
 export const benchmarkSelectors = {
   getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
+
   isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
     s.loadingBenchmarkDetailIds.includes(id),
 };
@@ -218,7 +524,7 @@ const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(bench
 
 ## Decision Tree
 
-```text
+```
 Need to store data?
 │
 ├─ Is it a LIST for display?
@@ -241,40 +547,43 @@ Need to store data?
 
 When designing store state structure:
 
-- [ ] **Organize types by entity** in separate files (e.g. `benchmark.ts`, `agentEvalDataset.ts`)
+- [ ] **Organize types by entity** in separate files (e.g., `benchmark.ts`, `agentEvalDataset.ts`)
 - [ ] Create **Detail** type (full entity with all fields including heavy ones)
 - [ ] Create **ListItem** type:
-  - [ ] Subset of Detail (exclude heavy fields)
+  - [ ] Subset of Detail type (exclude heavy fields)
   - [ ] May include computed statistics for UI
-  - [ ] **NOT** `extends` Detail
+  - [ ] **NOT** extending Detail type (it's a subset, not extension)
 - [ ] Use **array** for list data: `xxxList: XxxListItem[]`
 - [ ] Use **Map** for detail data: `xxxDetailMap: Record<string, Xxx>`
-- [ ] Per-item loading: `loadingXxxDetailIds: string[]`
-- [ ] **Reducer** for detail map if optimistic updates needed (see [`references/reducer.md`](./references/reducer.md))
-- [ ] **Internal dispatch** and **loading** methods
-- [ ] **Selectors** for clean access (optional but recommended)
-- [ ] Document in comments which fields are excluded from List and why
+- [ ] Add per-item loading: `loadingXxxDetailIds: string[]`
+- [ ] Create **reducer** for detail map if optimistic updates needed
+- [ ] Add **internal dispatch** and **loading** methods
+- [ ] Create **selectors** for clean access (optional but recommended)
+- [ ] Document in comments:
+  - [ ] What fields are excluded from List and why
+  - [ ] What computed fields mean
+  - [ ] What each Map is for
 
 ---
 
 ## Best Practices
 
-1. **File organization** — one entity per file, not mixed
-2. **List is a subset** — ListItem excludes heavy fields, does not `extends` Detail
-3. **Clear naming** — `xxxList` for arrays, `xxxDetailMap` for maps
-4. **Consistent patterns** — all detail maps follow the same shape
-5. **Type safety** — never use `any`, always use proper types
-6. **Document exclusions** — comment which fields are excluded and why
-7. **Selectors** — encapsulate access patterns
-8. **Loading states** — per-item for details, global for mutations
-9. **Immutability** — use Immer in reducers
+1. **File organization** - One entity per file, not mixed together
+2. **List is subset** - ListItem excludes heavy fields, not extends Detail
+3. **Clear naming** - `xxxList` for arrays, `xxxDetailMap` for maps
+4. **Consistent patterns** - All detail maps follow same structure
+5. **Type safety** - Never use `any`, always use proper types
+6. **Document exclusions** - Comment which fields are excluded from List and why
+7. **Selectors** - Encapsulate access patterns
+8. **Loading states** - Per-item for details, global for lists
+9. **Immutability** - Use Immer in reducers
 
 ### Common Mistakes to Avoid
 
 ❌ **DON'T extend Detail in List:**
 
 ```typescript
-// Wrong — pulls heavy fields back in
+// Wrong - List should not extend Detail
 export interface BenchmarkListItem extends Benchmark {
   testCaseCount?: number;
 }
@@ -283,6 +592,7 @@ export interface BenchmarkListItem extends Benchmark {
 ✅ **DO create separate subset:**
 
 ```typescript
+// Correct - List is a subset with computed fields
 export interface BenchmarkListItem {
   id: string;
   name: string;
@@ -293,14 +603,14 @@ export interface BenchmarkListItem {
 
 ❌ **DON'T mix entities in one file:**
 
-```text
-// Wrong — all entities in agentEvalEntities.ts
+```typescript
+// Wrong - all entities in agentEvalEntities.ts
 ```
 
 ✅ **DO separate by entity:**
 
-```text
-// Correct — separate files
+```typescript
+// Correct - separate files
 // benchmark.ts
 // agentEvalDataset.ts
 // agentEvalRun.ts
@@ -310,5 +620,5 @@ export interface BenchmarkListItem {
 
 ## Related Skills
 
-- `data-fetching-architecture` — how to fetch and update this data
-- `zustand` — general Zustand patterns
+- `data-fetching` - How to fetch and update this data
+- `zustand` - General Zustand patterns

.agents/skills/store-data-structures/references/reducer.md

@@ -1,118 +0,0 @@
-# Reducer Pattern (for Detail Map)
-
-## Why Use a Reducer?
-
-- **Immutable updates** — Immer makes immutability easy
-- **Type-safe actions** — discriminated union of action types prevents typos
-- **Testable** — pure function, easy to unit test
-- **Reusable** — same reducer powers optimistic updates and server-data writes
-
-## Reducer Structure
-
-```typescript
-// src/store/eval/slices/benchmark/reducer.ts
-import { produce } from 'immer';
-import type { AgentEvalBenchmark } from '@lobechat/types';
-
-// Action types — discriminated union
-type SetBenchmarkDetailAction = {
-  id: string;
-  type: 'setBenchmarkDetail';
-  value: AgentEvalBenchmark;
-};
-
-type UpdateBenchmarkDetailAction = {
-  id: string;
-  type: 'updateBenchmarkDetail';
-  value: Partial<AgentEvalBenchmark>;
-};
-
-type DeleteBenchmarkDetailAction = {
-  id: string;
-  type: 'deleteBenchmarkDetail';
-};
-
-export type BenchmarkDetailDispatch =
-  | SetBenchmarkDetailAction
-  | UpdateBenchmarkDetailAction
-  | DeleteBenchmarkDetailAction;
-
-export const benchmarkDetailReducer = (
-  state: Record<string, AgentEvalBenchmark> = {},
-  payload: BenchmarkDetailDispatch,
-): Record<string, AgentEvalBenchmark> => {
-  switch (payload.type) {
-    case 'setBenchmarkDetail': {
-      return produce(state, (draft) => {
-        draft[payload.id] = payload.value;
-      });
-    }
-
-    case 'updateBenchmarkDetail': {
-      return produce(state, (draft) => {
-        if (draft[payload.id]) {
-          draft[payload.id] = { ...draft[payload.id], ...payload.value };
-        }
-      });
-    }
-
-    case 'deleteBenchmarkDetail': {
-      return produce(state, (draft) => {
-        delete draft[payload.id];
-      });
-    }
-
-    default:
-      return state;
-  }
-};
-```
-
-## Internal Dispatch Methods
-
-The slice exposes two `internal_*` methods so the reducer and the loading state stay encapsulated behind a stable contract:
-
-```typescript
-// In action.ts
-export interface BenchmarkAction {
-  // ... other methods ...
-
-  // Internal — not for direct UI use
-  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
-  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
-}
-
-export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
-  // ... other methods ...
-
-  // Dispatch to reducer
-  internal_dispatchBenchmarkDetail: (payload) => {
-    const currentMap = get().benchmarkDetailMap;
-    const nextMap = benchmarkDetailReducer(currentMap, payload);
-
-    // Skip set when nothing changed — avoids unnecessary re-renders
-    if (isEqual(nextMap, currentMap)) return;
-
-    set(
-      { benchmarkDetailMap: nextMap },
-      false,
-      `dispatchBenchmarkDetail/${payload.type}`,
-    );
-  },
-
-  // Update loading state for a specific id
-  internal_updateBenchmarkDetailLoading: (id, loading) => {
-    set(
-      (state) => ({
-        loadingBenchmarkDetailIds: loading
-          ? [...state.loadingBenchmarkDetailIds, id]
-          : state.loadingBenchmarkDetailIds.filter((i) => i !== id),
-      }),
-      false,
-      'updateBenchmarkDetailLoading',
-    );
-  },
-});
-```
-
-The `internal_` prefix is a convention — UI components should call the public mutation methods (e.g. `updateBenchmark`), which in turn call `internal_dispatch*`. This keeps reducer dispatch shapes out of the component layer.

.agents/skills/store-data-structures/references/types.md

@@ -1,101 +0,0 @@
-# Type Definitions in Detail
-
-The skill body's Type Definitions section covers the rules; this file holds the full worked examples to keep SKILL.md lean.
-
-## Organization
-
-Types should be organized by entity in separate files (not mixed):
-
-```text
-@lobechat/types/src/eval/
-├── benchmark.ts        # Benchmark types
-├── agentEvalDataset.ts # Dataset types
-├── agentEvalRun.ts     # Run types
-└── index.ts            # Re-exports
-```
-
-## Example: Benchmark Types
-
-```typescript
-// packages/types/src/eval/benchmark.ts
-import type { EvalBenchmarkRubric } from './rubric';
-
-/**
- * Full benchmark entity with all fields including heavy data.
- */
-export interface AgentEvalBenchmark {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  metadata?: Record<string, unknown> | null;
-  name: string;
-  referenceUrl?: string | null;
-  rubrics: EvalBenchmarkRubric[]; // Heavy field
-  updatedAt: Date;
-}
-
-/**
- * Lightweight benchmark item — excludes heavy fields, may add computed stats.
- */
-export interface AgentEvalBenchmarkListItem {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  name: string;
-  // Note: rubrics NOT included (heavy field)
-
-  // Computed statistics for UI display
-  datasetCount?: number;
-  runCount?: number;
-  testCaseCount?: number;
-}
-```
-
-## Example: Document Types (with heavy content)
-
-```typescript
-// packages/types/src/document.ts
-
-/**
- * Full document entity — includes heavy content fields.
- */
-export interface Document {
-  id: string;
-  title: string;
-  description?: string;
-  content: string; // Heavy field — full markdown content
-  editorData: any; // Heavy field — editor state
-  metadata?: Record<string, unknown>;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Lightweight document item — excludes heavy content.
- */
-export interface DocumentListItem {
-  id: string;
-  title: string;
-  description?: string;
-  // Note: content and editorData NOT included
-  createdAt: Date;
-  updatedAt: Date;
-
-  // Computed statistics
-  wordCount?: number;
-  lastEditedBy?: string;
-}
-```
-
-## Heavy Fields to Exclude from List
-
-- Large text content (`content`, `editorData`, `fullDescription`)
-- Complex objects (`rubrics`, `config`, `metrics`)
-- Binary data (`image`, `file`)
-- Large arrays (`messages`, `items`)
-
-The reason these belong only on Detail: list pages render many rows, so pulling heavy fields blows up payload size and slows render. Detail pages render one entity, so the full payload is fine.

.agents/skills/testing/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: testing
-description: 'Vitest testing guide. Use when writing or updating tests, fixing failing tests, improving coverage, debugging test issues, or setting up mocks.'
-user-invocable: false
+description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
 ---
 
 # LobeHub Testing Guide

.agents/skills/trpc-router/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: trpc-router
-description: 'TRPC router development guide. Use when creating or modifying src/server/routers, adding procedures, or implementing server-side API endpoints.'
-user-invocable: false
+description: TRPC router development guide. Use when creating or modifying TRPC routers (src/server/routers/**), adding procedures, or working with server-side API endpoints. Triggers on TRPC router creation, procedure implementation, or API endpoint tasks.
 ---
 
 # TRPC Router Guide

.agents/skills/typescript/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: typescript
-description: 'LobeHub TypeScript style and type-safety guide. Use when editing TS/TSX/MTS, fixing types, choosing interface vs type, avoiding any/object, import type, async flow, or ts-expect-error.'
-user-invocable: false
+description: TypeScript code style and optimization guidelines. MUST READ before writing or modifying any TypeScript code (.ts, .tsx, .mts files). Also use when reviewing code quality or implementing type-safe patterns. Triggers on any TypeScript file edit, code style discussions, or type safety questions.
 ---
 
 # TypeScript Code Style Guide
@@ -29,16 +28,12 @@ user-invocable: false
 ## Imports
 
 - This project uses `simple-import-sort/imports` and `consistent-type-imports` (`fixStyle: 'separate-type-imports'`)
-
 - **Separate type imports**: always use `import type { ... }` for type-only imports, NOT `import { type ... }` inline syntax
-
 - When a file already has `import type { ... }` from a package and you need to add a value import, keep them as **two separate statements**:
-
   ```ts
   import type { ChatTopicBotContext } from '@lobechat/types';
   import { RequestTrigger } from '@lobechat/types';
   ```
-
 - Within each import statement, specifiers are sorted **alphabetically by name**
 
 ## Code Structure
@@ -47,8 +42,6 @@ user-invocable: false
 - Use consistent, descriptive naming; avoid obscure abbreviations
 - Replace magic numbers/strings with well-named constants
 - Defer formatting to tooling
-- Prefer **named exports** over `export default` — keeps refactor renames and IDE auto-import in sync, and avoids the `default` re-naming drift you get with `import Foo from './foo'`. Reserve `export default` for files where the framework requires it (Next.js page/route/layout, React.lazy targets, config files like `vitest.config.ts`)
-- Before adding local helpers for common guards/parsing/normalization (record checks, string extraction, empty-string handling, timing helpers, JSON-safe utilities, etc.), search `packages/utils` first. If the helper already exists or clearly belongs there, import it from `@lobechat/utils` (or the relevant `@lobechat/utils/*` subpath) instead of duplicating tiny helpers across feature files.
 
 ## UI and Theming
 
@@ -58,6 +51,7 @@ user-invocable: false
 
 ## Performance
 
+- Prefer `for…of` loops over index-based `for` loops
 - Reuse existing utils in `packages/utils` or installed npm packages
 - Query only required columns from database
 

.agents/skills/upstash-workflow/reference/cloud.md

@@ -1,20 +1,6 @@
 # Cloud Project Workflow Configuration
 
-Cloud-specific workflow configurations and patterns for the lobehub-cloud project.
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Directory Structure](#directory-structure) — submodule + cloud layout
-3. [Cloud-Specific Patterns](#cloud-specific-patterns) — cloud-only workflows + re-export pattern
-4. [TypeScript Path Mappings](#typescript-path-mappings)
-5. [Workflow Class Location](#workflow-class-location) — cloud-only vs shared
-6. [Environment Variables](#environment-variables)
-7. [Best Practices](#best-practices) — decide cloud vs OSS, re-export rules, naming
-8. [Migration Guide](#migration-guide) — moving workflows from cloud to lobehub
-9. [Examples](#examples) — `welcome-placeholder`, `agent-eval-run`
-10. [Troubleshooting](#troubleshooting) — circular imports, 404s, type errors
-11. [Related Documentation](#related-documentation)
+This document covers cloud-specific workflow configurations and patterns for the lobehub-cloud project.
 
 ## Overview
 
@@ -29,7 +15,7 @@ The lobehub-cloud project extends the open-source lobehub codebase with cloud-sp
 
 ### Lobehub Submodule (Open-source)
 
-```text
+```
 lobehub/
 └── src/
     ├── app/(backend)/api/workflows/
@@ -42,7 +28,7 @@ lobehub/
 
 ### Lobehub-cloud (Proprietary)
 
-```text
+```
 lobehub-cloud/
 └── src/
     ├── app/(backend)/api/workflows/
@@ -74,7 +60,7 @@ lobehub-cloud/
 
 **Structure**:
 
-```text
+```
 lobehub-cloud/src/
 ├── app/(backend)/api/workflows/
 │   └── feature-name/
@@ -176,7 +162,7 @@ This allows cloud to override specific modules while using lobehub defaults.
 
 Place workflow class in cloud:
 
-```text
+```
 lobehub-cloud/src/server/workflows/featureName/index.ts
 ```
 
@@ -184,7 +170,7 @@ lobehub-cloud/src/server/workflows/featureName/index.ts
 
 Place workflow class in lobehub, re-export in cloud if needed:
 
-```text
+```
 lobehub/src/server/workflows/featureName/index.ts
 ```
 
@@ -259,7 +245,7 @@ For shared features:
 
 Follow consistent naming across lobehub and cloud:
 
-```text
+```
 # Both should use same structure
 lobehub/src/app/(backend)/api/workflows/feature-name/
 lobehub-cloud/src/app/(backend)/api/workflows/feature-name/
@@ -320,7 +306,7 @@ import { Workflow } from 'lobehub/src/server/workflows/feature';
 
 **Structure**:
 
-```text
+```
 lobehub-cloud/
 ├── src/app/(backend)/api/workflows/welcome-placeholder/
 │   ├── process-users/route.ts

.agents/skills/upstash-workflow/references/best-practices.md

@@ -1,226 +0,0 @@
-# Best Practices & Common Pitfalls
-
-Apply these once your scaffold from `implementation.md` is in place.
-
-## Table of Contents
-
-1. [Error Handling](#1-error-handling)
-2. [Logging](#2-logging)
-3. [Return Values](#3-return-values)
-4. [flowControl Configuration](#4-flowcontrol-configuration)
-5. [context.run() Best Practices](#5-contextrun-best-practices)
-6. [Payload Validation](#6-payload-validation)
-7. [Database Connection](#7-database-connection)
-8. [Testing](#8-testing)
-9. [Common Pitfalls](#common-pitfalls)
-
----
-
-## 1. Error Handling
-
-```typescript
-export const { POST } = serve<Payload>(
-  async (context) => {
-    const { itemId } = context.requestPayload ?? {};
-
-    if (!itemId) {
-      return { success: false, error: 'Missing itemId in payload' };
-    }
-
-    try {
-      const result = await context.run('step-name', () => doWork(itemId));
-      return { success: true, itemId, result };
-    } catch (error) {
-      console.error('[workflow:error]', error);
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : 'Unknown error',
-      };
-    }
-  },
-  { flowControl: { ... } },
-);
-```
-
-## 2. Logging
-
-Consistent prefixes make debugging much easier across QStash dashboards and grep:
-
-```typescript
-console.log('[{workflow}:{layer}] Starting with payload:', payload);
-console.log('[{workflow}:{layer}] Processing items:', { count: items.length });
-console.log('[{workflow}:{layer}] Completed:', result);
-console.error('[{workflow}:{layer}:error]', error);
-```
-
-## 3. Return Values
-
-Pick the shape that matches the layer's purpose — entry points return statistics, execution layers return per-item results.
-
-```typescript
-// Success
-return { success: true, itemId, result, message: 'Optional success message' };
-
-// Error
-return { success: false, error: 'Error description', itemId };
-
-// Statistics (entry point)
-return {
-  success: true,
-  totalEligible: 100,
-  toProcess: 80,
-  alreadyProcessed: 20,
-  dryRun: true, // if applicable
-  message: 'Summary message',
-};
-```
-
-## 4. flowControl Configuration
-
-Tune concurrency by layer — entry points are singletons, execution layers fan out.
-
-```typescript
-// Layer 1: Entry — single instance to avoid duplicate processing
-flowControl: { key: '{workflow}.process',  parallelism: 1,  ratePerSecond: 1 }
-
-// Layer 2: Pagination — moderate concurrency
-flowControl: { key: '{workflow}.paginate', parallelism: 20, ratePerSecond: 5 }
-
-// Layer 3: Execution — higher concurrency for parallel item work
-flowControl: { key: '{workflow}.execute',  parallelism: 10, ratePerSecond: 5 }
-```
-
-**Why these defaults:**
-
-- **Layer 1** always uses `parallelism: 1` so concurrent triggers don't both start the same batch.
-- **Layer 2** can fan out widely (10-20) since pagination is cheap.
-- **Layer 3** caps at 5-10 by default; raise/lower based on external API rate limits.
-
-## 5. context.run() Best Practices
-
-- Use descriptive step names with prefixes: `{workflow}:step-name`
-- Each step should be idempotent (safe to retry)
-- Don't nest `context.run()` calls — keep them flat
-- Use unique step names when processing multiple items:
-
-```typescript
-// ✅ Unique step names
-await Promise.all(
-  items.map((item) => context.run(`{workflow}:execute:${item.id}`, () => processItem(item))),
-);
-
-// ❌ Same step name — Upstash de-dupes by step name and you'll lose data
-await Promise.all(items.map((item) => context.run(`{workflow}:execute`, () => processItem(item))));
-```
-
-## 6. Payload Validation
-
-Validate at the top so failures are explicit, not silent `undefined` cascades:
-
-```typescript
-export const { POST } = serve<Payload>(
-  async (context) => {
-    const { itemId, configId } = context.requestPayload ?? {};
-
-    if (!itemId)   return { success: false, error: 'Missing itemId in payload' };
-    if (!configId) return { success: false, error: 'Missing configId in payload' };
-
-    // Proceed with work...
-  },
-  { flowControl: { ... } },
-);
-```
-
-## 7. Database Connection
-
-Get the connection once per workflow — `getServerDB()` is async, repeating it inside each step adds latency:
-
-```typescript
-export const { POST } = serve<Payload>(
-  async (context) => {
-    const db = await getServerDB();
-
-    const item = await context.run('get-item', () => itemModel.findById(db, itemId));
-    const result = await context.run('save-result', () => resultModel.create(db, result));
-  },
-  { flowControl: { ... } },
-);
-```
-
-## 8. Testing
-
-Integration tests should exercise both the dry-run statistics path and the full execution path:
-
-```typescript
-describe('WorkflowName', () => {
-  it('should process items successfully', async () => {
-    const items = await createTestItems();
-    await WorkflowClass.triggerProcessItems({ dryRun: false });
-    await waitForCompletion();
-    const results = await getResults();
-    expect(results).toHaveLength(items.length);
-  });
-
-  it('should support dryRun mode', async () => {
-    const result = await WorkflowClass.triggerProcessItems({ dryRun: true });
-    expect(result).toMatchObject({
-      success: true,
-      dryRun: true,
-      totalEligible: expect.any(Number),
-      toProcess: expect.any(Number),
-    });
-  });
-});
-```
-
----
-
-## Common Pitfalls
-
-### ❌ Reusing `context.run()` step names
-
-```typescript
-// Bad — Upstash dedupes by step name
-await Promise.all(items.map((item) => context.run('process', () => process(item))));
-
-// Good
-await Promise.all(items.map((item) => context.run(`process:${item.id}`, () => process(item))));
-```
-
-### ❌ Skipping payload validation
-
-```typescript
-// Bad — undefined cascades into a confusing failure later
-const { itemId } = context.requestPayload ?? {};
-const result = await process(itemId);
-
-// Good — fail fast with a clear error
-if (!itemId) return { success: false, error: 'Missing itemId' };
-```
-
-### ❌ Skipping the filter step
-
-```typescript
-// Bad — duplicates work for items that were already processed
-const allItems = await getAllItems();
-await Promise.all(allItems.map((item) => triggerExecute(item)));
-
-// Good — keeps the pipeline idempotent
-const allItems = await getAllItems();
-const itemsNeedingProcessing = await filterExisting(allItems);
-await Promise.all(itemsNeedingProcessing.map((item) => triggerExecute(item)));
-```
-
-### ❌ Inconsistent logging
-
-```typescript
-// Bad — different prefixes, mixed formats
-console.log('Starting workflow');
-log.info('Processing item:', itemId);
-console.log(`Done with ${itemId}`);
-
-// Good — uniform prefix lets you grep by workflow+layer
-console.log('[workflow:layer] Starting with payload:', payload);
-console.log('[workflow:layer] Processing item:', { itemId });
-console.log('[workflow:layer] Completed:', { itemId, result });
-```

.agents/skills/upstash-workflow/references/examples.md

@@ -1,91 +0,0 @@
-# Worked Examples
-
-Two real workflows already in the codebase that follow this skill's pattern verbatim. Skim them when you want to see the pattern applied to concrete entities.
-
-## Example 1: Welcome Placeholder
-
-**Use case:** Generate AI-powered welcome placeholders for users.
-
-**Structure:**
-
-- Layer 1: `process-users` — entry point, checks eligible users
-- Layer 2: `paginate-users` — paginates through active users
-- Layer 3: `generate-user` — generates placeholders for ONE user
-
-**Key features:**
-
-- Filters users who already have cached placeholders in Redis
-- `paidOnly` flag to scope to subscribed users
-- `dryRun` mode for statistics
-- Fan-out for large user batches (`CHUNK_SIZE=20`)
-
-**Layer 3 shape:**
-
-```typescript
-export const { POST } = serve<GenerateUserPlaceholderPayload>(async (context) => {
-  const { userId } = context.requestPayload ?? {};
-
-  const workflow = new WelcomePlaceholderWorkflow(db, userId);
-  const placeholders = await context.run('generate', () => workflow.generate());
-
-  return { success: true, userId, placeholdersCount: placeholders.length };
-});
-```
-
-**Files:**
-
-- `/api/workflows/welcome-placeholder/process-users/route.ts`
-- `/api/workflows/welcome-placeholder/paginate-users/route.ts`
-- `/api/workflows/welcome-placeholder/generate-user/route.ts`
-- `/server/workflows/welcomePlaceholder/index.ts`
-
----
-
-## Example 2: Agent Welcome
-
-**Use case:** Generate welcome messages and open questions for AI agents.
-
-**Structure:**
-
-- Layer 1: `process-agents` — entry point, checks eligible agents
-- Layer 2: `paginate-agents` — paginates through active agents
-- Layer 3: `generate-agent` — generates welcome data for ONE agent
-
-**Key features:**
-
-- Filters agents who already have cached data in Redis
-- `paidOnly` flag for subscribed users' agents only
-- `dryRun` mode for statistics
-- Fan-out for large agent batches (`CHUNK_SIZE=20`)
-
-**Layer 3 shape:**
-
-```typescript
-export const { POST } = serve<GenerateAgentWelcomePayload>(async (context) => {
-  const { agentId } = context.requestPayload ?? {};
-
-  const workflow = new AgentWelcomeWorkflow(db, agentId);
-  const data = await context.run('generate', () => workflow.generate());
-
-  return { success: true, agentId, data };
-});
-```
-
-**Files:**
-
-- `/api/workflows/agent-welcome/process-agents/route.ts`
-- `/api/workflows/agent-welcome/paginate-agents/route.ts`
-- `/api/workflows/agent-welcome/generate-agent/route.ts`
-- `/server/workflows/agentWelcome/index.ts`
-
----
-
-## What's identical, what differs
-
-Both workflows are the **same pattern** — they only differ in:
-
-- Entity type (users vs agents)
-- Business logic (placeholder generation vs welcome generation)
-- Data source (different database queries)
-
-Everything else — the 3-layer split, dry-run handling, fan-out, filter-existing, flowControl tuning — is identical. That's the whole point: once you internalize the pattern, adding a new workflow is mostly entity-substitution.

.agents/skills/upstash-workflow/references/implementation.md

@@ -1,333 +0,0 @@
-# Implementation Patterns
-
-Full code templates for the 3-layer architecture. Read this when actually writing workflow files.
-
-## Table of Contents
-
-1. [Workflow Class](#workflow-class) — `src/server/workflows/{workflowName}/index.ts`
-2. [Layer 1: Entry Point](#layer-1-entry-point-process-) — `process-*` route
-3. [Layer 2: Pagination](#layer-2-pagination-paginate-) — `paginate-*` route
-4. [Layer 3: Execution](#layer-3-execution-execute--generate-) — `execute-*` / `generate-*` route
-
----
-
-## Workflow Class
-
-**Location:** `src/server/workflows/{workflowName}/index.ts`
-
-```typescript
-import { Client } from '@upstash/workflow';
-import debug from 'debug';
-
-const log = debug('lobe-server:workflows:{workflow-name}');
-
-// Workflow paths
-const WORKFLOW_PATHS = {
-  processItems: '/api/workflows/{workflow-name}/process-items',
-  paginateItems: '/api/workflows/{workflow-name}/paginate-items',
-  executeItem: '/api/workflows/{workflow-name}/execute-item',
-} as const;
-
-// Payload types
-export interface ProcessItemsPayload {
-  dryRun?: boolean;
-  force?: boolean;
-}
-
-export interface PaginateItemsPayload {
-  cursor?: string;
-  itemIds?: string[]; // For fanout chunks
-}
-
-export interface ExecuteItemPayload {
-  itemId: string;
-}
-
-const getWorkflowUrl = (path: string): string => {
-  const baseUrl = process.env.APP_URL;
-  if (!baseUrl) throw new Error('APP_URL is required to trigger workflows');
-  return new URL(path, baseUrl).toString();
-};
-
-const getWorkflowClient = (): Client => {
-  const token = process.env.QSTASH_TOKEN;
-  if (!token) throw new Error('QSTASH_TOKEN is required to trigger workflows');
-
-  const config: ConstructorParameters<typeof Client>[0] = { token };
-  if (process.env.QSTASH_URL) {
-    (config as Record<string, unknown>).url = process.env.QSTASH_URL;
-  }
-  return new Client(config);
-};
-
-export class {WorkflowName}Workflow {
-  private static client: Client;
-
-  private static getClient(): Client {
-    if (!this.client) this.client = getWorkflowClient();
-    return this.client;
-  }
-
-  static triggerProcessItems(payload: ProcessItemsPayload) {
-    const url = getWorkflowUrl(WORKFLOW_PATHS.processItems);
-    log('Triggering process-items workflow');
-    return this.getClient().trigger({ body: payload, url });
-  }
-
-  static triggerPaginateItems(payload: PaginateItemsPayload) {
-    const url = getWorkflowUrl(WORKFLOW_PATHS.paginateItems);
-    log('Triggering paginate-items workflow');
-    return this.getClient().trigger({ body: payload, url });
-  }
-
-  static triggerExecuteItem(payload: ExecuteItemPayload) {
-    const url = getWorkflowUrl(WORKFLOW_PATHS.executeItem);
-    log('Triggering execute-item workflow: %s', payload.itemId);
-    return this.getClient().trigger({ body: payload, url });
-  }
-
-  /**
-   * Filter items that need processing (e.g. check Redis cache, database state).
-   * Return only the ones that actually need work — keeps the pipeline idempotent.
-   */
-  static async filterItemsNeedingProcessing(itemIds: string[]): Promise<string[]> {
-    if (itemIds.length === 0) return [];
-    // Check existing state and return items that need processing
-    return itemIds;
-  }
-}
-```
-
----
-
-## Layer 1: Entry Point (process-\*)
-
-**Purpose:** Validates prerequisites, calculates statistics, supports dry-run mode.
-
-```typescript
-import { serve } from '@upstash/workflow/nextjs';
-import { getServerDB } from '@/database/server';
-import { WorkflowClass, type ProcessPayload } from '@/server/workflows/{workflowName}';
-
-export const { POST } = serve<ProcessPayload>(
-  async (context) => {
-    const { dryRun, force } = context.requestPayload ?? {};
-
-    console.log('[{workflow}:process] Starting with payload:', { dryRun, force });
-
-    const allItemIds = await context.run('{workflow}:get-all-items', async () => {
-      const db = await getServerDB();
-      // Query database for eligible items
-      return items.map((item) => item.id);
-    });
-
-    console.log('[{workflow}:process] Total eligible items:', allItemIds.length);
-
-    if (allItemIds.length === 0) {
-      return { success: true, totalEligible: 0, message: 'No eligible items found' };
-    }
-
-    const itemsNeedingProcessing = await context.run('{workflow}:filter-existing', () =>
-      WorkflowClass.filterItemsNeedingProcessing(allItemIds),
-    );
-
-    const result = {
-      success: true,
-      totalEligible: allItemIds.length,
-      toProcess: itemsNeedingProcessing.length,
-      alreadyProcessed: allItemIds.length - itemsNeedingProcessing.length,
-    };
-
-    // Dry-run short-circuits before any side effects
-    if (dryRun) {
-      console.log('[{workflow}:process] Dry run mode, returning statistics only');
-      return {
-        ...result,
-        dryRun: true,
-        message: `[DryRun] Would process ${itemsNeedingProcessing.length} items`,
-      };
-    }
-
-    if (itemsNeedingProcessing.length === 0) {
-      return { ...result, message: 'All items already processed' };
-    }
-
-    await context.run('{workflow}:trigger-paginate', () => WorkflowClass.triggerPaginateItems({}));
-
-    return {
-      ...result,
-      message: `Triggered pagination for ${itemsNeedingProcessing.length} items`,
-    };
-  },
-  {
-    flowControl: {
-      key: '{workflow}.process',
-      parallelism: 1, // single instance — avoids duplicate processing
-      ratePerSecond: 1,
-    },
-  },
-);
-```
-
----
-
-## Layer 2: Pagination (paginate-\*)
-
-**Purpose:** Handles cursor-based pagination, implements fan-out for large batches.
-
-```typescript
-import { serve } from '@upstash/workflow/nextjs';
-import { chunk } from 'es-toolkit/compat';
-import { getServerDB } from '@/database/server';
-import { WorkflowClass, type PaginatePayload } from '@/server/workflows/{workflowName}';
-
-const PAGE_SIZE = 50;
-const CHUNK_SIZE = 20;
-
-export const { POST } = serve<PaginatePayload>(
-  async (context) => {
-    const { cursor, itemIds: payloadItemIds } = context.requestPayload ?? {};
-
-    console.log('[{workflow}:paginate] Starting:', {
-      cursor,
-      itemIdsCount: payloadItemIds?.length ?? 0,
-    });
-
-    // If specific itemIds were passed in (from a fanout chunk), process them directly
-    if (payloadItemIds && payloadItemIds.length > 0) {
-      await Promise.all(
-        payloadItemIds.map((itemId) =>
-          context.run(`{workflow}:execute:${itemId}`, () =>
-            WorkflowClass.triggerExecuteItem({ itemId }),
-          ),
-        ),
-      );
-      return { success: true, processedItems: payloadItemIds.length };
-    }
-
-    // Paginate through all items
-    const itemBatch = await context.run('{workflow}:get-batch', async () => {
-      const db = await getServerDB();
-      const items = await db.query(...);
-      if (!items.length) return { ids: [] };
-      const last = items.at(-1);
-      return {
-        ids: items.map((item) => item.id),
-        cursor: last ? last.id : undefined,
-      };
-    });
-
-    const batchItemIds = itemBatch.ids;
-    const nextCursor = 'cursor' in itemBatch ? itemBatch.cursor : undefined;
-
-    if (batchItemIds.length === 0) {
-      return { success: true, message: 'Pagination complete' };
-    }
-
-    const itemIds = await context.run('{workflow}:filter-existing', () =>
-      WorkflowClass.filterItemsNeedingProcessing(batchItemIds),
-    );
-
-    if (itemIds.length > 0) {
-      if (itemIds.length > CHUNK_SIZE) {
-        // Fan out — recursively re-enter pagination with each chunk
-        const chunks = chunk(itemIds, CHUNK_SIZE);
-        console.log('[{workflow}:paginate] Fanout mode:', {
-          chunks: chunks.length,
-          chunkSize: CHUNK_SIZE,
-        });
-
-        await Promise.all(
-          chunks.map((ids, idx) =>
-            context.run(`{workflow}:fanout:${idx + 1}/${chunks.length}`, () =>
-              WorkflowClass.triggerPaginateItems({ itemIds: ids }),
-            ),
-          ),
-        );
-      } else {
-        // Process this page directly
-        await Promise.all(
-          itemIds.map((itemId) =>
-            context.run(`{workflow}:execute:${itemId}`, () =>
-              WorkflowClass.triggerExecuteItem({ itemId }),
-            ),
-          ),
-        );
-      }
-    }
-
-    // Tail-call into the next page
-    if (nextCursor) {
-      await context.run('{workflow}:next-page', () =>
-        WorkflowClass.triggerPaginateItems({ cursor: nextCursor }),
-      );
-    }
-
-    return {
-      success: true,
-      processedItems: itemIds.length,
-      skippedItems: batchItemIds.length - itemIds.length,
-      nextCursor: nextCursor ?? null,
-    };
-  },
-  {
-    flowControl: {
-      key: '{workflow}.paginate',
-      parallelism: 20,
-      ratePerSecond: 5,
-    },
-  },
-);
-```
-
----
-
-## Layer 3: Execution (execute-\* / generate-\*)
-
-**Purpose:** Performs the actual business logic for exactly ONE item.
-
-```typescript
-import { serve } from '@upstash/workflow/nextjs';
-import { getServerDB } from '@/database/server';
-import { WorkflowClass, type ExecutePayload } from '@/server/workflows/{workflowName}';
-
-export const { POST } = serve<ExecutePayload>(
-  async (context) => {
-    const { itemId } = context.requestPayload ?? {};
-
-    if (!itemId) {
-      return { success: false, error: 'Missing itemId' };
-    }
-
-    const db = await getServerDB();
-
-    const item = await context.run('{workflow}:get-item', async () => {
-      // Query database for item
-      return item;
-    });
-
-    if (!item) {
-      return { success: false, error: 'Item not found' };
-    }
-
-    const result = await context.run('{workflow}:process-item', async () => {
-      const workflow = new WorkflowClass(db, itemId);
-      return workflow.generate(); // or process(), execute(), etc.
-    });
-
-    await context.run('{workflow}:save-result', async () => {
-      const workflow = new WorkflowClass(db, itemId);
-      return workflow.saveToRedis(result); // or saveToDatabase(), etc.
-    });
-
-    return { success: true, itemId, result };
-  },
-  {
-    flowControl: {
-      key: '{workflow}.execute',
-      parallelism: 10,
-      ratePerSecond: 5,
-    },
-  },
-);
-```

.agents/skills/version-release/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: version-release
-description: 'Version release workflow — release process and GitHub Release notes (not docs/changelog pages).'
-disable-model-invocation: true
-argument-hint: '[minor|patch] [version?]'
+description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. This skill is for release process and GitHub Release notes (not docs/changelog page writing)."
 ---
 
 # Version Release Workflow
 
-This skill is a router. The detailed steps live in `references/`.
-
 ## Scope Boundary (Important)
 
 This skill is only for:
@@ -32,12 +28,68 @@ The primary development branch is **canary**. All day-to-day development happens
 
 Only two release types are used in practice (major releases are extremely rare and can be ignored):
 
-| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       | Reference                               |
-| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | --------------------------------------- |
-| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  | `references/minor-release.md`           |
-| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `references/patch-release-scenarios.md` |
+| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       |
+| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- |
+| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  |
+| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 |
 
-For writing the release-note body (any release type), see `references/release-notes-style.md`.
+## Minor Release Workflow
+
+Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks.
+
+### Steps
+
+1. **Create a release branch from canary**
+
+```bash
+git checkout canary
+git pull origin canary
+git checkout -b release/v{version}
+git push -u origin release/v{version}
+```
+
+2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x -> 2.2.0)
+
+3. **Create a PR to main**
+
+```bash
+gh pr create \
+  --title "🚀 release: v{version}" \
+  --base main \
+  --head release/v{version} \
+  --body "## 📦 Release v{version} ..."
+```
+
+> \[!IMPORTANT]
+> The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
+
+4. **Automatic trigger after merge**: `auto-tag-release` detects the title format and uses the version number from the title to complete the release.
+
+### Scripts
+
+```bash
+bun run release:branch         # Interactive
+bun run release:branch --minor # Directly specify minor
+```
+
+## Patch Release Workflow
+
+Version number is automatically bumped by patch +1. There are 4 common scenarios:
+
+| Scenario            | Source Branch | Branch Naming                 | Description                                      |
+| ------------------- | ------------- | ----------------------------- | ------------------------------------------------ |
+| Weekly Release      | canary        | `release/weekly-{YYYYMMDD}`   | Weekly release train, canary -> main             |
+| Bug Hotfix          | main          | `hotfix/v{version}-{hash}`    | Emergency bug fix                                |
+| New Model Launch    | canary        | Community PR merged directly  | New model launch, triggered by PR title prefix   |
+| DB Schema Migration | main          | `release/db-migration-{name}` | Database migration, requires dedicated changelog |
+
+All scenarios auto-bump patch +1. Patch PR titles do not need a version number. See `reference/patch-release-scenarios.md` for detailed steps per scenario.
+
+### Scripts
+
+```bash
+bun run hotfix:branch # Hotfix scenario
+```
 
 ## Auto-Release Trigger Rules (`auto-tag-release.yml`)
 
@@ -75,7 +127,7 @@ PRs that don't match any conditions above (e.g. `docs`, `chore`, `ci`, `test`) w
 
 When the user requests a release:
 
-### Precheck (applies to all release types)
+### Precheck
 
 Before creating the release branch, verify the source branch:
 
@@ -83,18 +135,204 @@ Before creating the release branch, verify the source branch:
 - **All other release/hotfix branches**: must branch from `main`; run `git merge-base --is-ancestor main <branch> && echo OK`
 - If the branch is based on the wrong source, recreate from the correct base
 
-### Routing
+### Minor Release
 
-Pick the right reference and follow it end-to-end:
+1. Read `package.json` to get the current version and compute the next minor version
+2. Create a `release/v{version}` branch from canary
+3. Push and create PR — **title must be `🚀 release: v{version}`**
+4. Inform the user that merge will auto-trigger release
 
-- **Minor release** → `references/minor-release.md`
-- **Patch release** (weekly / hotfix / model launch / DB migration) → `references/patch-release-scenarios.md`
-- **Writing the PR body / release notes** (any release type) → `references/release-notes-style.md`
+### Patch Release
 
-### Hard Rules (apply to every release type)
+Choose workflow by scenario (see `reference/patch-release-scenarios.md`):
 
-- **Do NOT** manually modify `package.json` version — CI handles it.
-- **Do NOT** manually create tags — CI handles them.
-- Minor PR title format is strict (`🚀 release: v{x.y.z}`).
-- Patch PRs do not need an explicit version number.
-- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `references/release-notes-style.md` § Computing Inputs — never from memory or descriptions.
+- **Weekly Release**: create `release/weekly-{YYYYMMDD}` from canary; use `git log main..canary` for release note inputs; title like `🚀 release: 20260222`
+- **Bug Hotfix**: create `hotfix/` from main; use gitmoji prefix title (e.g. `🐛 fix: ...`)
+- **New Model Launch**: community PRs trigger automatically via title prefix (`feat` / `style`)
+- **DB Migration**: create `release/db-migration-{name}` from main; cherry-pick migration commits; include dedicated migration notes
+
+### Hard Rules
+
+- **Do NOT** manually modify `package.json` version
+- **Do NOT** manually create tags
+- Minor PR title format is strict
+- Patch PRs do not need explicit version number
+- Keep release facts accurate; do not invent metrics or availability statements
+
+## GitHub Release Changelog Standard (Long-Form Style)
+
+Use this section for writing **GitHub Release notes** (or release PR body when the PR body is intended to become release notes).\
+Do not use this as `docs/changelog` page guidance.
+
+### Positioning
+
+This release-note style is:
+
+1. **Data-backed at the top** (date, range, key metrics)
+2. **Narrative first, then structured detail**
+3. **Deep but scannable** (clear sectioning + compact bullets)
+4. **Contributor-forward** (credits are part of the release story)
+
+### Required Inputs Before Writing
+
+Collect these inputs first:
+
+1. Compare range (`<prev_tag>...<current_tag>`)
+2. Release metrics (commits, merged PRs, resolved issues, contributors, optional files/insertions/deletions)
+3. High-impact changes by domain (core loop, platform/gateway, UX, tooling, security, reliability)
+4. Contributor list (with standout contributions if known)
+5. Known risks / migrations / rollout notes (if any)
+
+If metrics cannot be reliably computed, omit unknown numbers instead of guessing.
+
+### Canonical Structure
+
+Follow this section order unless the user asks otherwise:
+
+1. `# 🚀 LobeHub Release (<YYYYMMDD>)`
+2. Metadata lines:
+   - `Release Date`
+   - `Since <Previous Version>` metrics
+3. One quoted release thesis (single paragraph, 1-2 lines)
+4. `## ✨ Highlights` (6-12 bullets for major releases; 3-8 for weekly)
+5. Domain blocks with optional `###` subsections:
+   - `## 🏗️ Core Agent & Architecture` (or equivalent product core)
+   - `## 📱 Platforms / Integrations`
+   - `## 🖥️ CLI & User Experience`
+   - `## 🔧 Tooling`
+   - `## 🔒 Security & Reliability`
+   - `## 📚 Documentation` (optional if meaningful)
+6. `## 👥 Contributors`
+7. `**Full Changelog**: <prev>...<current>`
+
+Use `---` separators between major blocks for long releases.
+
+### Writing Rules (Hard)
+
+1. **No fabricated metrics**: all numbers must be traceable.
+2. **No vague headline bullets**: each bullet must include capability + impact.
+3. **No internal-only framing**: phrase from user/operator perspective.
+4. **Security must be explicit** when security-sensitive fixes are present.
+5. **PR/issue linkage**: use `(#1234)` when IDs are available.
+6. **Terminology consistency**: same feature/provider name across sections.
+7. **Do not bury migration or breaking changes**: elevate to dedicated section or callout.
+
+### Style Rules (Long-Form)
+
+1. Start with an "everyday use" framing, not implementation internals.
+2. Mix narrative sentence + evidence bullets.
+3. Keep bullets compact but informative:
+   - Good: `**Fast Mode (`/fast`)** — Priority routing for OpenAI and Anthropic, reducing latency on supported models. (#6875, #6960)`
+4. Use bold only for capability names, not for whole sentences.
+5. Keep heading depth <= 3 levels.
+
+### Release Size Heuristics
+
+- **Minor / major milestone release**
+  - Include full structure with multiple domain blocks.
+  - `Highlights` usually 8-12 bullets.
+- **Weekly patch release**
+  - Keep full skeleton but reduce subsection count.
+  - `Highlights` usually 4-8 bullets.
+- **DB migration release**
+  - Keep concise.
+  - Must include `Migration overview`, operator impact, and rollback/backup note.
+
+### Contributor Ordering
+
+Render contributors as a **single flat list** (no separate "Community" / "Core Team" subsections). Order: **community contributors first, team members after**. Within each group, sort by PR count desc. Bots (`@lobehubbot`, `renovate[bot]`) go on a separate "maintenance" line.
+
+**LobeHub team roster** — anyone in this list is a team member; anyone not in this list is a community contributor:
+
+- @arvinxx
+- @Innei
+- @tjx666 (commit author name: YuTengjing)
+- @LiJian
+- @Neko
+- @Rdmclin2
+- @AmAzing129
+- @sudongyuer
+- @rivertwilight
+- @CanisMinor
+
+> **Resolving handles** — git author names (e.g. `YuTengjing`) are not always the GitHub handle. Verify via `gh pr view <PR> --json author` or `gh api search/users -f q='<email>'` before listing.
+
+If a new contributor appears who is not on this list, treat them as community by default and ask the user whether to add them to the roster.
+
+### GitHub Release Changelog Template
+
+```md
+# 🚀 LobeHub Release (<YYYYMMDD>)
+
+**Release Date:** <Month DD, YYYY>  
+**Since <Previous Version>:** <N merged PRs> · <N resolved issues> · <N contributors>
+
+> <One release thesis sentence: what this release unlocks in practice.>
+
+---
+
+## ✨ Highlights
+
+- **<Capability A>** — <What changed and why it matters>. (#1234)
+- **<Capability B>** — <What changed and why it matters>. (#2345)
+- **<Capability C>** — <What changed and why it matters>. (#3456)
+
+---
+
+## 🏗️ Core Product & Architecture
+
+### <Subdomain>
+
+- <Concrete change + impact>. (#...)
+- <Concrete change + impact>. (#...)
+
+---
+
+## 📱 Platforms / Integrations
+
+- <Platform update + impact>. (#...)
+- <Compatibility/reliability fix + impact>. (#...)
+
+---
+
+## 🖥️ CLI & User Experience
+
+- <User-facing workflow improvement>. (#...)
+- <Quality-of-life fix>. (#...)
+
+---
+
+## 🔧 Tooling
+
+- <Tool/runtime improvement>. (#...)
+
+---
+
+## 🔒 Security & Reliability
+
+- **Security:** <hardening or vulnerability fix>. (#...)
+- **Reliability:** <stability/performance behavior improvement>. (#...)
+
+---
+
+## 👥 Contributors
+
+Huge thanks to **<N contributors>** who shipped **<N merged PRs>** this cycle.
+
+@<community-handle> · @<community-handle> · @<team-handle> · @<team-handle>
+
+Plus @lobehubbot and renovate[bot] for maintenance.
+
+---
+
+**Full Changelog**: <previous_tag>...<current_tag>
+```
+
+### Quick Checklist
+
+- [ ] Uses top metadata and a clear release thesis
+- [ ] Includes `Highlights` plus domain-grouped sections
+- [ ] Every major bullet states both change and user/operator impact
+- [ ] Security and reliability updates are explicitly surfaced (when present)
+- [ ] Contributor credits and compare range are included
+- [ ] All numbers and claims are verifiable

.agents/skills/version-release/reference/patch-release-scenarios.md

@@ -21,16 +21,12 @@ git push -u origin release/weekly-{YYYYMMDD}
 
 2. **Scan changes and write changelog**
 
-Compute the previous tag from main first — never reuse the last weekly's tag, since hotfixes published in between will be missed:
-
 ```bash
-git fetch origin main canary --tags
-PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
-git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --oneline --no-merges
-git diff "$PREV_TAG...origin/release/weekly-{YYYYMMDD}" --stat
+git log main..canary --oneline
+git diff main...canary --stat
 ```
 
-Then follow `./release-notes-style.md` § **Computing Inputs (Hard Rules)** to derive PR refs, metrics, and contributors. Every `(#XXXX)` in the body must come from actual commit subjects in this range — never inferred from descriptions.
+Write a user-facing changelog following the format in `patch-release-changelog-example.md`.
 
 3. **Create PR to main** with the changelog as the PR body
 

.agents/skills/version-release/references/minor-release.md

@@ -1,47 +0,0 @@
-# Minor Release Workflow
-
-Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks. The PR title carries the exact version number; CI parses it to drive the rest of the release.
-
-## Steps
-
-1. **Create a release branch from canary**
-
-   ```bash
-   git checkout canary
-   git pull origin canary
-   git checkout -b release/v{version}
-   git push -u origin release/v{version}
-   ```
-
-2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. `2.1.x` → `2.2.0`).
-
-3. **Create a PR to main**
-
-   ```bash
-   gh pr create \
-     --title "🚀 release: v{version}" \
-     --base main \
-     --head release/v{version} \
-     --body-file release_body.md
-   ```
-
-   > \[!IMPORTANT]
-   > The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
-
-4. **Write the PR body as release notes** — Follow `release-notes-style.md`. Compare base is the latest semver tag on main (`git describe --tags --abbrev=0 origin/main`).
-
-5. **Automatic trigger after merge** — `auto-tag-release` detects the title format, uses the version number from the title, bumps `package.json`, tags `v{x.y.z}`, creates the GitHub Release, and dispatches `sync-main-to-canary`.
-
-## Scripts
-
-```bash
-bun run release:branch         # Interactive
-bun run release:branch --minor # Directly specify minor
-```
-
-## Hard Rules (specific to Minor)
-
-- PR title format is **strict**: `🚀 release: v{x.y.z}`. Any deviation falls through to patch detection.
-- Do **NOT** manually modify `package.json` version — CI will bump it.
-- Do **NOT** manually create the tag — CI will tag.
-- Highlights bullet count is usually 8–12 (see `release-notes-style.md` size heuristics).

.agents/skills/version-release/references/release-notes-style.md

@@ -1,330 +0,0 @@
-# GitHub Release Changelog Standard (Long-Form Style)
-
-Use this guide for **GitHub Release notes** — the body of a release PR that becomes the GitHub Release after merge. Do **not** use it for `docs/changelog/*.mdx` website pages (load `../../docs-changelog/SKILL.md` instead).
-
-## Table of Contents
-
-1. [Positioning](#positioning) — what this style optimizes for
-2. [Required Inputs Before Writing](#required-inputs-before-writing)
-3. [Computing Inputs (Hard Rules — Verify, Never Guess)](#computing-inputs-hard-rules--verify-never-guess) — base ref, PR refs, metrics, authors, pre-publish verification
-4. [Canonical Structure (Long-Form: Minor / Weekly)](#canonical-structure-long-form-minor--weekly)
-5. [Variants for Shorter Releases](#variants-for-shorter-releases) — hotfix, DB migration
-6. [Writing Rules (Hard)](#writing-rules-hard)
-7. [Style Rules (Long-Form)](#style-rules-long-form)
-8. [Release Size Heuristics](#release-size-heuristics) — when to use which variant
-9. [Contributor Ordering](#contributor-ordering)
-10. [Template](#template) — copy-paste skeleton
-11. [Quick Checklist](#quick-checklist) — long-form + hotfix
-
-## Positioning
-
-This release-note style is:
-
-1. **Data-backed at the top** (date, range, key metrics)
-2. **Narrative first, then structured detail**
-3. **Deep but scannable** (clear sectioning + compact bullets)
-4. **Contributor-forward** (credits are part of the release story)
-
-## Required Inputs Before Writing
-
-Collect these inputs first:
-
-1. Compare range (`<prev_tag>...<current_tag>`)
-2. Release metrics (commits, merged PRs, resolved issues, contributors, optional files/insertions/deletions)
-3. High-impact changes by domain (core loop, platform/gateway, UX, tooling, security, reliability)
-4. Contributor list (with standout contributions if known)
-5. Known risks / migrations / rollout notes (if any)
-
-If metrics cannot be reliably computed, omit unknown numbers instead of guessing.
-
-## Computing Inputs (Hard Rules — Verify, Never Guess)
-
-> Hallucinated PR numbers and wrong "Since v..." bases are the #1 failure mode of this skill. Every number and every `(#XXXX)` must come from `git`, never from memory or inference.
-
-### 1. Compare base = latest semver tag on `main`
-
-Do **not** eyeball the tag list or pick the "last weekly" PR. Compute it:
-
-```bash
-git fetch origin main canary --tags
-PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
-echo "$PREV_TAG"
-```
-
-Sanity check that the tag is reachable from the release branch:
-
-```bash
-git merge-base --is-ancestor "$PREV_TAG" origin/release/weekly-{YYYYMMDD} && echo OK
-```
-
-If the check fails, stop and ask the user — the release branch is based on the wrong source.
-
-> **Why not "the last weekly release PR"?** Hotfixes (`v2.1.54`, `v2.1.55`, …) merge directly into main between weeklies. They get back-merged via `sync-main-to-canary`, so the latest semver tag on main _is_ the correct previous release for both weekly and minor flows. Picking the previous weekly's tag will silently undercount and put a stale version in "Since v…".
-
-### 2. PR refs must come from commit subjects — never from descriptions
-
-Compute the canonical set:
-
-```bash
-git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" \
-  --pretty=format:'%s' --no-merges \
-  | grep -oE '\(#[0-9]+\)$' \
-  | sort -u > /tmp/release_prs.txt
-```
-
-Hard rules:
-
-- Every `(#XXXX)` you write in the body **must** appear in `/tmp/release_prs.txt`. No exceptions.
-- Never infer a PR number from a feature description. If you remember "the KB BM25 PR was around #14501", that memory is wrong about half the time. Look up the commit hash by feature keyword and read its actual subject.
-- If your terminal truncates long subjects (any wrapper that compresses output, e.g. `rtk`), bypass it. With `rtk` use `rtk proxy git log …`. Verify with `wc -l /tmp/release_prs.txt` — the count must match `git log $PREV_TAG..HEAD --no-merges --pretty=format:'%h' | wc -l` minus the few commits without a PR ref. A mismatch of >5% means subjects are being silently truncated.
-
-### 3. Metrics must come from git counts
-
-```bash
-PR_COUNT=$(wc -l < /tmp/release_prs.txt | tr -d ' ')
-
-COMMIT_COUNT=$(git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --no-merges --pretty=format:'%h' | wc -l | tr -d ' ')
-
-CONTRIBUTOR_COUNT=$(git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --no-merges --pretty=format:'%an' \
-  | sort -u \
-  | grep -viE '^(lobehubbot|LobeHub Bot|renovate\[bot\])$' \
-  | wc -l | tr -d ' ')
-```
-
-If a number cannot be confidently derived, omit it — never guess.
-
-### 4. Author-to-handle resolution
-
-Git `%an` is the commit author display name, not the GitHub handle. For each author you mention, confirm the handle:
-
-```bash
-gh pr view "$PR_NUMBER" --repo lobehub/lobe-chat --json author --jq '.author.login'
-```
-
-Use the result for `@handle`. Then classify each author per the `LobeHub team roster` below; community first, team after.
-
-### 5. Pre-publish verification (mandatory)
-
-Before `gh pr create` / `gh pr edit --body-file`, diff body PR refs against the canonical set:
-
-```bash
-grep -oE '#[0-9]+' release_body.md | sort -u > /tmp/body_prs.txt
-sed 's/[()]//g' /tmp/release_prs.txt > /tmp/release_prs_clean.txt
-
-echo "=== In body but NOT in actual range (must be EMPTY) ==="
-comm -23 /tmp/body_prs.txt /tmp/release_prs_clean.txt
-```
-
-Empty diff = OK. Any output = the body cites a PR that wasn't merged in this range. Stop and fix before publishing.
-
-Also verify the metrics line in the body matches the computed values (`PR_COUNT`, `CONTRIBUTOR_COUNT`) and that `**Full Changelog**` uses `$PREV_TAG`, not some older tag.
-
-## Canonical Structure (Long-Form: Minor / Weekly)
-
-Follow this section order for **Minor** and **Weekly** releases unless the user asks otherwise. For **Hotfix** and **DB Migration**, see § Variants for Shorter Releases below — the canonical structure does not apply.
-
-1. `# 🚀 LobeHub Release (<YYYYMMDD>)`
-2. Metadata lines:
-   - `Release Date`
-   - `Since <Previous Version>` metrics
-3. One quoted release thesis (single paragraph, 1-2 lines)
-4. `## ✨ Highlights` (6-12 bullets for major releases; 3-8 for weekly)
-5. Domain blocks with optional `###` subsections:
-   - `## 🏗️ Core Agent & Architecture` (or equivalent product core)
-   - `## 📱 Platforms / Integrations`
-   - `## 🖥️ CLI & User Experience`
-   - `## 🔧 Tooling`
-   - `## 🔒 Security & Reliability`
-   - `## 📚 Documentation` (optional if meaningful)
-6. `## 👥 Contributors`
-7. `**Full Changelog**: <prev>...<current>`
-
-Use `---` separators between major blocks for long releases.
-
-## Variants for Shorter Releases
-
-The Canonical Structure above is for **long-form** (Minor / Weekly). Two short-form variants override it.
-
-### Hotfix Variant
-
-A hotfix targets one regression and ships fast. The body is short and operator-focused — no Highlights, no domain blocks, no Contributors line.
-
-Required sections, in order:
-
-1. `# 🚀 LobeHub Release (<YYYYMMDD>)`
-2. `**Hotfix Scope:**` — one line summarizing the regression scope (e.g. `Agent topic-switching regression — stale chat state on agent change`). Replaces the long-form `Release Date` / `Since vX.Y.Z` metrics.
-3. One quoted thesis (single paragraph, 1-2 lines) describing what is now restored.
-4. `## 🐛 What's Fixed` — 1-3 bullets, each `**<symptom>** — <fix in one sentence>. (#PR)`. No root-cause prose; that lives in the commit message.
-5. `## ⚙️ Upgrade` — short notes for self-hosted (pull image / restart, schema or env changes) and cloud (usually "applied automatically").
-6. `## 👥 Owner` — single `@handle` for the PR author, resolved via `gh pr view "$PR" --json author --jq '.author.login'`. Never hardcoded.
-
-Hard rules specific to hotfix:
-
-- **No Highlights / domain blocks / Contributors / Full Changelog** — these add noise to a one-shot fix.
-- **No metric line** — `Since vX.Y.Z` doesn't apply; the body cites the single PR (or 1-3 PRs) directly.
-- **Owner ≠ Contributors** — one author, listed under § Owner. Not a flat handle list.
-- See `changelog-example/hotfix.md` for the canonical template.
-
-### DB Migration Variant
-
-Database schema changes that need to be released independently. Operator impact is the headline.
-
-Required sections, in order:
-
-1. `# 🚀 LobeHub Release (<YYYYMMDD>)` + scope line
-2. **Migration overview** — what tables / columns are added, modified, or removed
-3. **Operator impact** — backwards-compatible? required actions for self-hosted?
-4. **Rollback / backup note** — how to recover
-5. `## 👥 Owner` — single PR author, resolved via `gh pr view`
-
-See `changelog-example/db-migration.md` for the canonical template.
-
-## Writing Rules (Hard)
-
-1. **No fabricated metrics**: all numbers must be traceable.
-2. **No vague headline bullets**: each bullet must include capability + impact.
-3. **No internal-only framing**: phrase from user/operator perspective.
-4. **Security must be explicit** when security-sensitive fixes are present.
-5. **PR/issue linkage**: use `(#1234)` when IDs are available.
-6. **Terminology consistency**: same feature/provider name across sections.
-7. **Do not bury migration or breaking changes**: elevate to dedicated section or callout.
-
-## Style Rules (Long-Form)
-
-1. Start with an "everyday use" framing, not implementation internals.
-2. Mix narrative sentence + evidence bullets.
-3. Keep bullets compact but informative:
-   - Good: `**Fast Mode (`/fast`)** — Priority routing for OpenAI and Anthropic, reducing latency on supported models. (#6875, #6960)`
-4. Use bold only for capability names, not for whole sentences.
-5. Keep heading depth ≤ 3 levels.
-
-## Release Size Heuristics
-
-- **Minor / major milestone release**
-  - Long-form structure with multiple domain blocks.
-  - `Highlights` usually 8-12 bullets.
-- **Weekly patch release**
-  - Long-form skeleton with reduced subsection count.
-  - `Highlights` usually 4-8 bullets.
-- **Hotfix release**
-  - Short-form (see § Variants → Hotfix). No Highlights, no domain blocks, no Contributors.
-  - 1-3 fix bullets. Body should fit on one screen.
-- **DB migration release**
-  - Short-form (see § Variants → DB Migration).
-  - Must include `Migration overview`, operator impact, and rollback/backup note.
-
-## Contributor Ordering
-
-Render contributors as a **single flat list** (no separate "Community" / "Core Team" subsections). Order: **community contributors first, team members after**. Within each group, sort by PR count desc. Bots (`@lobehubbot`, `renovate[bot]`) go on a separate "maintenance" line.
-
-**LobeHub team roster** — anyone in this list is a team member; anyone not in this list is a community contributor:
-
-- @arvinxx
-- @Innei
-- @tjx666 (commit author name: YuTengjing)
-- @LiJian
-- @Neko
-- @Rdmclin2
-- @AmAzing129
-- @sudongyuer (commit author name: Tsuki)
-- @rivertwilight (commit author name: René Wang)
-- @CanisMinor
-- @cy948 (commit author name: Rylan Cai)
-
-> **Resolving handles** — git author names (e.g. `YuTengjing`) are not always the GitHub handle. Verify via `gh pr view "$PR" --json author` or `gh api search/users -f q='<email>'` before listing.
-
-If a new contributor appears who is not on this list, treat them as community by default and ask the user whether to add them to the roster.
-
-## Template
-
-```md
-# 🚀 LobeHub Release (<YYYYMMDD>)
-
-**Release Date:** <Month DD, YYYY>  
-**Since <Previous Version>:** <N merged PRs> · <N resolved issues> · <N contributors>
-
-> <One release thesis sentence: what this release unlocks in practice.>
-
----
-
-## ✨ Highlights
-
-- **<Capability A>** — <What changed and why it matters>. (#1234)
-- **<Capability B>** — <What changed and why it matters>. (#2345)
-- **<Capability C>** — <What changed and why it matters>. (#3456)
-
----
-
-## 🏗️ Core Product & Architecture
-
-### <Subdomain>
-
-- <Concrete change + impact>. (#...)
-- <Concrete change + impact>. (#...)
-
----
-
-## 📱 Platforms / Integrations
-
-- <Platform update + impact>. (#...)
-- <Compatibility/reliability fix + impact>. (#...)
-
----
-
-## 🖥️ CLI & User Experience
-
-- <User-facing workflow improvement>. (#...)
-- <Quality-of-life fix>. (#...)
-
----
-
-## 🔧 Tooling
-
-- <Tool/runtime improvement>. (#...)
-
----
-
-## 🔒 Security & Reliability
-
-- **Security:** <hardening or vulnerability fix>. (#...)
-- **Reliability:** <stability/performance behavior improvement>. (#...)
-
----
-
-## 👥 Contributors
-
-Huge thanks to **<N contributors>** who shipped **<N merged PRs>** this cycle.
-
-@<community-handle> · @<community-handle> · @<team-handle> · @<team-handle>
-
-Plus @lobehubbot and renovate[bot] for maintenance.
-
----
-
-**Full Changelog**: <previous_tag>...<current_tag>
-```
-
-## Quick Checklist
-
-### Long-Form (Minor / Weekly)
-
-- [ ] `PREV_TAG` is `git describe --tags --abbrev=0 origin/main` (latest semver), not the last weekly's tag
-- [ ] Every `(#XXXX)` in the body appears in `/tmp/release_prs.txt` (verified via `comm -23`)
-- [ ] `Since v…` line uses `$PREV_TAG`; PR / contributor counts match `wc -l` on the computed sets
-- [ ] `**Full Changelog**` uses `$PREV_TAG...release/weekly-<YYYYMMDD>` (or `…v{x.y.z}` for minor)
-- [ ] Author handles resolved via `gh pr view --json author`, not assumed from `%an`
-- [ ] Uses top metadata and a clear release thesis
-- [ ] Includes `Highlights` plus domain-grouped sections
-- [ ] Every major bullet states both change and user/operator impact
-- [ ] Security and reliability updates are explicitly surfaced (when present)
-- [ ] Contributor credits and compare range are included
-- [ ] All numbers and claims are verifiable
-
-### Hotfix
-
-- [ ] `**Hotfix Scope:**` line replaces metrics line
-- [ ] Single quoted thesis describes what is restored (operator-facing, not internal)
-- [ ] `## 🐛 What's Fixed` has 1-3 bullets, each `**<symptom>** — <fix>. (#PR)` with PR ref verified to exist and be merged
-- [ ] `## ⚙️ Upgrade` notes self-hosted action and cloud auto-apply
-- [ ] `## 👥 Owner` is a single `@handle` resolved via `gh pr view "$PR" --json author`
-- [ ] No Highlights / domain blocks / Contributors / Full Changelog included

.agents/skills/zustand/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: zustand
-description: 'LobeHub Zustand store conventions. Use when editing src/store, store slices, public/internal actions, dispatch actions, flattenActions, optimistic updates, selectors, maps, or class action migration.'
-user-invocable: false
+description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
 ---
 
 # LobeHub Zustand State Management
@@ -177,12 +176,29 @@ export const chatGroupAction: StateCreator<
 
 ### Slices That Don't Currently Need `set`
 
-When a slice doesn't write local state (e.g. it delegates to another store or just runs hooks), drop `#set` and mark the constructor param as `_set` with `void _set` to keep the `(set, get, api)` shape:
+When a slice doesn't write local state at the moment — e.g. it reads context
+from `#get()` and forwards calls to another store, or just runs hooks — drop
+the `#set` field. Otherwise ESLint's `no-unused-vars` flags the unused private
+field.
+
+Mark the constructor's `set` param as `_set` and `void _set` it to keep the
+`(set, get, api)` shape aligned with `StateCreator`. This is **a snapshot of
+the current need, not a permanent contract** — if a later change needs `set`,
+restore the `#set` field and use it; do not invent a workaround to keep the
+"unused" form.
 
 ```ts
+type Setter = StoreSetter<ConversationStore>;
+
+export const toolSlice = (set: Setter, get: () => ConversationStore, _api?: unknown) =>
+  new ToolActionImpl(set, get, _api);
+
 export class ToolActionImpl {
   readonly #get: () => ConversationStore;
 
+  // Mark unused params with `_` prefix and `void _x` so the constructor still
+  // matches StateCreator's `(set, get, api)` shape without triggering unused
+  // diagnostics.
   constructor(_set: Setter, get: () => ConversationStore, _api?: unknown) {
     void _set;
     void _api;
@@ -195,8 +211,27 @@ export class ToolActionImpl {
     hooks.onToolCallComplete?.(id, undefined);
   };
 }
+
+export type ToolAction = Pick<ToolActionImpl, keyof ToolActionImpl>;
 ```
 
-- Drop `#set` when unused; restore it when a later edit needs `set` — re-adding costs nothing.
-- Don't add `setNamespace` for slices that don't write state.
-- Don't keep both old slice objects and class actions active at the same time during migration.
+Rules of thumb:
+
+- If a slice doesn't currently call `set`, drop `#set` (use `_set` + `void _set`
+  in the constructor). When a later edit needs `set`, restore `#set` and use it.
+- Don't add `setNamespace` for slices that don't write state. Add it when the
+  slice starts writing state.
+- Never leave `#set` declared but unused "for future use" — lint will fail and
+  re-adding it later costs nothing.
+
+### Do / Don't
+
+- **Do**: keep constructor signature aligned with `StateCreator` params `(set, get, api)`.
+- **Do**: use `#private` to avoid `set/get` being exposed.
+- **Do**: use `flattenActions` instead of spreading class instances.
+- **Do**: drop `#set` (and use `_set` + `void _set` in the constructor) for
+  delegate-only slices that never write state — keeps lint green without
+  breaking the `(set, get, api)` shape.
+- **Don't**: keep both old slice objects and class actions active at the same time.
+- **Don't**: keep an unused `#set` field "for future use" — it fails ESLint and
+  re-adding it later costs nothing.

.claude/prompts/issue-triage.md

@@ -1,10 +1,6 @@
 # Issue Triage Guide
 
-This guide is used for triaging GitHub issues — analyzing issues and applying only the most essential business-domain labels.
-
-## Core Principle
-
-**Each issue should have 1-3 labels that describe its core business domain.** Do NOT apply redundant labels that can be inferred from other labels. Less is more.
+This guide is used for batch triaging GitHub issues - analyzing issues and applying appropriate labels.
 
 ## Workflow
 
@@ -24,76 +20,23 @@ For each issue number, run:
 gh issue view [ISSUE_NUMBER] --json number,title,body,labels,comments
 ```
 
-### Step 3: Select Labels (1-3 per issue)
+### Step 3: Analyze and Select Labels
 
-Only apply labels from these THREE categories:
+Extract information from the issue template and content:
 
-#### Category 1: Technology Carrier
+#### Template Fields Mapping
 
-The runtime environment or technology wrapper where the issue occurs:
+- 📦 Platform field → `platform:web/desktop/mobile`
+- 💻 Operating System → `os:windows/macos/linux/ios`
+- 🌐 Browser → `device:pc/mobile`
+- 📦 Deployment mode → `deployment:server/client/pglite`
+- Platform (hosting) → `hosting:cloud/self-host/vercel/zeabur/railway`
 
-| Label | When to apply |
-|-------|--------------|
-| `electron` | Desktop/Electron-specific issues. This REPLACES `platform:desktop`, `os:*`, `deployment:*`, `hosting:*` — do NOT add those. |
-| `pwa` | PWA/mobile-app-specific issues |
-| `docker` | Docker-specific deployment issues |
+#### Provider Detection
 
-**Rule**: If `electron` is applied, do NOT add `platform:desktop`, `os:*`, `deployment:*`, or `hosting:*`. The `electron` label already implies all of these.
+**IMPORTANT**: Always check issue title and body for provider mentions!
 
-#### Category 2: Feature / Component
-
-The functional area affected. Select the 1-2 MOST relevant:
-
-Core Features:
-
-- `feature:agent` - Agent/Assistant functionality
-- `feature:topic` - Topic/Conversation management
-- `feature:marketplace` - Agent/plugin marketplace
-- `feature:settings` - Settings and configuration
-
-Content & Knowledge:
-
-- `feature:editor` - Lobe Editor / rich text / markdown rendering
-- `feature:markdown` - Markdown rendering (if separate from editor)
-- `feature:files` - File upload/management
-- `feature:knowledge-base` - Knowledge base and RAG
-- `feature:export` - Export functionality
-
-Model Capabilities:
-
-- `feature:tool` - Tool calling and function execution
-- `feature:streaming` - Streaming responses
-- `feature:vision` - Vision/multimodal capabilities
-- `feature:image` - AI image generation
-- `feature:tts` - Text-to-speech
-
-Technical:
-
-- `feature:api` - Backend API
-- `feature:auth` - Authentication/authorization
-- `feature:sync` - Cloud sync functionality
-- `feature:search` - Search functionality
-- `feature:mcp` - MCP integration
-- `feature:thread` - Thread/Subtopic functionality
-
-Collaboration:
-
-- `feature:group-chat` - Group chat functionality
-- `feature:memory` - Memory feature
-- `feature:team-workspace` - Team workspace
-- `feature:im-integration` - IM and bot integration
-
-Other:
-
-- `feature:schedule-task` - Scheduled task functionality
-
-**Rule**: Pick only the 1-2 most specific feature labels. Don't stack multiple features unless the issue genuinely spans multiple areas.
-
-#### Category 3: Model Provider
-
-Only when the issue is SPECIFICALLY about a provider's behavior:
-
-**Official Providers** (check title and body for these keywords):
+**Official Providers** (check for these keywords in title/body):
 
 - `openai`, `gpt` → `provider:openai`
 - `gemini` → `provider:gemini`
@@ -114,100 +57,197 @@ Only when the issue is SPECIFICALLY about a provider's behavior:
 **Third-party Aggregation Providers**:
 
 - `aihubmix`, `AIHubMix`, `AIHUBMIX` → `provider:aihubmix`
-- `zenmux` → `provider:zenmux`
+- Check environment variables like `AIHUBMIX_*` in issue body
 
-**Rule**: Only add a provider label if the issue is specifically about that provider's behavior (e.g., "Gemini returns error X"). Do NOT add provider labels just because the issue template mentions a provider.
+**Multiple Providers**: If issue mentions multiple providers, add ALL applicable provider labels.
 
-#### Special Labels (use sparingly)
+### Label Categories
+
+#### a) Issue Type (select ONE if applicable)
+
+- `💄 Design` - UI/UX design issues
+- `📝 Documentation` - Documentation improvements
+- `⚡️ Performance` - Performance optimization
+
+#### b) Priority (select ONE if applicable)
+
+- `priority:high` - Critical issues, data loss, security, maintainer mentions "urgent"/"serious"/"critical"
+- `priority:medium` - Important issues affecting multiple users, significant functionality impact
+- `priority:low` - Nice to have, minor issues, edge cases
+
+**Priority Guidelines**:
+
+- Set `priority:high` for: data loss, authentication failures, deployment blockers, critical bugs
+- Set `priority:medium` for: feature bugs affecting multiple users, workflow issues
+- Set `priority:low` for: cosmetic issues, feature requests, configuration questions
+
+#### c) Platform (select ALL applicable)
+
+- `platform:web`
+- `platform:desktop`
+- `platform:mobile`
+
+#### d) Device (for platform:web, select ONE)
+
+- `device:pc`
+- `device:mobile`
+
+#### e) Operating System (select ALL applicable)
+
+- `os:windows`
+- `os:macos`
+- `os:linux`
+- `os:ios`
+- `os:android`
+
+#### f) Hosting Platform (select ONE)
+
+- `hosting:cloud` - Official LobeHub Cloud
+- `hosting:self-host` - Self-hosted deployment
+- `hosting:vercel` - Vercel deployment
+- `hosting:zeabur` - Zeabur deployment
+- `hosting:railway` - Railway deployment
+
+#### g) Deployment Mode (select ONE if mentioned)
+
+- `deployment:server` - Server-side database mode
+- `deployment:client` - Client-side database mode
+- `deployment:pglite` - PGLite mode
+
+**Additional deployment tags**:
+
+- `docker` - If using Docker deployment
+- `electron` - If desktop/Electron specific
+
+#### h) Model Provider (select ALL applicable)
+
+See "Provider Detection" section above for complete list.
+
+**IMPORTANT**: Always scan issue title and body for provider keywords!
+
+#### i) Feature/Component (select ALL applicable)
+
+Core Features:
+
+- `feature:settings` - Settings and configuration
+- `feature:agent` - Agent/Assistant functionality
+- `feature:topic` - Topic/Conversation management
+- `feature:marketplace` - Agent marketplace
+
+File & Knowledge:
+
+- `feature:files` - File upload/management
+- `feature:knowledge-base` - Knowledge base and RAG
+- `feature:export` - Export functionality
+
+Model Capabilities:
+
+- `feature:streaming` - Streaming responses
+- `feature:tool` - Tool calling
+- `feature:vision` - Vision/multimodal capabilities
+- `feature:image` - AI image generation
+- `feature:dalle` - DALL-E specific
+- `feature:tts` - Text-to-speech
+
+Technical:
+
+- `feature:api` - Backend API
+- `feature:auth` - Authentication/authorization
+- `feature:sync` - Cloud sync functionality
+- `feature:search` - Search functionality
+- `feature:mcp` - MCP integration
+- `feature:editor` - Lobe Editor
+- `feature:markdown` - Markdown rendering
+- `feature:thread` - Thread/Subtopic functionality
+
+Collaboration:
+
+- `feature:group-chat` - Group chat functionality
+- `feature:memory` - Memory feature
+- `feature:team-workspace` - Team workspace
+
+#### j) Workflow/Status
 
-- `i18n` - Internationalization / translation issues
 - `Duplicate` - Only if duplicate of an OPEN issue (mention issue number)
-- `🤔 Need Reproduce` - Needs reproduction steps
+- `needs-reproduction` - Cannot reproduce, needs more information
 - `good-first-issue` - Good for first-time contributors
+- `🤔 Need Reproduce` - Needs reproduction steps
 
 ### Step 4: Apply Labels
 
+Add labels (comma-separated, no spaces after commas):
+
+```bash
+gh issue edit [ISSUE_NUMBER] --add-label "label1,label2,label3"
+```
+
+Remove "unconfirm" label if adding other labels:
+
 ```bash
-gh issue edit [ISSUE_NUMBER] --add-label "label1,label2"
 gh issue edit [ISSUE_NUMBER] --remove-label "unconfirm"
 ```
 
+**Important**: Combine both commands when possible for efficiency.
+
 ### Step 5: Log Summary
 
-For each issue, provide a brief reasoning (1-2 sentences) explaining why each label was chosen.
+For each issue, provide reasoning (2-4 sentences):
 
-## What NOT to Label
-
-These categories are INTENTIONALLY OMITTED — do NOT apply them:
-
-| Do NOT apply | Reason |
-|-------------|--------|
-| `platform:web`, `platform:desktop`, `platform:mobile` | Inferred from `electron`/`pwa` or issue context |
-| `os:windows`, `os:macos`, `os:linux`, `os:ios`, `os:android` | Low triage value; inferred from `electron` |
-| `device:pc`, `device:mobile` | Redundant with platform |
-| `hosting:cloud`, `hosting:self-host`, `hosting:vercel`, etc. | Low triage value unless deployment-specific |
-| `deployment:server`, `deployment:client`, `deployment:pglite` | Low triage value; inferred from `electron` |
-| `priority:high`, `priority:medium`, `priority:low` | Maintainers judge priority themselves |
-| `🐛 Bug`, `💄 Design`, `📝 Documentation`, `⚡️ Performance` | Issue type is already indicated by GitHub issue template |
-| `Inactive` | Handled separately; do NOT add during triage |
-
-## Examples
-
-### Example 1: Electron desktop bug
-
-**Issue**: "Connection failure when executing tasks on macOS desktop app"
-
-**Analysis**: Desktop Electron app issue with task scheduling.
-
-**Labels**: `electron,feature:schedule-task`
-
-**Why**: `electron` covers the desktop platform. `feature:schedule-task` identifies the affected feature. No need for `platform:desktop`, `os:macos`, `hosting:cloud`, `priority:*`, or `Bug`.
-
-### Example 2: Provider-specific issue
-
-**Issue**: "Gemini tool calling returns empty response on desktop"
-
-**Analysis**: Desktop app issue, but the core problem is Gemini provider behavior with tool calling.
-
-**Labels**: `electron,provider:gemini`
-
-**Why**: `electron` for the desktop context. `provider:gemini` because the issue is about Gemini's behavior. The tool calling aspect is secondary — the provider is the key domain.
-
-### Example 3: Feature-specific issue
-
-**Issue**: "Underscore auto-escaped in markdown editor"
-
-**Analysis**: Markdown rendering bug in the editor component.
-
-**Labels**: `feature:markdown`
-
-**Why**: Single label is sufficient — the issue is purely about markdown rendering. No need for platform, OS, or priority labels.
-
-### Example 4: Web-only feature request
-
-**Issue**: "Add search functionality to plugin marketplace"
-
-**Analysis**: Feature request for marketplace search. Web platform, no specific provider.
-
-**Labels**: `feature:marketplace,feature:search`
-
-**Why**: Two feature labels capture the core domain. No platform label needed — it's a web app by default.
-
-### Example 5: Ollama self-hosted issue
-
-**Issue**: "Ollama model not loading on self-hosted Docker deployment"
-
-**Analysis**: Provider-specific issue with Ollama on Docker.
-
-**Labels**: `docker,provider:ollama`
-
-**Why**: `docker` for the deployment context, `provider:ollama` for the model provider. No need for `hosting:self-host` or `platform:*`.
+- Labels applied and why
+- Key factors from issue template/comments
+- Provider detection reasoning (if applicable)
 
 ## Important Rules
 
-1. **1-3 labels per issue** — Never exceed 3 labels. If you find yourself adding more, you're being too granular.
-2. **`electron` replaces all platform/OS/deployment labels** — Never combine `electron` with `platform:desktop`, `os:*`, `deployment:*`, or `hosting:*`.
-3. **Provider only when relevant** — Only add `provider:*` if the issue is specifically about that provider's behavior.
-4. **No priority, no type** — Do NOT add `priority:*`, `🐛 Bug`, `💄 Design`, etc. Maintainers handle these.
-5. **No comments** — Only apply labels. Do NOT post comments to issues.
-6. **Remove `unconfirm`** — Always remove the `unconfirm` label when applying triage labels.
+1. **Read Carefully**: Read issue template fields AND issue body/title for complete context
+2. **Provider Detection**: ALWAYS check title and body for provider keywords (including aihubmix, etc.)
+3. **Multiple Categories**: Use ALL applicable labels from different categories
+4. **Label Prefixes**: Always use proper prefixes (`feature:`, `provider:`, `os:`, `platform:`, etc.)
+5. **Maintainer Comments**: Check maintainer comments for priority/status hints
+6. **No Comments**: Only apply labels, DO NOT post comments to issues
+7. **Batch Efficiency**: Process issues in parallel when possible
+
+## Common Patterns
+
+### Provider in Environment Variables
+
+If issue body contains `AIHUBMIX_*`, add `provider:aihubmix`
+
+### Multiple Provider Issues
+
+If comparing providers (e.g., "works with OpenAI but not Gemini"), add both provider labels
+
+### Desktop Issues
+
+Desktop issues often need: `platform:desktop`, `electron`, specific `os:*`, and `deployment:client` or `deployment:server`
+
+### Knowledge Base Issues
+
+Usually need: `feature:knowledge-base`, often with `feature:files`, may need `provider:*` for embedding models
+
+### Tool Calling Issues
+
+Usually need: `feature:tool`, specific `provider:*`, may need `feature:mcp` if MCP-related
+
+### Streaming Issues
+
+Usually need: `feature:streaming`, specific `provider:*`, check for timeout/performance issues
+
+## Example Triage
+
+**Issue #8850**: "aihubmix 的优惠 app 没有生效"
+
+**Analysis**:
+
+- Title contains "aihubmix" → `provider:aihubmix`
+- Template shows: Windows, Chrome, Docker, Client mode
+- About API discount codes not working
+
+**Labels Applied**:
+
+```bash
+gh issue edit 8850 --add-label "provider:aihubmix,platform:web,os:windows,deployment:client,hosting:self-host,docker"
+gh issue edit 8850 --remove-label "unconfirm"
+```
+
+**Reasoning**: AIHubMix provider discount feature not working. Client mode deployment on Windows with Docker. Provider detection from title keyword "aihubmix".

.cursorindexingignore

@@ -1,7 +1,6 @@
 # Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
-
 locales/
 apps/desktop/resources/locales/
 **/__snapshots__/
 **/fixtures/
-packages/database/migrations/
+src/database/migrations/

.env.example

@@ -56,6 +56,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # add your custom model name, multi model separate by comma. for example gpt-3.5-1106,gpt-4-1106
 # OPENAI_MODEL_LIST=gpt-3.5-turbo
 
+
 # ## Azure OpenAI ###
 
 # you can learn azure OpenAI Service on https://learn.microsoft.com/en-us/azure/ai-services/openai/overview
@@ -70,6 +71,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # Azure's API version, follows the YYYY-MM-DD format
 # AZURE_API_VERSION=2024-10-21
 
+
 # ## Anthropic Service ####
 
 # ANTHROPIC_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -77,19 +79,19 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # use a proxy to connect to the Anthropic API
 # ANTHROPIC_PROXY_URL=https://api.anthropic.com
 
-# Anthropic SDK client timeout in milliseconds
-# ANTHROPIC_CLIENT_TIMEOUT=295000
 
 # ## Google AI  ####
 
 # GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+
 # ## AWS Bedrock  ###
 
 # AWS_REGION=us-east-1
 # AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxx
 # AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+
 # ## Ollama AI ####
 
 # You can use ollama to get and run LLM locally, learn more about it via https://github.com/ollama/ollama
@@ -99,11 +101,13 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 
 # OLLAMA_MODEL_LIST=your_ollama_model_names
 
+
 # ## OpenRouter Service ###
 
 # OPENROUTER_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 # OPENROUTER_MODEL_LIST=model1,model2,model3
 
+
 # ## Mistral AI ###
 
 # MISTRAL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -164,6 +168,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 
 # SILICONCLOUD_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+
 # ## TencentCloud AI  ####
 
 # TENCENT_CLOUD_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -176,6 +181,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 
 # INFINIAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+
 # ## 302.AI ###
 
 # AI302_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -216,6 +222,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 
 # VERCELAIGATEWAY_API_KEY=your_vercel_ai_gateway_api_key
 
+
 # #######################################
 # ########### Market Service ############
 # #######################################
@@ -223,29 +230,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # The LobeChat agents market index url
 # AGENTS_INDEX_URL=https://chat-agents.lobehub.com
 
-# #######################################
-# ######### Cloud Sandbox Service #######
-# #######################################
-
-# Sandbox provider for built-in code execution, shell, file operations, and export.
-# Supported values: market, onlyboxes
-# SANDBOX_PROVIDER=market
-
-# Required when SANDBOX_PROVIDER=onlyboxes. Base URL of the Onlyboxes console API, without /api/v1.
-# ONLYBOXES_BASE_URL=https://onlyboxes.example.com
-
-# Required when SANDBOX_PROVIDER=onlyboxes. Must match Onlyboxes CONSOLE_JIT_SIGNING_KEY.
-# ONLYBOXES_JIT_SIGNING_KEY=onlyboxes-jit-signing-secret
-
-# Optional JIT token issuer. Defaults to APP_URL.
-# ONLYBOXES_JIT_ISSUER=https://lobehub.example.com
-
-# Optional JIT token TTL in seconds.
-# ONLYBOXES_JIT_TTL_SEC=1800
-
-# Optional terminal session lease in seconds for the Onlyboxes provider.
-# ONLYBOXES_LEASE_TTL_SEC=900
-
 # #######################################
 # ########### Plugin Service ############
 # #######################################
@@ -299,6 +283,7 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # but some service providers may require configuration
 # S3_REGION=us-west-1
 
+
 # #######################################
 # ########### Auth Service ##############
 # #######################################
@@ -399,11 +384,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # Postgres database URL
 # DATABASE_URL=postgres://username:password@host:port/database
 
-# Optional: server-side timeout (in milliseconds) for a single SQL statement.
-# When set, Postgres aborts any statement/idle transaction exceeding it, so a stuck
-# query can't block indefinitely. Leave unset to keep Postgres' default of no timeout.
-# DATABASE_STATEMENT_TIMEOUT=300000
-
 # use `openssl rand -base64 32` to generate a key for the encryption of the database
 # we use this key to encrypt the user api key and proxy url
 # KEY_VAULTS_SECRET=xxxxx/xxxxxxxxxxxxxx=
@@ -444,23 +424,3 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # MESSAGE_GATEWAY_ENABLED=1
 # MESSAGE_GATEWAY_URL=https://message-gateway.lobehub.com
 # MESSAGE_GATEWAY_SERVICE_TOKEN=your_service_token_here
-
-# #######################################
-# ########### Messenger Bot #############
-# #######################################
-
-# LobeHub-operated bots that users link their account to once and then chat
-# with any of their agents from. Credentials (Telegram / Slack / Discord) are
-# now managed in dc-center → Agent → System Bots and stored in the
-# `system_bot_providers` table. See docs/development/messenger/managed-by-dc-center.md.
-#
-# Webhook URLs are registered against APP_URL:
-#   Telegram: <APP_URL>/api/agent/messenger/webhooks/telegram
-#   Slack:    <APP_URL>/api/agent/messenger/webhooks/slack
-#   Discord:  <APP_URL>/api/agent/messenger/webhooks/discord
-#
-# For local dev with bot platforms, point APP_URL at your tunnel
-# (ngrok / cloudflared) so platforms can reach your machine.
-
-# Verify-im link token TTL in seconds (default 1800 = 30 min)
-# LOBE_LINK_TOKEN_TTL_SECONDS=1800

.github/actions/desktop-publish-s3/action.yml

@@ -75,7 +75,7 @@ runs:
 
         # 1. 上传安装包到版本目录
         echo "📦 Uploading release files to s3://$S3_BUCKET/$CHANNEL/$VERSION/"
-        for file in release/*.dmg release/*.zip release/*.exe release/*.AppImage release/*.deb release/*.rpm release/*.snap release/*.tar.gz release/*.blockmap; do
+        for file in release/*.dmg release/*.zip release/*.exe release/*.AppImage release/*.deb release/*.rpm release/*.snap release/*.tar.gz; do
           if [ -f "$file" ]; then
             filename=$(basename "$file")
             echo "   ↗️ $filename"