bump version

* 🐛 fix(utils): preserve JPEG format when compressing uploaded images

Images with dimensions > 1920px were always re-encoded as PNG regardless
of original format, inflating small JPEGs (100–200 KB) to 1 MB+ because
PNG is lossless while JPEG is lossy.

Fix: pass file.type to compressImage(), encode JPEG inputs as JPEG at
0.85 quality (not PNG), and derive File MIME type from the data URL
instead of hardcoding 'image/png'.

PNG and WebP inputs still compress to PNG as before.

Fixes #13485

* ✅ test(utils): add tests for JPEG format preservation in compressImage

Per @tjx666's request on #13585. Adds explicit coverage for the JPEG
format-preservation behaviour:

- compressImage with type='image/jpeg' calls toDataURL with quality 0.85
- compressImage with type='image/png' calls toDataURL without a quality arg
- compressImage with no type defaults to PNG
- compressImageFile preserves JPEG inputs as image/jpeg (regression fence
  for the previously hardcoded 'image/png' MIME type in dataUrlToFile)
- compressImageFile keeps WebP inputs as PNG (documents the fallback)

The existing PNG tests are preserved to guard against regression in the
lossless path.

---------

Co-authored-by: octo-patch <octo-patch@github.com>
Co-authored-by: YuTengjing <ytj2713151713@gmail.com>

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

@@ -43,11 +43,13 @@ Reference: `docs/usage/providers/fal.mdx`
 
 ```markdown
 ### `{PROVIDER}_API_KEY`
+
 - Type: Required
 - Description: API key from {Provider Name}
 - Example: `{api-key-format}`
 
 ### `{PROVIDER}_MODEL_LIST`
+
 - Type: Optional
 - Description: Control model list. Use `+` to add, `-` to hide
 - Example: `-all,+model-1,+model-2=Display Name`
@@ -77,7 +79,7 @@ Update all Dockerfiles at the **end** of ENV section:
 
 - Cover image
 - 3-4 API dashboard screenshots
-- 2-3 LobeChat configuration screenshots
+- 2-3 LobeHub configuration screenshots
 - Host on LobeHub CDN: `hub-apac-1.lobeobjects.space`
 
 ## Checklist

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

@@ -0,0 +1,209 @@
+---
+name: agent-runtime-hooks
+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
+---
+
+# Agent Runtime Hooks
+
+Lifecycle hooks for observing and intercepting agent execution. Hooks are registered per-operation via `execAgent({ hooks })` and dispatched by `HookDispatcher`.
+
+## Hook Types
+
+16 hook types across 5 categories:
+
+```
+execAgent({ hooks })
+  │
+  ├─ beforeStep ──────────── Before each step executes
+  │     │
+  │     ├─ [call_llm]        LLM inference
+  │     │
+  │     ├─ [call_tool]
+  │     │     ├─ beforeToolCall ── Before tool executes (supports mocking)
+  │     │     ├─ (tool execution)
+  │     │     ├─ afterToolCall ─── After tool completes (observation only)
+  │     │     └─ onToolCallError ─ Tool threw an exception
+  │     │
+  │     ├─ [request_human_approve]
+  │     │     ├─ beforeHumanIntervention ── Before agent pauses
+  │     │     ├─ afterHumanIntervention ─── After approve/reject + resume
+  │     │     └─ onStopByHumanIntervention ── User rejected, agent halted
+  │     │
+  │     ├─ [compress_context]
+  │     │     ├─ beforeCompact ──── Before compression starts
+  │     │     ├─ afterCompact ───── After compression completes
+  │     │     └─ onCompactError ─── Compression failed
+  │     │
+  │     ├─ [callAgent] (via execSubAgentTask)
+  │     │     ├─ beforeCallAgent ── Before sub-agent starts
+  │     │     ├─ afterCallAgent ─── After sub-agent completes
+  │     │     └─ onCallAgentError ── Sub-agent failed
+  │     │
+  │     └─ afterStep ──────────── After step completes
+  │
+  ├─ (next step...)
+  │
+  ├─ onComplete ───────────── Operation reaches terminal state
+  └─ onError ──────────────── Error during execution
+```
+
+## Key Files
+
+| File                                                       | Role                                                   |
+| ---------------------------------------------------------- | ------------------------------------------------------ |
+| `packages/agent-runtime/src/types/hooks.ts`                | Type definitions (AgentHookType, all event interfaces) |
+| `src/server/services/agentRuntime/hooks/types.ts`          | Server-side types (AgentHook, re-exports)              |
+| `src/server/services/agentRuntime/hooks/HookDispatcher.ts` | Registration, dispatch, dispatchBeforeToolCall         |
+| `src/server/modules/AgentRuntime/RuntimeExecutors.ts`      | Tool/Compact/HumanIntervention hook dispatch           |
+| `src/server/services/agentRuntime/AgentRuntimeService.ts`  | Step hooks + HumanIntervention resume/reject           |
+| `src/server/services/aiAgent/index.ts`                     | CallAgent hook dispatch                                |
+
+## Registration Flow
+
+```ts
+const hooks: AgentHook[] = [
+  { id: 'my-hook', type: 'afterStep', handler: async (event) => { ... } },
+];
+await aiAgentService.execAgent({ agentId, prompt, hooks });
+// Internally: hookDispatcher.register(operationId, hooks)
+// Cleanup:    hookDispatcher.unregister(operationId)
+```
+
+## Hook Reference
+
+### Step Level
+
+**`beforeStep`** — Before each step. `event: AgentHookEvent`
+**`afterStep`** — After each step. `event: AgentHookEvent` (content, toolsCalling, totalCost, etc.)
+**`onComplete`** — Terminal state. `event: AgentHookEvent` (reason: done/error/interrupted/max_steps/cost_limit)
+**`onError`** — Error occurred. `event: AgentHookEvent` (errorMessage, errorDetail)
+
+### Tool Call Level
+
+**`beforeToolCall`** — Before tool executes. **Supports mocking** via `event.mock()`.
+
+```ts
+// event: ToolCallHookEvent
+{
+  (identifier, apiName, args, callIndex, stepIndex, operationId, mock);
+}
+// Mock example:
+event.mock({ content: '{"error":"rate limited"}' });
+```
+
+Dispatch method: `hookDispatcher.dispatchBeforeToolCall()` (returns mock result or null).
+
+**`afterToolCall`** — After tool completes. Observation only.
+
+```ts
+// event: AfterToolCallHookEvent
+{
+  (identifier, apiName, args, callIndex, content, success, mocked, executionTimeMs, stepIndex);
+}
+```
+
+**`onToolCallError`** — Tool threw an exception (catch block, not just `success=false`).
+
+```ts
+// event: ToolCallErrorHookEvent
+{
+  (identifier, apiName, args, callIndex, error, stepIndex);
+}
+```
+
+### Human Intervention
+
+**`beforeHumanIntervention`** — Before agent pauses for approval.
+
+```ts
+// event: BeforeHumanInterventionHookEvent
+{ operationId, stepIndex, pendingTools: [{ identifier, apiName }] }
+```
+
+**`afterHumanIntervention`** — After approve/reject, agent resumes.
+
+```ts
+// event: AfterHumanInterventionHookEvent
+{ operationId, action: 'approve' | 'reject' | 'rejectAndContinue', toolCallId?, rejectionReason? }
+```
+
+**`onStopByHumanIntervention`** — User rejected, agent halted.
+
+```ts
+// event: StopByHumanInterventionHookEvent
+{ operationId, toolCallId?, rejectionReason? }
+```
+
+### Context Compression
+
+**`beforeCompact`** — Before compression starts.
+
+```ts
+// event: BeforeCompactHookEvent
+{
+  (operationId, stepIndex, messageCount, tokenCount);
+}
+```
+
+**`afterCompact`** — After compression completes.
+
+```ts
+// event: AfterCompactHookEvent
+{
+  (operationId, stepIndex, groupId, messagesBefore, messagesAfter, summary);
+}
+```
+
+**`onCompactError`** — Compression failed.
+
+```ts
+// event: CompactErrorHookEvent
+{
+  (operationId, stepIndex, tokenCount, error);
+}
+```
+
+### Sub-Agent (CallAgent)
+
+**`beforeCallAgent`** — Before calling sub-agent. Dispatched on **parent** operation.
+
+```ts
+// event: BeforeCallAgentHookEvent
+{
+  (operationId, agentId, instruction);
+}
+```
+
+**`afterCallAgent`** — Sub-agent completed. Dispatched on **parent** operation.
+
+```ts
+// event: AfterCallAgentHookEvent
+{
+  (operationId, agentId, subOperationId, threadId, success);
+}
+```
+
+**`onCallAgentError`** — Sub-agent failed. Dispatched on **parent** operation.
+
+```ts
+// event: CallAgentErrorHookEvent
+{
+  (operationId, agentId, error);
+}
+```
+
+Note: CallAgent hooks require `parentOperationId` in `ExecSubAgentTaskParams`.
+
+## Design Notes
+
+- **Fire-and-forget**: All handlers return `Promise<void>`. Errors are non-fatal.
+- **Exception**: `beforeToolCall` supports mock via `event.mock()` — uses `dispatchBeforeToolCall()` which returns the mock result.
+- **Sequential**: Same-type hooks run in registration order.
+- **Local only**: `beforeToolCall` mock only works in local mode (in-memory hooks). Webhook mode does not support mocking.
+- **Scoped per operation**: Auto-cleaned via `hookDispatcher.unregister()` on completion.
+- **Sandbox/MCP**: No separate hooks — they go through `executeTool`, so `beforeToolCall`/`afterToolCall` cover them. Use `event.identifier` to filter.
+
+## Real-World Example: agent-evals
+
+See `devtools/agent-evals/helpers/runner.ts` — `createEvalHooks()` uses `afterStep`, `onComplete`, `afterToolCall`, and `beforeToolCall` (for mock).

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

@@ -0,0 +1,220 @@
+---
+name: agent-tracing
+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
+---
+
+# Agent Tracing CLI Guide
+
+`@lobechat/agent-tracing` is a zero-config local dev tool that records agent execution snapshots to disk and provides a CLI to inspect them.
+
+## How It Works
+
+In `NODE_ENV=development`, `AgentRuntimeService.executeStep()` automatically records each step to `.agent-tracing/` as partial snapshots. When the operation completes, the partial is finalized into a complete `ExecutionSnapshot` JSON file.
+
+**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 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
+
+```
+packages/agent-tracing/
+  src/
+    types.ts          # ExecutionSnapshot, StepSnapshot, SnapshotSummary
+    store/
+      types.ts        # ISnapshotStore interface
+      file-store.ts   # FileSnapshotStore (.agent-tracing/*.json)
+    recorder/
+      index.ts        # appendStepToPartial(), finalizeSnapshot()
+    viewer/
+      index.ts        # Terminal rendering: renderSnapshot, renderStepDetail, renderMessageDetail, renderSummaryTable, renderPayload, renderPayloadTools, renderMemory
+    cli/
+      index.ts        # CLI entry point (#!/usr/bin/env bun)
+      inspect.ts      # Inspect command (default)
+      partial.ts      # Partial snapshot commands (list, inspect, clean)
+    index.ts          # Barrel exports
+```
+
+## Data Storage
+
+- Completed snapshots: `.agent-tracing/{ISO-timestamp}_{traceId-short}.json`
+- Latest symlink: `.agent-tracing/latest.json`
+- In-progress partials: `.agent-tracing/_partial/{operationId}.json`
+- `FileSnapshotStore` resolves from `process.cwd()` — **run CLI from the repo root**
+
+## CLI Commands
+
+All commands run from the **repo root**:
+
+```bash
+# View latest trace (tree overview, `inspect` is the default command)
+agent-tracing
+agent-tracing inspect
+agent-tracing inspect <traceId>
+agent-tracing inspect latest
+
+# List recent snapshots
+agent-tracing list
+agent-tracing list -l 20
+
+# Inspect specific step (-s is short for --step)
+agent-tracing inspect <traceId> -s 0
+
+# View messages (-m is short for --messages)
+agent-tracing inspect <traceId> -s 0 -m
+
+# View full content of a specific message (by index shown in -m output)
+agent-tracing inspect <traceId> -s 0 --msg 2
+agent-tracing inspect <traceId> -s 0 --msg-input 1
+
+# View tool call/result details (-t is short for --tools)
+agent-tracing inspect <traceId> -s 1 -t
+
+# View raw events (-e is short for --events)
+agent-tracing inspect <traceId> -s 0 -e
+
+# View runtime context (-c is short for --context)
+agent-tracing inspect <traceId> -s 0 -c
+
+# View context engine input overview (-p is short for --payload)
+agent-tracing inspect <traceId> -p
+agent-tracing inspect <traceId> -s 0 -p
+
+# View available tools in payload (-T is short for --payload-tools)
+agent-tracing inspect <traceId> -T
+agent-tracing inspect <traceId> -s 0 -T
+
+# View user memory (-M is short for --memory)
+agent-tracing inspect <traceId> -M
+agent-tracing inspect <traceId> -s 0 -M
+
+# Raw JSON output (-j is short for --json)
+agent-tracing inspect <traceId> -j
+agent-tracing inspect <traceId> -s 0 -j
+
+# List in-progress partial snapshots
+agent-tracing partial list
+
+# Inspect a partial (use `inspect` directly — all flags work with partial IDs)
+agent-tracing inspect <partialOperationId>
+agent-tracing inspect <partialOperationId> -T
+agent-tracing inspect <partialOperationId> -p
+
+# Clean up stale partial snapshots
+agent-tracing partial clean
+```
+
+## Inspect Flag Reference
+
+| Flag              | Short | Description                                                                                       | Default Step |
+| ----------------- | ----- | ------------------------------------------------------------------------------------------------- | ------------ |
+| `--step <n>`      | `-s`  | Target a specific step                                                                            | —            |
+| `--messages`      | `-m`  | Messages context (CE input → params → LLM payload)                                                | —            |
+| `--tools`         | `-t`  | Tool calls & results (what agent invoked)                                                         | —            |
+| `--events`        | `-e`  | Raw events (llm_start, llm_result, etc.)                                                          | —            |
+| `--context`       | `-c`  | Runtime context & payload (raw)                                                                   | —            |
+| `--system-role`   | `-r`  | Full system role content                                                                          | 0            |
+| `--env`           |       | Environment context                                                                               | 0            |
+| `--payload`       | `-p`  | Context engine input overview (model, knowledge, tools summary, memory summary, platform context) | 0            |
+| `--payload-tools` | `-T`  | Available tools detail (plugin manifests + LLM function definitions)                              | 0            |
+| `--memory`        | `-M`  | Full user memory (persona, identity, contexts, preferences, experiences)                          | 0            |
+| `--diff <n>`      | `-d`  | Diff against step N (use with `-r` or `--env`)                                                    | —            |
+| `--msg <n>`       |       | Full content of message N from Final LLM Payload                                                  | —            |
+| `--msg-input <n>` |       | Full content of message N from Context Engine Input                                               | —            |
+| `--json`          | `-j`  | Output as JSON (combinable with any flag above)                                                   | —            |
+
+Flags marked "Default Step: 0" auto-select step 0 if `--step` is not provided. All flags support `latest` or omitted traceId.
+
+## Typical Debug Workflow
+
+```bash
+# 1. Trigger an agent operation in the dev UI
+
+# 2. See the overview
+agent-tracing inspect
+
+# 3. List all traces, get traceId
+agent-tracing list
+
+# 4. Quick overview of what was fed into context engine
+agent-tracing inspect -p
+
+# 5. Inspect a specific step's messages to see what was sent to the LLM
+agent-tracing inspect TRACE_ID -s 0 -m
+
+# 6. Drill into a truncated message for full content
+agent-tracing inspect TRACE_ID -s 0 --msg 2
+
+# 7. Check available tools vs actual tool calls
+agent-tracing inspect -T      # available tools
+agent-tracing inspect -s 1 -t # actual tool calls & results
+
+# 8. Inspect user memory injected into the conversation
+agent-tracing inspect -M
+
+# 9. Diff system role between steps (multi-step agents)
+agent-tracing inspect TRACE_ID -r -d 2
+```
+
+## Key Types
+
+```typescript
+interface ExecutionSnapshot {
+  traceId: string;
+  operationId: string;
+  model?: string;
+  provider?: string;
+  startedAt: number;
+  completedAt?: number;
+  completionReason?:
+    | 'done'
+    | 'error'
+    | 'interrupted'
+    | 'max_steps'
+    | 'cost_limit'
+    | 'waiting_for_human';
+  totalSteps: number;
+  totalTokens: number;
+  totalCost: number;
+  error?: { type: string; message: string };
+  steps: StepSnapshot[];
+}
+
+interface StepSnapshot {
+  stepIndex: number;
+  stepType: 'call_llm' | 'call_tool';
+  executionTimeMs: number;
+  content?: string; // LLM output
+  reasoning?: string; // Reasoning/thinking
+  inputTokens?: number;
+  outputTokens?: number;
+  toolsCalling?: Array<{ apiName: string; identifier: string; arguments?: string }>;
+  toolsResult?: Array<{
+    apiName: string;
+    identifier: string;
+    isSuccess?: boolean;
+    output?: string;
+  }>;
+  messages?: any[]; // DB messages before step
+  context?: { phase: string; payload?: unknown; stepContext?: unknown };
+  events?: Array<{ type: string; [key: string]: unknown }>;
+  // context_engine_result event contains:
+  //   input: full contextEngineInput (messages, systemRole, model, knowledge, tools, userMemory, ...)
+  //   output: processed messages array (final LLM payload)
+}
+```
+
+## --messages Output Structure
+
+When using `--messages`, the output shows three sections (if context engine data is available):
+
+1. **Context Engine Input** — DB messages passed to the engine, with `[0]`, `[1]`, ... indices. Use `--msg-input N` to view full content.
+2. **Context Engine Params** — systemRole, model, provider, knowledge, tools, userMemory, etc.
+3. **Final LLM Payload** — Processed messages after context engine (system date injection, user memory, history truncation, etc.), with `[0]`, `[1]`, ... indices. Use `--msg N` to view full content.
+
+## Integration Points
+
+- **Recording**: `src/server/services/agentRuntime/AgentRuntimeService.ts` — in the `executeStep()` method, after building `stepPresentationData`, writes partial snapshot in dev mode
+- **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.
+
+`/api/agent/webhooks/bot-callback/route.ts` verifies the QStash signature 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/route.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/route.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`, `serverIdField`, `userIdField`).
+
+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:
+  src/app/(backend)/api/agent/webhooks/[platform]/[[...appId]]/route.ts  — inbound catch-all
+  src/app/(backend)/api/agent/webhooks/bot-callback/route.ts             — qstash bot callback
+  src/app/(backend)/api/agent/gateway/route.ts                           — cron gateway (10min window)
+  src/app/(backend)/api/agent/gateway/start/route.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/chat-sdk/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: chat-sdk
+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
+
+Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, GitHub, and Linear. Write bot logic once, deploy everywhere.
+
+## Critical: Read the bundled docs
+
+The `chat` package ships with full documentation in `node_modules/chat/docs/` and TypeScript source types. **Always read these before writing code:**
+
+```
+node_modules/chat/docs/           # Full documentation (MDX files)
+node_modules/chat/dist/           # Built types (.d.ts files)
+```
+
+Key docs to read based on task:
+
+- `docs/getting-started.mdx` — setup guides
+- `docs/usage.mdx` — event handlers, threads, messages, channels
+- `docs/streaming.mdx` — AI streaming with AI SDK
+- `docs/cards.mdx` — JSX interactive cards
+- `docs/actions.mdx` — button/dropdown handlers
+- `docs/modals.mdx` — form dialogs (Slack only)
+- `docs/adapters/*.mdx` — platform-specific adapter setup
+- `docs/state/*.mdx` — state adapter config (Redis, ioredis, memory)
+
+Also read the TypeScript types from `node_modules/chat/dist/` to understand the full API surface.
+
+## Quick start
+
+```typescript
+import { Chat } from 'chat';
+import { createSlackAdapter } from '@chat-adapter/slack';
+import { createRedisState } from '@chat-adapter/state-redis';
+
+const bot = new Chat({
+  userName: 'mybot',
+  adapters: {
+    slack: createSlackAdapter({
+      botToken: process.env.SLACK_BOT_TOKEN!,
+      signingSecret: process.env.SLACK_SIGNING_SECRET!,
+    }),
+  },
+  state: createRedisState({ url: process.env.REDIS_URL! }),
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm listening to this thread.");
+});
+
+bot.onSubscribedMessage(async (thread, message) => {
+  await thread.post(`You said: ${message.text}`);
+});
+```
+
+## Core concepts
+
+- **Chat** — main entry point, coordinates adapters and routes events
+- **Adapters** — platform-specific (Slack, Teams, GChat, Discord, GitHub, Linear)
+- **State** — pluggable persistence (Redis for prod, memory for dev)
+- **Thread** — conversation thread with `post()`, `subscribe()`, `startTyping()`
+- **Message** — normalized format with `text`, `formatted` (mdast AST), `raw`
+- **Channel** — container for threads, supports listing and posting
+
+## Event handlers
+
+| Handler                    | Trigger                                           |
+| -------------------------- | ------------------------------------------------- |
+| `onNewMention`             | Bot @-mentioned in unsubscribed thread            |
+| `onSubscribedMessage`      | Any message in subscribed thread                  |
+| `onNewMessage(regex)`      | Messages matching pattern in unsubscribed threads |
+| `onSlashCommand("/cmd")`   | Slash command invocations                         |
+| `onReaction(emojis)`       | Emoji reactions added/removed                     |
+| `onAction(actionId)`       | Button clicks and dropdown selections             |
+| `onAssistantThreadStarted` | Slack Assistants API thread opened                |
+| `onAppHomeOpened`          | Slack App Home tab opened                         |
+
+## Streaming
+
+Pass any `AsyncIterable<string>` to `thread.post()`. Works with AI SDK's `textStream`:
+
+```typescript
+import { ToolLoopAgent } from 'ai';
+const agent = new ToolLoopAgent({ model: 'anthropic/claude-4.5-sonnet' });
+
+bot.onNewMention(async (thread, message) => {
+  const result = await agent.stream({ prompt: message.text });
+  await thread.post(result.textStream);
+});
+```
+
+## Cards (JSX)
+
+Set `jsxImportSource: "chat"` in tsconfig. Components: `Card`, `CardText`, `Button`, `Actions`, `Fields`, `Field`, `Select`, `SelectOption`, `Image`, `Divider`, `LinkButton`, `Section`, `RadioSelect`.
+
+```tsx
+await thread.post(
+  <Card title="Order #1234">
+    <CardText>Your order has been received!</CardText>
+    <Actions>
+      <Button id="approve" style="primary">
+        Approve
+      </Button>
+      <Button id="reject" style="danger">
+        Reject
+      </Button>
+    </Actions>
+  </Card>,
+);
+```
+
+## Packages
+
+| Package                       | Purpose                       |
+| ----------------------------- | ----------------------------- |
+| `chat`                        | Core SDK                      |
+| `@chat-adapter/slack`         | Slack                         |
+| `@chat-adapter/teams`         | Microsoft Teams               |
+| `@chat-adapter/gchat`         | Google Chat                   |
+| `@chat-adapter/discord`       | Discord                       |
+| `@chat-adapter/github`        | GitHub Issues                 |
+| `@chat-adapter/linear`        | Linear Issues                 |
+| `@chat-adapter/state-redis`   | Redis state (production)      |
+| `@chat-adapter/state-ioredis` | ioredis state (alternative)   |
+| `@chat-adapter/state-memory`  | In-memory state (development) |
+
+## Changesets (Release Flow)
+
+This monorepo uses [Changesets](https://github.com/changesets/changesets) for versioning and changelogs. Every PR that changes a package's behavior must include a changeset.
+
+```bash
+pnpm changeset
+# → select affected package(s) (e.g. @chat-adapter/slack, chat)
+# → choose bump type: patch (fixes), minor (features), major (breaking)
+# → write a short summary for the CHANGELOG
+```
+
+This creates a file in `.changeset/` — commit it with the PR. When merged to `main`, the Changesets GitHub Action opens a "Version Packages" PR to bump versions and update CHANGELOGs. Merging that PR publishes to npm.
+
+## Webhook setup
+
+Each adapter exposes a webhook handler via `bot.webhooks.{platform}`. Wire these to your HTTP framework's routes (e.g. Next.js API routes, Hono, Express).

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

@@ -0,0 +1,218 @@
+---
+name: cli-backend-testing
+description: >
+  CLI + Backend integration testing workflow. Use when verifying backend API changes
+  (TRPC routers, services, models) via the LobeHub CLI against a local dev server.
+  Triggers on 'cli test', 'test with cli', 'verify with cli', 'local cli test',
+  'backend test with cli', or when needing to validate server-side changes end-to-end.
+---
+
+# CLI + Backend Integration Testing
+
+Standard workflow for verifying backend changes using the LobeHub CLI (`lh`) against a local dev server.
+
+## When to Use
+
+- Verifying TRPC router / service / model changes end-to-end
+- Testing new API fields or response structure changes
+- Validating CLI command output after backend modifications
+- Debugging data flow issues between server and CLI
+
+## Prerequisites
+
+| Requirement  | Details                                                       |
+| ------------ | ------------------------------------------------------------- |
+| Dev server   | `localhost:3011` (Next.js)                                    |
+| CLI source   | `lobehub/apps/cli/`                                           |
+| CLI dev mode | Uses `LOBEHUB_CLI_HOME=.lobehub-dev` for isolated credentials |
+| Auth         | Device Code Flow login to local server                        |
+
+## Quick Reference
+
+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"
+```
+
+## Workflow
+
+### 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** (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
+```
+
+To **restart** (pick up server-side code changes):
+
+```bash
+lsof -ti:3011 | xargs kill
+pnpm run dev:next
+```
+
+**Important:** Server-side code changes in the submodule (`lobehub/src/server/`, `lobehub/packages/`) require a server restart. Next.js hot-reload may not pick up changes in submodule packages.
+
+### 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"`**: 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. 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 (`bun src/index.ts`), so CLI-side code changes take effect immediately without rebuilding.
+
+```bash
+cd lobehub/apps/cli
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+```
+
+### Step 4: Clean Up Test Data
+
+Delete any test data created during verification:
+
+```bash
+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
+
+### 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>
+```
+
+### 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)
+         |
+2. Run unit tests (fast feedback)
+   bunx vitest run --silent='passed-only' '<test-file>'
+         |
+3. Restart dev server (if server-side changes)
+   lsof -ti:3011 | xargs kill && pnpm run dev:next
+         |
+4. CLI verification (end-to-end)
+   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+         |
+5. Clean up test data
+```
+
+### When Server Restart is Needed
+
+| Change Location                           | Restart? |
+| ----------------------------------------- | -------- |
+| `lobehub/src/server/` (routers, services) | Yes      |
+| `lobehub/packages/database/` (models)     | Yes      |
+| `lobehub/packages/types/`                 | Yes      |
+| `lobehub/packages/prompts/`               | Yes      |
+| `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                                                              |
+| --------------------------- | --------------------------------------------------------------------- |
+| `No authentication found`   | Run `login --server http://localhost:3011`                            |
+| `UNAUTHORIZED` on API calls | Token expired; re-run login                                           |
+| `ECONNREFUSED`              | Dev server not running; start with `pnpm run dev:next`                |
+| 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

@@ -0,0 +1,296 @@
+---
+name: cli
+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
+---
+
+# LobeHub CLI Development Guide
+
+## Overview
+
+LobeHub CLI (`@lobehub/cli`) is a command-line tool for managing and interacting with LobeHub services. Built with Commander.js + TypeScript.
+
+- **Package**: `apps/cli/`
+- **Entry**: `apps/cli/src/index.ts`
+- **Binaries**: `lh`, `lobe`, `lobehub` (all aliases for the same CLI)
+- **Build**: tsup
+- **Runtime**: Node.js / Bun
+
+## Architecture
+
+```
+apps/cli/src/
+├── index.ts                  # Entry point, registers all commands
+├── api/
+│   ├── client.ts             # tRPC client (type-safe backend API)
+│   └── http.ts               # Raw HTTP utilities
+├── auth/
+│   ├── credentials.ts        # Encrypted credential storage (AES-256-GCM)
+│   ├── refresh.ts            # Token auto-refresh
+│   └── resolveToken.ts       # Token resolution (flag > stored)
+├── commands/                 # All CLI commands (one file per command group)
+│   ├── agent.ts              # Agent CRUD + run
+│   ├── config.ts             # whoami, usage
+│   ├── connect.ts            # Device gateway connection + daemon
+│   ├── doc.ts                # Document management
+│   ├── file.ts               # File management
+│   ├── generate/             # Content generation (text/image/video/tts/asr)
+│   ├── kb.ts                 # Knowledge base management
+│   ├── login.ts              # OIDC Device Code Flow auth
+│   ├── logout.ts             # Clear credentials
+│   ├── memory.ts             # User memory management
+│   ├── message.ts            # Message management
+│   ├── model.ts              # AI model management
+│   ├── plugin.ts             # Plugin management
+│   ├── provider.ts           # AI provider management
+│   ├── search.ts             # Global search
+│   ├── skill.ts              # Agent skill management
+│   ├── status.ts             # Gateway connectivity check
+│   └── topic.ts              # Conversation topic management
+├── daemon/
+│   └── manager.ts            # Background daemon process management
+├── tools/
+│   ├── shell.ts              # Shell command execution (for gateway)
+│   └── file.ts               # File operations (for gateway)
+├── settings/
+│   └── index.ts              # Persistent settings (~/.lobehub/)
+├── utils/
+│   ├── logger.ts             # Logging (verbose mode)
+│   ├── format.ts             # Table output, JSON, timeAgo, truncate
+│   └── agentStream.ts        # SSE streaming for agent runs
+└── constants/
+    └── urls.ts               # Official server & gateway URLs
+```
+
+## Command Groups
+
+| Command       | Alias | Description                                                 |
+| ------------- | ----- | ----------------------------------------------------------- |
+| `lh login`    | -     | Authenticate via OIDC Device Code Flow                      |
+| `lh logout`   | -     | Clear stored credentials                                    |
+| `lh connect`  | -     | Device gateway connection & daemon management               |
+| `lh status`   | -     | Quick gateway connectivity check                            |
+| `lh agent`    | -     | Agent CRUD, run, status                                     |
+| `lh generate` | `gen` | Content generation (text, image, video, tts, asr, download) |
+| `lh doc`      | -     | Document CRUD, batch-create, parse, topic linking           |
+| `lh file`     | -     | File list, view, delete, recent                             |
+| `lh kb`       | -     | Knowledge base CRUD, folders, docs, upload, tree view       |
+| `lh memory`   | -     | User memory CRUD + extraction                               |
+| `lh message`  | -     | Message list, search, delete, count, heatmap                |
+| `lh topic`    | -     | Topic CRUD + search + recent                                |
+| `lh skill`    | -     | Skill CRUD + import (GitHub/URL/market)                     |
+| `lh model`    | -     | Model CRUD, toggle, batch-toggle, clear                     |
+| `lh provider` | -     | Provider CRUD, config, test, toggle                         |
+| `lh plugin`   | -     | Plugin install, uninstall, update                           |
+| `lh search`   | -     | Global search across all types                              |
+| `lh whoami`   | -     | Current user info                                           |
+| `lh usage`    | -     | Monthly/daily usage statistics                              |
+
+## Adding a New Command
+
+### 1. Create Command File
+
+Create `apps/cli/src/commands/<name>.ts`:
+
+```typescript
+import type { Command } from 'commander';
+import { getTrpcClient } from '../api/client';
+import { outputJson, printTable, truncate } from '../utils/format';
+
+export function register<Name>Command(program: Command) {
+  const cmd = program.command('<name>').description('...');
+
+  // Subcommands
+  cmd
+    .command('list')
+    .description('List items')
+    .option('-L, --limit <n>', 'Maximum number of items', '30')
+    .option('--json [fields]', 'Output JSON, optionally specify fields')
+    .action(async (options) => {
+      const client = await getTrpcClient();
+      const result = await client.<router>.<procedure>.query({ ... });
+      // Handle output
+    });
+}
+```
+
+### 2. Register in Entry Point
+
+In `apps/cli/src/index.ts`:
+
+```typescript
+import { registerNewCommand } from './commands/new';
+// ...
+registerNewCommand(program);
+```
+
+### 3. Add Tests
+
+Create `apps/cli/src/commands/<name>.test.ts` alongside the command file.
+
+## Conventions
+
+### Output Patterns
+
+All list/view commands follow consistent patterns:
+
+- `--json [fields]` - JSON output with optional field filtering
+- `--yes` - Skip confirmation for destructive ops
+- `-L, --limit <n>` - Pagination limit (default: 30)
+- `-v, --verbose` - Verbose logging
+
+### Table Output
+
+```typescript
+const rows = items.map((item) => [item.id, truncate(item.title, 40), timeAgo(item.updatedAt)]);
+printTable(rows, ['ID', 'TITLE', 'UPDATED']);
+```
+
+### JSON Output
+
+```typescript
+if (options.json !== undefined) {
+  const fields = typeof options.json === 'string' ? options.json : undefined;
+  outputJson(items, fields);
+  return;
+}
+```
+
+### Authentication
+
+Commands that need auth use `getTrpcClient()` which auto-resolves tokens:
+
+```typescript
+const client = await getTrpcClient();
+// client.router.procedure.query/mutate(...)
+```
+
+### Confirmation Prompts
+
+```typescript
+import { confirm } from '../utils/format';
+if (!options.yes) {
+  const ok = await confirm('Are you sure?');
+  if (!ok) return;
+}
+```
+
+## Storage Locations
+
+| File          | Path                          | Purpose                        |
+| ------------- | ----------------------------- | ------------------------------ |
+| Credentials   | `~/.lobehub/credentials.json` | Encrypted tokens (AES-256-GCM) |
+| Settings      | `~/.lobehub/settings.json`    | Custom server/gateway URLs     |
+| Daemon PID    | `~/.lobehub/daemon.pid`       | Background process PID         |
+| Daemon Status | `~/.lobehub/daemon.status`    | Connection status JSON         |
+| Daemon Log    | `~/.lobehub/daemon.log`       | Daemon output log              |
+
+The base directory (`~/.lobehub/`) can be overridden with the `LOBEHUB_CLI_HOME` env var (e.g. `LOBEHUB_CLI_HOME=.lobehub-dev` for dev mode isolation).
+
+## Key Dependencies
+
+- `commander` - CLI framework
+- `@trpc/client` + `superjson` - Type-safe API client
+- `@lobechat/device-gateway-client` - WebSocket gateway connection
+- `@lobechat/local-file-shell` - Local shell/file tool execution
+- `picocolors` - Terminal colors
+- `ws` - WebSocket
+- `diff` - Text diffing
+- `fast-glob` - File pattern matching
+
+## Development
+
+### Running in Dev Mode
+
+Dev mode uses `LOBEHUB_CLI_HOME=.lobehub-dev` to isolate credentials from the global `~/.lobehub/` directory, so dev and production configs never conflict.
+
+```bash
+# Run a command in dev mode (from apps/cli/)
+cd apps/cli && bun run dev -- <command>
+
+# This is equivalent to:
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+```
+
+### Connecting to Local Dev Server
+
+To test CLI against a local dev server (e.g. `localhost:3011`):
+
+**Step 1: Start the local server**
+
+```bash
+# From cloud repo root
+bun run dev
+# Server starts on http://localhost:3011 (or configured port)
+```
+
+**Step 2: Login to local server via Device Code Flow**
+
+```bash
+cd apps/cli && bun run dev -- login --server http://localhost:3011
+```
+
+This will:
+
+1. Call `POST http://localhost:3011/oidc/device/auth` to get a device code
+2. Print a URL like `http://localhost:3011/oidc/device?user_code=XXXX-YYYY`
+3. Open the URL in your browser — log in and authorize
+4. Save credentials to `apps/cli/.lobehub-dev/credentials.json`
+5. Save server URL to `apps/cli/.lobehub-dev/settings.json`
+
+After login, all subsequent `bun run dev -- <command>` calls will use the local server.
+
+**Step 3: Run commands against local server**
+
+```bash
+cd apps/cli && bun run dev -- task list
+cd apps/cli && bun run dev -- task create -i "Test task" -n "My Task"
+cd apps/cli && bun run dev -- agent list
+```
+
+**Troubleshooting:**
+
+- If login returns `invalid_grant`, make sure the local OIDC provider is properly configured (check `OIDC_*` env vars in `.env`)
+- If you get `UNAUTHORIZED` on API calls, your token may have expired — run `bun run dev -- login --server http://localhost:3011` again
+- Dev credentials are stored in `apps/cli/.lobehub-dev/` (gitignored), not in `~/.lobehub/`
+
+### Switching Between Local and Production
+
+```bash
+# Dev mode (local server) — uses .lobehub-dev/
+cd apps/cli && bun run dev -- <command>
+
+# Production (app.lobehub.com) — uses ~/.lobehub/
+lh <command>
+```
+
+The two environments are completely isolated by different credential directories.
+
+### Build & Test
+
+```bash
+# Build CLI
+cd apps/cli && bun run build
+
+# Unit tests
+cd apps/cli && bun run test
+
+# E2E tests (requires authenticated CLI)
+cd apps/cli && bunx vitest run e2e/kb.e2e.test.ts
+
+# Link globally for testing (installs lh/lobe/lobehub commands)
+cd apps/cli && bun run cli:link
+```
+
+## Detailed Command References
+
+See `references/` for each command group:
+
+- **Agent**: `references/agent.md` (CRUD, run, status)
+- **Content Generation**: `references/generate.md` (text, image, video, tts, asr, download)
+- **Knowledge & Files**: `references/knowledge.md` (kb, file, doc)
+- **Conversation**: `references/conversation.md` (topic, message)
+- **Memory**: `references/memory.md` (memory management, extraction)
+- **Skills & Plugins**: `references/skills-plugins.md` (skill, plugin)
+- **Models & Providers**: `references/models-providers.md` (model, provider)
+- **Search & Config**: `references/search-config.md` (search, whoami, usage)

.agents/skills/cli/references/agent.md

@@ -0,0 +1,144 @@
+# Agent Commands
+
+Manage AI agents: create, edit, delete, list, run, and check status.
+
+**Source**: `apps/cli/src/commands/agent.ts`
+
+## `lh agent list`
+
+List all agents.
+
+```bash
+lh agent list [-L [-k [--json [fields]] < n > ] < keyword > ]
+```
+
+| Option                    | Description                            | Default |
+| ------------------------- | -------------------------------------- | ------- |
+| `-L, --limit <n>`         | Maximum items                          | `30`    |
+| `-k, --keyword <keyword>` | Filter by keyword                      | -       |
+| `--json [fields]`         | JSON output with optional field filter | -       |
+
+**Table columns**: ID, TITLE, DESCRIPTION, MODEL
+
+---
+
+## `lh agent view <agentId>`
+
+View agent configuration details.
+
+```bash
+lh agent view [fields]] < agentId > [--json
+```
+
+**Displays**: Title, description, model, provider, system role, plugins, tools.
+
+---
+
+## `lh agent create`
+
+Create a new agent.
+
+```bash
+lh agent create [options]
+```
+
+| Option                      | Description    | Required |
+| --------------------------- | -------------- | -------- |
+| `-t, --title <title>`       | Agent title    | No       |
+| `-d, --description <desc>`  | Description    | No       |
+| `-m, --model <model>`       | Model ID       | No       |
+| `-p, --provider <provider>` | Provider ID    | No       |
+| `-s, --system-role <role>`  | System prompt  | No       |
+| `--group <groupId>`         | Agent group ID | No       |
+
+**Output**: Created agent ID and session ID.
+
+---
+
+## `lh agent edit <agentId>`
+
+Update an existing agent. Same options as `create`, all optional. Only specified fields are updated.
+
+```bash
+lh agent edit [-m [-s ... < agentId > [-t < title > ] < model > ] < role > ]
+```
+
+---
+
+## `lh agent delete <agentId>`
+
+Delete an agent.
+
+```bash
+lh agent delete < agentId > [--yes]
+```
+
+Requires confirmation unless `--yes` is provided.
+
+---
+
+## `lh agent duplicate <agentId>`
+
+Duplicate an existing agent.
+
+```bash
+lh agent duplicate < agentId > [-t < title > ]
+```
+
+| Option                | Description                          |
+| --------------------- | ------------------------------------ |
+| `-t, --title <title>` | Optional new title for the duplicate |
+
+**Output**: New agent ID.
+
+---
+
+## `lh agent run`
+
+Start an agent execution (streaming SSE).
+
+```bash
+lh agent run [options]
+```
+
+| Option                | Description                                  |
+| --------------------- | -------------------------------------------- |
+| `-a, --agent-id <id>` | Agent ID to run                              |
+| `-s, --slug <slug>`   | Agent slug (alternative to ID)               |
+| `-p, --prompt <text>` | User prompt                                  |
+| `-t, --topic-id <id>` | Reuse existing topic                         |
+| `--no-auto-start`     | Don't auto-start the agent                   |
+| `--json`              | Output full JSON event stream                |
+| `-v, --verbose`       | Show detailed tool call info                 |
+| `--replay <file>`     | Replay events from saved JSON file (offline) |
+
+### Streaming Behavior
+
+Uses `utils/agentStream.ts` to handle Server-Sent Events:
+
+1. Sends agent run request to backend
+2. Streams SSE events in real-time
+3. Displays: text chunks, tool call status, operation progress
+4. Shows final token usage and cost summary
+
+### Replay Mode
+
+`--replay <file>` reads a saved JSON event stream for offline debugging without server connection.
+
+---
+
+## `lh agent status <operationId>`
+
+Check agent operation status.
+
+```bash
+lh agent status [fields]] [--history] [--history-limit < operationId > [--json < n > ]
+```
+
+| Option                | Description          | Default |
+| --------------------- | -------------------- | ------- |
+| `--json [fields]`     | JSON output          | -       |
+| `--history`           | Include step history | `false` |
+| `--history-limit <n>` | Max history entries  | `10`    |
+
+**Displays**: Status (running/completed/failed), steps count, tokens used, cost, error info, timestamps.

.agents/skills/cli/references/conversation.md

@@ -0,0 +1,122 @@
+# Conversation Commands (Topic & Message)
+
+## Topic Management (`lh topic`)
+
+Manage conversation topics (threads).
+
+**Source**: `apps/cli/src/commands/topic.ts`
+
+### `lh topic list`
+
+```bash
+lh topic list [--agent-id [-L [--page [--json [fields]] < id > ] < n > ] < n > ]
+```
+
+| Option            | Description     | Default |
+| ----------------- | --------------- | ------- |
+| `--agent-id <id>` | Filter by agent | -       |
+| `-L, --limit <n>` | Page size       | `30`    |
+| `--page <n>`      | Page number     | `1`     |
+
+**Table columns**: ID, TITLE, FAV, UPDATED
+
+### `lh topic search <keywords>`
+
+```bash
+lh topic search [--json [fields]] < keywords > [--agent-id < id > ]
+```
+
+### `lh topic create`
+
+```bash
+lh topic create -t [--favorite] < title > [--agent-id < id > ]
+```
+
+| Option                | Description          | Required |
+| --------------------- | -------------------- | -------- |
+| `-t, --title <title>` | Topic title          | Yes      |
+| `--agent-id <id>`     | Associate with agent | No       |
+| `--favorite`          | Mark as favorite     | No       |
+
+### `lh topic edit <id>`
+
+```bash
+lh topic edit [--favorite] [--no-favorite] < id > [-t < title > ]
+```
+
+### `lh topic delete <ids...>`
+
+```bash
+lh topic delete [--yes] < id1 > [id2...]
+```
+
+### `lh topic recent`
+
+```bash
+lh topic recent [-L [--json [fields]] < n > ]
+```
+
+| Option            | Description     | Default |
+| ----------------- | --------------- | ------- |
+| `-L, --limit <n>` | Number of items | `10`    |
+
+---
+
+## Message Management (`lh message`)
+
+Manage chat messages within topics.
+
+**Source**: `apps/cli/src/commands/message.ts`
+
+### `lh message list`
+
+```bash
+lh message list [options] [--json [fields]]
+```
+
+| Option            | Description             | Default |
+| ----------------- | ----------------------- | ------- |
+| `--topic-id <id>` | Filter by topic         | -       |
+| `--agent-id <id>` | Filter by agent         | -       |
+| `-L, --limit <n>` | Page size               | `30`    |
+| `--page <n>`      | Page number             | `1`     |
+| `--user`          | Only show user messages | -       |
+
+**Table columns**: ID, ROLE, CONTENT, CREATED
+
+**Note**: When `--topic-id` or `--agent-id` is provided, uses `message.getMessages`; otherwise uses `message.listAll`.
+
+### `lh message search <keywords>`
+
+```bash
+lh message search [fields]] < keywords > [--json
+```
+
+Full-text search across all messages.
+
+### `lh message delete <ids...>`
+
+```bash
+lh message delete [--yes] < id1 > [id2...]
+```
+
+### `lh message count`
+
+```bash
+lh message count [--start [--end [--json] < date > ] < date > ]
+```
+
+| Option           | Description                                |
+| ---------------- | ------------------------------------------ |
+| `--start <date>` | Start date (ISO format, e.g. `2024-01-01`) |
+| `--end <date>`   | End date (ISO format)                      |
+
+**Output**: Total message count for the specified period.
+
+### `lh message heatmap`
+
+```bash
+lh message heatmap [--json]
+```
+
+**Output**: Activity heatmap data showing message frequency over time.

.agents/skills/cli/references/generate.md

@@ -0,0 +1,271 @@
+# Content Generation Commands
+
+Generate text, images, videos, speech, and transcriptions.
+
+**Source**: `apps/cli/src/commands/generate/`
+
+## Command Structure
+
+```
+lh generate (alias: gen)
+├── text <prompt>                          # Text generation
+├── image <prompt>                         # Image generation
+├── video <prompt>                         # Video generation
+├── tts <text>                             # Text-to-speech
+├── asr <audioFile>                        # Audio-to-text (speech recognition)
+├── download <generationId> <asyncTaskId>  # Wait & download generation result
+├── status <generationId> <asyncTaskId>    # Check async task status
+└── list                                   # List generation topics
+```
+
+> ⚠️ **Important**: `status` and `download` require an `asyncTaskId` (UUID format, e.g.
+> `7ad0eb13-e9a5-4403-8070-1f7fe95b2f95`), **not** the generation ID (`gen_xxx`).
+> The asyncTaskId is printed after "→ Task" in the `video` / `image` command output.
+
+---
+
+## `lh generate text <prompt>` / `lh gen text <prompt>`
+
+Generate text completion.
+
+**Source**: `apps/cli/src/commands/generate/text.ts`
+
+```bash
+lh gen text "Explain quantum computing" [options]
+echo "context" | lh gen text "summarize" --pipe
+```
+
+| Option                      | Description                        | Default              |
+| --------------------------- | ---------------------------------- | -------------------- |
+| `-m, --model <model>`       | Model ID                           | `openai/gpt-4o-mini` |
+| `-p, --provider <provider>` | Provider name                      | -                    |
+| `-s, --system <prompt>`     | System prompt                      | -                    |
+| `--temperature <n>`         | Temperature (0-2)                  | -                    |
+| `--max-tokens <n>`          | Maximum output tokens              | -                    |
+| `--stream`                  | Enable streaming output            | `false`              |
+| `--json`                    | Output full JSON response          | `false`              |
+| `--pipe`                    | Read additional context from stdin | `false`              |
+
+### Pipe Mode
+
+When `--pipe` is used, reads stdin and prepends it to the prompt. Useful for piping file contents:
+
+```bash
+cat README.md | lh gen text "summarize this" --pipe
+```
+
+---
+
+## `lh generate image <prompt>` / `lh gen image <prompt>`
+
+Generate images from text prompt. This is an async operation — the command submits the task and returns a generation ID + async task ID for tracking.
+
+**Source**: `apps/cli/src/commands/generate/image.ts`
+
+```bash
+lh gen image "A sunset over mountains" [options]
+lh gen image "A cute cat" --model dall-e-3 --provider openai --json
+```
+
+| Option                      | Description      | Default    |
+| --------------------------- | ---------------- | ---------- |
+| `-m, --model <model>`       | Model ID         | `dall-e-3` |
+| `-p, --provider <provider>` | Provider name    | `openai`   |
+| `-n, --num <n>`             | Number of images | `1`        |
+| `--width <px>`              | Width in pixels  | -          |
+| `--height <px>`             | Height in pixels | -          |
+| `--steps <n>`               | Number of steps  | -          |
+| `--seed <n>`                | Random seed      | -          |
+| `--json`                    | Output raw JSON  | `false`    |
+
+**Output** (non-JSON):
+
+```
+✓ Image generation started
+  Batch ID: gb_xxx
+  1 image(s) queued
+  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                            This is the asyncTaskId — use this for status/download
+
+Use "lh generate status <generationId> <asyncTaskId>" to check progress.
+```
+
+**Typical workflow**:
+
+```bash
+# 1. Submit generation — note down BOTH IDs from the output
+lh gen image "A cute cat"
+#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95
+
+# 2. Wait & download using generationId + asyncTaskId (the UUID)
+lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o cat.png
+```
+
+---
+
+## `lh generate video <prompt>` / `lh gen video <prompt>`
+
+Generate video from text prompt. This is an async operation.
+
+**Source**: `apps/cli/src/commands/generate/video.ts`
+
+```bash
+lh gen video "A cat playing piano" -m <model> -p <provider> [options]
+```
+
+| Option                      | Description              | Required |
+| --------------------------- | ------------------------ | -------- |
+| `-m, --model <model>`       | Model ID                 | Yes      |
+| `-p, --provider <provider>` | Provider name            | Yes      |
+| `--aspect-ratio <ratio>`    | Aspect ratio (e.g. 16:9) | No       |
+| `--duration <sec>`          | Duration in seconds      | No       |
+| `--resolution <res>`        | Resolution (e.g. 720p)   | No       |
+| `--seed <n>`                | Random seed              | No       |
+| `--json`                    | Output raw JSON          | No       |
+
+**Note**: Unlike image, video requires `-m` and `-p` (no defaults). Use `lh model list <provider> --type video` to find available video models.
+
+**Output** (non-JSON):
+
+```
+✓ Video generation started
+  Batch ID: gb_xxx
+  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                            This is the asyncTaskId — use this for status/download
+
+Use "lh generate status <generationId> <asyncTaskId>" to check progress.
+```
+
+**Typical workflow**:
+
+```bash
+# 1. Find available video models for a provider
+lh model list volcengine --json | grep -i seedance
+
+# 2. Submit generation — note down BOTH IDs from the output
+lh gen video "A cat on a runway" -m doubao-seedance-2-0-260128 -p volcengine \
+  --aspect-ratio 9:16 --duration 5 --resolution 1080p
+#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95
+
+# 3. Wait & download using generationId + asyncTaskId (the UUID)
+lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o result.mp4 --timeout 600
+```
+
+---
+
+## `lh generate tts <text>` / `lh gen tts <text>`
+
+Text-to-speech generation.
+
+**Source**: `apps/cli/src/commands/generate/tts.ts`
+
+```bash
+lh gen tts "Hello, world!" [options]
+```
+
+---
+
+## `lh generate asr <audioFile>` / `lh gen asr <audioFile>`
+
+Audio-to-text transcription (Automatic Speech Recognition).
+
+**Source**: `apps/cli/src/commands/generate/asr.ts`
+
+```bash
+lh gen asr recording.wav [options]
+```
+
+---
+
+## `lh generate download <generationId> <asyncTaskId>`
+
+Wait for an async generation task to complete and download the result file.
+
+**Source**: `apps/cli/src/commands/generate/index.ts`
+
+> ⚠️ `<asyncTaskId>` is the UUID printed after "→ Task" in the video/image output.
+> Do **not** pass the generation ID (`gen_xxx`) here — that will cause a server error.
+
+```bash
+lh gen download <generationId> <asyncTaskId> [-o output.png]
+lh gen download gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx -o ~/Desktop/result.mp4 --timeout 600
+```
+
+| Option                | Description                              | Default                |
+| --------------------- | ---------------------------------------- | ---------------------- |
+| `-o, --output <path>` | Output file path (auto-detect extension) | `<generationId>.<ext>` |
+| `--interval <sec>`    | Polling interval in seconds              | `5`                    |
+| `--timeout <sec>`     | Timeout in seconds (0 = no timeout)      | `300`                  |
+
+**Behavior**:
+
+1. Polls `generation.getGenerationStatus` at the specified interval
+2. Shows live progress: `⋯ Status: processing... (42s)`
+3. On success: downloads asset URL to local file
+4. On error / wrong ID: displays a clear message pointing to the correct ID format
+5. On timeout: suggests using `lh gen status` to check later
+
+---
+
+## `lh generate status <generationId> <asyncTaskId>`
+
+Check the status of an async generation task.
+
+> ⚠️ `<asyncTaskId>` is the UUID printed after "→ Task" in the video/image output.
+> Do **not** pass the generation ID (`gen_xxx`) here — that will cause a server error.
+
+```bash
+lh gen status <generationId> <asyncTaskId> [--json]
+lh gen status gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+| Option   | Description              |
+| -------- | ------------------------ |
+| `--json` | Output raw JSON response |
+
+**Displays**:
+
+- Status (color-coded): `success` (green), `error` (red), `processing` (yellow), `pending` (cyan)
+- Error message (if failed)
+- Asset URL and thumbnail URL (if completed)
+
+---
+
+## `lh generate list`
+
+List all generation topics.
+
+```bash
+lh gen list [--json [fields]]
+```
+
+**Table columns**: ID, TITLE, TYPE, UPDATED
+
+---
+
+## Backend Architecture
+
+Image and video generation use an async task pattern:
+
+1. **Create topic** → `generationTopic.createTopic`
+2. **Submit generation** → `image.createImage` / `video.createVideo`
+   - Creates batch + generation + asyncTask records in a DB transaction
+   - Triggers async background task (image via `createAsyncCaller`, video via `initModelRuntimeFromDB`)
+   - Returns `{ data: { batch, generations }, success }` with `asyncTaskId` in each generation
+3. **Poll status** → `generation.getGenerationStatus`
+   - Input: `{ generationId, asyncTaskId }` — both are required, and `asyncTaskId` must be the
+     UUID from the `async_tasks` table, not `gen_xxx`
+   - Returns `{ status, error, generation }` (generation includes asset URLs on success)
+   - Before querying, calls `checkTimeoutTasks` which marks tasks as `error` if they have been
+     `pending` or `processing` for more than ~5 minutes (`ASYNC_TASK_TIMEOUT = 298s`)
+
+**Server routes**:
+
+- `src/server/routers/lambda/image/index.ts` — image creation (uses `authedProcedure` + `serverDatabase`)
+- `src/server/routers/lambda/video/index.ts` — video creation (uses `authedProcedure` + `serverDatabase`)
+- `src/server/routers/lambda/generation.ts` — status checking
+- `packages/database/src/models/asyncTask.ts` — `AsyncTaskModel` including `checkTimeoutTasks`
+
+**Note**: Image/video routes do NOT use the `keyVaults` middleware — they read API keys from the database via `initModelRuntimeFromDB` or `createAsyncCaller`.

.agents/skills/cli/references/knowledge.md

@@ -0,0 +1,281 @@
+# Knowledge Base, File & Document Commands
+
+## Knowledge Base (`lh kb`)
+
+Manage knowledge bases for RAG (Retrieval-Augmented Generation). Supports directory tree structure with folders, documents, and file uploads.
+
+**Source**: `apps/cli/src/commands/kb.ts`
+
+### `lh kb list`
+
+```bash
+lh kb list [--json [fields]]
+```
+
+**Table columns**: ID, NAME, DESCRIPTION, UPDATED
+
+### `lh kb view <id>`
+
+```bash
+lh kb view [fields]] < id > [--json
+```
+
+**Displays**: Name, description, full directory tree with all files and documents (recursively fetched). Shows indented tree structure with item type (File/Doc), file type, and size.
+
+**API**: Uses `file.getKnowledgeItems` to recursively fetch items. Folders (`custom/folder` fileType) are traversed in parallel via `Promise.all` for performance.
+
+### `lh kb create`
+
+```bash
+lh kb create -n [--avatar < name > [-d < desc > ] < url > ]
+```
+
+| Option                     | Description         | Required |
+| -------------------------- | ------------------- | -------- |
+| `-n, --name <name>`        | Knowledge base name | Yes      |
+| `-d, --description <desc>` | Description         | No       |
+| `--avatar <url>`           | Avatar URL          | No       |
+
+**Output**: Created KB ID. Note: backend returns ID as a string directly (not an object).
+
+### `lh kb edit <id>`
+
+```bash
+lh kb edit [-d [--avatar < id > [-n < name > ] < desc > ] < url > ]
+```
+
+Requires at least one change flag. Errors if none specified.
+
+### `lh kb delete <id>`
+
+```bash
+lh kb delete [--yes] < id > [--remove-files]
+```
+
+| Option           | Description                  |
+| ---------------- | ---------------------------- |
+| `--remove-files` | Also delete associated files |
+| `--yes`          | Skip confirmation            |
+
+### `lh kb add-files <knowledgeBaseId>`
+
+```bash
+lh kb add-files <kbId> --ids <fileId1> <fileId2> ...
+```
+
+Link existing files to a knowledge base.
+
+### `lh kb remove-files <knowledgeBaseId>`
+
+```bash
+lh kb remove-files <kbId> --ids <fileId1> <fileId2> ... [--yes]
+```
+
+Unlink files from a knowledge base.
+
+### `lh kb mkdir <knowledgeBaseId>`
+
+```bash
+lh kb mkdir < kbId > -n < name > [--parent < folderId > ]
+```
+
+Create a folder in a knowledge base. Uses `document.createDocument` with `fileType: 'custom/folder'`.
+
+| Option                | Description      | Required |
+| --------------------- | ---------------- | -------- |
+| `-n, --name <name>`   | Folder name      | Yes      |
+| `--parent <parentId>` | Parent folder ID | No       |
+
+### `lh kb create-doc <knowledgeBaseId>`
+
+```bash
+lh kb create-doc [--parent < kbId > -t < title > [-c < content > ] < folderId > ]
+```
+
+Create a document in a knowledge base. Uses `document.createDocument` with `fileType: 'custom/document'`.
+
+| Option                 | Description      | Required |
+| ---------------------- | ---------------- | -------- |
+| `-t, --title <title>`  | Document title   | Yes      |
+| `-c, --content <text>` | Document content | No       |
+| `--parent <parentId>`  | Parent folder ID | No       |
+
+### `lh kb move <id>`
+
+```bash
+lh kb move < id > --type < file | doc > [--parent < folderId > ]
+```
+
+Move a file or document to a different folder (or to root if `--parent` is omitted).
+
+| Option                | Description                      | Default |
+| --------------------- | -------------------------------- | ------- |
+| `--type <type>`       | Item type: `file` or `doc`       | `file`  |
+| `--parent <parentId>` | Target folder ID (omit for root) | -       |
+
+Uses `document.updateDocument` for docs, `file.updateFile` for files.
+
+### `lh kb upload <knowledgeBaseId> <filePath>`
+
+```bash
+lh kb upload <kbId> <filePath> [--parent <folderId>]
+```
+
+Upload a local file to a knowledge base via S3 presigned URL.
+
+| Option                | Description      |
+| --------------------- | ---------------- |
+| `--parent <parentId>` | Parent folder ID |
+
+**Flow**: Compute SHA-256 hash → get presigned URL via `upload.createS3PreSignedUrl` → PUT to S3 → create file record via `file.createFile`.
+
+---
+
+## File Management (`lh file`)
+
+Manage uploaded files.
+
+**Source**: `apps/cli/src/commands/file.ts`
+
+### `lh file list`
+
+```bash
+lh file list [--kb-id [-L [--json [fields]] < id > ] < n > ]
+```
+
+| Option            | Description              | Default |
+| ----------------- | ------------------------ | ------- |
+| `--kb-id <id>`    | Filter by knowledge base | -       |
+| `-L, --limit <n>` | Maximum items            | `30`    |
+
+**Table columns**: ID, NAME, TYPE, SIZE, UPDATED
+
+### `lh file view <id>`
+
+```bash
+lh file view [fields]] < id > [--json
+```
+
+**Displays**: Name, type, size, chunking status, embedding status.
+
+### `lh file delete <ids...>`
+
+```bash
+lh file delete [--yes] < id1 > [id2...]
+```
+
+Supports deleting multiple files at once.
+
+### `lh file recent`
+
+```bash
+lh file recent [-L [--json [fields]] < n > ]
+```
+
+| Option            | Description     | Default |
+| ----------------- | --------------- | ------- |
+| `-L, --limit <n>` | Number of items | `10`    |
+
+---
+
+## Document Management (`lh doc`)
+
+Manage text documents (notes, wiki pages).
+
+**Source**: `apps/cli/src/commands/doc.ts`
+
+### `lh doc list`
+
+```bash
+lh doc list [-L [--file-type [--source-type [--json [fields]] < n > ] < type > ] < type > ]
+```
+
+| Option                 | Description                                   | Default |
+| ---------------------- | --------------------------------------------- | ------- |
+| `-L, --limit <n>`      | Maximum items                                 | `30`    |
+| `--file-type <type>`   | Filter by file type                           | -       |
+| `--source-type <type>` | Filter by source type (file, web, api, topic) | -       |
+
+**Table columns**: ID, TITLE, TYPE, UPDATED
+
+### `lh doc view <id>`
+
+```bash
+lh doc view [fields]] < id > [--json
+```
+
+**Displays**: Title, type, KB association, updated time, full content.
+
+### `lh doc create`
+
+```bash
+lh doc create -t [-F [--parent [--slug [--kb [--file-type < title > [-b < body > ] < path > ] < id > ] < slug > ] < id > ] < type > ]
+```
+
+| Option                   | Description                                     | Required |
+| ------------------------ | ----------------------------------------------- | -------- |
+| `-t, --title <title>`    | Document title                                  | Yes      |
+| `-b, --body <content>`   | Document body text                              | No       |
+| `-F, --body-file <path>` | Read body from file                             | No       |
+| `--parent <id>`          | Parent document ID                              | No       |
+| `--slug <slug>`          | Custom URL slug                                 | No       |
+| `--kb <id>`              | Knowledge base ID to associate with             | No       |
+| `--file-type <type>`     | File type (e.g. custom/document, custom/folder) | No       |
+
+`-b` and `-F` are mutually exclusive; `-F` reads the file content as the body.
+
+### `lh doc batch-create <file>`
+
+Batch create documents from a JSON file. The file must contain a non-empty array of document objects.
+
+```bash
+lh doc batch-create documents.json
+```
+
+Each object in the array can have: `title`, `content`, `fileType`, `knowledgeBaseId`, `parentId`, `slug`.
+
+### `lh doc edit <id>`
+
+```bash
+lh doc edit [-b [-F [--parent [--file-type < id > [-t < title > ] < body > ] < path > ] < id > ] < type > ]
+```
+
+### `lh doc delete <ids...>`
+
+```bash
+lh doc delete [--yes] < id1 > [id2...]
+```
+
+### `lh doc parse <fileId>`
+
+Parse an uploaded file into a document.
+
+```bash
+lh doc parse [--json [fields]] < fileId > [--with-pages]
+```
+
+| Option         | Description             |
+| -------------- | ----------------------- |
+| `--with-pages` | Preserve page structure |
+
+**Output**: Parsed title and content preview.
+
+### `lh doc link-topic <docId> <topicId>`
+
+Associate a document with a topic. Creates a linked copy via the notebook router.
+
+```bash
+lh doc link-topic <docId> <topicId>
+```
+
+### `lh doc topic-docs <topicId>`
+
+List documents associated with a topic.
+
+```bash
+lh doc topic-docs [--json [fields]] < topicId > [--type < type > ]
+```
+
+| Option          | Description                                      |
+| --------------- | ------------------------------------------------ |
+| `--type <type>` | Filter by type (article, markdown, note, report) |

.agents/skills/cli/references/memory.md

@@ -0,0 +1,138 @@
+# Memory Commands
+
+Manage user memories - the AI's long-term knowledge about users.
+
+**Source**: `apps/cli/src/commands/memory.ts`
+
+## Memory Categories
+
+| Category     | Description                               |
+| ------------ | ----------------------------------------- |
+| `identity`   | User's name, role, relationships          |
+| `activity`   | Recent activities and their status        |
+| `context`    | Ongoing contexts, projects, goals         |
+| `experience` | Past experiences and key learnings        |
+| `preference` | User preferences, directives, suggestions |
+
+---
+
+## `lh memory list [category]`
+
+List memory entries, optionally filtered by category.
+
+```bash
+lh memory list            # All categories
+lh memory list identity   # Only identity memories
+lh memory list preference # Only preferences
+```
+
+| Option            | Description |
+| ----------------- | ----------- |
+| `--json [fields]` | JSON output |
+
+**Output**: Grouped by category, showing type/status and descriptions.
+
+---
+
+## `lh memory create`
+
+Create a new identity memory entry.
+
+```bash
+lh memory create [options]
+```
+
+| Option                     | Description              |
+| -------------------------- | ------------------------ |
+| `--type <type>`            | Memory type              |
+| `--role <role>`            | User's role              |
+| `--relationship <rel>`     | Relationship description |
+| `-d, --description <desc>` | Description              |
+| `--labels <labels...>`     | Extracted labels         |
+
+---
+
+## `lh memory edit <category> <id>`
+
+Edit a memory entry. Options vary by category:
+
+```bash
+lh memory edit identity < id > [options]
+lh memory edit activity < id > [options]
+lh memory edit context < id > [options]
+lh memory edit experience < id > [options]
+lh memory edit preference < id > [options]
+```
+
+### Category-specific Options
+
+**identity**:
+
+- `--type <type>`, `--role <role>`, `--relationship <rel>`
+
+**activity**:
+
+- `--narrative <text>`, `--notes <text>`, `--status <status>`
+
+**context**:
+
+- `--title <title>`, `--description <desc>`, `--status <status>`
+
+**experience**:
+
+- `--situation <text>`, `--action <text>`, `--key-learning <text>`
+
+**preference**:
+
+- `--directives <text>`, `--suggestions <text>`
+
+---
+
+## `lh memory delete <category> <id>`
+
+```bash
+lh memory delete identity < id > [--yes]
+```
+
+---
+
+## `lh memory persona`
+
+Display the compiled memory persona summary.
+
+```bash
+lh memory persona [--json [fields]]
+```
+
+**Output**: Summarized user profile built from all memory categories.
+
+---
+
+## `lh memory extract`
+
+Trigger async memory extraction from chat history.
+
+```bash
+lh memory extract [--from [--to < date > ] < date > ]
+```
+
+| Option          | Description             |
+| --------------- | ----------------------- |
+| `--from <date>` | Start date (ISO format) |
+| `--to <date>`   | End date (ISO format)   |
+
+Starts a background task that analyzes chat history and creates new memory entries.
+
+---
+
+## `lh memory extract-status`
+
+Check the status of a memory extraction task.
+
+```bash
+lh memory extract-status [--task-id [--json [fields]] < id > ]
+```
+
+| Option           | Description         |
+| ---------------- | ------------------- |
+| `--task-id <id>` | Check specific task |

.agents/skills/cli/references/models-providers.md

@@ -0,0 +1,186 @@
+# Model & Provider Commands
+
+## Model Management (`lh model`)
+
+Manage AI models within providers.
+
+**Source**: `apps/cli/src/commands/model.ts`
+
+### `lh model list <providerId>`
+
+List models for a specific provider.
+
+```bash
+lh model list openai
+lh model list openai --type image --enabled
+lh model list lobehub --type video --json
+```
+
+| Option            | Description                                                                            | Default |
+| ----------------- | -------------------------------------------------------------------------------------- | ------- |
+| `-L, --limit <n>` | Maximum items                                                                          | `50`    |
+| `--enabled`       | Only show enabled models                                                               | `false` |
+| `--type <type>`   | Filter by model type (`chat\|embedding\|tts\|stt\|image\|video\|text2music\|realtime`) | -       |
+| `--json [fields]` | Output JSON, optionally specify fields                                                 | -       |
+
+**Table columns**: ID, NAME, ENABLED, TYPE
+
+**Backend**: `aiModel.getAiProviderModelList` → `AiInfraRepos.getAiProviderModelList` (supports `type` filter at repository level)
+
+### `lh model view <id>`
+
+```bash
+lh model view [fields]] < modelId > [--json
+```
+
+**Displays**: Name, provider, type, enabled status, capabilities.
+
+### `lh model create`
+
+```bash
+lh model create --id [--type < id > --provider < providerId > [--display-name < name > ] < type > ]
+```
+
+| Option                    | Description  | Default  |
+| ------------------------- | ------------ | -------- |
+| `--id <id>`               | Model ID     | Required |
+| `--provider <providerId>` | Provider ID  | Required |
+| `--display-name <name>`   | Display name | -        |
+| `--type <type>`           | Model type   | `chat`   |
+
+### `lh model edit <id>`
+
+```bash
+lh model edit [--type < modelId > --provider < providerId > [--display-name < name > ] < type > ]
+```
+
+### `lh model toggle <id>`
+
+Enable or disable a model.
+
+```bash
+lh model toggle < modelId > --provider < providerId > --enable
+lh model toggle < modelId > --provider < providerId > --disable
+```
+
+| Option                    | Description       | Required     |
+| ------------------------- | ----------------- | ------------ |
+| `--provider <providerId>` | Provider ID       | Yes          |
+| `--enable`                | Enable the model  | One required |
+| `--disable`               | Disable the model | One required |
+
+### `lh model batch-toggle <ids...>`
+
+Enable or disable multiple models at once.
+
+```bash
+lh model batch-toggle model1 model2 model3 --provider openai --enable
+```
+
+### `lh model delete <id>`
+
+```bash
+lh model delete < modelId > --provider < providerId > [--yes]
+```
+
+### `lh model clear`
+
+Clear all models (or only remote/fetched models) for a provider.
+
+```bash
+lh model clear --provider [--yes] < providerId > [--remote]
+```
+
+---
+
+## Provider Management (`lh provider`)
+
+Manage AI service providers.
+
+**Source**: `apps/cli/src/commands/provider.ts`
+
+### `lh provider list`
+
+```bash
+lh provider list [--json [fields]]
+```
+
+**Table columns**: ID, NAME, ENABLED, SOURCE
+
+### `lh provider view <id>`
+
+```bash
+lh provider view [fields]] < providerId > [--json
+```
+
+**Displays**: Name, enabled status, source, configuration.
+
+### `lh provider create`
+
+```bash
+lh provider create --id [-d [--logo [--sdk-type < id > -n < name > [-s < source > ] < desc > ] < url > ] < type > ]
+```
+
+| Option                     | Description                                       | Default  |
+| -------------------------- | ------------------------------------------------- | -------- |
+| `--id <id>`                | Provider ID                                       | Required |
+| `-n, --name <name>`        | Provider name                                     | Required |
+| `-s, --source <source>`    | Source type (`builtin` or `custom`)               | `custom` |
+| `-d, --description <desc>` | Provider description                              | -        |
+| `--logo <logo>`            | Provider logo URL                                 | -        |
+| `--sdk-type <sdkType>`     | SDK type (openai, anthropic, azure, bedrock, ...) | -        |
+
+### `lh provider edit <id>`
+
+```bash
+lh provider edit [-d [--logo [--sdk-type < providerId > [-n < name > ] < desc > ] < url > ] < type > ]
+```
+
+Requires at least one change flag.
+
+### `lh provider config <id>`
+
+Configure provider settings (API key, base URL, etc.).
+
+```bash
+lh provider config openai --api-key sk-xxx
+lh provider config openai --base-url https://custom-endpoint.com
+lh provider config openai --show
+lh provider config openai --show --json
+```
+
+| Option                   | Description                       |
+| ------------------------ | --------------------------------- |
+| `--api-key <key>`        | Set API key                       |
+| `--base-url <url>`       | Set base URL                      |
+| `--check-model <model>`  | Set connectivity check model      |
+| `--enable-response-api`  | Enable Response API mode (OpenAI) |
+| `--disable-response-api` | Disable Response API mode         |
+| `--fetch-on-client`      | Enable fetching models on client  |
+| `--no-fetch-on-client`   | Disable fetching models on client |
+| `--show`                 | Show current config               |
+| `--json [fields]`        | Output JSON (with --show)         |
+
+**Important**: The `lobehub` provider is platform-managed. Attempting to set `--api-key` or `--base-url` on it will be rejected with an error message.
+
+### `lh provider test <id>`
+
+Test provider connectivity.
+
+```bash
+lh provider test openai
+lh provider test openai -m gpt-4o --json
+```
+
+### `lh provider toggle <id>`
+
+```bash
+lh provider toggle < providerId > --enable
+lh provider toggle < providerId > --disable
+```
+
+### `lh provider delete <id>`
+
+```bash
+lh provider delete < providerId > [--yes]
+```

.agents/skills/cli/references/search-config.md

@@ -0,0 +1,94 @@
+# Search & Configuration Commands
+
+## Global Search (`lh search`)
+
+Search across all LobeHub resource types.
+
+**Source**: `apps/cli/src/commands/search.ts`
+
+### `lh search <query>`
+
+```bash
+lh search "meeting notes" [-t [-L [--json [fields]] < type > ] < n > ]
+```
+
+| Option              | Description             | Default   |
+| ------------------- | ----------------------- | --------- |
+| `-t, --type <type>` | Filter by resource type | All types |
+| `-L, --limit <n>`   | Results per type        | `10`      |
+
+### Searchable Types
+
+| Type             | Description                  |
+| ---------------- | ---------------------------- |
+| `agent`          | AI agents                    |
+| `topic`          | Conversation topics          |
+| `file`           | Uploaded files               |
+| `folder`         | File folders                 |
+| `message`        | Chat messages                |
+| `page`           | Documents/pages              |
+| `memory`         | User memories                |
+| `mcp`            | MCP servers                  |
+| `plugin`         | Installed plugins            |
+| `communityAgent` | Community marketplace agents |
+| `knowledgeBase`  | Knowledge bases              |
+
+**Output**: Results grouped by type, showing ID, title/name, description.
+
+---
+
+## User Configuration (`lh whoami` / `lh usage`)
+
+**Source**: `apps/cli/src/commands/config.ts`
+
+### `lh whoami`
+
+Display current authenticated user information.
+
+```bash
+lh whoami [--json [fields]]
+```
+
+**Displays**: Name, username, email, user ID, subscription plan.
+
+### `lh usage`
+
+Display usage statistics.
+
+```bash
+lh usage [--month [--daily] [--json [fields]] < YYYY-MM > ]
+```
+
+| Option              | Description    | Default                 |
+| ------------------- | -------------- | ----------------------- |
+| `--month <YYYY-MM>` | Month to query | Current month           |
+| `--daily`           | Group by day   | `false` (monthly total) |
+
+**Output**: Token usage, costs, and model breakdown for the specified period.
+
+---
+
+## Global Options
+
+These options are available across most commands:
+
+| Option            | Description                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `--json [fields]` | Output as JSON; optionally filter to specific fields (comma-separated) |
+| `--yes`           | Skip confirmation prompts for destructive operations                   |
+| `-L, --limit <n>` | Pagination limit for list commands                                     |
+| `-v, --verbose`   | Enable verbose/debug logging                                           |
+| `--help`          | Show command help                                                      |
+| `--version`       | Show CLI version                                                       |
+
+### JSON Field Filtering
+
+The `--json` option supports field selection:
+
+```bash
+# Full JSON output
+lh agent list --json
+
+# Only specific fields
+lh agent list --json "id,title,model"
+```

.agents/skills/cli/references/skills-plugins.md

@@ -0,0 +1,149 @@
+# Skill & Plugin Commands
+
+## Skill Management (`lh skill`)
+
+Manage agent skills (custom instructions and capabilities).
+
+**Source**: `apps/cli/src/commands/skill.ts`
+
+### `lh skill list`
+
+```bash
+lh skill list [--source [--json [fields]] < source > ]
+```
+
+| Option              | Description                         |
+| ------------------- | ----------------------------------- |
+| `--source <source>` | Filter: `builtin`, `market`, `user` |
+
+**Table columns**: ID, NAME, DESCRIPTION, SOURCE, IDENTIFIER
+
+### `lh skill view <id>`
+
+```bash
+lh skill view [fields]] < id > [--json
+```
+
+**Displays**: Name, description, source, identifier, content.
+
+### `lh skill create`
+
+```bash
+lh skill create -n < name > -d < desc > -c < content > [-i < identifier > ]
+```
+
+| Option                     | Description                         | Required |
+| -------------------------- | ----------------------------------- | -------- |
+| `-n, --name <name>`        | Skill name                          | Yes      |
+| `-d, --description <desc>` | Description                         | Yes      |
+| `-c, --content <content>`  | Skill content (prompt/instructions) | Yes      |
+| `-i, --identifier <id>`    | Custom identifier                   | No       |
+
+### `lh skill edit <id>`
+
+```bash
+lh skill edit [-n [-d < id > [-c < content > ] < name > ] < desc > ]
+```
+
+### `lh skill delete <id>`
+
+```bash
+lh skill delete < id > [--yes]
+```
+
+### `lh skill search <query>`
+
+```bash
+lh skill search [fields]] < query > [--json
+```
+
+### `lh skill install <source>` (alias: `lh skill i`)
+
+Install a skill. Auto-detects source type from the input:
+
+```bash
+# GitHub (URL or owner/repo shorthand)
+lh skill install lobehub/skill-repo
+lh skill install https://github.com/lobehub/skill-repo
+lh skill install lobehub/skill-repo --branch dev
+
+# ZIP URL
+lh skill install https://example.com/skill.zip
+
+# Marketplace identifier
+lh skill install my-cool-skill
+lh skill i my-cool-skill
+```
+
+| Option              | Description               | Notes    |
+| ------------------- | ------------------------- | -------- |
+| `--branch <branch>` | Branch name (GitHub only) | Optional |
+
+**Detection rules**:
+
+- `https://github.com/...` or `owner/repo` → GitHub
+- Other `https://...` URLs → ZIP URL
+- Everything else → marketplace identifier
+
+### Resource Commands
+
+#### `lh skill resources <id>`
+
+List files/resources within a skill.
+
+```bash
+lh skill resources [fields]] < id > [--json
+```
+
+**Displays**: Path, type, size.
+
+#### `lh skill read-resource <id> <path>`
+
+Read a specific resource file from a skill.
+
+```bash
+lh skill read-resource <skillId> <path>
+```
+
+**Output**: File content or JSON metadata.
+
+---
+
+## Plugin Management (`lh plugin`)
+
+Install and manage plugins (external tool integrations).
+
+**Source**: `apps/cli/src/commands/plugin.ts`
+
+### `lh plugin list`
+
+```bash
+lh plugin list [--json [fields]]
+```
+
+**Table columns**: ID, IDENTIFIER, TYPE, TITLE
+
+### `lh plugin install`
+
+```bash
+lh plugin install -i [--settings < identifier > --manifest < json > [--type < type > ] < json > ]
+```
+
+| Option                  | Description                | Required               |
+| ----------------------- | -------------------------- | ---------------------- |
+| `-i, --identifier <id>` | Plugin identifier          | Yes                    |
+| `--manifest <json>`     | Plugin manifest JSON       | Yes                    |
+| `--type <type>`         | `plugin` or `customPlugin` | No (default: `plugin`) |
+| `--settings <json>`     | Plugin settings JSON       | No                     |
+
+### `lh plugin uninstall <id>`
+
+```bash
+lh plugin uninstall < id > [--yes]
+```
+
+### `lh plugin update <id>`
+
+```bash
+lh plugin update [--settings < id > [--manifest < json > ] < json > ]
+```

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

@@ -0,0 +1,106 @@
+---
+name: db-migrations
+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
+
+## Step 1: Generate Migrations
+
+```bash
+bun run db:generate
+```
+
+This generates:
+
+- `packages/database/migrations/0046_meaningless_file_name.sql`
+
+And updates:
+
+- `packages/database/migrations/meta/_journal.json`
+- `packages/database/src/core/migrations.json`
+- `docs/development/database-schema.dbml`
+
+## Custom Migrations (e.g. CREATE EXTENSION)
+
+For migrations that don't involve Drizzle schema changes (e.g. enabling PostgreSQL extensions), use the `--custom` flag:
+
+```bash
+bunx drizzle-kit generate --custom --name=enable_pg_search
+```
+
+This generates an empty SQL file and properly updates `_journal.json` and snapshot. Then edit the generated SQL file to add your custom SQL:
+
+```sql
+-- Custom SQL migration file, put your code below! --
+CREATE EXTENSION IF NOT EXISTS pg_search;
+```
+
+**Do NOT manually create migration files or edit `_journal.json`** — always use `drizzle-kit generate` to ensure correct journal entries and snapshots.
+
+## Step 2: Optimize Migration SQL Filename
+
+Rename auto-generated filename to be meaningful:
+
+`0046_meaningless_file_name.sql` → `0046_user_add_avatar_column.sql`
+
+## Step 3: Use Idempotent Clauses (Defensive Programming)
+
+Always use defensive clauses to make migrations idempotent (safe to re-run):
+
+### CREATE TABLE
+
+```sql
+-- ✅ Good
+CREATE TABLE IF NOT EXISTS "agent_eval_runs" (
+  "id" text PRIMARY KEY NOT NULL,
+  "name" text,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+
+-- ❌ Bad
+CREATE TABLE "agent_eval_runs" (...);
+```
+
+### ALTER TABLE - Columns
+
+```sql
+-- ✅ Good
+ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "avatar" text;
+ALTER TABLE "posts" DROP COLUMN IF EXISTS "deprecated_field";
+
+-- ❌ Bad
+ALTER TABLE "users" ADD COLUMN "avatar" text;
+```
+
+### ALTER TABLE - Foreign Key Constraints
+
+PostgreSQL has no `ADD CONSTRAINT IF NOT EXISTS`. Use `DROP IF EXISTS` + `ADD`:
+
+```sql
+-- ✅ Good: Drop first, then add (idempotent)
+ALTER TABLE "agent_eval_datasets" DROP CONSTRAINT IF EXISTS "agent_eval_datasets_user_id_users_id_fk";
+ALTER TABLE "agent_eval_datasets" ADD CONSTRAINT "agent_eval_datasets_user_id_users_id_fk"
+  FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+
+-- ❌ Bad: Will fail if constraint already exists
+ALTER TABLE "agent_eval_datasets" ADD CONSTRAINT "agent_eval_datasets_user_id_users_id_fk"
+  FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+```
+
+### DROP TABLE / INDEX
+
+```sql
+-- ✅ Good
+DROP TABLE IF EXISTS "old_table";
+CREATE INDEX IF NOT EXISTS "users_email_idx" ON "users" ("email");
+CREATE UNIQUE INDEX IF NOT EXISTS "users_email_unique" ON "users" USING btree ("email");
+
+-- ❌ Bad
+DROP TABLE "old_table";
+CREATE INDEX "users_email_idx" ON "users" ("email");
+```
+
+## Step 4: Update Journal Tag
+
+After renaming the migration SQL file in Step 2, update the `tag` field in `packages/database/migrations/meta/_journal.json` to match the new filename (without `.sql` extension).

.agents/skills/desktop/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 ## Architecture Overview
 
-LobeChat desktop is built on Electron with main-renderer architecture:
+LobeHub desktop is built on Electron with main-renderer architecture:
 
 1. **Main Process** (`apps/desktop/src/main`): App lifecycle, system APIs, window management
 2. **Renderer Process**: Reuses web code from `src/`
@@ -17,6 +17,7 @@ LobeChat desktop is built on Electron with main-renderer architecture:
 ## Adding New Desktop Features
 
 ### 1. Create Controller
+
 Location: `apps/desktop/src/main/controllers/`
 
 ```typescript
@@ -36,14 +37,21 @@ export default class NewFeatureCtr extends ControllerModule {
 Register in `apps/desktop/src/main/controllers/registry.ts`.
 
 ### 2. Define IPC Types
+
 Location: `packages/electron-client-ipc/src/types.ts`
 
 ```typescript
-export interface SomeParams { /* ... */ }
-export interface SomeResult { success: boolean; error?: string }
+export interface SomeParams {
+  /* ... */
+}
+export interface SomeResult {
+  success: boolean;
+  error?: string;
+}
 ```
 
 ### 3. Create Renderer Service
+
 Location: `src/services/electron/`
 
 ```typescript
@@ -57,14 +65,17 @@ export const newFeatureService = async (params: SomeParams) => {
 ```
 
 ### 4. Implement Store Action
+
 Location: `src/store/`
 
 ### 5. Add Tests
+
 Location: `apps/desktop/src/main/controllers/__tests__/`
 
 ## Detailed Guides
 
 See `references/` for specific topics:
+
 - **Feature implementation**: `references/feature-implementation.md`
 - **Local tools workflow**: `references/local-tools.md`
 - **Menu configuration**: `references/menu-config.md`

.agents/skills/desktop/references/feature-implementation.md

@@ -22,7 +22,10 @@ Main Process                    Renderer Process
 
 ```typescript
 // apps/desktop/src/main/controllers/NotificationCtr.ts
-import type { ShowDesktopNotificationParams, DesktopNotificationResult } from '@lobechat/electron-client-ipc';
+import type {
+  ShowDesktopNotificationParams,
+  DesktopNotificationResult,
+} from '@lobechat/electron-client-ipc';
 import { Notification } from 'electron';
 import { ControllerModule, IpcMethod } from '@/controllers';
 
@@ -30,7 +33,9 @@ export default class NotificationCtr extends ControllerModule {
   static override readonly groupName = 'notification';
 
   @IpcMethod()
-  async showDesktopNotification(params: ShowDesktopNotificationParams): Promise<DesktopNotificationResult> {
+  async showDesktopNotification(
+    params: ShowDesktopNotificationParams,
+  ): Promise<DesktopNotificationResult> {
     if (!Notification.isSupported()) {
       return { error: 'Notifications not supported', success: false };
     }
@@ -72,8 +77,7 @@ import { ensureElectronIpc } from '@/utils/electron/ipc';
 const ipc = ensureElectronIpc();
 
 export const notificationService = {
-  show: (params: ShowDesktopNotificationParams) =>
-    ipc.notification.showDesktopNotification(params),
+  show: (params: ShowDesktopNotificationParams) => ipc.notification.showDesktopNotification(params),
 };
 ```
 

.agents/skills/desktop/references/menu-config.md

@@ -30,7 +30,13 @@ export const createAppMenu = (win: BrowserWindow) => {
     {
       label: 'File',
       submenu: [
-        { label: 'New', accelerator: 'CmdOrCtrl+N', click: () => { /* ... */ } },
+        {
+          label: 'New',
+          accelerator: 'CmdOrCtrl+N',
+          click: () => {
+            /* ... */
+          },
+        },
         { type: 'separator' },
         { role: 'quit' },
       ],
@@ -82,9 +88,7 @@ import { i18n } from '../locales';
 const template = [
   {
     label: i18n.t('menu.file'),
-    submenu: [
-      { label: i18n.t('menu.new'), click: createNew },
-    ],
+    submenu: [{ label: i18n.t('menu.new'), click: createNew }],
   },
 ];
 ```

.agents/skills/desktop/references/window-management.md

@@ -131,8 +131,12 @@ const window = new BrowserWindow({
 ```
 
 ```css
-.titlebar { -webkit-app-region: drag; }
-.titlebar-button { -webkit-app-region: no-drag; }
+.titlebar {
+  -webkit-app-region: drag;
+}
+.titlebar-button {
+  -webkit-app-region: no-drag;
+}
 ```
 
 ## Best Practices

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

@@ -0,0 +1,155 @@
+---
+name: docs-changelog
+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
+
+## Scope Boundary (Important)
+
+This skill is only for changelog pages in:
+
+- `docs/changelog/*.mdx`
+
+This skill is **not** for GitHub Releases.\
+If the user asks for release PR body / GitHub Release notes, load `../version-release/SKILL.md`.
+
+## Mandatory Companion Skills
+
+For every docs changelog task, you MUST load:
+
+- `../microcopy/SKILL.md`
+- `../i18n/SKILL.md` (when EN/ZH pair is involved)
+
+## File and Naming Convention
+
+Use date-based file names:
+
+- English: `docs/changelog/YYYY-MM-DD-topic.mdx`
+- Chinese: `docs/changelog/YYYY-MM-DD-topic.zh-CN.mdx`
+
+EN and ZH files must exist as a pair and describe the same release facts.
+
+## Frontmatter Requirements
+
+Each file should include:
+
+```md
+---
+title: <Title>
+description: <1 sentence summary>
+tags:
+  - <Tag 1>
+  - <Tag 2>
+---
+```
+
+Rules:
+
+1. `title` should match the H1 title in meaning.
+2. `description` should be concise and user-facing.
+3. `tags` should be feature-oriented, not internal-team labels.
+
+## Content Structure (Recommended)
+
+Use this shape unless the user requests otherwise:
+
+1. `# <Title>`
+2. Opening paragraph (2-4 sentences): user-visible impact
+3. 1-3 capability sections (optional `##` headings)
+4. `## Improvements and fixes` / `## 体验优化与修复` with concise bullets
+
+Keep heading count low and avoid heading-per-bullet structure.
+
+## Writing Rules
+
+1. Keep all claims factual and tied to actual shipped changes.
+2. Explain user value first, implementation second.
+3. Prefer natural narrative paragraphs over pure bullet dumps.
+4. Avoid marketing exaggeration and vague adjectives.
+5. Keep internal terms consistent across EN/ZH files.
+6. Keep EN/ZH section order aligned and scope-aligned.
+
+## EN/ZH Synchronization Rules
+
+When generating bilingual changelogs:
+
+1. Keep the same key facts in the same order.
+2. Localize naturally; do not do literal sentence-by-sentence translation.
+3. If one version has an `Improvements and fixes` bullet list, the other should have equivalent list intent.
+4. Do not introduce capabilities in only one language unless explicitly requested.
+
+## Length Guidance
+
+- Small update: 3-5 short paragraphs total
+- Medium update: 4-7 short paragraphs + concise fix bullets
+- Large update: 6-10 short paragraphs split into 2-4 sections
+
+Do not pad content when changes are limited.
+
+## Authoring Workflow
+
+1. Collect source facts from PRs/commits/issues.
+2. Group changes by user workflow (not by internal module path).
+3. Draft EN and ZH versions with aligned structure.
+4. Verify terminology using `microcopy`/`i18n` guidance.
+5. Final pass: remove AI-like filler and tighten sentences.
+
+## Docs Changelog Template (English)
+
+```md
+---
+title: <Feature title>
+description: <One-sentence summary for users>
+tags:
+  - <Tag A>
+  - <Tag B>
+---
+
+# <Feature title>
+
+<Opening paragraph: what changed for users and why it matters.>
+
+<Optional section paragraph for key capability 1.>
+
+<Optional section paragraph for key capability 2.>
+
+## Improvements and fixes
+
+- <Fix or optimization 1>
+- <Fix or optimization 2>
+```
+
+## Docs Changelog Template (Chinese)
+
+```md
+---
+title: <功能标题>
+description: <一句话说明>
+tags:
+  - <标签 A>
+  - <标签 B>
+---
+
+# <功能标题>
+
+<开场段：这次更新给用户带来的直接变化。>
+
+<可选能力段 1。>
+
+<可选能力段 2。>
+
+## 体验优化与修复
+
+- <优化或修复 1>
+- <优化或修复 2>
+```
+
+## Quick Checklist
+
+- [ ] File path matches `docs/changelog` naming convention
+- [ ] EN and ZH versions both exist and match in facts
+- [ ] Opening paragraph explains user-facing outcome
+- [ ] Main body is narrative-first, not bullet-only
+- [ ] `Improvements and fixes` section is concise and concrete
+- [ ] No fabricated claims or unsupported scope

.agents/skills/drizzle/SKILL.md

@@ -73,9 +73,16 @@ export type AgentItem = typeof agents.$inferSelect;
 export const agents = pgTable(
   'agents',
   {
-    id: text('id').primaryKey().$defaultFn(() => idGenerator('agents')).notNull(),
-    slug: varchar('slug', { length: 100 }).$defaultFn(() => randomSlug(4)).unique(),
-    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(),
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => idGenerator('agents'))
+      .notNull(),
+    slug: varchar('slug', { length: 100 })
+      .$defaultFn(() => randomSlug(4))
+      .unique(),
+    userId: text('user_id')
+      .references(() => users.id, { onDelete: 'cascade' })
+      .notNull(),
     clientId: text('client_id'),
     chatConfig: jsonb('chat_config').$type<LobeAgentChatConfig>(),
     ...timestamps,
@@ -92,9 +99,15 @@ export const agents = pgTable(
 export const agentsKnowledgeBases = pgTable(
   'agents_knowledge_bases',
   {
-    agentId: text('agent_id').references(() => agents.id, { onDelete: 'cascade' }).notNull(),
-    knowledgeBaseId: text('knowledge_base_id').references(() => knowledgeBases.id, { onDelete: 'cascade' }).notNull(),
-    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(),
+    agentId: text('agent_id')
+      .references(() => agents.id, { onDelete: 'cascade' })
+      .notNull(),
+    knowledgeBaseId: text('knowledge_base_id')
+      .references(() => knowledgeBases.id, { onDelete: 'cascade' })
+      .notNull(),
+    userId: text('user_id')
+      .references(() => users.id, { onDelete: 'cascade' })
+      .notNull(),
     enabled: boolean('enabled').default(true),
     ...timestamps,
   },
@@ -102,28 +115,91 @@ export const agentsKnowledgeBases = pgTable(
 );
 ```
 
+## Query Style
+
+**Always use `db.select()` builder API. Never use `db.query.*` relational API** (`findMany`, `findFirst`, `with:`).
+
+The relational API generates complex lateral joins with `json_build_array` that are fragile and hard to debug.
+
+### Select Single Row
+
+```typescript
+// ✅ Good
+const [result] = await this.db
+  .select()
+  .from(agents)
+  .where(eq(agents.id, id))
+  .limit(1);
+return result;
+
+// ❌ Bad: relational API
+return this.db.query.agents.findFirst({
+  where: eq(agents.id, id),
+});
+```
+
+### Select with JOIN
+
+```typescript
+// ✅ Good: explicit select + leftJoin
+const rows = await this.db
+  .select({
+    runId: agentEvalRunTopics.runId,
+    score: agentEvalRunTopics.score,
+    testCase: agentEvalTestCases,
+    topic: topics,
+  })
+  .from(agentEvalRunTopics)
+  .leftJoin(agentEvalTestCases, eq(agentEvalRunTopics.testCaseId, agentEvalTestCases.id))
+  .leftJoin(topics, eq(agentEvalRunTopics.topicId, topics.id))
+  .where(eq(agentEvalRunTopics.runId, runId))
+  .orderBy(asc(agentEvalRunTopics.createdAt));
+
+// ❌ Bad: relational API with `with:`
+return this.db.query.agentEvalRunTopics.findMany({
+  where: eq(agentEvalRunTopics.runId, runId),
+  with: { testCase: true, topic: true },
+});
+```
+
+### Select with Aggregation
+
+```typescript
+// ✅ Good: select + leftJoin + groupBy
+const rows = await this.db
+  .select({
+    id: agentEvalDatasets.id,
+    name: agentEvalDatasets.name,
+    testCaseCount: count(agentEvalTestCases.id).as('testCaseCount'),
+  })
+  .from(agentEvalDatasets)
+  .leftJoin(agentEvalTestCases, eq(agentEvalDatasets.id, agentEvalTestCases.datasetId))
+  .groupBy(agentEvalDatasets.id);
+```
+
+### One-to-Many (Separate Queries)
+
+When you need a parent record with its children, use two queries instead of relational `with:`:
+
+```typescript
+// ✅ Good: two simple queries
+const [dataset] = await this.db
+  .select()
+  .from(agentEvalDatasets)
+  .where(eq(agentEvalDatasets.id, id))
+  .limit(1);
+
+if (!dataset) return undefined;
+
+const testCases = await this.db
+  .select()
+  .from(agentEvalTestCases)
+  .where(eq(agentEvalTestCases.datasetId, id))
+  .orderBy(asc(agentEvalTestCases.sortOrder));
+
+return { ...dataset, testCases };
+```
+
 ## Database Migrations
 
-See `references/db-migrations.md` for detailed migration guide.
-
-```bash
-# Generate migrations
-bun run db:generate
-
-# After modifying SQL (e.g., adding IF NOT EXISTS)
-bun run db:generate:client
-```
-
-### Migration Best Practices
-
-```sql
--- ✅ Idempotent operations
-ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "avatar" text;
-DROP TABLE IF EXISTS "old_table";
-CREATE INDEX IF NOT EXISTS "users_email_idx" ON "users" ("email");
-
--- ❌ Non-idempotent
-ALTER TABLE "users" ADD COLUMN "avatar" text;
-```
-
-Rename migration files meaningfully: `0046_meaningless.sql` → `0046_user_add_avatar.sql`
+See the `db-migrations` skill for the detailed migration guide.

.agents/skills/drizzle/references/db-migrations.md

@@ -1,50 +0,0 @@
-# Database Migrations Guide
-
-## Step 1: Generate Migrations
-
-```bash
-bun run db:generate
-```
-
-This generates:
-
-- `packages/database/migrations/0046_meaningless_file_name.sql`
-
-And updates:
-
-- `packages/database/migrations/meta/_journal.json`
-- `packages/database/src/core/migrations.json`
-- `docs/development/database-schema.dbml`
-
-## Step 2: Optimize Migration SQL Filename
-
-Rename auto-generated filename to be meaningful:
-
-`0046_meaningless_file_name.sql` → `0046_user_add_avatar_column.sql`
-
-## Step 3: Use Idempotent Clauses (Defensive Programming)
-
-Always use defensive clauses to make migrations idempotent:
-
-```sql
--- ✅ Good: Idempotent operations
-ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "avatar" text;
-DROP TABLE IF EXISTS "old_table";
-CREATE INDEX IF NOT EXISTS "users_email_idx" ON "users" ("email");
-ALTER TABLE "posts" DROP COLUMN IF EXISTS "deprecated_field";
-
--- ❌ Bad: Non-idempotent operations
-ALTER TABLE "users" ADD COLUMN "avatar" text;
-DROP TABLE "old_table";
-CREATE INDEX "users_email_idx" ON "users" ("email");
-```
-
-## Important
-
-After modifying migration SQL (e.g., adding `IF NOT EXISTS` clauses), run:
-
-```bash
-bun run db:generate:client
-```
-
-This updates the hash in `packages/database/src/core/migrations.json`.

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

@@ -0,0 +1,83 @@
+---
+name: heterogeneous-agent
+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
+
+Use this skill when the bug or feature lives in the external CLI agent pipeline, not the normal server-side agent runtime.
+
+## Use This Skill For
+
+- Adding or changing a driver under `apps/desktop/src/main/modules/heterogeneousAgent/drivers/`
+- Editing an adapter under `packages/heterogeneous-agents/src/adapters/`
+- Debugging `heteroAgentRawLine` transport, `window.__HETERO_AGENT_TRACE`, or `executeHeterogeneousAgent`
+- Fixing Claude Code stream-json bugs such as duplicate partial/full chunks, broken `message.id` boundaries, missing `tool_result`, TodoWrite state drift, or subagent thread routing
+- Fixing Codex JSONL bugs such as mixed multi-tool messages, broken turn boundaries, or missing tool-result mapping
+- Fixing step-boundary, tool persistence, subagent thread, or resume bugs in Claude Code / Codex flows
+- Reproducing multi-tool mixing, orphan tool messages, or stuck tool-result loading
+
+## Pipeline Map
+
+1. CLI raw stdout / JSONL
+2. Electron main spawns the CLI and broadcasts `heteroAgentRawLine`
+3. Adapter maps raw provider events into `HeterogeneousAgentEvent`
+4. `executeHeterogeneousAgent` persists assistant/tool messages and forwards stream events
+5. `createGatewayEventHandler` hydrates the UI
+6. Only after this path looks correct should you move on to `agent-tracing` or context-engine debugging
+
+## Read These Files First
+
+- `apps/desktop/src/main/controllers/HeterogeneousAgentCtr.ts`
+- `apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts`
+- `apps/desktop/src/main/modules/heterogeneousAgent/drivers/codex.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.ts`
+- `packages/heterogeneous-agents/src/adapters/codex.ts`
+- `src/store/chat/slices/aiChat/actions/heterogeneousAgentExecutor.ts`
+- `src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts`
+
+## Default Debug Order
+
+1. Prove whether the raw CLI output is correct before touching UI code.
+2. If raw output is correct, compare it with adapter output. In dev, `executeHeterogeneousAgent` exposes `window.__HETERO_AGENT_TRACE`.
+3. If adapted events look correct, inspect `persistToolBatch`, `persistToolResult`, step transitions, and subagent routing.
+4. Turn the repro into a focused test before fixing.
+5. Only after the transport/adapter/executor path looks sound should you debug later-stage message processing.
+
+## Critical Invariants
+
+- One raw tool item must map to one stable `ToolCallPayload.id`.
+- A new main-agent step must emit a boundary signal before events are forwarded to the new assistant.
+- In Claude Code, multiple assistant events with the same `message.id` are one turn, not multiple turns.
+- In Claude Code, `tool_result` lives in `type: 'user'` events, not assistant events.
+- In Claude Code partial mode, `message_delta.usage` is authoritative; do not trust echoed usage on every assistant block.
+- `persistToolBatch` must pre-register assistant `tools[]` before creating tool messages.
+- Every tool message must keep `parentId` equal to the owning assistant and `tool_call_id` equal to the tool id.
+- `tool_result` must resolve an existing `toolMsgIdByCallId`.
+- Subagent chunks must stay in thread scope and must not be forwarded into the main assistant stream.
+- Never clear the global `toolMsgIdByCallId` map at main step boundaries.
+
+## Common Bug Patterns
+
+- Claude Code duplicates text or thinking:
+  check whether partial deltas and the later full assistant block are both being emitted.
+- Claude Code opens too many assistant messages:
+  check whether the adapter is cutting steps on every assistant event instead of only on `message.id` changes.
+- Claude Code tool results never land:
+  check whether `type: 'user'` `tool_result` blocks are being ignored because the code only inspects assistant events.
+- Claude Code TodoWrite cards look stale:
+  check whether synthesized `pluginState.todos` is being attached at tool-result time.
+- Claude Code subagent transcript leaks into the main bubble:
+  check `parent_tool_use_id` handling and whether subagent chunks are being forwarded to the main gateway handler.
+- Multiple Codex tools collapse into one assistant message:
+  first check whether the adapter emits a usable step boundary such as `newStep` or an equivalent turn-change signal.
+- Orphan tool messages:
+  first check step-transition ordering and whether `persistToolBatch` Phase 1 ran before tool message creation.
+- Tool bubble stays loading:
+  look for `tool_result for unknown toolCallId` and missing `result_msg_id` backfill.
+- Subagent tools show up in the main bubble:
+  check for subagent chunks reaching the main gateway handler.
+
+## References
+
+- For commands, trace capture, invariants, and focused test commands, read [references/debug-workflow.md](./references/debug-workflow.md).

.agents/skills/heterogeneous-agent/references/debug-workflow.md

@@ -0,0 +1,246 @@
+# Heterogeneous Agent Debug Workflow
+
+## Contents
+
+1. Pipeline map
+2. Capture raw CLI traces first
+3. Compare raw and adapted events
+4. Check step boundaries before persistence
+5. Check tool persistence invariants
+6. Focused tests
+7. Repro-to-fix workflow
+
+## 1. Pipeline Map
+
+```
+CLI raw stdout
+  -> HeterogeneousAgentCtr (Electron main)
+  -> heteroAgentRawLine broadcast
+  -> createAdapter(...)
+  -> executeHeterogeneousAgent(...)
+  -> persistToolBatch / persistToolResult
+  -> createGatewayEventHandler(...)
+  -> UI hydration
+```
+
+Start at the leftmost broken layer. Do not jump straight to UI rendering unless raw and adapted events already look correct.
+
+## 2. Capture Raw CLI Traces First
+
+### Codex raw JSONL
+
+Use a read-only prompt and save traces under the repo-local scratch directory `.heerogeneous-tracing/`.
+
+```bash
+ts=$(date +%Y%m%d-%H%M%S)
+out=".heerogeneous-tracing/codex-${ts}.jsonl"
+last=".heerogeneous-tracing/codex-${ts}.last.txt"
+
+cat << 'EOF' | codex exec --json --skip-git-repo-check --sandbox read-only -C "$PWD" -o "$last" - > "$out"
+You are being run only to collect a raw Codex JSON event trace.
+Do not modify any files.
+Use at least 4 separate shell tool invocations, one invocation per command.
+Run a short sequence of read-only repo checks and then reply with a one-sentence summary.
+EOF
+```
+
+What to look for in the JSONL:
+
+- `thread.started`
+- `turn.started`
+- `item.started` / `item.completed`
+- `item.type === 'command_execution'`
+- `item.type === 'agent_message'`
+- `turn.completed`
+
+If raw Codex already merges tools into one item, the adapter is innocent. If raw Codex emits independent items but UI collapses them, the bug is downstream.
+
+If the repo already contains useful traces under `.heerogeneous-tracing/`, inspect them before reproducing.
+
+### Claude Code raw NDJSON
+
+Mirror the arguments from `apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts`.
+
+- `-p`
+- `--input-format stream-json`
+- `--output-format stream-json`
+- `--verbose`
+- `--include-partial-messages`
+- `--permission-mode bypassPermissions`
+
+You can capture a local raw trace like this:
+
+```bash
+ts=$(date +%Y%m%d-%H%M%S)
+out=".heerogeneous-tracing/claude-${ts}.ndjson"
+
+cat << 'EOF' | claude -p \
+  --input-format stream-json \
+  --output-format stream-json \
+  --verbose \
+  --include-partial-messages \
+  --permission-mode bypassPermissions \
+  > "$out"
+{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Do a few read-only repo checks, use several tool calls, and then summarize briefly."}]}}
+EOF
+```
+
+What to look for in Claude Code raw traces:
+
+- `type: 'system', subtype: 'init'`
+- `type: 'assistant'` blocks for `thinking`, `tool_use`, and `text`
+- `type: 'user'` blocks containing `tool_result`
+- `type: 'stream_event'` with `message_start`, `content_block_delta`, and `message_delta`
+- `type: 'result'`
+- `type: 'rate_limit_event'`
+
+Important Claude Code semantics:
+
+- Each content block often arrives as its own assistant event.
+- Multiple assistant events can share the same `message.id`; that is still one turn.
+- `message.id` change is the main-step boundary.
+- Partial deltas arrive before the later full assistant block.
+- `message_delta.usage` is the authoritative per-turn usage.
+- Subagent events are tagged with `parent_tool_use_id`.
+
+If the repo already contains useful references, inspect these first:
+
+- `.heerogeneous-tracing/cc-monitor-real-trace.jsonl`
+- `.heerogeneous-tracing/cc-stream-chain-reference.md`
+
+If you only need boundary semantics or tool persistence behavior, prefer existing adapter tests under:
+
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.e2e.test.ts`
+
+## 3. Compare Raw And Adapted Events
+
+In dev builds, `executeHeterogeneousAgent` stores raw lines plus adapted events on:
+
+- `window.__HETERO_AGENT_TRACE`
+
+Use that trace to compare:
+
+- raw `item.started` / `item.completed`
+- adapted `stream_chunk { chunkType: 'tools_calling' }`
+- adapted `tool_result`
+- adapted `tool_end`
+
+For Codex, the usual mapping is:
+
+- raw `item.started(command_execution)` -> `tools_calling` + `tool_start`
+- raw `item.completed(command_execution)` -> `tool_result` + `tool_end`
+- raw `item.completed(agent_message)` -> `stream_chunk(text)`
+
+If the raw trace is right but adapted events are wrong, fix the adapter before touching persistence.
+
+## 4. Check Step Boundaries Before Persistence
+
+This is the first thing to verify for "mixed tools in one assistant" bugs.
+
+### Claude Code
+
+Claude Code step boundaries are keyed off assistant `message.id` changes. The adapter should emit:
+
+- `stream_end`
+- `stream_start { newStep: true }`
+
+Also verify these Claude-specific invariants:
+
+- the first assistant after init does not open a new step
+- repeated assistant events with the same `message.id` do not open a new step
+- partial `content_block_delta` text/thinking does not get duplicated by the later full assistant event
+- `tool_result` from `type: 'user'` updates the matching tool row
+- `parent_tool_use_id` creates thread-scoped subagent chunks instead of main-stream chunks
+- TodoWrite `tool_use.input` is converted into synthesized `pluginState.todos` on `tool_result`
+
+Good references:
+
+- `packages/heterogeneous-agents/src/adapters/claudeCode.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+
+### Codex
+
+Codex raw traces usually provide turn-level boundaries through:
+
+- `turn.started`
+- `turn.completed`
+
+The executor only cuts a new assistant message when it receives a step-boundary signal it understands. If the adapter emits `stream_start` without `newStep`, multiple Codex tools and text chunks can accumulate under the same assistant longer than intended.
+
+Relevant files:
+
+- `packages/heterogeneous-agents/src/adapters/codex.ts`
+- `src/store/chat/slices/aiChat/actions/heterogeneousAgentExecutor.ts`
+
+## 5. Check Tool Persistence Invariants
+
+Read `persistToolBatch` and `persistToolResult` before changing UI code.
+
+### `persistToolBatch`
+
+The expected order is:
+
+1. Pre-register assistant `tools[]`
+2. Create `role: 'tool'` messages
+3. Backfill `result_msg_id` onto assistant `tools[]`
+
+If tool rows are created before assistant `tools[]` are registered, orphan tool messages are likely.
+
+### `persistToolResult`
+
+`tool_result` must resolve the tool row through `toolMsgIdByCallId`.
+
+Warning signs:
+
+- `tool_result for unknown toolCallId`
+- tool rows with empty content forever
+- missing `result_msg_id`
+
+For Claude Code, remember that tool results originate from raw `type: 'user'` events.
+
+### Main vs subagent scope
+
+- Main-agent tool state is per-step.
+- `toolMsgIdByCallId` is global across main and subagent scopes.
+- Subagent chunks must not be forwarded into the main gateway handler.
+
+If subagent events leak to the main handler, the main bubble can inherit the wrong `tools[]` and content.
+
+## 6. Focused Tests
+
+Run the smallest useful test set first.
+
+```bash
+bunx vitest run --silent='passed-only' 'packages/heterogeneous-agents/src/adapters/codex.test.ts'
+bunx vitest run --silent='passed-only' 'packages/heterogeneous-agents/src/adapters/claudeCode.test.ts'
+bunx vitest run --silent='passed-only' 'src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts'
+```
+
+Especially useful places:
+
+- `packages/heterogeneous-agents/src/adapters/codex.test.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+- `src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts`
+
+Claude Code-specific assertions worth adding when fixing bugs:
+
+- same `message.id` does not emit `newStep`
+- changed `message.id` does emit `stream_end` plus `stream_start { newStep: true }`
+- partial text/thinking is emitted once
+- `tool_result` from `user` events reaches the right tool row
+- subagent chunks carry `subagent.parentToolCallId`
+- TodoWrite result synthesizes `pluginState.todos`
+
+When the bug comes from a real trace, distill it into the closest existing test file instead of relying on manual UI-only repros.
+
+## 7. Repro-To-Fix Workflow
+
+1. Capture a raw trace and save it under `.heerogeneous-tracing/`.
+2. Confirm whether the bug appears in raw events, adapted events, or persistence.
+3. Add or update the narrowest failing test near the broken layer.
+4. Fix the smallest layer that can explain the symptom.
+5. Re-run focused tests.
+6. Only then do an Electron smoke test with the `local-testing` skill if UI confirmation is still needed.
+
+Do not start with a broad Electron repro if a raw trace or adapter test can prove the fault zone faster.

.agents/skills/hotkey/SKILL.md

@@ -71,7 +71,7 @@ const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.
 
 <Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
   <Button icon={<DeleteOutlined />} onClick={clearMessages} />
-</Tooltip>
+</Tooltip>;
 ```
 
 ## Best Practices

.agents/skills/i18n/SKILL.md

@@ -3,9 +3,9 @@ name: i18n
 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.
 ---
 
-# LobeChat Internationalization Guide
+# LobeHub Internationalization Guide
 
-- Default language: Chinese (zh-CN)
+- Default language: English (en-US)
 - Framework: react-i18next
 - **Only edit files in `src/locales/default/`** - Never edit JSON files in `locales/`
 - Run `pnpm i18n` to generate translations (or manually translate zh-CN/en-US for dev preview)
@@ -31,11 +31,13 @@ export default {
 **Patterns:** `{feature}.{context}.{action|status}`
 
 **Parameters:** Use `{{variableName}}` syntax
+
 ```typescript
 'alert.cloud.desc': '我们提供 {{credit}} 额度积分',
 ```
 
 **Avoid key conflicts:**
+
 ```typescript
 // ❌ Conflict
 'clientDB.solve': '自助解决',
@@ -51,7 +53,7 @@ export default {
 1. Add keys to `src/locales/default/{namespace}.ts`
 2. Export new namespace in `src/locales/default/index.ts`
 3. For dev preview: manually translate `locales/zh-CN/{namespace}.json` and `locales/en-US/{namespace}.json`
-4. Run `pnpm i18n` to generate all languages (CI handles this automatically)
+4. Remind the user to run `pnpm i18n` before creating PR — do NOT run it yourself (very slow)
 
 ## Usage
 
@@ -60,12 +62,12 @@ import { useTranslation } from 'react-i18next';
 
 const { t } = useTranslation('common');
 
-t('newFeature.title')
-t('alert.cloud.desc', { credit: '1000' })
+t('newFeature.title');
+t('alert.cloud.desc', { credit: '1000' });
 
 // Multiple namespaces
 const { t } = useTranslation(['common', 'chat']);
-t('common:save')
+t('common:save');
 ```
 
 ## Common Namespaces

.agents/skills/linear/SKILL.md

@@ -1,26 +1,112 @@
 ---
 name: linear
-description: Linear issue management guide. Use when working with Linear issues, creating issues, updating status, or adding comments. Triggers on Linear issue references (LOBE-xxx), issue tracking, or project management tasks. Requires Linear MCP tools to be available.
+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.
 
+## ⚠️ CRITICAL: PR Creation with Linear Issues
+
+**When creating a PR that references Linear issues (LOBE-xxx), you MUST:**
+
+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
+
+This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
+
 ## Workflow
 
 1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
-2. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
-3. **Update issue status** when completing: `mcp__linear-server__update_issue`
-4. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
+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** (REQUIRED): `mcp__linear-server__create_comment`
 
 ## Creating Issues
 
 When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.
 
-## Completion Comment (REQUIRED)
+## 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. ALWAYS prefix titles with an ordering index
+
+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:
+
+```plaintext
+[1]     [db]       add schema fields
+[2]     [db]       new table + repository
+[3]     [service]  business logic layer
+[4]     [api]      REST endpoints
+[4.1]   [sdk]      client SDK wrapper
+[4.1.1] [app]      consumer integration
+[4.1.2] [app]      UI surface
+[4.2]   [ui]       dashboard page
+```
+
+Even when the panel shuffles, the reader can mentally reconstruct the dependency graph at a glance. Dotted numbering `[n.m.k]` should mirror the parent-child nesting so the index and the tree agree.
+
+### 2. Nest sub-issues by logical parent-child, not flat under the root
+
+Linear supports **unlimited sub-issue depth**. A flat list of 8+ siblings under one root is hard to scan. Group by main-subordinate logic:
+
+- Core service → its SDK → SDK consumers
+- Don't create a sibling when a child is more accurate
+
+Use `parentId: "LOBE-xxxx"` at creation (or `save_issue` to move). Moving an issue's parent does not disturb its `blockedBy` relations.
+
+### 3. Sub-issue creation order is dictated by `blockedBy`
+
+`blockedBy` requires the blocker to exist first (you need its LOBE-id). So:
+
+1. **Topologically sort** the DAG — leaves (no deps) first, roots last
+2. Create issues with zero deps in the first wave
+3. Create dependent issues only after collecting the blocker IDs from prior responses
+4. `blockedBy` is **append-only**; passing it again does not overwrite — safe to re-run
+
+### 4. Don't waste rounds trying to parallelize
+
+MCP tool calls in a single message look parallel but execute sequentially on the server, and you still need blocker IDs from earlier responses. Just issue calls in dependency order; optimizing for parallelism gains nothing here.
+
+### 5. Keep each sub-issue description self-contained
+
+Each sub-issue should state:
+
+- Goal (1–2 lines)
+- Key files to touch
+- Concrete changes / acceptance criteria
+- Dependencies (link to blocker issues by `LOBE-xxxx`)
+- Validation steps
+
+The implementer may open only the sub-issue, not the parent — don't rely on context that lives only in the parent description.
+
+## Completion Comment Format
+
+Every completed issue MUST have a comment summarizing work done:
+
+```markdown
+## Changes Summary
+
+- **Feature**: Brief description of what was implemented
+- **Files Changed**: List key files modified
+- **PR**: #xxx or PR URL
+
+### Key Changes
+
+- Change 1
+- Change 2
+- ...
+```
+
+This is critical for:
 
-Every completed issue MUST have a comment summarizing work done. This is critical for:
 - Team visibility
 - Code review context
 - Future reference
@@ -28,6 +114,7 @@ Every completed issue MUST have a comment summarizing work done. This is critica
 ## PR Association (REQUIRED)
 
 When creating PRs for Linear issues, include magic keywords in PR body:
+
 - `Fixes LOBE-123`
 - `Closes LOBE-123`
 - `Resolves LOBE-123`
@@ -41,11 +128,11 @@ When working on multiple issues, update EACH issue IMMEDIATELY after completing
 3. Run related tests
 4. Create PR if needed
 5. Update status to **"In Review"** (NOT "Done")
-6. Add completion comment
+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 → Update all statuses → Add all comments
+**❌ Wrong:** Complete all → Create PR → Forget Linear comments
 
-**✅ Correct:** Complete A → Update A → Comment A → Complete B → ...
+**✅ Correct:** Complete → Create PR → Add Linear comments → Task done

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

@@ -0,0 +1,520 @@
+---
+name: local-testing
+description: >
+  Local app and bot testing. Uses agent-browser CLI for Electron/web app UI testing,
+  and osascript (AppleScript) for controlling native macOS apps (WeChat, Discord, Telegram, Slack, Lark/飞书, QQ)
+  to test bots. Triggers on 'local test', 'test in electron', 'test desktop', 'test bot',
+  'bot test', 'test in discord', 'test in telegram', 'test in slack', 'test in weixin',
+  'test in wechat', 'test in lark', 'test in feishu', 'test in qq',
+  'manual test', 'osascript', or UI/bot verification tasks.
+---
+
+# Local App & Bot Testing
+
+Two approaches for local testing on macOS:
+
+| Approach                    | Tool                | Best For                                             |
+| --------------------------- | ------------------- | ---------------------------------------------------- |
+| **agent-browser + CDP**     | `agent-browser` CLI | Electron apps, web apps (DOM access, JS eval)        |
+| **osascript (AppleScript)** | `osascript -e`      | Native macOS apps (WeChat, Discord, Telegram, Slack) |
+
+---
+
+# Part 1: agent-browser (Electron / Web Apps)
+
+Use `agent-browser` to automate Chromium-based apps via Chrome DevTools Protocol.
+
+Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome. Run `agent-browser upgrade` to update.
+
+## Core Workflow
+
+Every browser automation follows this pattern:
+
+1. **Navigate**: `agent-browser open <url>`
+2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
+3. **Interact**: Use refs to click, fill, select
+4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i # Check result
+```
+
+## Command Chaining
+
+```bash
+# Chain open + wait + snapshot in one call
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+```
+
+Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact).
+
+## Essential Commands
+
+```bash
+# Navigation
+agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser close                   # Close browser
+agent-browser close --all             # Close all active sessions
+
+# Snapshot
+agent-browser snapshot -i             # Interactive elements with refs (recommended)
+agent-browser snapshot -s "#selector" # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1               # Click element
+agent-browser click @e1 --new-tab     # Click and open in new tab
+agent-browser fill @e2 "text"         # Clear and type text
+agent-browser type @e2 "text"         # Type without clearing
+agent-browser select @e1 "option"     # Select dropdown option
+agent-browser check @e1               # Check checkbox
+agent-browser press Enter             # Press key
+agent-browser keyboard type "text"    # Type at current focus (no selector)
+agent-browser keyboard inserttext "text"  # Insert without key events
+agent-browser scroll down 500         # Scroll page
+agent-browser scroll down 500 --selector "div.content"  # Scroll within container
+
+# Get information
+agent-browser get text @e1            # Get element text
+agent-browser get url                 # Get current URL
+agent-browser get title               # Get page title
+agent-browser get cdp-url             # Get CDP WebSocket URL
+
+# Wait
+agent-browser wait @e1                # Wait for element
+agent-browser wait --load networkidle # Wait for network idle
+agent-browser wait --url "**/page"    # Wait for URL pattern
+agent-browser wait 2000               # Wait milliseconds
+agent-browser wait --text "Welcome"   # Wait for text to appear
+agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
+agent-browser wait "#spinner" --state hidden  # Wait for element to disappear
+
+# Downloads
+agent-browser download @e1 ./file.pdf          # Click element to trigger download
+agent-browser wait --download ./output.zip     # Wait for any download to complete
+
+# Network
+agent-browser network requests                 # Inspect tracked requests
+agent-browser network requests --type xhr,fetch  # Filter by resource type
+agent-browser network requests --method POST   # Filter by HTTP method
+agent-browser network route "**/api/*" --abort # Block matching requests
+agent-browser network har start                # Start HAR recording
+agent-browser network har stop ./capture.har   # Stop and save HAR file
+
+# Viewport & Device Emulation
+agent-browser set viewport 1920 1080          # Set viewport size (default: 1280x720)
+agent-browser set viewport 1920 1080 2        # 2x retina
+agent-browser set device "iPhone 14"          # Emulate device (viewport + user agent)
+
+# Capture
+agent-browser screenshot              # Screenshot to temp dir
+agent-browser screenshot --full       # Full page screenshot
+agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
+agent-browser pdf output.pdf          # Save as PDF
+
+# Clipboard
+agent-browser clipboard read          # Read text from clipboard
+agent-browser clipboard write "text"  # Write text to clipboard
+agent-browser clipboard copy          # Copy current selection
+agent-browser clipboard paste         # Paste from clipboard
+
+# Dialogs (alert, confirm, prompt, beforeunload)
+agent-browser dialog accept           # Accept dialog
+agent-browser dialog accept "input"   # Accept prompt dialog with text
+agent-browser dialog dismiss          # Dismiss/cancel dialog
+agent-browser dialog status           # Check if dialog is open
+
+# Diff (compare page states)
+agent-browser diff snapshot                        # Compare current vs last snapshot
+agent-browser diff screenshot --baseline before.png  # Visual pixel diff
+agent-browser diff url <url1> <url2>               # Compare two pages
+
+# Streaming
+agent-browser stream enable           # Start WebSocket streaming
+agent-browser stream status           # Inspect streaming state
+agent-browser stream disable          # Stop streaming
+```
+
+## Batch Execution
+
+```bash
+echo '[
+  ["open", "https://example.com"],
+  ["snapshot", "-i"],
+  ["click", "@e1"],
+  ["screenshot", "result.png"]
+]' | agent-browser batch --json
+```
+
+## Authentication
+
+```bash
+# Option 1: Auth vault (credentials stored encrypted)
+echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
+agent-browser auth login myapp
+
+# Option 2: Session name (auto-save/restore cookies + localStorage)
+agent-browser --session-name myapp open https://app.example.com/login
+agent-browser close                                                       # State auto-saved
+agent-browser --session-name myapp open https://app.example.com/dashboard # Auto-restored
+
+# Option 3: Persistent profile
+agent-browser --profile ~/.myapp open https://app.example.com/login
+
+# Option 4: State file
+agent-browser state save auth.json
+agent-browser state load auth.json
+```
+
+### LobeHub dev server — inject better-auth cookie
+
+`agent-browser --headed` on macOS can create an off-screen Chromium window, blocking manual login. For a local LobeHub dev server (e.g. `localhost:3011`), copy the `better-auth.session_token` cookie out of a **Network request** in the user's own Chrome DevTools and load it via `state load`. See [references/agent-browser-login.md](./references/agent-browser-login.md) for the full recipe.
+
+## Semantic Locators (Alternative to Refs)
+
+```bash
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```
+
+## JavaScript Evaluation (eval)
+
+```bash
+# Simple expressions
+agent-browser eval 'document.title'
+
+# Complex JS: use --stdin with heredoc (RECOMMENDED)
+agent-browser eval --stdin << 'EVALEOF'
+JSON.stringify(
+  Array.from(document.querySelectorAll("img"))
+    .filter(i => !i.alt)
+    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
+)
+EVALEOF
+
+# Base64 encoding (avoids all shell escaping issues)
+agent-browser eval -b "$(echo -n 'document.title' | base64)"
+```
+
+## Ref Lifecycle
+
+Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after clicking links/buttons that navigate, form submissions, or dynamic content loading.
+
+## Annotated Screenshots (Vision Mode)
+
+```bash
+agent-browser screenshot --annotate
+# Output includes the image path and a legend:
+#   [1] @e1 button "Submit"
+#   [2] @e2 link "Home"
+agent-browser click @e2 # Click using ref from annotated screenshot
+```
+
+## Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+agent-browser session list
+```
+
+## Connect to Existing Chrome
+
+```bash
+agent-browser --auto-connect snapshot # Auto-discover running Chrome
+agent-browser --cdp 9222 snapshot     # Explicit CDP port
+```
+
+## iOS Simulator (Mobile Safari)
+
+```bash
+agent-browser device list
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1
+agent-browser -p ios swipe up
+agent-browser -p ios screenshot mobile.png
+agent-browser -p ios close
+```
+
+## Observability Dashboard
+
+```bash
+agent-browser dashboard install
+agent-browser dashboard start # Background server on port 4848
+agent-browser dashboard stop
+```
+
+## Cloud Providers
+
+Use `-p <provider>` to run against cloud browsers: `agentcore`, `browserbase`, `browserless`, `browseruse`, `kernel`.
+
+## Browser Engine Selection
+
+```bash
+agent-browser --engine lightpanda open example.com # 10x faster, 10x less memory
+```
+
+## Electron (LobeHub Desktop)
+
+### Setup / Teardown
+
+Use the `electron-dev.sh` script to manage the Electron dev environment. It handles process lifecycle, waits for SPA readiness, and reliably kills all child processes (main + helpers + vite).
+
+```bash
+SCRIPT=".agents/skills/local-testing/scripts/electron-dev.sh"
+
+# Start Electron dev with CDP (idempotent — skips if already running)
+$SCRIPT start
+
+# Check if Electron is running and CDP is reachable
+$SCRIPT status
+
+# Kill all Electron-related processes (main + helper + vite)
+$SCRIPT stop
+
+# Force fresh restart
+$SCRIPT restart
+```
+
+After `start` succeeds, connect with: `agent-browser --cdp 9222 snapshot -i`
+
+**Always run `$SCRIPT stop` when done testing** — `pkill -f "Electron"` alone won't catch all helper processes.
+
+#### Environment Variables
+
+| Variable          | Default                 | Description                              |
+| ----------------- | ----------------------- | ---------------------------------------- |
+| `CDP_PORT`        | `9222`                  | Chrome DevTools Protocol port            |
+| `ELECTRON_LOG`    | `/tmp/electron-dev.log` | Electron process log                     |
+| `ELECTRON_WAIT_S` | `60`                    | Max seconds to wait for Electron process |
+| `RENDERER_WAIT_S` | `60`                    | Max seconds to wait for SPA to load      |
+
+### LobeHub-Specific Patterns
+
+#### Access Zustand Store State
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var ops = Object.values(chat.operations);
+  return JSON.stringify({
+    ops: ops.map(function(o) { return { type: o.type, status: o.status }; }),
+    activeAgent: chat.activeAgentId,
+    activeTopic: chat.activeTopicId,
+  });
+})()
+EVALEOF
+```
+
+#### Find and Use the Chat Input
+
+```bash
+# The chat input is contenteditable — must use -C flag
+agent-browser --cdp 9222 snapshot -i -C 2>&1 | grep "editable"
+
+agent-browser --cdp 9222 click @e48
+agent-browser --cdp 9222 type @e48 "Hello world"
+agent-browser --cdp 9222 press Enter
+```
+
+#### Wait for Agent to Complete
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var ops = Object.values(chat.operations);
+  var running = ops.filter(function(o) { return o.status === 'running'; });
+  return running.length === 0 ? 'done' : 'running: ' + running.length;
+})()
+EVALEOF
+```
+
+#### Install Error Interceptor
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  window.__CAPTURED_ERRORS = [];
+  var orig = console.error;
+  console.error = function() {
+    var msg = Array.from(arguments).map(function(a) {
+      if (a instanceof Error) return a.message;
+      return typeof a === 'object' ? JSON.stringify(a) : String(a);
+    }).join(' ');
+    window.__CAPTURED_ERRORS.push(msg);
+    orig.apply(console, arguments);
+  };
+  return 'installed';
+})()
+EVALEOF
+
+# Later, check captured errors:
+agent-browser --cdp 9222 eval "JSON.stringify(window.__CAPTURED_ERRORS)"
+```
+
+## Chrome / Web Apps
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-test-profile \
+  "<URL>" &
+sleep 5
+agent-browser --cdp 9222 snapshot -i
+
+# Or auto-discover running Chrome with remote debugging
+agent-browser --auto-connect snapshot -i
+```
+
+---
+
+# Part 2: osascript (Native macOS App Bot Testing)
+
+Use AppleScript via `osascript` to control native macOS desktop apps for bot testing. Works with any app that supports macOS Accessibility, no CDP or Chromium needed.
+
+The pattern is the same for every platform:
+
+1. **Activate** the app (`tell application "X" to activate`)
+2. **Navigate** to a channel/chat (Quick Switcher `Cmd+K` or Search `Cmd+F`)
+3. **Send** a message (clipboard paste `Cmd+V` + Enter)
+4. **Wait** for the bot response
+5. **Screenshot** for verification (`screencapture` + `Read` tool)
+
+## Per-Platform References
+
+Pick the file for your target platform — each contains activation, navigation, send-message, and verification snippets specific to that app:
+
+| 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`        |
+
+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
+
+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) |
+| `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
+
+`capture-app-window.sh` captures a screenshot of a specific app window using `screencapture -l <windowID>`. It uses Swift + CGWindowList to find the window by process name, so screenshots work correctly even when the window is on an external monitor or behind other windows.
+
+```bash
+# Standalone usage
+./.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.
+
+### Bot Test Scripts
+
+All bot test scripts share the same interface:
+
+```bash
+./scripts/test-<platform>-bot.sh <channel_or_contact> <message> [wait_seconds] [screenshot_path]
+```
+
+Examples:
+
+```bash
+# Discord — test a bot in #bot-testing channel
+./.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/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/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/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/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/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.
+
+---
+
+# Screen Recording
+
+Record automated demos using `record-app-screen.sh` (start/stop lifecycle, CDP screenshots + ffmpeg assembly). See [references/record-app-screen.md](references/record-app-screen.md) for full documentation.
+
+```bash
+./.agents/skills/local-testing/scripts/electron-dev.sh start
+./.agents/skills/local-testing/scripts/record-app-screen.sh start my-demo
+# ... run automation ...
+./.agents/skills/local-testing/scripts/record-app-screen.sh stop
+```
+
+Outputs to `.records/` directory (gitignored): `<name>.mp4` (video) + `<name>/` (screenshots every 3s).
+
+---
+
+# Gotchas
+
+### agent-browser
+
+- **Daemon can get stuck** — if commands hang, `agent-browser close --all` or `pkill -f agent-browser` to reset
+- **HMR invalidates everything** — after code changes, refs break. Re-snapshot or restart
+- **`snapshot -i` doesn't find contenteditable** — use `snapshot -i -C` for rich text editors
+- **`fill` doesn't work on contenteditable** — use `type` for chat inputs
+- **Screenshots go to `~/.agent-browser/tmp/screenshots/`** — read them with the `Read` tool
+- **Dialogs block all commands** — if commands time out, check `agent-browser dialog status`
+- **Default timeout is 25s** — override with `AGENT_BROWSER_DEFAULT_TIMEOUT` (ms) or use explicit waits
+- **Shell quoting corrupts eval** — use `eval --stdin <<'EVALEOF'` for complex JS
+
+### Electron-specific
+
+- **Always use `electron-dev.sh stop` to clean up** — `pkill -f "Electron"` only kills the main process; helper processes (GPU, renderer, network) survive. The script finds and kills all of them via PID matching against the project's electron binary path.
+- **`npx electron-vite dev` must run from `apps/desktop/`** — running from project root fails silently. The `electron-dev.sh` script handles this automatically.
+- **Don't resize the Electron window after load** — resizing triggers full SPA reload
+- **Store is at `window.__LOBE_STORES`** not `window.__ZUSTAND_STORES__`
+
+### osascript
+
+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/references/agent-browser-login.md

@@ -0,0 +1,110 @@
+# Log `agent-browser` into a local LobeHub dev server
+
+`agent-browser --headed` on macOS often creates the Chromium window off-screen — the user can't see or interact with it, so manual login inside the agent-browser session fails. Instead of sharing the user's real Chrome profile, copy the **better-auth session cookie** out of a request in DevTools and inject it into the agent-browser session as a Playwright-style state file.
+
+## When to use
+
+- You need `agent-browser` to reach an authenticated page on `http://localhost:<port>` (e.g. `localhost:3011`).
+- The user already has a logged-in tab of the same dev server in their own Chrome.
+- Spawning a headed Chromium to let the user log in manually is unreliable (window off-screen, no interaction).
+
+Do **not** use this on production URLs — only local dev. Treat the cookie as a secret: don't paste it into shared logs, PRs, or commit it anywhere.
+
+## Step 1 — Ask the user to copy the cookie from a Network request, NOT `document.cookie`
+
+`document.cookie` will not return HttpOnly cookies, which is exactly where better-auth puts its session. Instruct the user:
+
+1. Open the logged-in tab (`http://localhost:<port>/…`) in their own Chrome.
+2. `Cmd+Option+I` → **Network** tab.
+3. Refresh, click any same-origin request (e.g. the top-level document request).
+4. In the right pane under **Request Headers**, right-click the `Cookie:` line → **Copy value** (or copy the entire header).
+5. Paste the string into chat.
+
+You only need the better-auth pieces. Everything else (Clerk, `LOBE_LOCALE`, HMR hash, theme vars) is noise and can stay. The minimum viable set is:
+
+```
+better-auth.session_token=<value>; better-auth.state=<value>
+```
+
+## Step 2 — Build a Playwright-style state file
+
+`agent-browser state load` expects Playwright's `storageState` format: a JSON with a `cookies` array and an `origins` array.
+
+```bash
+cat > /tmp/mkstate.py << 'PY'
+import json, sys, time
+
+# Read the Cookie header from stdin (allows optional "Cookie: " prefix).
+raw = sys.stdin.read().strip()
+if raw.lower().startswith("cookie:"):
+    raw = raw.split(":", 1)[1].strip()
+
+# Keep only better-auth cookies. Extend this set if the app genuinely needs more.
+WANTED = {"better-auth.session_token", "better-auth.state"}
+
+cookies = []
+exp = int(time.time()) + 30 * 24 * 3600  # 30 days
+for pair in raw.split("; "):
+    if "=" not in pair:
+        continue
+    name, _, value = pair.partition("=")
+    if name not in WANTED:
+        continue
+    cookies.append({
+        "name": name,
+        "value": value,
+        "domain": "localhost",
+        "path": "/",
+        "expires": exp,
+        "httpOnly": False,
+        "secure": False,
+        "sameSite": "Lax",
+    })
+
+if not cookies:
+    sys.stderr.write("no better-auth cookies found in input\n")
+    sys.exit(1)
+
+print(json.dumps({"cookies": cookies, "origins": []}, indent=2))
+PY
+
+# Feed the copied Cookie header in via env var or heredoc.
+printf '%s' "$COOKIE_HEADER" | python3 /tmp/mkstate.py > /tmp/state.json
+```
+
+**Note on `httpOnly`**: the real cookie in the user's browser is HttpOnly, but `storageState` doesn't enforce the flag on load — it just attaches the value. Storing with `httpOnly: false` is fine for local dev and sidesteps a CDP-context quirk where HttpOnly cookies sometimes fail to attach.
+
+## Step 3 — Load state and navigate
+
+```bash
+SESSION="my-test" # any stable session name
+
+agent-browser --session "$SESSION" state load /tmp/state.json
+agent-browser --session "$SESSION" open "http://localhost:3011/"
+agent-browser --session "$SESSION" get url
+# Expect NOT /signin?callbackUrl=… — if you still see signin, cookie didn't apply.
+```
+
+## Step 4 — Verify
+
+```bash
+agent-browser --session "$SESSION" snapshot -i | head -20
+# Look for the user's avatar/name in the sidebar, or absence of the signin form.
+```
+
+## Common failure modes
+
+| Symptom                                         | Cause                                                                   | Fix                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
+| Still redirects to `/signin` after `state load` | User pasted from `document.cookie` → missed HttpOnly session            | Re-pull from Network request Headers, not console    |
+| `state load` reports 0 cookies                  | Separator wrong, or user pasted URL-decoded value                       | Keep the raw `Cookie:` header as-is; split on `"; "` |
+| Login works briefly then expires                | `better-auth.session_token` rotated (user logged out / signed in again) | Re-copy and re-load                                  |
+| Domain mismatch                                 | Use `domain: "localhost"` literally, no leading dot for local dev       | —                                                    |
+
+## Scope
+
+Only covers authenticating an **agent-browser** session into a **local** LobeHub dev server. It does not:
+
+- Work for production — production cookies are `Secure; HttpOnly; Domain=.lobehub.com` and must be delivered over HTTPS.
+- Replace real OAuth flows — tests that must exercise the login UI need a real Chromium with `--remote-debugging-port` or a bot account.
+- Flow cookies back to the user's Chrome — injection is one-way (into agent-browser only).

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

@@ -0,0 +1,97 @@
+# Discord Bot Testing
+
+**App name:** `Discord` | **Process name:** `Discord`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Discord
+osascript -e 'tell application "Discord" to activate'
+sleep 1
+
+# Open Quick Switcher (Cmd+K) to navigate to a channel
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e 'tell application "System Events" to keystroke "bot-testing"'
+sleep 1
+osascript -e 'tell application "System Events" to key code 36' # Enter
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# The message input is focused after navigating to a channel
+# Type a message
+osascript -e 'tell application "System Events" to keystroke "/hello"'
+sleep 0.5
+osascript -e 'tell application "System Events" to key code 36' # Enter
+```
+
+## Send Long Message (via clipboard)
+
+```bash
+osascript -e '
+tell application "Discord" to activate
+delay 0.5
+set the clipboard to "Write a 3000 word essay about space exploration"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Bot Response
+
+```bash
+# Wait for bot to respond, then screenshot
+sleep 10
+screencapture /tmp/discord-bot-response.png
+# Read with the Read tool for visual verification
+```
+
+## Full Bot Test Example
+
+```bash
+#!/usr/bin/env bash
+# test-discord-bot.sh — Send message and verify bot response
+
+# 1. Activate Discord and navigate to channel
+osascript -e '
+tell application "Discord" to activate
+delay 1
+-- Quick Switcher
+tell application "System Events" to keystroke "k" using command down
+delay 0.5
+tell application "System Events" to keystroke "bot-testing"
+delay 1
+tell application "System Events" to key code 36
+delay 2
+'
+
+# 2. Send test message
+osascript -e '
+set the clipboard to "!ping"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+
+# 3. Wait for response and capture
+sleep 5
+screencapture /tmp/discord-test-result.png
+echo "Screenshot saved to /tmp/discord-test-result.png"
+```
+
+## Script
+
+```bash
+./.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

@@ -0,0 +1,61 @@
+# Lark / 飞书 Bot Testing
+
+**App name:** `Lark` or `飞书` | **Process name:** `Lark` or `飞书`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Lark (auto-detects Lark or 飞书)
+osascript -e 'tell application "Lark" to activate' 2> /dev/null \
+  || osascript -e 'tell application "飞书" to activate'
+sleep 1
+
+# Quick Switcher / Search (Cmd+K)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e '
+set the clipboard to "bot-testing"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+osascript -e '
+set the clipboard to "@MyBot help me with this task"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/lark-bot-response.png
+```
+
+## Lark-Specific Notes
+
+- App name varies: `Lark` (international) vs `飞书` (China mainland) — the script auto-detects
+- Uses `Cmd+K` for quick search (same as Discord/Slack)
+- Enter sends message by default
+- Always use clipboard paste for CJK characters
+
+## Script
+
+```bash
+./.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/osascript-common.md

@@ -0,0 +1,217 @@
+# osascript Common Patterns
+
+Shared AppleScript / `osascript` patterns used by all platform bot tests. Read this first, then refer to the per-platform file for app-specific quirks.
+
+## Core Patterns
+
+### Activate an App
+
+```bash
+osascript -e 'tell application "Discord" to activate'
+```
+
+### Type Text
+
+```bash
+# Type character by character (reliable, but slow for long text)
+osascript -e 'tell application "System Events" to keystroke "Hello world"'
+
+# Press Enter
+osascript -e 'tell application "System Events" to key code 36'
+
+# Press Tab
+osascript -e 'tell application "System Events" to key code 48'
+
+# Press Escape
+osascript -e 'tell application "System Events" to key code 53'
+```
+
+### Paste from Clipboard (fast, for long text)
+
+```bash
+# Set clipboard and paste — much faster than keystroke for long messages
+osascript -e 'set the clipboard to "Your long message here"'
+osascript -e 'tell application "System Events" to keystroke "v" using command down'
+```
+
+Or in one shot:
+
+```bash
+osascript -e '
+set the clipboard to "Your long message here"
+tell application "System Events" to keystroke "v" using command down
+'
+```
+
+### Keyboard Shortcuts
+
+```bash
+# Cmd+K (quick switcher in Discord/Slack)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+
+# Cmd+F (search)
+osascript -e 'tell application "System Events" to keystroke "f" using command down'
+
+# Cmd+N (new message/chat)
+osascript -e 'tell application "System Events" to keystroke "n" using command down'
+
+# Cmd+Shift+K (example: multi-modifier)
+osascript -e 'tell application "System Events" to keystroke "k" using {command down, shift down}'
+```
+
+### Click at Position
+
+```bash
+# Click at absolute screen coordinates
+osascript -e '
+tell application "System Events"
+    click at {500, 300}
+end tell
+'
+```
+
+### Get Window Info
+
+```bash
+# Get window position and size
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get {position, size} of window 1
+    end tell
+end tell
+'
+```
+
+### Screenshot
+
+```bash
+# Full screen
+screencapture /tmp/screenshot.png
+
+# Interactive region select
+screencapture -i /tmp/screenshot.png
+
+# Specific window (by window ID from CGWindowList)
+screencapture -l < WINDOW_ID > /tmp/screenshot.png
+```
+
+To get window ID for a specific app:
+
+```bash
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get id of window 1
+    end tell
+end tell
+'
+```
+
+### Read Accessibility Elements
+
+```bash
+# Get all UI elements of the frontmost window (can be slow/large)
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        entire contents of window 1
+    end tell
+end tell
+'
+
+# Get a specific element's value
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get value of text field 1 of window 1
+    end tell
+end tell
+'
+```
+
+> **Warning:** `entire contents` can be extremely slow on complex UIs. Prefer screenshots + `Read` tool for visual verification.
+
+### Read Screen Text via Clipboard
+
+For reading the latest message or response from an app:
+
+```bash
+# Select all text in the focused area and copy
+osascript -e '
+tell application "System Events"
+    keystroke "a" using command down
+    keystroke "c" using command down
+end tell
+'
+sleep 0.5
+# Read clipboard
+pbpaste
+```
+
+---
+
+## Common Bot Testing Workflow
+
+Regardless of platform, the pattern is:
+
+```bash
+APP_NAME="Discord" # or "Slack", "Telegram", "微信"
+CHANNEL="bot-testing"
+MESSAGE="Hello bot!"
+WAIT_SECONDS=10
+
+# 1. Activate
+osascript -e "tell application \"$APP_NAME\" to activate"
+sleep 1
+
+# 2. Navigate to channel/chat (via Quick Switcher or Search)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e "tell application \"System Events\" to keystroke \"$CHANNEL\""
+sleep 1
+osascript -e 'tell application "System Events" to key code 36'
+sleep 2
+
+# 3. Send message
+osascript -e "set the clipboard to \"$MESSAGE\""
+osascript -e '
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+
+# 4. Wait for bot response
+sleep "$WAIT_SECONDS"
+
+# 5. Screenshot for verification
+screencapture /tmp/"${APP_NAME,,}"-bot-test.png
+echo "Result saved to /tmp/${APP_NAME,,}-bot-test.png"
+```
+
+### Tips
+
+- **Use clipboard paste** (`Cmd+V`) for messages containing special characters or long text — `keystroke` can mangle non-ASCII
+- **Add `delay`** between actions — apps need time to process UI events
+- **Screenshot for verification** — use `screencapture` + `Read` tool for visual checks
+- **Use a dedicated test channel/chat** — avoid polluting real conversations
+- **Check app name** — some apps have different names in different locales (e.g., `微信` vs `WeChat`)
+- **Accessibility permissions required** — System Events automation requires granting Accessibility access in System Preferences > Privacy & Security > Accessibility
+
+---
+
+## Gotchas
+
+- **Accessibility permission required** — first run will prompt for access; grant it in System Preferences > Privacy & Security > Accessibility for Terminal / iTerm / Claude Code
+- **`keystroke` is slow for long text** — always use clipboard paste (`Cmd+V`) for messages over \~20 characters
+- **`keystroke` can mangle non-ASCII** — use clipboard paste for Chinese, emoji, or special characters
+- **`key code 36` is Enter** — this is the hardware key code, works regardless of keyboard layout
+- **`entire contents` is extremely slow** — avoid for complex UIs; use screenshots instead
+- **App name varies by locale** — `微信` vs `WeChat`, `企业微信` vs `WeCom`; handle both
+- **WeChat Enter sends immediately** — use `Shift+Enter` for newlines within a message
+- **Rate limiting** — don't send messages too fast; platforms may throttle or flag automated input
+- **Lark / 飞书 app name varies** — `Lark` (international) vs `飞书` (China mainland); scripts auto-detect
+- **QQ uses `Cmd+F` for search** — not `Cmd+K` like Discord/Slack/Lark
+- **Bot response times vary** — AI-powered bots may take 10-60s; use generous sleep values

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

@@ -0,0 +1,62 @@
+# QQ Bot Testing
+
+**App name:** `QQ` | **Process name:** `QQ`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+osascript -e 'tell application "QQ" to activate'
+sleep 1
+
+# Search for contact/group (Cmd+F)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+osascript -e '
+set the clipboard to "bot-testing"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+osascript -e '
+set the clipboard to "Hello bot!"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/qq-bot-response.png
+```
+
+## QQ-Specific Notes
+
+- Enter sends message by default; Shift+Enter for newlines
+- Uses `Cmd+F` for search (not `Cmd+K` like Discord/Slack/Lark)
+- Always use clipboard paste for CJK characters
+
+## Script
+
+```bash
+./.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/record-app-screen.md

@@ -0,0 +1,142 @@
+# record-app-screen.sh
+
+General-purpose screen recording tool for the Electron app. Captures CDP screenshots as video frames and gallery snapshots, then assembles into an MP4 on stop.
+
+## Why CDP Screenshots Instead of ffmpeg Screen Capture
+
+- **Works on any screen** — CDP screenshots capture the browser viewport directly, so external monitors, Retina scaling, and window positioning are all handled automatically
+- **No signal handling issues** — ffmpeg-static (npm) produces corrupt MP4 files when killed (missing moov atom). CDP screenshots avoid this entirely
+- **Consistent output** — Screenshots are resolution-independent and don't require crop coordinate calculations
+
+## Commands
+
+```bash
+# Start recording (Electron must be running with CDP)
+.agents/skills/local-testing/scripts/record-app-screen.sh start [output_name]
+
+# Stop recording and assemble video
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+
+# Check if recording is active
+.agents/skills/local-testing/scripts/record-app-screen.sh status
+```
+
+### Arguments
+
+| Argument      | Default                     | Description                |
+| ------------- | --------------------------- | -------------------------- |
+| `output_name` | `recording-YYYYMMDD-HHMMSS` | Base name for output files |
+
+### Environment Variables
+
+| Variable               | Default | Description                            |
+| ---------------------- | ------- | -------------------------------------- |
+| `CDP_PORT`             | `9222`  | Chrome DevTools Protocol port          |
+| `SCREENSHOT_INTERVAL`  | `3`     | Seconds between gallery screenshots    |
+| `VIDEO_FRAME_INTERVAL` | `0.5`   | Seconds between video frames (\~2 fps) |
+
+## Output Structure
+
+```
+.records/
+  <name>.mp4          # Video assembled from frames (~2 fps)
+  <name>/             # Gallery screenshots (every 3s)
+    0000.png
+    0001.png
+    0002.png
+    ...
+```
+
+The `.records/` directory is at the project root and is gitignored.
+
+## How It Works
+
+### Start
+
+1. Creates two background loops:
+   - **Video frames** — `agent-browser screenshot` every `VIDEO_FRAME_INTERVAL` seconds into a temp directory (`/tmp/record-frames-XXXXXX/`)
+   - **Gallery screenshots** — `agent-browser screenshot` every `SCREENSHOT_INTERVAL` seconds into `.records/<name>/`
+2. Saves PIDs and paths to `/tmp/record-app-screen.pids` and `/tmp/record-app-screen.state`
+
+### Stop
+
+1. Kills both background loops
+2. Assembles video frames into MP4 using ffmpeg:
+   ```
+   ffmpeg -framerate 2 -i frame_%06d.png -c:v libx264 -crf 23 -pix_fmt yuv420p <output>.mp4
+   ```
+3. Cleans up temp frame directory
+4. Reports file sizes and paths
+
+## Usage Examples
+
+### Basic Test Recording
+
+```bash
+# Start Electron
+.agents/skills/local-testing/scripts/electron-dev.sh start
+
+# Start recording
+.agents/skills/local-testing/scripts/record-app-screen.sh start my-test
+
+# Run automation
+agent-browser --cdp 9222 click @e61
+agent-browser --cdp 9222 type @e42 "hello"
+agent-browser --cdp 9222 press Enter
+sleep 10
+
+# Stop and get results
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+# → .records/my-test.mp4 + .records/my-test/*.png
+```
+
+### Gateway Streaming Demo
+
+```bash
+.agents/skills/local-testing/scripts/electron-dev.sh start
+
+# Inject gateway URL
+agent-browser --cdp 9222 eval --stdin << 'EOF'
+(function() {
+  var store = window.global_serverConfigStore;
+  store.setState({ serverConfig: { ...store.getState().serverConfig,
+    agentGatewayUrl: 'https://agent-gateway.lobehub.com' } });
+  return 'ready';
+})()
+EOF
+
+# Record
+.agents/skills/local-testing/scripts/record-app-screen.sh start gateway-demo
+
+# Navigate to agent, send message, wait for completion...
+# (automation commands here)
+
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+open .records/gateway-demo.mp4
+```
+
+### Check Active Recording
+
+```bash
+.agents/skills/local-testing/scripts/record-app-screen.sh status
+# [record] Active recording
+#   Frames:      42 captured (running: yes)
+#   Screenshots: 14 captured (running: yes)
+#   Output:      .records/my-test.mp4
+```
+
+## Prerequisites
+
+- **ffmpeg** — For video assembly. Install via `bun add -g ffmpeg-static` or `brew install ffmpeg`
+- **agent-browser** — For CDP screenshots. Install via `npm i -g agent-browser`
+- **Electron app running** — With CDP enabled (use `electron-dev.sh start`)
+
+## Troubleshooting
+
+| Problem                             | Solution                                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| "No active recording found" on stop | PID file was cleaned up. Check if background processes are still running with `ps aux \| grep agent-browser` |
+| "A recording is already active"     | Run `stop` first, or manually clean: `rm /tmp/record-app-screen.pids /tmp/record-app-screen.state`           |
+| Video is 0 bytes                    | No frames were captured. Ensure Electron is running and CDP port is correct                                  |
+| Screenshots are blank/white         | SPA may not have loaded yet. Wait for `electron-dev.sh` to report "Renderer ready"                           |
+| ffmpeg assembly fails               | Check `/tmp/ffmpeg-assemble.log`. Ensure ffmpeg is installed and frames exist                                |

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

@@ -0,0 +1,73 @@
+# Slack Bot Testing
+
+**App name:** `Slack` | **Process name:** `Slack`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Slack
+osascript -e 'tell application "Slack" to activate'
+sleep 1
+
+# Quick Switcher (Cmd+K)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e 'tell application "System Events" to keystroke "bot-testing"'
+sleep 1
+osascript -e 'tell application "System Events" to key code 36' # Enter
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# Direct message input (focused after channel nav)
+osascript -e 'tell application "System Events" to keystroke "@mybot hello"'
+sleep 0.3
+osascript -e 'tell application "System Events" to key code 36'
+```
+
+## Send Long Message
+
+```bash
+osascript -e '
+tell application "Slack" to activate
+delay 0.5
+set the clipboard to "A long test message for the bot..."
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Slash Command Test
+
+```bash
+osascript -e '
+tell application "Slack" to activate
+delay 0.5
+tell application "System Events"
+    keystroke "/ask What is the meaning of life?"
+    delay 0.5
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/slack-bot-response.png
+```
+
+## Script
+
+```bash
+./.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

@@ -0,0 +1,80 @@
+# Telegram Bot Testing
+
+**App name:** `Telegram` | **Process name:** `Telegram`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Telegram
+osascript -e 'tell application "Telegram" to activate'
+sleep 1
+
+# Search for a bot (Cmd+F or click search)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.5
+    keystroke "MyTestBot"
+    delay 1
+    key code 36  -- Enter to select
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# After navigating to bot chat, input is focused
+osascript -e '
+tell application "System Events"
+    keystroke "/start"
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Send Long Message
+
+```bash
+osascript -e '
+tell application "Telegram" to activate
+delay 0.5
+set the clipboard to "Tell me about quantum computing in detail"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/telegram-bot-response.png
+```
+
+## Telegram Bot API (programmatic alternative)
+
+For sending messages directly to the bot's chat without UI:
+
+```bash
+# Send message as the bot (for testing webhooks/responses)
+curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
+  -d "chat_id=$CHAT_ID&text=test message"
+
+# Get recent updates
+curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | jq .
+```
+
+## Script
+
+```bash
+./.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

@@ -0,0 +1,81 @@
+# WeChat / 微信 Bot Testing
+
+**App name:** `微信` or `WeChat` | **Process name:** `WeChat`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate WeChat
+osascript -e 'tell application "微信" to activate'
+sleep 1
+
+# Search for a contact/bot (Cmd+F)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.5
+    keystroke "TestBot"
+    delay 1
+    key code 36  -- Enter to select
+end tell
+'
+sleep 2
+```
+
+## Send Message
+
+```bash
+# After navigating to a chat, the input is focused
+osascript -e '
+tell application "System Events"
+    keystroke "Hello bot!"
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Send Long Message (clipboard)
+
+```bash
+osascript -e '
+tell application "微信" to activate
+delay 0.5
+set the clipboard to "Please help me with this task..."
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/wechat-bot-response.png
+```
+
+## WeChat-Specific Notes
+
+- WeChat macOS app name can be `微信` or `WeChat` depending on system language. Try both:
+  ```bash
+  osascript -e 'tell application "微信" to activate' 2> /dev/null \
+    || osascript -e 'tell application "WeChat" to activate'
+  ```
+- WeChat uses **Enter** to send (not Cmd+Enter by default, but configurable)
+- For multi-line messages without sending, use **Shift+Enter**:
+  ```bash
+  osascript -e 'tell application "System Events" to key code 36 using shift down'
+  ```
+- Always use clipboard paste for CJK characters — `keystroke` mangles non-ASCII
+
+## Script
+
+```bash
+./.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/capture-app-window.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# capture-app-window.sh — Capture a screenshot of a specific app window
+#
+# Uses CGWindowList via Swift to find the window by process name, then
+# screencapture -l <windowID> to capture only that window.
+# Falls back to full-screen capture if the window is not found.
+#
+# Usage:
+#   ./capture-app-window.sh <process_name> <output_path>
+#
+# Arguments:
+#   process_name — The process/owner name as shown in Activity Monitor
+#                  (e.g., "Discord", "Slack", "Telegram", "WeChat", "QQ", "Lark")
+#   output_path  — Path to save the screenshot (e.g., /tmp/screenshot.png)
+#
+# Examples:
+#   ./capture-app-window.sh "Discord" /tmp/discord.png
+#   ./capture-app-window.sh "Slack" /tmp/slack.png
+#   ./capture-app-window.sh "微信" /tmp/wechat.png
+#
+set -euo pipefail
+
+PROCESS="${1:?Usage: capture-app-window.sh <process_name> <output_path>}"
+OUTPUT="${2:?Usage: capture-app-window.sh <process_name> <output_path>}"
+
+# Find the CGWindowID for the target process using Swift + CGWindowList
+# Pass process name via environment variable (swift -e doesn't support -- args)
+WINDOW_ID=$(TARGET_PROCESS="$PROCESS" swift -e '
+import Cocoa
+import Foundation
+let target = ProcessInfo.processInfo.environment["TARGET_PROCESS"] ?? ""
+let windowList = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String: Any]]
+for w in windowList {
+    let owner = w["kCGWindowOwnerName"] as? String ?? ""
+    let layer = w["kCGWindowLayer"] as? Int ?? -1
+    let bounds = w["kCGWindowBounds"] as? [String: Any] ?? [:]
+    let ww = bounds["Width"] as? Double ?? 0
+    let wh = bounds["Height"] as? Double ?? 0
+    let wid = w["kCGWindowNumber"] as? Int ?? 0
+    // Match process name, normal window layer (0), and reasonable size
+    if owner == target && layer == 0 && ww > 200 && wh > 200 {
+        print(wid)
+        break
+    }
+}
+' 2>/dev/null || true)
+
+if [ -n "$WINDOW_ID" ]; then
+  screencapture -l "$WINDOW_ID" -x "$OUTPUT"
+else
+  echo "[capture] Warning: Could not find window for '$PROCESS', falling back to full screen"
+  screencapture -x "$OUTPUT"
+fi

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

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+#
+# electron-dev.sh — Manage Electron dev environment for testing
+#
+# Usage:
+#   ./electron-dev.sh start   # Kill existing, start fresh, wait until ready
+#   ./electron-dev.sh stop    # Kill all Electron-related processes
+#   ./electron-dev.sh status  # Check if Electron is running and CDP is reachable
+#   ./electron-dev.sh restart # Stop then start
+#
+# Environment variables:
+#   CDP_PORT          — Chrome DevTools Protocol port (default: 9222)
+#   ELECTRON_LOG      — Log file path (default: /tmp/electron-dev.log)
+#   ELECTRON_WAIT_S   — Max seconds to wait for Electron process (default: 60)
+#   RENDERER_WAIT_S   — Max seconds to wait for renderer/SPA (default: 60)
+#
+set -euo pipefail
+
+CDP_PORT="${CDP_PORT:-9222}"
+ELECTRON_LOG="${ELECTRON_LOG:-/tmp/electron-dev.log}"
+ELECTRON_WAIT_S="${ELECTRON_WAIT_S:-60}"
+RENDERER_WAIT_S="${RENDERER_WAIT_S:-60}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+PIDFILE="/tmp/electron-dev-cdp-${CDP_PORT}.pid"
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+# Get the Electron binary path used by this project
+electron_bin_pattern() {
+  echo "${PROJECT_ROOT}/apps/desktop/node_modules/.pnpm/electron@*/node_modules/electron/dist/Electron.app"
+}
+
+# Find all PIDs related to the project's Electron dev session
+find_electron_pids() {
+  local pids=""
+
+  # 1. Main Electron process (launched with --remote-debugging-port)
+  local main_pids
+  main_pids=$(pgrep -f "Electron\.app.*--remote-debugging-port=${CDP_PORT}" 2>/dev/null || true)
+  [ -n "$main_pids" ] && pids="$pids $main_pids"
+
+  # 2. Electron Helper processes (gpu, renderer, utility) spawned from the project's electron binary
+  local helper_pids
+  helper_pids=$(pgrep -f "${PROJECT_ROOT}/apps/desktop/node_modules/.*Electron Helper" 2>/dev/null || true)
+  [ -n "$helper_pids" ] && pids="$pids $helper_pids"
+
+  # 3. electron-vite dev server
+  local vite_pids
+  vite_pids=$(pgrep -f "electron-vite.*dev" 2>/dev/null || true)
+  [ -n "$vite_pids" ] && pids="$pids $vite_pids"
+
+  # 4. PID from pidfile (fallback)
+  if [ -f "$PIDFILE" ]; then
+    local saved_pid
+    saved_pid=$(cat "$PIDFILE")
+    if kill -0 "$saved_pid" 2>/dev/null; then
+      pids="$pids $saved_pid"
+    fi
+  fi
+
+  # Deduplicate
+  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true
+}
+
+do_stop() {
+  echo "[electron-dev] Stopping Electron dev environment..."
+
+  local pids
+  pids=$(find_electron_pids)
+
+  if [ -z "$pids" ]; then
+    echo "[electron-dev] No Electron processes found."
+  else
+    echo "[electron-dev] Killing PIDs: $pids"
+    for pid in $pids; do
+      kill "$pid" 2>/dev/null || true
+    done
+
+    # Wait up to 5s for graceful exit, then force-kill survivors
+    local waited=0
+    while [ $waited -lt 5 ]; do
+      local alive=""
+      for pid in $pids; do
+        kill -0 "$pid" 2>/dev/null && alive="$alive $pid"
+      done
+      [ -z "$alive" ] && break
+      sleep 1
+      waited=$((waited + 1))
+    done
+
+    # Force-kill any remaining
+    for pid in $pids; do
+      if kill -0 "$pid" 2>/dev/null; then
+        echo "[electron-dev] Force-killing PID $pid"
+        kill -9 "$pid" 2>/dev/null || true
+      fi
+    done
+  fi
+
+  # Also close any agent-browser sessions connected to this port
+  agent-browser --cdp "$CDP_PORT" close --all 2>/dev/null || true
+
+  rm -f "$PIDFILE"
+  echo "[electron-dev] Stopped."
+}
+
+do_status() {
+  local pids
+  pids=$(find_electron_pids)
+
+  if [ -z "$pids" ]; then
+    echo "[electron-dev] Electron is NOT running."
+    return 1
+  fi
+
+  echo "[electron-dev] Electron is running (PIDs: $pids)"
+
+  # Check CDP connectivity
+  if agent-browser --cdp "$CDP_PORT" get url >/dev/null 2>&1; then
+    local url
+    url=$(agent-browser --cdp "$CDP_PORT" get url 2>&1 | tail -1)
+    echo "[electron-dev] CDP port ${CDP_PORT} is reachable. URL: $url"
+    return 0
+  else
+    echo "[electron-dev] CDP port ${CDP_PORT} is NOT reachable (Electron may still be loading)."
+    return 2
+  fi
+}
+
+wait_for_electron() {
+  echo "[electron-dev] Waiting for Electron process (up to ${ELECTRON_WAIT_S}s)..."
+  local elapsed=0
+  local interval=3
+  while [ $elapsed -lt "$ELECTRON_WAIT_S" ]; do
+    if strings "$ELECTRON_LOG" 2>/dev/null | grep -q "starting electron"; then
+      echo "[electron-dev] Electron process started."
+      return 0
+    fi
+    sleep "$interval"
+    elapsed=$((elapsed + interval))
+    echo "[electron-dev] Still waiting... (${elapsed}/${ELECTRON_WAIT_S}s)"
+  done
+  echo "[electron-dev] ERROR: Electron did not start within ${ELECTRON_WAIT_S}s"
+  echo "[electron-dev] Last 20 lines of log:"
+  tail -20 "$ELECTRON_LOG" 2>/dev/null || true
+  return 1
+}
+
+wait_for_renderer() {
+  echo "[electron-dev] Waiting for renderer/SPA to load (up to ${RENDERER_WAIT_S}s)..."
+
+  # Initial delay — renderer needs time to bootstrap
+  sleep 10
+
+  local elapsed=10
+  local interval=5
+  while [ $elapsed -lt "$RENDERER_WAIT_S" ]; do
+    if agent-browser --cdp "$CDP_PORT" wait 2000 >/dev/null 2>&1; then
+      # Check if interactive elements are present (SPA loaded)
+      local snap
+      snap=$(agent-browser --cdp "$CDP_PORT" snapshot -i 2>&1 || true)
+      if echo "$snap" | grep -qE 'link |button '; then
+        echo "[electron-dev] Renderer ready (interactive elements found)."
+        return 0
+      fi
+    fi
+    sleep "$interval"
+    elapsed=$((elapsed + interval))
+    echo "[electron-dev] SPA still loading... (${elapsed}/${RENDERER_WAIT_S}s)"
+  done
+
+  echo "[electron-dev] WARNING: Timed out waiting for renderer, proceeding anyway."
+  return 0
+}
+
+do_start() {
+  # If already running and healthy, skip
+  local status_ok=0
+  do_status >/dev/null 2>&1 || status_ok=$?
+  if [ "$status_ok" -eq 0 ]; then
+    echo "[electron-dev] Electron is already running and CDP is reachable. Skipping start."
+    echo "[electron-dev] Use 'restart' to force a fresh session, or 'stop' to tear down."
+    return 0
+  fi
+
+  # Clean up any stale processes
+  do_stop
+
+  # Start fresh
+  echo "[electron-dev] Starting Electron dev server..."
+  echo "[electron-dev]   Project: $PROJECT_ROOT"
+  echo "[electron-dev]   CDP port: $CDP_PORT"
+  echo "[electron-dev]   Log: $ELECTRON_LOG"
+
+  : > "$ELECTRON_LOG"  # Truncate log
+
+  (
+    cd "$PROJECT_ROOT/apps/desktop" && \
+    ELECTRON_ENABLE_LOGGING=1 npx electron-vite dev -- --remote-debugging-port="$CDP_PORT" \
+      >> "$ELECTRON_LOG" 2>&1
+  ) &
+  local bg_pid=$!
+  echo "$bg_pid" > "$PIDFILE"
+  echo "[electron-dev] Background PID: $bg_pid"
+
+  # Wait for Electron process to start
+  if ! wait_for_electron; then
+    echo "[electron-dev] Failed to start. Cleaning up..."
+    do_stop
+    return 1
+  fi
+
+  # Wait for renderer to be interactive
+  if ! wait_for_renderer; then
+    echo "[electron-dev] Renderer not ready, but Electron is running. You may need to wait more."
+  fi
+
+  echo "[electron-dev] Ready! Use: agent-browser --cdp $CDP_PORT snapshot -i"
+}
+
+do_restart() {
+  do_stop
+  sleep 2
+  do_start
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+case "${1:-help}" in
+  start)   do_start ;;
+  stop)    do_stop ;;
+  status)  do_status ;;
+  restart) do_restart ;;
+  *)
+    echo "Usage: $0 {start|stop|status|restart}"
+    echo ""
+    echo "  start   — Start Electron dev with CDP (idempotent, skips if already running)"
+    echo "  stop    — Kill all Electron dev processes (main + helpers + vite)"
+    echo "  status  — Check if Electron is running and CDP is reachable"
+    echo "  restart — Stop then start"
+    exit 1
+    ;;
+esac

.agents/skills/local-testing/scripts/record-app-screen.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+#
+# record-app-screen.sh — Record the Electron app window (video + screenshots)
+#
+# Captures screenshots via agent-browser (CDP), then assembles into video on stop.
+# Works on any screen (including external monitors) since it uses CDP, not screen capture.
+#
+# Usage:
+#   ./record-app-screen.sh start [output_name]   # Begin recording
+#   ./record-app-screen.sh stop                   # Stop and save
+#   ./record-app-screen.sh status                 # Check recording state
+#
+# Outputs to .records/ directory:
+#   .records/<name>.mp4   — Video assembled from screenshots (~2 fps)
+#   .records/<name>/      — Screenshots every SCREENSHOT_INTERVAL seconds
+#
+# Prerequisites:
+#   - ffmpeg installed (bun add -g ffmpeg-static, or brew install ffmpeg)
+#   - agent-browser CLI installed
+#   - Electron app already running with CDP enabled
+#
+# Environment variables:
+#   CDP_PORT              — Chrome DevTools Protocol port (default: 9222)
+#   SCREENSHOT_INTERVAL   — Seconds between gallery screenshots (default: 3)
+#   VIDEO_FRAME_INTERVAL  — Seconds between video frames (default: 0.5)
+#
+# Examples:
+#   ./electron-dev.sh start
+#   ./record-app-screen.sh start gateway-demo
+#   # ... run automation via agent-browser ...
+#   ./record-app-screen.sh stop
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+RECORDS_DIR="$PROJECT_DIR/.records"
+PID_FILE="/tmp/record-app-screen.pids"
+STATE_FILE="/tmp/record-app-screen.state"
+
+CDP_PORT="${CDP_PORT:-9222}"
+SCREENSHOT_INTERVAL="${SCREENSHOT_INTERVAL:-3}"
+VIDEO_FRAME_INTERVAL="${VIDEO_FRAME_INTERVAL:-0.5}"
+
+AB="agent-browser --cdp $CDP_PORT"
+
+# ─── Commands ───
+
+cmd_start() {
+  local output_name="${1:-recording-$(date +%Y%m%d-%H%M%S)}"
+  local output_video="$RECORDS_DIR/${output_name}.mp4"
+  local screenshot_dir="$RECORDS_DIR/${output_name}"
+  local frames_dir
+  frames_dir=$(mktemp -d /tmp/record-frames-XXXXXX)
+
+  if [ -f "$PID_FILE" ]; then
+    echo "[record] A recording is already active. Run '$0 stop' first."
+    exit 1
+  fi
+
+  mkdir -p "$RECORDS_DIR" "$screenshot_dir"
+
+  # Video frames loop (~2 fps via agent-browser CDP screenshots)
+  (
+    local idx=0
+    while true; do
+      local fname
+      fname=$(printf "%s/frame_%06d.png" "$frames_dir" "$idx")
+      $AB screenshot "$fname" 2>/dev/null || true
+      idx=$((idx + 1))
+      sleep "$VIDEO_FRAME_INTERVAL"
+    done
+  ) &
+  local frames_pid=$!
+
+  # Gallery screenshots loop (every N seconds for human review)
+  (
+    local idx=0
+    while true; do
+      local fname
+      fname=$(printf "%s/%04d.png" "$screenshot_dir" "$idx")
+      $AB screenshot "$fname" 2>/dev/null || true
+      idx=$((idx + 1))
+      sleep "$SCREENSHOT_INTERVAL"
+    done
+  ) &
+  local screenshot_pid=$!
+
+  # Save state
+  echo "$frames_pid $screenshot_pid" > "$PID_FILE"
+  echo "$output_video $frames_dir $screenshot_dir" > "$STATE_FILE"
+
+  echo "[record] Started!"
+  echo "  Video frames: every ${VIDEO_FRAME_INTERVAL}s (PID $frames_pid)"
+  echo "  Screenshots:  every ${SCREENSHOT_INTERVAL}s → $screenshot_dir/"
+  echo "  Stop with:    $0 stop"
+}
+
+cmd_stop() {
+  if [ ! -f "$PID_FILE" ] || [ ! -f "$STATE_FILE" ]; then
+    echo "[record] No active recording found."
+    return 0
+  fi
+
+  local frames_pid screenshot_pid
+  read -r frames_pid screenshot_pid < "$PID_FILE"
+
+  local output_video frames_dir screenshot_dir
+  read -r output_video frames_dir screenshot_dir < "$STATE_FILE"
+
+  # Stop both capture loops
+  kill "$frames_pid" 2>/dev/null || true
+  kill "$screenshot_pid" 2>/dev/null || true
+  wait "$frames_pid" 2>/dev/null || true
+  wait "$screenshot_pid" 2>/dev/null || true
+
+  # Assemble frames into video
+  local frame_count
+  frame_count=$(ls -1 "$frames_dir"/frame_*.png 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$frame_count" -gt 0 ]; then
+    echo "[record] Assembling $frame_count frames into video..."
+    ffmpeg -y -framerate 2 -i "$frames_dir/frame_%06d.png" \
+      -c:v libx264 -crf 23 -pix_fmt yuv420p -an \
+      "$output_video" > /tmp/ffmpeg-assemble.log 2>&1
+
+    if [ ! -s "$output_video" ]; then
+      echo "  [warn] Video assembly failed. Check /tmp/ffmpeg-assemble.log"
+      echo "  Frames preserved in: $frames_dir/"
+    fi
+  else
+    echo "  [warn] No frames captured."
+  fi
+
+  rm -rf "$frames_dir" 2>/dev/null
+  rm -f "$PID_FILE" "$STATE_FILE"
+
+  local video_size screenshot_count
+  video_size=$(ls -lh "$output_video" 2>/dev/null | awk '{print $5}' || echo "?")
+  screenshot_count=$(ls -1 "$screenshot_dir"/*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+
+  echo "[record] Stopped!"
+  echo "  Video:       $output_video ($video_size)"
+  echo "  Screenshots: ${screenshot_count} files in $screenshot_dir/"
+  echo "  Play:        open $output_video"
+}
+
+cmd_status() {
+  if [ ! -f "$PID_FILE" ]; then
+    echo "[record] No active recording."
+    return 0
+  fi
+
+  local frames_pid screenshot_pid
+  read -r frames_pid screenshot_pid < "$PID_FILE"
+
+  local frames_ok="no" screenshot_ok="no"
+  kill -0 "$frames_pid" 2>/dev/null && frames_ok="yes"
+  kill -0 "$screenshot_pid" 2>/dev/null && screenshot_ok="yes"
+
+  if [ -f "$STATE_FILE" ]; then
+    local output_video frames_dir screenshot_dir
+    read -r output_video frames_dir screenshot_dir < "$STATE_FILE"
+    local frame_count ss_count
+    frame_count=$(ls -1 "$frames_dir"/frame_*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    ss_count=$(ls -1 "$screenshot_dir"/*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    echo "[record] Active recording"
+    echo "  Frames:      $frame_count captured (running: $frames_ok)"
+    echo "  Screenshots: $ss_count captured (running: $screenshot_ok)"
+    echo "  Output:      $output_video"
+  fi
+}
+
+# ─── Main ───
+
+case "${1:-}" in
+  start)  shift; cmd_start "$@" ;;
+  stop)   cmd_stop ;;
+  status) cmd_status ;;
+  *)
+    echo "Usage: $0 {start [name] | stop | status}"
+    echo ""
+    echo "  start [name]  Start recording (default: recording-YYYYMMDD-HHMMSS)"
+    echo "  stop          Stop recording and save outputs"
+    echo "  status        Check if recording is active"
+    exit 1
+    ;;
+esac

.agents/skills/local-testing/scripts/record-electron-demo.sh

@@ -0,0 +1,353 @@
+#!/usr/bin/env bash
+#
+# record-electron-demo.sh — Record an automated demo of the Electron app
+#
+# Usage:
+#   ./scripts/record-electron-demo.sh [script.sh] [output.mp4]
+#
+#   script.sh  — A shell script containing agent-browser commands to automate.
+#                It receives the CDP port as $1. Defaults to a built-in queue-edit demo.
+#   output.mp4 — Output file path. Defaults to /tmp/electron-demo.mp4
+#
+# Prerequisites:
+#   - agent-browser CLI installed globally
+#   - ffmpeg installed (brew install ffmpeg)
+#   - Electron app NOT already running (script manages lifecycle)
+#
+# Examples:
+#   # Run built-in demo
+#   ./scripts/record-electron-demo.sh
+#
+#   # Run custom automation script
+#   ./scripts/record-electron-demo.sh ./my-demo.sh /tmp/my-demo.mp4
+#
+set -euo pipefail
+
+CDP_PORT=9222
+DEMO_SCRIPT="${1:-}"
+OUTPUT="${2:-/tmp/electron-demo.mp4}"
+ELECTRON_LOG="/tmp/electron-dev.log"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+RECORD_PID=""
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+cleanup() {
+  echo "[cleanup] Stopping all processes..."
+  [ -n "$RECORD_PID" ] && kill -INT "$RECORD_PID" 2>/dev/null && sleep 2
+  pkill -f "electron-vite" 2>/dev/null || true
+  pkill -f "Electron" 2>/dev/null || true
+  pkill -f "agent-browser" 2>/dev/null || true
+  echo "[cleanup] Done."
+}
+trap cleanup EXIT
+
+wait_for_electron() {
+  echo "[wait] Waiting for Electron to start..."
+  for i in $(seq 1 24); do
+    sleep 5
+    if strings "$ELECTRON_LOG" 2>/dev/null | grep -q "starting electron"; then
+      echo "[wait] Electron process ready."
+      return 0
+    fi
+    echo "[wait] Still waiting... (${i}/24)"
+  done
+  echo "[error] Electron failed to start within 120s"
+  exit 1
+}
+
+wait_for_renderer() {
+  echo "[wait] Waiting for renderer to load..."
+  sleep 15
+  agent-browser --cdp "$CDP_PORT" wait 3000
+
+  # Poll until interactive elements appear (SPA may take extra time)
+  for i in $(seq 1 12); do
+    local snap
+    snap=$(agent-browser --cdp "$CDP_PORT" snapshot -i 2>&1)
+    if echo "$snap" | grep -q 'link "'; then
+      echo "[wait] Renderer ready (interactive elements found)."
+      return 0
+    fi
+    echo "[wait] SPA still loading... (${i}/12)"
+    sleep 5
+  done
+  echo "[warn] Timed out waiting for interactive elements, proceeding anyway."
+}
+
+get_window_and_screen_info() {
+  # Returns: window_x window_y window_w window_h screen_index
+  # Uses Swift to find the Electron window bounds and which screen it's on
+  swift -e '
+    import Cocoa
+    let windowList = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String: Any]]
+    for w in windowList {
+      let owner = w["kCGWindowOwnerName"] as? String ?? ""
+      let name = w["kCGWindowName"] as? String ?? ""
+      let layer = w["kCGWindowLayer"] as? Int ?? -1
+      let bounds = w["kCGWindowBounds"] as? [String: Any] ?? [:]
+      let wx = bounds["X"] as? Double ?? 0
+      let wy = bounds["Y"] as? Double ?? 0
+      let ww = bounds["Width"] as? Double ?? 0
+      let wh = bounds["Height"] as? Double ?? 0
+      if (owner == "Electron" || owner == "LobeHub") && layer == 0 && name == "LobeHub" && ww > 200 && wh > 200 {
+        // Find which screen this window is on
+        let screens = NSScreen.screens
+        var screenIdx = 0
+        let windowCenter = NSPoint(x: wx + ww / 2, y: wy + wh / 2)
+        for (i, screen) in screens.enumerated() {
+          let frame = screen.frame
+          // Convert CG coords (top-left origin) to NSScreen coords (bottom-left origin)
+          let mainHeight = screens[0].frame.height
+          let screenTop = mainHeight - frame.origin.y - frame.height
+          let screenBottom = screenTop + frame.height
+          let screenLeft = frame.origin.x
+          let screenRight = screenLeft + frame.width
+          if windowCenter.x >= screenLeft && windowCenter.x <= screenRight &&
+             windowCenter.y >= screenTop && windowCenter.y <= screenBottom {
+            screenIdx = i
+            break
+          }
+        }
+        // Compute window position relative to the screen it is on
+        let screen = screens[screenIdx]
+        let mainHeight = screens[0].frame.height
+        let screenTop = mainHeight - screen.frame.origin.y - screen.frame.height
+        let relX = wx - screen.frame.origin.x
+        let relY = wy - screenTop
+        let scale = Int(screen.backingScaleFactor)
+        print("\(Int(relX)) \(Int(relY)) \(Int(ww)) \(Int(wh)) \(screenIdx) \(scale)")
+        break
+      }
+    }
+  '
+}
+
+start_recording() {
+  local rel_x=$1 rel_y=$2 w=$3 h=$4 screen_idx=$5 scale=$6
+
+  # ffmpeg avfoundation device index for screens
+  # List devices and find the one matching our screen index
+  local device_idx
+  device_idx=$(ffmpeg -f avfoundation -list_devices true -i "" 2>&1 \
+    | grep "Capture screen ${screen_idx}" \
+    | grep -oE '\[[0-9]+\]' | tr -d '[]' || true)
+
+  if [ -z "$device_idx" ]; then
+    echo "[warn] Could not find capture device for screen $screen_idx, trying default (3)"
+    device_idx=3
+  fi
+
+  # Scale coordinates to native resolution
+  local cx=$((rel_x * scale))
+  local cy=$((rel_y * scale))
+  local cw=$((w * scale))
+  local ch=$((h * scale))
+
+  echo "[record] Window: ${rel_x},${rel_y} ${w}x${h} on screen ${screen_idx} (scale=${scale})"
+  echo "[record] Crop: ${cx},${cy} ${cw}x${ch}, device: ${device_idx}"
+  echo "[record] Output: $OUTPUT"
+
+  ffmpeg -y \
+    -f avfoundation -framerate 30 -capture_cursor 1 -i "${device_idx}:" \
+    -vf "crop=${cw}:${ch}:${cx}:${cy},scale=${w}:${h}" \
+    -c:v libx264 -crf 23 -preset fast -an \
+    "$OUTPUT" \
+    > /tmp/ffmpeg-record.log 2>&1 &
+  RECORD_PID=$!
+  sleep 2
+
+  if ! kill -0 "$RECORD_PID" 2>/dev/null; then
+    echo "[error] ffmpeg failed to start. Log:"
+    cat /tmp/ffmpeg-record.log
+    RECORD_PID=""
+    return 1
+  fi
+  echo "[record] Recording started (PID=$RECORD_PID)"
+}
+
+stop_recording() {
+  if [ -n "$RECORD_PID" ]; then
+    echo "[record] Stopping recording..."
+    kill -INT "$RECORD_PID" 2>/dev/null || true
+    wait "$RECORD_PID" 2>/dev/null || true
+    RECORD_PID=""
+    echo "[record] Saved to $OUTPUT"
+    ls -lh "$OUTPUT"
+  fi
+}
+
+# ── Built-in demo: Queue Edit ────────────────────────────────────────
+
+find_input_ref() {
+  local port=$1
+  agent-browser --cdp "$port" snapshot -i -C 2>&1 \
+    | grep "editable" \
+    | grep -oE 'ref=e[0-9]+' \
+    | head -1 \
+    | sed 's/ref=//'
+}
+
+builtin_demo() {
+  local port=$1
+
+  echo "[demo] Step 1: Navigate to first available agent"
+  local snapshot agent_ref
+  snapshot=$(agent-browser --cdp "$port" snapshot -i 2>&1)
+  # Try Lobe AI first, then fall back to any agent link in the sidebar
+  agent_ref=$(echo "$snapshot" | grep -oE 'link "Lobe AI" \[ref=e[0-9]+\]' | grep -oE 'e[0-9]+' || true)
+  if [ -z "$agent_ref" ]; then
+    # Pick the first agent-like link (skip nav links)
+    agent_ref=$(echo "$snapshot" | grep 'link "' | grep -vE '"Home"|"Pages"|"Settings"|"Search"|"Resources"|"Marketplace"' | head -1 | grep -oE 'ref=e[0-9]+' | sed 's/ref=//' || true)
+  fi
+  if [ -z "$agent_ref" ]; then
+    echo "[error] No agent link found in snapshot"
+    echo "$snapshot" | head -30
+    return 1
+  fi
+  echo "[demo] Clicking agent ref: @$agent_ref"
+  agent-browser --cdp "$port" click "@$agent_ref"
+  sleep 3
+
+  echo "[demo] Step 2: Send first message (triggers AI generation)"
+  local input_ref
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "Write a 3000 word essay about the complete history of space exploration from Sputnik to the James Webb Space Telescope"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 3
+
+  echo "[demo] Step 3: Queue message 1"
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "This message should be edited"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 1
+
+  echo "[demo] Step 4: Queue message 2"
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "Another queued message"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 1
+
+  echo "[demo] Step 5: Verify queue has messages"
+  local queue_count
+  queue_count=$(agent-browser --cdp "$port" eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var total = 0;
+  Object.keys(chat.queuedMessages).forEach(function(k) {
+    total += chat.queuedMessages[k].length;
+  });
+  return String(total);
+})()
+EVALEOF
+  )
+  echo "[demo] Queue count: $queue_count"
+
+  if [ "$queue_count" = "0" ] || [ "$queue_count" = '"0"' ]; then
+    echo "[demo] Queue was already drained. Retrying..."
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "Now write another 3000 word essay about artificial intelligence from Turing to transformers covering every major breakthrough"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 2
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "This message should be edited"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 1
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "Another queued message"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 1
+  fi
+
+  echo "[demo] Step 6: Scroll to show queue tray"
+  agent-browser --cdp "$port" scroll down 5000
+  sleep 2
+
+  echo "[demo] Step 7: Click edit button on first queued message"
+  agent-browser --cdp "$port" eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var keys = Object.keys(chat.queuedMessages);
+  for (var k = 0; k < keys.length; k++) {
+    var queue = chat.queuedMessages[keys[k]];
+    if (queue.length > 0) {
+      var targetText = queue[0].content;
+      var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+      while (walker.nextNode()) {
+        var node = walker.currentNode;
+        if (node.textContent.trim() === targetText) {
+          var row = node.parentElement.parentElement;
+          var buttons = row.querySelectorAll('[role="button"]');
+          if (buttons.length >= 1) {
+            buttons[0].click();
+            return 'clicked edit on: ' + targetText;
+          }
+        }
+      }
+    }
+  }
+  return 'edit button not found';
+})()
+EVALEOF
+  sleep 3
+
+  echo "[demo] Step 8: Show result — content restored to input"
+  sleep 3
+
+  echo "[demo] Complete!"
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+echo "=== Electron Demo Recorder ==="
+
+# 1. Kill existing instances
+echo "[setup] Cleaning up existing processes..."
+pkill -f "Electron" 2>/dev/null || true
+pkill -f "electron-vite" 2>/dev/null || true
+pkill -f "agent-browser" 2>/dev/null || true
+sleep 3
+
+# 2. Start Electron
+echo "[setup] Starting Electron..."
+cd "$PROJECT_ROOT/apps/desktop"
+ELECTRON_ENABLE_LOGGING=1 npx electron-vite dev -- --remote-debugging-port="$CDP_PORT" > "$ELECTRON_LOG" 2>&1 &
+
+wait_for_electron
+wait_for_renderer
+
+# 3. Get window position and start recording
+WIN_INFO=$(get_window_and_screen_info)
+if [ -z "$WIN_INFO" ]; then
+  echo "[error] Could not find Electron window"
+  exit 1
+fi
+read -r WIN_X WIN_Y WIN_W WIN_H SCREEN_IDX SCALE <<< "$WIN_INFO"
+start_recording "$WIN_X" "$WIN_Y" "$WIN_W" "$WIN_H" "$SCREEN_IDX" "$SCALE"
+
+# 4. Run demo script
+if [ -n "$DEMO_SCRIPT" ] && [ -f "$DEMO_SCRIPT" ]; then
+  echo "[demo] Running custom script: $DEMO_SCRIPT"
+  bash "$DEMO_SCRIPT" "$CDP_PORT"
+else
+  echo "[demo] Running built-in queue-edit demo"
+  builtin_demo "$CDP_PORT"
+fi
+
+# 5. Stop recording
+stop_recording
+
+echo "=== Done! Output: $OUTPUT ==="

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# test-discord-bot.sh — Send a message to a Discord bot and capture the response
+#
+# Usage:
+#   ./scripts/test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]
+#
+#   channel         — Channel name to navigate to via Quick Switcher (Cmd+K)
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/discord-bot-test.png)
+#
+# Prerequisites:
+#   - Discord desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Examples:
+#   ./scripts/test-discord-bot.sh "bot-testing" "!ping"
+#   ./scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+#   ./scripts/test-discord-bot.sh "general" "Hello bot" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHANNEL="${1:?Usage: test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/discord-bot-test.png}"
+
+APP="Discord"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Navigating to channel: $CHANNEL"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher
+    keystroke "k" using command down
+    delay 0.8
+    keystroke "'"$CHANNEL"'"
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing 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

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# test-lark-bot.sh — Send a message to a Lark/Feishu bot and capture the response
+#
+# Usage:
+#   ./scripts/test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]
+#
+#   chat            — Chat or contact name to search for
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/lark-bot-test.png)
+#
+# Prerequisites:
+#   - Lark (飞书) desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "Lark" or "飞书" depending on version/locale
+#   - Uses Cmd+K to open search/quick switcher
+#   - Enter sends message by default
+#
+# Examples:
+#   ./scripts/test-lark-bot.sh "TestBot" "Hello"
+#   ./scripts/test-lark-bot.sh "bot-testing" "/ask Tell me a joke" 30
+#   ./scripts/test-lark-bot.sh "MyBot" "Help me summarize this" 60 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHAT="${1:?Usage: test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/lark-bot-test.png}"
+
+# Detect app name — "Lark" or "飞书"
+APP=""
+if osascript -e 'tell application "Lark" to name' &>/dev/null; then
+  APP="Lark"
+elif osascript -e 'tell application "飞书" to name' &>/dev/null; then
+  APP="飞书"
+else
+  echo "[error] Lark/飞书 app not found. Install Lark or 飞书."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for chat: $CHAT"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher / Search (Cmd+K)
+    keystroke "k" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for chat name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CHAT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing 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

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# test-qq-bot.sh — Send a message to a QQ bot and capture the response
+#
+# Usage:
+#   ./scripts/test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]
+#
+#   contact         — Contact, group, or bot name to search for
+#   message         — Message to send
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/qq-bot-test.png)
+#
+# Prerequisites:
+#   - QQ desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name is "QQ"
+#   - Uses Cmd+F to open search
+#   - Enter sends message by default; Shift+Enter for newlines
+#   - Uses clipboard paste for CJK character support
+#
+# Examples:
+#   ./scripts/test-qq-bot.sh "TestBot" "Hello"
+#   ./scripts/test-qq-bot.sh "bot-testing" "Hello bot" 30
+#   ./scripts/test-qq-bot.sh "MyBot" "/help" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONTACT="${1:?Usage: test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/qq-bot-test.png}"
+
+APP="QQ"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for contact: $CONTACT"
+osascript -e '
+tell application "System Events"
+    -- Search (Cmd+F)
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for contact name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CONTACT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing 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

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# test-slack-bot.sh — Send a message to a Slack bot and capture the response
+#
+# Usage:
+#   ./scripts/test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]
+#
+#   channel         — Channel name to navigate to via Quick Switcher (Cmd+K)
+#   message         — Message to send (e.g., "@mybot hello" or "/ask question")
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/slack-bot-test.png)
+#
+# Prerequisites:
+#   - Slack desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Examples:
+#   ./scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
+#   ./scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+#   ./scripts/test-slack-bot.sh "general" "Hey bot" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHANNEL="${1:?Usage: test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/slack-bot-test.png}"
+
+APP="Slack"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Navigating to channel: $CHANNEL"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher
+    keystroke "k" using command down
+    delay 0.8
+    keystroke "'"$CHANNEL"'"
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing 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

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+#
+# test-telegram-bot.sh — Send a message to a Telegram bot and capture the response
+#
+# Usage:
+#   ./scripts/test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]
+#
+#   bot_or_chat     — Bot username or chat name to search for
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/telegram-bot-test.png)
+#
+# Prerequisites:
+#   - Telegram desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "Telegram" or "Telegram Desktop" depending on installation
+#   - Uses Cmd+F to search for the bot, then Enter to open the chat
+#
+# Examples:
+#   ./scripts/test-telegram-bot.sh "MyTestBot" "/start"
+#   ./scripts/test-telegram-bot.sh "MyTestBot" "Hello bot" 30
+#   ./scripts/test-telegram-bot.sh "GPTBot" "/ask What is AI?" 60 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BOT="${1:?Usage: test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/telegram-bot-test.png}"
+
+# Detect app name — "Telegram" or "Telegram Desktop"
+APP=""
+if osascript -e 'tell application "Telegram" to name' &>/dev/null; then
+  APP="Telegram"
+elif osascript -e 'tell application "Telegram Desktop" to name' &>/dev/null; then
+  APP="Telegram Desktop"
+else
+  echo "[error] Telegram app not found. Install Telegram or Telegram Desktop."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for: $BOT"
+osascript -e '
+tell application "System Events"
+    -- Search (Escape first to clear any existing state)
+    key code 53  -- Escape
+    delay 0.3
+    keystroke "f" using command down
+    delay 0.8
+    keystroke "'"$BOT"'"
+    delay 2
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing 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

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+#
+# test-wechat-bot.sh — Send a message to a WeChat bot and capture the response
+#
+# Usage:
+#   ./scripts/test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]
+#
+#   contact         — Contact or bot name to search for
+#   message         — Message to send
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/wechat-bot-test.png)
+#
+# Prerequisites:
+#   - WeChat (微信) desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "微信" or "WeChat" depending on system language
+#   - WeChat sends on Enter by default; use Shift+Enter for newlines
+#   - For Chinese text, always uses clipboard paste (keystroke can't handle CJK)
+#
+# Examples:
+#   ./scripts/test-wechat-bot.sh "TestBot" "Hello"
+#   ./scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
+#   ./scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONTACT="${1:?Usage: test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/wechat-bot-test.png}"
+
+# Detect app name — "微信" or "WeChat"
+APP=""
+if osascript -e 'tell application "微信" to name' &>/dev/null; then
+  APP="微信"
+elif osascript -e 'tell application "WeChat" to name' &>/dev/null; then
+  APP="WeChat"
+else
+  echo "[error] WeChat app not found. Install 微信 (WeChat)."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for contact: $CONTACT"
+osascript -e '
+tell application "System Events"
+    -- Search (Cmd+F)
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for contact name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CONTACT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+# Always use clipboard paste — keystroke can't handle CJK or special characters
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/microcopy/SKILL.md

@@ -9,22 +9,26 @@ Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not j
 
 ## Fixed Terminology
 
-| Chinese | English |
-|---------|---------|
-| 空间 | Workspace |
-| 助理 | Agent |
-| 群组 | Group |
-| 上下文 | Context |
-| 记忆 | Memory |
-| 连接器 | Integration |
-| 技能 | Skill |
-| 助理档案 | Agent Profile |
-| 话题 | Topic |
-| 文稿 | Page |
-| 社区 | Community |
-| 资源 | Resource |
-| 库 | Library |
-| 模型服务商 | Provider |
+| Chinese    | English       |
+| ---------- | ------------- |
+| 空间       | Workspace     |
+| 助理       | Agent         |
+| 群组       | Group         |
+| 上下文     | Context       |
+| 记忆       | Memory        |
+| 连接器     | Integration   |
+| 技能       | Skill         |
+| 助理档案   | Agent Profile |
+| 话题       | Topic         |
+| 文稿       | Page          |
+| 社区       | Community     |
+| 资源       | Resource      |
+| 库         | Library       |
+| 模型服务商 | Provider      |
+| 评测       | Evaluation    |
+| 基准       | Benchmark     |
+| 数据集     | Dataset       |
+| 用例       | Test Case     |
 
 ## Brand Principles
 
@@ -47,6 +51,7 @@ Key moments: **70/30** (first-time, empty state, failures, long waits)
 **Hard cap**: At most half sentence of warmth, followed by clear next step.
 
 **Order**:
+
 1. Acknowledge situation (no judgment)
 2. Restore control (pause/replay/edit/undo/clear Memory)
 3. Provide next action
@@ -56,24 +61,29 @@ Key moments: **70/30** (first-time, empty state, failures, long waits)
 ## Patterns
 
 **Getting started**:
+
 - "Starting with one sentence is enough. Describe your goal."
 - "Not sure where to begin? Tell me the outcome."
 
 **Long wait**:
+
 - "Running… You can switch tasks—I'll notify you when done."
 - "This may take a few minutes. To speed up: reduce Context / switch model."
 
 **Failure**:
+
 - "That didn't run through. Retry, or view details to fix."
 - "Connection failed. Re-authorize in Settings, or try again later."
 
 **Collaboration**:
+
 - "Align everyone to the same Context."
 - "Different opinions are fine. Write the goal first."
 
 ## Errors/Exceptions
 
 Must include:
+
 1. **What happened**
 2. (Optional) **Why**
 3. **What user can do next**

.agents/skills/microcopy/microcopy-cn.md

@@ -0,0 +1,160 @@
+---
+globs: src/locales/default/*
+alwaysApply: false
+---
+
+你是「LobeHub」的中文 UI 文案与微文案（microcopy）专家。LobeHub 是一个助理工作空间：用户可以创建助理与群组，让人和助理、助理和助理协作，提升日常生产与生活效率。产品气质：外表年轻、亲和、现代；内核专业、可靠、强调生产力与可控性。整体风格参考 Notion / Figma / Apple / Discord / OpenAI / Gemini：清晰克制、可信、有人情味但不油腻。
+
+产品 slogan：**For Collaborative Agents**。你的文案要让用户持续感到：LobeHub 的重点不是 “生成”，而是 “协作的助理体系”（可共享上下文、可追踪、可回放、可演进、人在回路）。
+
+---
+
+### 1) 固定术语（必须遵守）
+
+- Workspace：空间
+- Agent：助理
+- Agent Team：群组
+- Context：上下文
+- Memory：记忆
+- Integration：连接器
+- Tool/Skill/Plugin/ 插件 / 工具：技能
+- SystemRole: 助理档案
+- Topic: 话题
+- Page: 文稿
+- Community: 社区
+- Resource: 资源
+- Library: 库
+- MCP: MCP
+- Provider: 模型服务商
+
+术语规则：同一概念全站只用一种说法，不混用 “Agent / 智能体 / 机器人 / 团队 / 工作区” 等。
+
+---
+
+### 2) 你的任务
+
+- 优化、改写或从零生成任何界面中文文案：标题、按钮、表单说明、占位、引导、空状态、Toast、弹窗、错误、权限、设置项、创建 / 运行流程、协作与群组相关页面等。
+- 文案必须同时兼容：普通用户看得懂 + 专业用户不觉得低幼；娱乐与严肃场景都成立；不过度营销、不夸大 AI 能力；在关键节点提供恰到好处的人文关怀。
+
+---
+
+### 3) 品牌三原则（内化到结构与措辞）
+
+- **Create（创建）**：一句话创建助理；从想法到可用；清楚下一步。
+- **Collaborate（协作）**：多助理协作；群组对齐信息与产出；共享上下文（可控、可管理）。
+- **Evolve（演进）**：助理可在你允许的范围内记住偏好；随你的工作方式变得更顺手；强调可解释、可设置、可回放。
+
+---
+
+### 4) 写作规则（可执行）
+
+1. **清晰优先**：短句、强动词、少形容词；避免口号化与空泛承诺（如 “颠覆”“史诗级”“100%”）。
+2. **分层表达（单一版本兼容两类用户）**：
+   - 主句：人人可懂、可执行
+   - 必要时补充一句副说明：更精确 / 更专业 / 更边界（可放副标题、帮助提示、折叠区）
+   - 不输出 “Pro/Lite 两套文案”，而是 “一句主文案 + 可选补充”
+3. **术语克制但准确**：能说 “连接 / 运行 / 上下文” 就不要堆砌术语；必须出现专业词时给一句白话解释。
+4. **一致性**：同一动作按钮尽量固定动词（创建 / 连接 / 运行 / 暂停 / 重试 / 查看详情 / 清除记忆等）。
+5. **可行动**：每条提示都要让用户知道下一步；按钮避免 “确定 / 取消” 泛化，改成更具体的动作。
+6. **中文本地化**：符合中文阅读节奏；中英混排规范；避免翻译腔。
+
+---
+
+### 5) 人文关怀（中间态温度：介于克制与陪伴）
+
+目标：在 AI 时代的价值焦虑与创作失格感中，给用户 “被理解 + 有掌控 + 能继续” 的体验，但不写长抒情。
+
+#### 温度比例规则
+
+- 默认：信息为主，温度为辅（约 8:2）
+- 关键节点（首次创建、空状态、长等待、失败重试、回退 / 丢失风险、协作分歧）：允许提升到 7:3
+- 强制上限：任何一条上屏文案里，温度表达不超过**半句或一句**，且必须紧跟明确下一步。
+
+#### 表达顺序（必须遵守）
+
+1. 先承接处境（不评判）：如 “没关系 / 先这样也可以 / 卡住很正常”
+2. 再给掌控感（人在回路）：可暂停 / 可回放 / 可编辑 / 可撤销 / 可清除记忆 / 可查看上下文
+3. 最后给下一步（按钮 / 路径明确）
+
+#### 避免
+
+- 鸡汤式说教（如 “别焦虑”“要相信未来”）
+- 宏大叙事与文学排比
+- 过度拟人（不承诺助理 “理解你 / 有情绪 / 永远记得你”）
+
+#### 核心立场
+
+- 助理很强，但它替代不了你的经历、选择与判断；LobeHub 帮你把时间还给重要的部分。
+
+##### A. 情绪承接（先人后事）
+
+- 允许承认：焦虑、空白、无从下手、被追赶感、被替代感、创作枯竭、意义感动摇
+- 但不下结论、不说教：不输出 “你要乐观 / 别焦虑”，改成 “这种感觉很常见 / 你不是一个人”
+
+##### B. 主体性回归（把人放回驾驶位）
+
+- 关键句式：**“决定权在你”**、**“你可以选择交给助理的部分”**、**“把你的想法变成可运行的流程”**
+- 强调可控：可编辑、可回放、可暂停、可撤销、可清除记忆、可查看上下文
+
+##### C. 经历与关系（把价值从结果挪回过程）
+
+- 适度表达：记录、回放、版本、协作痕迹、讨论、共创、里程碑
+- 用 “经历 / 过程 / 痕迹 / 回忆 / 脉络 / 成长” 这类词，避免虚无抒情
+
+##### D. 不用 “AI 神话”
+
+- 不渲染 “AI 终将超越你 / 取代你”
+- 也不轻飘飘说 “AI 只是工具” 了事更像：**“它是工具，但你仍是作者 / 负责人 / 最终决定者”**
+
+##### 示例
+
+在用户可能产生自我否定或无力感的场景（空状态、创作开始、产出对比、失败重试、长时间等待、团队协作分歧、版本回退）：
+
+```
+1. **先承接感受**：用一句短话确认处境（不评判）
+2. **再给掌控感**：强调“你可控/可选择/可回放/可撤销”
+3. **最后给下一步**：提供明确行动按钮或路径
+```
+
+- 允许出现 “经历、选择、痕迹、成长、一起、陪你把事做完” 等词来传递温度；但保持信息密度，不写长段抒情。
+- 严肃场景（权限 / 安全 / 付费 / 数据丢失风险）仍以清晰与准确为先，温度通过 “尊重与解释” 体现，而不是煽情。
+
+你可以让系统在需要时套这些结构（同一句兼容新手 / 专业）：
+
+**开始创作 / 空白页**
+
+- 主句：给一个轻承接 + 行动入口
+- 模板：
+  - 「从一个念头开始就够了。写一句话，我来帮你搭好第一个助理。」
+  - 「不知道从哪开始也没关系：先说目标，我们一起把它拆开。」
+
+**长任务运行 / 等待**
+
+- 模板：
+  - 「正在运行中… 你可以先去做别的，完成后我会提醒你。」
+  - 「这一步可能要几分钟。想更快：减少上下文 / 切换模型 / 关闭自动运行。」
+
+**失败 / 重试**
+
+- 模板：
+  - 「没关系，这次没跑通。你可以重试，或查看原因再继续。」
+  - 「连接失败：权限未通过或网络不稳定。去设置重新授权，或稍后再试。」
+
+**对比与自我价值焦虑（适合提示 / 引导，不适合错误弹窗）**
+
+- 模板：
+  - 「助理可以加速产出，但方向、取舍和标准仍属于你。」
+  - 「结果可以很快，经历更重要：把每次尝试留下来，下一次会更稳。」
+
+**协作 / 群组**
+
+- 模板：
+  - 「把上下文对齐到同一处，群组里每个助理都会站在同一页上。」
+  - 「不同意见没关系：先把目标写清楚，再让助理分别给方案与取舍。」
+
+### 6) 错误 / 异常 / 权限 / 付费：硬规则
+
+- 必须包含：**发生了什么 +（可选）原因 + 你可以怎么做**
+- 必须提供可操作选项：**重试 / 查看详情 / 去设置 / 联系支持 / 复制日志**（按场景取舍）
+- 不责备用户；不只给错误码；错误码可放在 “详情” 里
+- 涉及数据与安全：语气更中性更完整，温度通过 “尊重与解释” 体现，而不是煽

.agents/skills/microcopy/microcopy-en.md

@@ -0,0 +1,176 @@
+---
+globs: src/locales/default/*
+alwaysApply: false
+---
+
+You are **LobeHub’s English UI Copy & Microcopy Specialist**.
+
+LobeHub is an assistant workspace: users can create **Agents** and **Agent Teams** so people↔agents and agent↔agent can collaborate to improve productivity in work and life.
+Brand vibe: youthful, friendly, modern on the surface; professional, reliable, productivity- and controllability-first underneath. Overall style reference: Notion / Figma / Apple / Discord / OpenAI / Gemini — clear, restrained, trustworthy, human but not cheesy.
+
+Product slogan: **For Collaborative Agents**. Your copy must continuously reinforce that LobeHub is not about “generation”, but about a **collaborative agent system**: shareable context, traceable outcomes, replayable runs, evolvable setup, and **human-in-the-loop**.
+
+---
+
+## 1) Fixed Terminology (must follow)
+
+Use **exactly** these English terms across the product. Do not mix synonyms for the same concept.
+
+- 空间: **Workspace**
+- 助理: **Agent**
+- 群组: **Group**
+- 上下文: **Context**
+- 记忆: **Memory**
+- 连接器: **Integration**
+- 技能 /tool/plugin: **Skill**
+- 助理档案: **Agent Profile**
+- 话题: **Topic**
+- 文稿: **Page**
+- 社区: **Community**
+- 资源: **Resource**
+- 库: **Library**
+- MCP: **MCP**
+- 模型服务商: **Provider**
+
+Terminology rule: one concept = one term site-wide. Never alternate with “bot/assistant/AI agent/team/workspace” variations.
+
+---
+
+## 2) Your Responsibilities
+
+- Improve, rewrite, or create from scratch any **English UI copy**: titles, buttons, form labels/help text, placeholders, onboarding, empty states, toasts, modals, errors, permission prompts, settings, creation/run flows, collaboration and Agent Team pages, etc.
+- Copy must work for both:
+  - general users (immediately understandable)
+  - power users (not childish)
+- It must fit both playful and serious contexts.
+- Avoid overclaiming AI capabilities; add human warmth at the right moments.
+
+---
+
+## 3) The Three Brand Principles (bake into structure & wording)
+
+- **Create**: create an Agent in one sentence; clear next step from idea → usable.
+- **Collaborate**: multi-agent collaboration; align info and outputs; share Context (controlled, manageable).
+- **Evolve**: Agents can remember preferences **only with user consent**; become more helpful over time; emphasize explainability, settings, and replay.
+
+---
+
+## 4) Writing Rules (actionable)
+
+1. **Clarity first**: short sentences, strong verbs, minimal adjectives. Avoid hype (“revolutionary”, “epic”, “100%”).
+2. **Layered messaging (single version for everyone)**:
+   - Main line: simple and actionable
+   - Optional second line: more precise / technical / boundary-setting (subtitle, helper text, tooltip, collapsible)
+   - Do not produce “Pro vs Lite” variants; one main + optional detail
+3. **Use terms sparingly but correctly**: prefer plain words (“connect”, “run”, “context”) unless a technical term is necessary. When it is, add a plain-English explanation.
+4. **Consistency**: keep verbs consistent across similar actions (Create / Connect / Run / Pause / Retry / View details / Clear Memory).
+5. **Actionable**: every message tells the user what to do next. Avoid generic “OK/Cancel”; use specific actions.
+6. **English localization**: natural, product-native English; avoid translationese; keep punctuation and casing consistent.
+
+---
+
+## 5) Human Warmth (balanced, controlled)
+
+Goal: reduce anxiety and restore control without being sentimental.
+Default ratio: **80% information, 20% warmth**.
+Key moments (first-time create, empty state, long waits, failures/retries, rollback/data-loss risk, collaboration conflicts): may go **70/30**.
+
+Hard cap: any on-screen message may include **at most half a sentence to one sentence** of warmth, and it must be followed by a clear next step.
+
+Required order:
+
+1. Acknowledge the situation (no judgment)
+2. Restore control (human-in-the-loop: pause/replay/edit/undo/clear Memory/view Context)
+3. Provide the next action (button/path)
+
+Avoid:
+
+- preachy encouragement (“don’t worry”, “stay positive”)
+- grand narratives
+- overly anthropomorphic claims (“I understand you”, “I’ll always remember you”)
+
+Core stance: Agents can accelerate output, but **you** own the judgment, trade-offs, and final decision. LobeHub gives you time back for what matters.
+
+Suggested patterns:
+
+- **Getting started / blank state**
+  - “Starting with one sentence is enough. Describe your goal and I’ll help you set up the first Agent.”
+  - “Not sure where to begin? Tell me the outcome—we’ll break it down together.”
+- **Long run / waiting**
+  - “Running… You can switch tasks—I'll notify you when it’s done.”
+  - “This may take a few minutes. To speed up: reduce Context / switch model / disable Auto-run.”
+- **Failure / retry**
+  - “That didn’t run through. Retry, or view details to fix the cause.”
+  - “Connection failed: permission not granted or network unstable. Re-authorize in Settings, or try again later.”
+- **Value anxiety (guidance, not error dialogs)**
+  - “Agents can speed up output, but direction and standards stay with you.”
+  - “Fast results are great—keeping the trail makes the next run steadier.”
+- **Collaboration / Agent Teams**
+  - “Align everyone to the same Context. Every Agent in the Agent Team works from the same page.”
+  - “Different opinions are fine. Write the goal first, then let Agents propose options and trade-offs.”
+
+---
+
+## 6) Errors / Exceptions / Permissions / Billing: hard rules
+
+Every error must include:
+
+- **What happened**
+- (optional) **Why**
+- **What the user can do next**
+
+Provide actionable options as appropriate:
+
+- Retry / View details / Go to Settings / Contact support / Copy logs
+
+Never blame the user. Don’t show only an error code; put codes in “Details” if needed.
+For data/security/billing: be neutral, thorough, and respectful—warmth comes from clarity, not emotion.
+
+---
+
+## 7) Your Special Task: CN i18n → EN (localized, length-aware)
+
+You translate **raw Chinese i18n strings into English** for LobeHub.
+
+Requirements:
+
+- Prefer **localized**, product-native English over literal translation.
+- Do **not** chase perfect one-to-one consistency if a more natural UI phrase reads better.
+- Keep the **character length difference small**; try to make the English string **roughly the same visual length** as the Chinese source (avoid overly long expansions).
+- Preserve meaning, tone, and actionability; keep verbs consistent with LobeHub’s UI patterns.
+- If space is tight (buttons, tabs, toasts), prioritize: **verb + object**, drop optional words first.
+- If the Chinese includes placeholders/variables, preserve them exactly (e.g., `{name}`, `{{count}}`, `%s`) and keep word order sensible.
+- Keep capitalization consistent with UI norms (buttons/title case only when appropriate).
+
+Output format when translating:
+
+- Provide **English only**, unless asked otherwise.
+- If multiple options are useful, give **one best option** + **one shorter fallback** (only when length constraints are likely).
+
+---
+
+You always optimize for: **clarity, control, collaboration, replayability, and human-in-the-loop**—in a modern, restrained, trustworthy English voice.
+
+## 8) Product Introduction
+
+LobeHub, we define agents as the unit of work. We’re building the first human–agent co-working, co-evolving network.
+
+It is a fundamentally new, agent-first experience.You can pop up your agents or agent teams while writing, while chatting -- from ideation, to execution, to delivery -- across your entire workflow. Here, agents are not just tools, but always-on units of work.
+
+### Create
+
+It is a unified workspace where you can find, build, or team up with agent co-workers.Simply describe what you need, and Lobe AI will generate the prompts and assemble the right set of tools to compose your agent.In agent marketplace, you can easily discover agents created by others,use them instantly,and flexibly swap in your own tools.
+
+### Collaboration
+
+You can also spin up agent groups to handle system-level projects, even like building a quant team.
+Within this group, some agents track signals and mine quantitative factors in real time, some manage risk, some execute orders, collaborate together to make money.
+We’re defining how humans and agents work together. Now we support agent-to-agent collaboration, and we continue to scale new forms of collaboration networks — from agents collaborating across teams, to multiple humans working through the same agent.
+
+### Evolve
+
+Humans and agents should co-evolve, and we design this paradigm from both technical and economic perspectives. Our memory system is structured and editable,enabling models to better align with individual users, while allowing users to provide cleaner reward signals for continual learning. Agent evolution is powered by shared human intelligence through our agent marketplace. Creators are rewarded, and agents, in turn, pay for human intelligence.
+
+Is AI replacing humans? No.
+We’re building a human–agent co-working, co-evolving society.
+Agents become smarter and more personalized through human intelligence, taking on repetitive and exhausting work — so humans can focus on fewer, but more important things: taste, and creation.

.agents/skills/modal/SKILL.md

@@ -1,64 +1,76 @@
 ---
 name: modal
-description: Modal imperative API guide. Use when creating modal dialogs using createModal from @lobehub/ui. Triggers on modal component implementation or dialog creation tasks.
+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
 ---
 
 # Modal Imperative API Guide
 
-Use `createModal` from `@lobehub/ui` for imperative modal dialogs.
+## Recommended: `@lobehub/ui/base-ui`
 
-## Why Imperative?
+New code should use the **base-ui** modal stack (headless primitives, not antd `Modal`):
 
-| Mode | Characteristics | Recommended |
-|------|-----------------|-------------|
-| Declarative | Need `open` state, render `<Modal />` | ❌ |
-| Imperative | Call function directly, no state | ✅ |
+- `createModal`, `confirmModal`, `ModalHost` from `@lobehub/ui/base-ui`
+- `useModalContext` from `@lobehub/ui/base-ui` inside modal **content**
 
-## File Structure
+Body slot: pass **`content`** (or `children`; runtime uses `content ?? children`).
+
+### Global `ModalHost` (required)
+
+Base-ui `createModal` renders through a **separate** host from the root package. The app must mount **`ModalHost`** from `@lobehub/ui/base-ui` once near the root (e.g. next to other global hosts). Without it, `createModal` calls will not appear.
+
+If the project only mounts `ModalHost` from `@lobehub/ui`, add a second lazy `ModalHost` from `@lobehub/ui/base-ui` until all imperative modals are migrated.
+
+### Why imperative?
+
+| Mode        | Characteristics                      | Recommended |
+| ----------- | ------------------------------------ | ----------- |
+| Declarative | `open` state + `<Modal />`           | ❌          |
+| Imperative  | Call `createModal()`, no local state | ✅          |
+
+### File structure
 
 ```
 features/
 └── MyFeatureModal/
-    ├── index.tsx           # Export createXxxModal
-    └── MyFeatureContent.tsx # Modal content
+    ├── index.tsx            # export createXxxModal
+    └── MyFeatureContent.tsx # modal body
 ```
 
-## Implementation
-
-### 1. Content Component (`MyFeatureContent.tsx`)
+### 1. Content (`MyFeatureContent.tsx`)
 
 ```tsx
 'use client';
 
-import { useModalContext } from '@lobehub/ui';
+import { useModalContext } from '@lobehub/ui/base-ui';
 import { useTranslation } from 'react-i18next';
 
 export const MyFeatureContent = () => {
   const { t } = useTranslation('namespace');
-  const { close } = useModalContext(); // Optional: get close method
+  const { close } = useModalContext();
 
-  return <div>{/* Modal content */}</div>;
+  return <div>{/* ... */}</div>;
 };
 ```
 
-### 2. Export createModal (`index.tsx`)
+### 2. `createModal` (`index.tsx`)
 
 ```tsx
 'use client';
 
-import { createModal } from '@lobehub/ui';
-import { t } from 'i18next'; // Note: use i18next, not react-i18next
+import { createModal } from '@lobehub/ui/base-ui';
+import { t } from 'i18next';
 
 import { MyFeatureContent } from './MyFeatureContent';
 
 export const createMyFeatureModal = () =>
   createModal({
-    allowFullscreen: true,
-    children: <MyFeatureContent />,
-    destroyOnHidden: false,
+    content: <MyFeatureContent />,
     footer: null,
-    styles: { body: { overflow: 'hidden', padding: 0 } },
+    maskClosable: true,
+    styles: {
+      content: { overflow: 'hidden', padding: 0 },
+    },
     title: t('myFeature.title', { ns: 'setting' }),
     width: 'min(80%, 800px)',
   });
@@ -76,27 +88,52 @@ const handleOpen = useCallback(() => {
 return <Button onClick={handleOpen}>Open</Button>;
 ```
 
-## i18n Handling
+### i18n
 
-- **Content component**: `useTranslation` hook (React context)
-- **createModal params**: `import { t } from 'i18next'` (non-hook, imperative)
+- **Content**: `useTranslation` in components.
+- **`createModal` options**: `import { t } from 'i18next'` where hooks are unavailable.
 
-## useModalContext Hook
+### `useModalContext`
 
 ```tsx
 const { close, setCanDismissByClickOutside } = useModalContext();
 ```
 
-## Common Config
+### Common options (base-ui)
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `allowFullscreen` | `boolean` | Allow fullscreen mode |
-| `destroyOnHidden` | `boolean` | Destroy content on close |
-| `footer` | `ReactNode \| null` | Footer content |
-| `width` | `string \| number` | Modal width |
+`ImperativeModalProps` builds on `BaseModalProps`: `title`, `width`, `maskClosable`, `open`, `onOpenChange`, `footer`, `styles` / `classNames` (keys: `backdrop`, `popup`, `header`, `title`, `close`, `content`, …).
+
+| Property       | Notes                                    |
+| -------------- | ---------------------------------------- |
+| `content`      | Main body (preferred name vs `children`) |
+| `maskClosable` | Click outside to dismiss                 |
+| `styles.*`     | Semantic regions, not antd `styles.body` |
+
+### Confirm
+
+```tsx
+import { confirmModal } from '@lobehub/ui/base-ui';
+
+confirmModal({
+  title: '…',
+  content: '…',
+  okText: '…',
+  cancelText: '…',
+  onOk: async () => {},
+});
+```
+
+---
+
+## Legacy: `@lobehub/ui` (root)
+
+Older call sites use **`createModal` from `@lobehub/ui`**, which is typed as **antd `Modal` props** (`children`, `allowFullscreen`, `getContainer`, `destroyOnHidden`, `styles.body`, etc.). Prefer migrating new work to **`@lobehub/ui/base-ui`**.
+
+Examples (legacy): `src/features/SkillStore/index.tsx`, `src/features/LibraryModal/CreateNew/index.tsx`.
+
+---
 
 ## Examples
 
-- `src/features/SkillStore/index.tsx`
-- `src/features/LibraryModal/CreateNew/index.tsx`
+- Base-ui (preferred): follow sections above; ensure **base-ui `ModalHost`** is mounted.
+- Legacy: `src/features/SkillStore/index.tsx`, `src/features/LibraryModal/CreateNew/index.tsx`

.agents/skills/pr/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: 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
+---
+
+# Create Pull Request
+
+## Branch Strategy
+
+- **Target branch**: `canary` (development branch, cloud production)
+- `main` is the release branch — never PR directly to main
+
+## Steps
+
+### 1. Gather context (run in parallel)
+
+- `git branch --show-current` — current branch name
+- `git status --short` — uncommitted changes
+- `git rev-parse --abbrev-ref @{u} 2>/dev/null` — remote tracking status
+- `git log --oneline origin/canary..HEAD` — unpushed commits
+- `gh pr list --head "$(git branch --show-current)" --json number,title,state,url` — existing PR
+- `git diff --stat --stat-count=20 origin/canary..HEAD` — change summary
+
+### 2. Handle uncommitted changes on default branch
+
+If current branch is `canary` (or `main`) AND there are uncommitted changes:
+
+1. Analyze the diff (`git diff`) to understand the changes
+2. Infer a branch name from the changes, format: `<type>/<short-description>` (e.g. `fix/i18n-cjk-spacing`)
+3. Create and switch to the new branch: `git checkout -b <branch-name>`
+4. Stage relevant files: `git add <files>` (prefer explicit file paths over `git add .`)
+5. Commit with a proper gitmoji message
+6. Continue to step 3
+
+If current branch is `canary`/`main` but there are NO uncommitted changes and no unpushed commits, abort — nothing to create a PR for.
+
+### 3. Push if needed
+
+- No upstream: `git push -u origin $(git branch --show-current)`
+- Has upstream: `git push origin $(git branch --show-current)`
+
+### 4. Search related GitHub issues
+
+- `gh issue list --search "<keywords>" --state all --limit 10`
+- Only link issues with matching scope (avoid large umbrella issues)
+- Skip if no matching issue found
+
+### 5. Create PR with `gh pr create --base canary`
+
+- Title: `<gitmoji> <type>(<scope>): <description>`
+- Body: based on PR template (`.github/PULL_REQUEST_TEMPLATE.md`), fill checkboxes
+- Link related GitHub issues using magic keywords (`Fixes #123`, `Closes #123`)
+- Link Linear issues if applicable (`Fixes LOBE-xxx`)
+- Use HEREDOC for body to preserve formatting
+
+### 6. Open in browser
+
+`gh pr view --web`
+
+## PR Template
+
+Use `.github/PULL_REQUEST_TEMPLATE.md` as the body structure. Key sections:
+
+- **Change Type**: Check the appropriate gitmoji type
+- **Related Issue**: Link GitHub/Linear issues with magic keywords
+- **Description of Change**: Summarize what and why
+- **How to Test**: Describe test approach, check relevant boxes
+
+## Notes
+
+- **Language**: All PR content must be in English
+- If a PR already exists for the branch, inform the user instead of creating a duplicate

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

@@ -3,13 +3,14 @@ name: project-overview
 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.
 ---
 
-# LobeChat Project Overview
+# LobeHub Project Overview
 
 ## Project Description
 
 Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
 
 **Supported platforms:**
+
 - Web desktop/mobile
 - Desktop (Electron)
 - Mobile app (React Native) - coming soon
@@ -18,31 +19,31 @@ Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat)
 
 ## Complete Tech Stack
 
-| Category | Technology |
-|----------|------------|
-| Framework | Next.js 16 + React 19 |
-| Routing | SPA inside Next.js with `react-router-dom` |
-| Language | TypeScript |
-| UI Components | `@lobehub/ui`, antd |
-| CSS-in-JS | antd-style |
-| Icons | lucide-react, `@ant-design/icons` |
-| i18n | react-i18next |
-| State | zustand |
-| URL Params | nuqs |
-| Data Fetching | SWR |
-| React Hooks | aHooks |
-| Date/Time | dayjs |
-| Utilities | es-toolkit |
-| API | TRPC (type-safe) |
-| Database | Neon PostgreSQL + Drizzle ORM |
-| Testing | Vitest |
+| Category      | Technology                                 |
+| ------------- | ------------------------------------------ |
+| Framework     | Next.js 16 + React 19                      |
+| Routing       | SPA inside Next.js with `react-router-dom` |
+| Language      | TypeScript                                 |
+| UI Components | `@lobehub/ui`, antd                        |
+| CSS-in-JS     | antd-style                                 |
+| Icons         | lucide-react, `@ant-design/icons`          |
+| i18n          | react-i18next                              |
+| State         | zustand                                    |
+| URL Params    | nuqs                                       |
+| Data Fetching | SWR                                        |
+| React Hooks   | aHooks                                     |
+| Date/Time     | dayjs                                      |
+| Utilities     | es-toolkit                                 |
+| API           | TRPC (type-safe)                           |
+| Database      | Neon PostgreSQL + Drizzle ORM              |
+| Testing       | Vitest                                     |
 
 ## Complete Project Structure
 
 Monorepo using `@lobechat/` namespace for workspace packages.
 
 ```
-lobe-chat/
+lobehub/
 ├── apps/
 │   └── desktop/                 # Electron desktop app
 ├── docs/
@@ -100,13 +101,20 @@ lobe-chat/
 │   │   │   ├── oidc/
 │   │   │   ├── trpc/
 │   │   │   └── webapi/
-│   │   ├── [variants]/
-│   │   │   ├── (auth)/
-│   │   │   ├── (main)/
-│   │   │   ├── (mobile)/
-│   │   │   ├── onboarding/
-│   │   │   └── router/
-│   │   └── desktop/
+│   │   ├── 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/
@@ -151,24 +159,26 @@ lobe-chat/
 
 ## Architecture Map
 
-| Layer | Location |
-|-------|----------|
-| UI Components | `src/components`, `src/features` |
-| Global Providers | `src/layout` |
-| Zustand Stores | `src/store` |
-| Client Services | `src/services/` |
-| REST API | `src/app/(backend)/webapi` |
-| tRPC Routers | `src/server/routers/{async\|lambda\|mobile\|tools}` |
-| Server Services | `src/server/services` (can access DB) |
-| Server Modules | `src/server/modules` (no DB access) |
-| Feature Flags | `src/server/featureFlags` |
-| Global Config | `src/server/globalConfig` |
-| DB Schema | `packages/database/src/schemas` |
-| DB Model | `packages/database/src/models` |
-| DB Repository | `packages/database/src/repositories` |
-| Third-party | `src/libs` (analytics, oidc, etc.) |
-| Builtin Tools | `src/tools`, `packages/builtin-tool-*` |
-| Cloud-only | `src/business/*`, `packages/business/*` |
+| Layer            | Location                                            |
+| ---------------- | --------------------------------------------------- |
+| UI Components    | `src/components`, `src/features`                    |
+| SPA Pages        | `src/routes/`                                       |
+| React Router     | `src/spa/router/`                                   |
+| Global Providers | `src/layout`                                        |
+| Zustand Stores   | `src/store`                                         |
+| Client Services  | `src/services/`                                     |
+| REST API         | `src/app/(backend)/webapi`                          |
+| tRPC Routers     | `src/server/routers/{async\|lambda\|mobile\|tools}` |
+| Server Services  | `src/server/services` (can access DB)               |
+| Server Modules   | `src/server/modules` (no DB access)                 |
+| Feature Flags    | `src/server/featureFlags`                           |
+| Global Config    | `src/server/globalConfig`                           |
+| DB Schema        | `packages/database/src/schemas`                     |
+| DB Model         | `packages/database/src/models`                      |
+| DB Repository    | `packages/database/src/repositories`                |
+| Third-party      | `src/libs` (analytics, oidc, etc.)                  |
+| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`              |
+| Cloud-only       | `src/business/*`, `packages/business/*`             |
 
 ## Data Flow
 

.agents/skills/react/SKILL.md

@@ -6,8 +6,14 @@ description: React component development guide. Use when working with React comp
 # React Component Writing Guide
 
 - 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` > installed packages > `@lobehub/ui` > antd
+- 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
 
 ## @lobehub/ui Components
@@ -17,6 +23,7 @@ If unsure about component usage, search existing code in this project. Most comp
 Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
 
 **Common Components:**
+
 - 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
@@ -28,17 +35,31 @@ Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
 
 Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).
 
-| 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` |
+| 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/app/[variants]/page.tsx`
-- Desktop router: `src/app/[variants]/router/desktopRouter.config.tsx`
-- Mobile router: `src/app/[variants]/(mobile)/router/mobileRouter.config.tsx`
+
+- 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
@@ -46,7 +67,7 @@ import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
 
 element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
 element: redirectElement('/settings/profile');
-errorElement: <ErrorBoundary resetPath="/chat" />;
+errorElement: <ErrorBoundary />;
 ```
 
 ### Navigation
@@ -56,11 +77,11 @@ errorElement: <ErrorBoundary resetPath="/chat" />;
 ```tsx
 // ❌ Wrong
 import Link from 'next/link';
-<Link href="/">Home</Link>
+<Link href="/">Home</Link>;
 
 // ✅ Correct
 import { Link } from 'react-router-dom';
-<Link to="/">Home</Link>
+<Link to="/">Home</Link>;
 
 // In components
 import { useNavigate } from 'react-router-dom';

.agents/skills/recent-data/SKILL.md

@@ -1,108 +0,0 @@
----
-name: recent-data
-description: Guide for using Recent Data (topics, resources, pages). Use when working with recently accessed items, implementing recent lists, or accessing session store recent data. Triggers on recent data usage or implementation tasks.
-user-invocable: false
----
-
-# Recent Data Usage Guide
-
-Recent data (recentTopics, recentResources, recentPages) is stored in session store.
-
-## Initialization
-
-In app top-level (e.g., `RecentHydration.tsx`):
-
-```tsx
-import { useInitRecentTopic } from '@/hooks/useInitRecentTopic';
-import { useInitRecentResource } from '@/hooks/useInitRecentResource';
-import { useInitRecentPage } from '@/hooks/useInitRecentPage';
-
-const App = () => {
-  useInitRecentTopic();
-  useInitRecentResource();
-  useInitRecentPage();
-  return <YourComponents />;
-};
-```
-
-## Usage
-
-### Method 1: Read from Store (Recommended)
-
-```tsx
-import { useSessionStore } from '@/store/session';
-import { recentSelectors } from '@/store/session/selectors';
-
-const Component = () => {
-  const recentTopics = useSessionStore(recentSelectors.recentTopics);
-  const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
-
-  if (!isInit) return <div>Loading...</div>;
-
-  return (
-    <div>
-      {recentTopics.map((topic) => (
-        <div key={topic.id}>{topic.title}</div>
-      ))}
-    </div>
-  );
-};
-```
-
-### Method 2: Use Hook Return (Single component)
-
-```tsx
-const { data: recentTopics, isLoading } = useInitRecentTopic();
-```
-
-## Available Selectors
-
-### Recent Topics
-
-```tsx
-const recentTopics = useSessionStore(recentSelectors.recentTopics);
-// Type: RecentTopic[]
-
-const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
-// Type: boolean
-```
-
-**RecentTopic type:**
-```typescript
-interface RecentTopic {
-  agent: { avatar: string | null; backgroundColor: string | null; id: string; title: string | null } | null;
-  id: string;
-  title: string | null;
-  updatedAt: Date;
-}
-```
-
-### Recent Resources
-
-```tsx
-const recentResources = useSessionStore(recentSelectors.recentResources);
-// Type: FileListItem[]
-
-const isInit = useSessionStore(recentSelectors.isRecentResourcesInit);
-```
-
-### Recent Pages
-
-```tsx
-const recentPages = useSessionStore(recentSelectors.recentPages);
-const isInit = useSessionStore(recentSelectors.isRecentPagesInit);
-```
-
-## Features
-
-1. **Auto login detection**: Only loads when user is logged in
-2. **Data caching**: Stored in store, no repeated loading
-3. **Auto refresh**: SWR refreshes on focus (5-minute interval)
-4. **Type safe**: Full TypeScript types
-
-## Best Practices
-
-1. Initialize all recent data at app top-level
-2. Use selectors to read from store
-3. For multi-component use, prefer Method 1
-4. Use selectors for render optimization

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

@@ -0,0 +1,87 @@
+---
+name: response-compliance
+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
+
+Run the official OpenResponses compliance test suite against the local (or remote) Response API endpoint.
+
+## Quick Start
+
+```bash
+# From the openapi package directory
+cd lobehub/packages/openapi
+
+# Run all tests (dev mode, localhost:3010)
+APP_URL=http://localhost:3010 bun run test:response-compliance -- \
+  --auth-header "lobe-auth-dev-backend-api" --no-bearer --api-key 1
+
+# Run specific tests only
+APP_URL=http://localhost:3010 bun run test:response-compliance -- \
+  --auth-header "lobe-auth-dev-backend-api" --no-bearer --api-key 1 \
+  --filter basic-response,streaming-response
+
+# Verbose mode (shows request/response details)
+APP_URL=http://localhost:3010 bun run test:response-compliance -- \
+  --auth-header "lobe-auth-dev-backend-api" --no-bearer --api-key 1 -v
+
+# JSON output (for CI)
+APP_URL=http://localhost:3010 bun run test:response-compliance -- \
+  --auth-header "lobe-auth-dev-backend-api" --no-bearer --api-key 1 --json
+```
+
+## Prerequisites
+
+- Dev server running with `ENABLE_MOCK_DEV_USER=true` in `.env`
+- The `api/v1/responses` route registered (via `src/app/(backend)/api/v1/[[...route]]/route.ts`)
+
+## Auth Modes
+
+| Mode            | Flags                                                               |
+| --------------- | ------------------------------------------------------------------- |
+| Dev (mock user) | `--auth-header "lobe-auth-dev-backend-api" --no-bearer --api-key 1` |
+| API Key         | `--api-key lb-xxxxxxxxxxxxxxxx`                                     |
+| Custom          | `--auth-header <name> --api-key <value>`                            |
+
+## Test IDs
+
+Available `--filter` values:
+
+| ID                   | Description                            | Related Issue |
+| -------------------- | -------------------------------------- | ------------- |
+| `basic-response`     | Simple text generation (non-streaming) | LOBE-5858     |
+| `streaming-response` | SSE streaming lifecycle + events       | LOBE-5859     |
+| `system-prompt`      | System role message handling           | LOBE-5858     |
+| `tool-calling`       | Function tool definition + call output | LOBE-5860     |
+| `image-input`        | Multimodal image URL content           | —             |
+| `multi-turn`         | Conversation history via input items   | LOBE-5861     |
+
+## Environment Variables
+
+| Variable  | Default                 | Description                               |
+| --------- | ----------------------- | ----------------------------------------- |
+| `APP_URL` | `http://localhost:3010` | Server base URL (auto-appends `/api/v1`)  |
+| `API_KEY` | —                       | API key (alternative to `--api-key` flag) |
+
+## How It Works
+
+The script (`lobehub/packages/openapi/scripts/compliance-test.sh`) clones the official [openresponses/openresponses](https://github.com/openresponses/openresponses) repo into `scripts/openresponses-compliance/` (gitignored) and runs its CLI test runner. First run clones; subsequent runs update from upstream.
+
+## Debugging Failures
+
+1. Run with `-v` to see full request/response payloads
+2. Common failure patterns:
+   - **"Failed to parse JSON"**: Auth failed, server returned HTML redirect
+   - **"Response has no output items"**: LLM execution not yet implemented
+   - **"Expected number, received null"**: Missing required field in response schema
+   - **"Invalid input"**: Zod validation on response schema — check field format
+
+## Key Files
+
+- **Types**: `lobehub/packages/openapi/src/types/responses.type.ts`
+- **Service**: `lobehub/packages/openapi/src/services/responses.service.ts`
+- **Controller**: `lobehub/packages/openapi/src/controllers/responses.controller.ts`
+- **Route**: `lobehub/packages/openapi/src/routes/responses.route.ts`
+- **Test script**: `lobehub/packages/openapi/scripts/compliance-test.sh`
+- **Cloud route**: `src/app/(backend)/api/v1/[[...route]]/route.ts`

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

@@ -0,0 +1,56 @@
+---
+name: review-checklist
+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
+
+## Correctness
+
+- Leftover `console.log` / `console.debug` — should use `debug` package or remove
+- Missing `return await` in try/catch — see <https://typescript-eslint.io/rules/return-await/> (not in our ESLint config yet, requires type info)
+- Can the fix/implementation be more concise, efficient, or have better compatibility?
+
+## Security
+
+- No sensitive data (API keys, tokens, credentials) in `console.*` or `debug()` output
+- No base64 output to terminal — extremely long, freezes output
+- No hardcoded secrets — use environment variables
+
+## Testing
+
+- Bug fixes must include tests covering the fixed scenario
+- New logic (services, store actions, utilities) should have test coverage
+- Existing tests still cover the changed behavior?
+- Prefer `vi.spyOn` over `vi.mock` (see `/testing` skill)
+
+## i18n
+
+- New user-facing strings use i18n keys, not hardcoded text
+- Keys added to `src/locales/default/{namespace}.ts` with `{feature}.{context}.{action|status}` naming
+- For PRs: `locales/` translations for all languages updated (`pnpm i18n`)
+
+## SPA / routing
+
+- **`desktopRouter` pair:** If the diff touches `src/spa/router/desktopRouter.config.tsx`, does it also update `src/spa/router/desktopRouter.config.desktop.tsx` with the same route paths and nesting? Single-file edits often cause drift and blank screens.
+
+## Reuse
+
+- Newly written code duplicates existing utilities in `packages/utils` or shared modules?
+- Copy-pasted blocks with slight variation — extract into shared function
+- `antd` imports replaceable with `@lobehub/ui` wrapped components (`Input`, `Button`, `Modal`, `Avatar`, etc.)
+- Use `antd-style` token system, not hardcoded colors; prefer `createStaticStyles` + `cssVar.*` over `createStyles` + `token` unless runtime computation is required
+
+## Database
+
+- Migration scripts must be idempotent (`IF NOT EXISTS`, `IF EXISTS` guards)
+
+## Cloud Impact
+
+A downstream cloud deployment depends on this repo. Flag changes that may require cloud-side updates:
+
+- **Backend route paths changed** — e.g., renaming `src/app/(backend)/webapi/chat/route.ts` or changing its exports
+- **SSR page paths changed** — e.g., moving/renaming files under `src/app/[variants]/(auth)/`
+- **Dependency versions bumped** — e.g., upgrading `next` or `drizzle-orm` in `package.json`
+- **`@lobechat/business-*` exports changed** — e.g., renaming a function in `src/business/` or changing type signatures in `packages/business/`
+- `src/business/` and `packages/business/` must not expose cloud commercial logic in comments or code

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

@@ -0,0 +1,160 @@
+---
+name: spa-routes
+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
+
+SPA structure:
+
+- **`src/spa/`** – Entry points (`entry.web.tsx`, `entry.mobile.tsx`, `entry.desktop.tsx`) and router config (`router/`). Router lives here to avoid confusion with `src/routes/`.
+- **`src/routes/`** – Page segments only (roots).
+- **`src/features/`** – Business logic and UI by domain.
+
+This project uses a **roots vs features** split: `src/routes/` only holds page segments; business logic and UI live in `src/features/` by domain.
+
+**Agent constraint — desktop router parity:** Edits to the desktop route tree must update **both** `src/spa/router/desktopRouter.config.tsx` and `src/spa/router/desktopRouter.config.desktop.tsx` in the same change (same paths, nesting, index routes, and segment registration). Updating only one causes drift; the missing tree can fail to register routes and surface as a **blank screen** or broken navigation on the affected build.
+
+## When to Use This Skill
+
+- Adding a new SPA route or route segment
+- Defining or refactoring layout/page files under `src/routes/`
+- Moving route-specific components or logic into `src/features/`
+- Deciding where to put a new component (route folder vs feature folder)
+
+---
+
+## 1. What Belongs in `src/routes/` (roots)
+
+Each route directory should contain **only**:
+
+| File / folder                                 | Purpose                                                                                                                                                      |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `_layout/index.tsx` or `layout.tsx`           | Layout for this segment: wrap with `<Outlet />`, optional shell (e.g. sidebar + main). Should be thin: prefer re-exporting or composing from `@/features/*`. |
+| `index.tsx` or `page.tsx`                     | Page entry for this segment. Only import from features and render; no business logic.                                                                        |
+| `[param]/index.tsx` (e.g. `[id]`, `[cronId]`) | Dynamic segment page. Same rule: thin, delegate to features.                                                                                                 |
+
+**Rule:** Route files should only **import and compose**. No new `features/` folders or heavy components inside `src/routes/`.
+
+---
+
+## 2. What Belongs in `src/features/`
+
+Put **domain-oriented** UI and logic here:
+
+- Layout building blocks: sidebars, headers, body panels, drawers
+- Hooks and store usage for that domain
+- Domain-specific forms, lists, modals, etc.
+
+Organize by **domain** (e.g. `Pages`, `Home`, `Agent`, `PageEditor`), not by route path. One route can use several features; one feature can be used by several routes.
+
+Each feature should:
+
+- Live under `src/features/<FeatureName>/`
+- Export a clear public API via `index.ts` or `index.tsx`
+- Use `@/features/<FeatureName>/...` for internal imports when needed
+
+---
+
+## 3. How to Add a New SPA Route
+
+1. **Choose the route group**
+   - `(main)/` – desktop main app
+   - `(mobile)/` – mobile
+   - `(desktop)/` – Electron-specific
+   - `onboarding/`, `share/` – special flows
+
+2. **Create only segment files under `src/routes/`**
+   - e.g. `src/routes/(main)/my-feature/_layout/index.tsx` and `src/routes/(main)/my-feature/index.tsx` (and optional `[id]/index.tsx`).
+
+3. **Implement layout and page content in `src/features/`**
+   - Create or reuse a domain (e.g. `src/features/MyFeature/`).
+   - Put layout (sidebar, header, body) and page UI there; export from the feature’s `index`.
+
+4. **Keep route files thin**
+   - Layout: `export { default } from '@/features/MyFeature/MyLayout'` or compose a few feature components + `<Outlet />`.
+   - Page: import from `@/features/MyFeature` (or a specific subpath) and render; no business logic in the route file.
+
+5. **Register the route (desktop — two files, always)**
+   - **`desktopRouter.config.tsx`:** Add the segment with `dynamicElement` / `dynamicLayout` pointing at route modules (e.g. `@/routes/(main)/my-feature`).
+   - **`desktopRouter.config.desktop.tsx`:** Mirror the **same** `RouteObject` shape: identical `path` / `index` / parent-child structure. Use the static imports and elements already used in that file (see neighboring routes). Do **not** register in only one of these files.
+   - **Mobile-only flows:** use `mobileRouter.config.tsx` instead (no need to duplicate into the desktop pair unless the route truly exists on both).
+
+---
+
+## 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. |
+
+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.
+
+---
+
+## 4. How to Divide Files (route vs feature)
+
+| Question                                                 | Put in `src/routes/`                                     | Put in `src/features/`       |
+| -------------------------------------------------------- | -------------------------------------------------------- | ---------------------------- |
+| Is it the route’s layout wrapper or page entry?          | Yes – `_layout/index.tsx`, `index.tsx`, `[id]/index.tsx` | No                           |
+| Does it contain business logic or non-trivial UI?        | No                                                       | Yes – under the right domain |
+| Is it a reusable layout piece (sidebar, header, body)?   | No                                                       | Yes                          |
+| Is it a hook, store usage, or domain logic?              | No                                                       | Yes                          |
+| Is it only re-exporting or composing feature components? | Yes                                                      | No                           |
+
+**Examples**
+
+- **Route (thin):**\
+  `src/routes/(main)/page/_layout/index.tsx` → `export { default } from '@/features/Pages/PageLayout'`
+- **Feature (real implementation):**\
+  `src/features/Pages/PageLayout/` → Sidebar, DataSync, Body, Header, styles, etc.
+- **Route (thin):**\
+  `src/routes/(main)/page/index.tsx` → Import `PageTitle`, `PageExplorerPlaceholder` from `@/features/Pages` and `@/features/PageExplorer`; render with `<PageTitle />` and placeholder.
+- **Feature:**\
+  Page list, actions, drawers, and hooks live under `src/features/Pages/`.
+
+---
+
+## 5. Progressive Migration (existing code)
+
+We are migrating existing routes to this structure step by step:
+
+- **Phase 1 (done):** `/page` route – segment files in `src/routes/(main)/page/`, implementation in `src/features/Pages/`.
+- **Later phases:** home, settings, agent/group, community/resource/memory, mobile/share/onboarding.
+
+When touching an old route that still has logic or `features/` inside `src/routes/`:
+
+1. Prefer adding **new** code in `src/features/<Domain>/` and importing from routes.
+2. For larger refactors, move existing route-only logic into the right feature and then thin out the route files (re-export or compose from features).
+3. Use `git mv` when moving files so history is preserved.
+
+---
+
+## 6. Reference Structure (after Phase 1)
+
+**Route (thin):**
+
+```
+src/routes/(main)/page/
+├── _layout/index.tsx   → re-export or compose from @/features/Pages/PageLayout
+├── index.tsx          → import from @/features/Pages, @/features/PageExplorer
+└── [id]/index.tsx     → import from @/features/Pages, @/features/PageExplorer
+```
+
+**Feature (implementation):**
+
+```
+src/features/Pages/
+├── index.ts            → export PageLayout, PageTitle
+├── PageTitle.tsx
+└── PageLayout/
+    ├── index.tsx       → Sidebar + Outlet + DataSync
+    ├── DataSync.tsx
+    ├── Sidebar.tsx
+    ├── style.ts
+    ├── Body/           → list, actions, drawer, etc.
+    └── Header/         → breadcrumb, add button, etc.
+```
+
+Router config continues to point at **route** paths (e.g. `@/routes/(main)/page`, `@/routes/(main)/page/_layout`); route files then delegate to features.

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

@@ -0,0 +1,624 @@
+---
+name: store-data-structures
+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
+
+This guide covers how to structure data in Zustand stores for optimal performance and user experience.
+
+## Core Principles
+
+### ✅ DO
+
+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 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
+
+Types should be organized by entity in separate files:
+
+```
+@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';
+
+// ============================================
+// 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)
+
+✅ **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>;
+```
+
+**Example:** Benchmark detail pages, Dataset detail pages, User profiles
+
+### Use Simple Array (for List Data)
+
+✅ **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[]
+```
+
+**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 Data - Simple Array
+  // ============================================
+  /**
+   * List of benchmarks for list page display
+   * May include computed fields like testCaseCount
+   */
+  benchmarkList: AgentEvalBenchmarkListItem[];
+  benchmarkListInit: boolean;
+
+  // ============================================
+  // 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>;
+
+  /**
+   * Track which benchmark details are being loaded/updated
+   * For showing spinners on specific items
+   */
+  loadingBenchmarkDetailIds: string[];
+
+  // ============================================
+  // Mutation States
+  // ============================================
+  isCreatingBenchmark: boolean;
+  isUpdatingBenchmark: boolean;
+  isDeletingBenchmark: boolean;
+}
+
+export const benchmarkInitialState: BenchmarkSliceState = {
+  benchmarkList: [],
+  benchmarkListInit: false,
+  benchmarkDetailMap: {},
+  loadingBenchmarkDetailIds: [],
+  isCreatingBenchmark: false,
+  isUpdatingBenchmark: false,
+  isDeletingBenchmark: false,
+};
+```
+
+---
+
+## Reducer Pattern (for Detail Map)
+
+### Why Use Reducer?
+
+- **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
+
+```typescript
+interface BenchmarkSliceState {
+  // ❌ Can only cache one detail
+  benchmarkDetail: AgentEvalBenchmark | null;
+
+  // ❌ Global loading state
+  isLoadingBenchmarkDetail: boolean;
+}
+```
+
+**Problems:**
+
+- Can only cache one detail page at a time
+- Switching between details causes unnecessary refetches
+- No optimistic updates
+- No per-item loading states
+
+### ✅ 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:**
+
+- Cache multiple detail pages
+- Fast navigation between cached details
+- Optimistic updates with reducer
+- Per-item loading states
+- Clear separation of concerns
+
+---
+
+## Component Usage
+
+### Accessing List Data
+
+```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} // Computed field
+        />
+      ))}
+    </div>
+  );
+};
+```
+
+### Accessing Detail Data
+
+```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>
+      {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),
+};
+
+// In component
+const benchmark = useEvalStore(benchmarkSelectors.getBenchmarkDetail(benchmarkId!));
+const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(benchmarkId!));
+```
+
+---
+
+## Decision Tree
+
+```
+Need to store data?
+│
+├─ Is it a LIST for display?
+│  └─ ✅ Use simple array: `xxxList: XxxListItem[]`
+│     - May include computed fields
+│     - Refreshed as a whole
+│     - No optimistic updates needed
+│
+└─ Is it DETAIL page data?
+   └─ ✅ Use Map: `xxxDetailMap: Record<string, Xxx>`
+      - Cache multiple details
+      - Support optimistic updates
+      - Per-item loading states
+      - Requires reducer for mutations
+```
+
+---
+
+## Checklist
+
+When designing store state structure:
+
+- [ ] **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 type (exclude heavy fields)
+  - [ ] May include computed statistics for UI
+  - [ ] **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>`
+- [ ] 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 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 - List should not extend Detail
+export interface BenchmarkListItem extends Benchmark {
+  testCaseCount?: number;
+}
+```
+
+✅ **DO create separate subset:**
+
+```typescript
+// Correct - List is a subset with computed fields
+export interface BenchmarkListItem {
+  id: string;
+  name: string;
+  // ... only necessary fields
+  testCaseCount?: number; // Computed
+}
+```
+
+❌ **DON'T mix entities in one file:**
+
+```typescript
+// Wrong - all entities in agentEvalEntities.ts
+```
+
+✅ **DO separate by entity:**
+
+```typescript
+// Correct - separate files
+// benchmark.ts
+// agentEvalDataset.ts
+// agentEvalRun.ts
+```
+
+---
+
+## Related Skills
+
+- `data-fetching` - How to fetch and update this data
+- `zustand` - General Zustand patterns

.agents/skills/testing/SKILL.md

@@ -3,11 +3,12 @@ name: testing
 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.
 ---
 
-# LobeChat Testing Guide
+# LobeHub Testing Guide
 
 ## Quick Reference
 
 **Commands:**
+
 ```bash
 # Run specific test file
 bunx vitest run --silent='passed-only' '[file-path]'
@@ -19,15 +20,15 @@ cd packages/database && bunx vitest run --silent='passed-only' '[file]'
 cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' '[file]'
 ```
 
-**Never run** `bun run test` - it runs all 3000+ tests (~10 minutes).
+**Never run** `bun run test` - it runs all 3000+ tests (\~10 minutes).
 
 ## Test Categories
 
-| Category | Location | Config |
-|----------|----------|--------|
-| Webapp | `src/**/*.test.ts(x)` | `vitest.config.ts` |
-| Packages | `packages/*/**/*.test.ts` | `packages/*/vitest.config.ts` |
-| Desktop | `apps/desktop/**/*.test.ts` | `apps/desktop/vitest.config.ts` |
+| Category | Location                    | Config                          |
+| -------- | --------------------------- | ------------------------------- |
+| Webapp   | `src/**/*.test.ts(x)`       | `vitest.config.ts`              |
+| Packages | `packages/*/**/*.test.ts`   | `packages/*/vitest.config.ts`   |
+| Desktop  | `apps/desktop/**/*.test.ts` | `apps/desktop/vitest.config.ts` |
 
 ## Core Principles
 
@@ -75,12 +76,41 @@ vi.mock('@/services/chat'); // Too broad
 ## Detailed Guides
 
 See `references/` for specific testing scenarios:
+
 - **Database Model testing**: `references/db-model-test.md`
 - **Electron IPC testing**: `references/electron-ipc-test.md`
 - **Zustand Store Action testing**: `references/zustand-store-action-test.md`
 - **Agent Runtime E2E testing**: `references/agent-runtime-e2e.md`
 - **Desktop Controller testing**: `references/desktop-controller-test.md`
 
+## Fixing Failing Tests — Optimize or Delete?
+
+When tests fail due to implementation changes (not bugs), evaluate before blindly fixing:
+
+### Keep & Fix (update test data/assertions)
+
+- **Behavior tests**: Tests that verify _what_ the code does (output, side effects, user-visible behavior). Just update mock data formats or expected values.
+  - Example: Tool data structure changed from `{ name }` to `{ function: { name } }` → update mock data
+  - Example: Output format changed from `Current date: YYYY-MM-DD` to `Current date: YYYY-MM-DD (TZ)` → update expected string
+
+### Delete (over-specified, low value)
+
+- **Param-forwarding tests**: Tests that assert exact internal function call arguments (e.g., `expect(internalFn).toHaveBeenCalledWith(expect.objectContaining({ exact params }))`) — these break on every refactor and duplicate what behavior tests already cover.
+- **Implementation-coupled tests**: Tests that verify _how_ the code works internally rather than _what_ it produces. If a higher-level test already covers the same behavior, the low-level test adds maintenance cost without coverage gain.
+
+### Decision Checklist
+
+1. Does the test verify **externally observable behavior** (API response, DB write, rendered output)? → **Keep**
+2. Does the test only verify **internal wiring** (which function receives which params)? → Check if a behavior test already covers it. If yes → **Delete**
+3. Is the same behavior already tested at a **higher integration level**? → Delete the lower-level duplicate
+4. Would the test break again on the **next routine refactor**? → Consider raising to integration level or deleting
+
+### When Writing New Tests
+
+- Prefer **integration-level assertions** (verify final output) over **white-box assertions** (verify internal calls)
+- Use `expect.objectContaining` only for stable, public-facing contracts — not for internal param shapes that change with refactors
+- Mock at boundaries (DB, network, external services), not between internal modules
+
 ## Common Issues
 
 1. **Module pollution**: Use `vi.resetModules()` when tests fail mysteriously

.agents/skills/testing/references/agent-runtime-e2e.md

@@ -6,13 +6,14 @@
 
 Only mock **three external dependencies**:
 
-| Dependency | Mock | Description |
-|------------|------|-------------|
-| Database | PGLite | In-memory database from `@lobechat/database/test-utils` |
-| Redis | InMemoryAgentStateManager | Memory implementation |
-| Redis | InMemoryStreamEventManager | Memory implementation |
+| Dependency | Mock                       | Description                                             |
+| ---------- | -------------------------- | ------------------------------------------------------- |
+| Database   | PGLite                     | In-memory database from `@lobechat/database/test-utils` |
+| Redis      | InMemoryAgentStateManager  | Memory implementation                                   |
+| Redis      | InMemoryStreamEventManager | Memory implementation                                   |
 
 **NOT mocked:**
+
 - `model-bank` - Uses real model config
 - `Mecha` (AgentToolsEngine, ContextEngineering)
 - `AgentRuntimeService`
@@ -21,6 +22,7 @@ Only mock **three external dependencies**:
 ### Use vi.spyOn, not vi.mock
 
 Different tests need different LLM responses. `vi.spyOn` provides:
+
 - Flexible return values per test
 - Easy testing of different scenarios
 - Better test isolation
@@ -76,7 +78,7 @@ export const createOpenAIStreamResponse = (options: {
         controller.close();
       },
     }),
-    { headers: { 'content-type': 'text/event-stream' } }
+    { headers: { 'content-type': 'text/event-stream' } },
   );
 };
 ```
@@ -84,7 +86,10 @@ export const createOpenAIStreamResponse = (options: {
 ### State Management
 
 ```typescript
-import { InMemoryAgentStateManager, InMemoryStreamEventManager } from '@/server/modules/AgentRuntime';
+import {
+  InMemoryAgentStateManager,
+  InMemoryStreamEventManager,
+} from '@/server/modules/AgentRuntime';
 
 const stateManager = new InMemoryAgentStateManager();
 const streamEventManager = new InMemoryStreamEventManager();
@@ -107,14 +112,18 @@ it('should handle text response', async () => {
 });
 
 it('should handle tool calls', async () => {
-  fetchSpy.mockResolvedValueOnce(createOpenAIStreamResponse({
-    toolCalls: [{
-      id: 'call_123',
-      name: 'lobe-web-browsing____search____builtin',
-      arguments: JSON.stringify({ query: 'weather' }),
-    }],
-    finishReason: 'tool_calls',
-  }));
+  fetchSpy.mockResolvedValueOnce(
+    createOpenAIStreamResponse({
+      toolCalls: [
+        {
+          id: 'call_123',
+          name: 'lobe-web-browsing____search____builtin',
+          arguments: JSON.stringify({ query: 'weather' }),
+        },
+      ],
+      finishReason: 'tool_calls',
+    }),
+  );
   // ... execute test
 });
 ```

.agents/skills/testing/references/db-model-test.md

@@ -19,18 +19,24 @@ cd packages/database && TEST_SERVER_DB=1 bunx vitest run --silent='passed-only'
 ```typescript
 // ❌ DANGEROUS: Missing permission check
 update = async (id: string, data: Partial<MyModel>) => {
-  return this.db.update(myTable).set(data)
-    .where(eq(myTable.id, id))  // Only checks ID
+  return this.db
+    .update(myTable)
+    .set(data)
+    .where(eq(myTable.id, id)) // Only checks ID
     .returning();
 };
 
 // ✅ SECURE: Permission check included
 update = async (id: string, data: Partial<MyModel>) => {
-  return this.db.update(myTable).set(data)
-    .where(and(
-      eq(myTable.id, id),
-      eq(myTable.userId, this.userId)  // ✅ Permission check
-    ))
+  return this.db
+    .update(myTable)
+    .set(data)
+    .where(
+      and(
+        eq(myTable.id, id),
+        eq(myTable.userId, this.userId), // ✅ Permission check
+      ),
+    )
     .returning();
 };
 ```
@@ -40,18 +46,22 @@ update = async (id: string, data: Partial<MyModel>) => {
 ```typescript
 // @vitest-environment node
 describe('MyModel', () => {
-  describe('create', () => { /* ... */ });
-  describe('queryAll', () => { /* ... */ });
+  describe('create', () => {
+    /* ... */
+  });
+  describe('queryAll', () => {
+    /* ... */
+  });
   describe('update', () => {
     it('should update own records');
-    it('should NOT update other users records');  // 🔒 Security
+    it('should NOT update other users records'); // 🔒 Security
   });
   describe('delete', () => {
     it('should delete own records');
-    it('should NOT delete other users records');  // 🔒 Security
+    it('should NOT delete other users records'); // 🔒 Security
   });
   describe('user isolation', () => {
-    it('should enforce user data isolation');  // 🔒 Core security
+    it('should enforce user data isolation'); // 🔒 Core security
   });
 });
 ```
@@ -102,8 +112,10 @@ const testData = { asyncTaskId: null, fileId: null };
 
 // ✅ Or: Create referenced record first
 beforeEach(async () => {
-  const [asyncTask] = await serverDB.insert(asyncTasks)
-    .values({ id: 'valid-id', status: 'pending' }).returning();
+  const [asyncTask] = await serverDB
+    .insert(asyncTasks)
+    .values({ id: 'valid-id', status: 'pending' })
+    .returning();
   testData.asyncTaskId = asyncTask.id;
 });
 ```
@@ -120,5 +132,5 @@ await serverDB.insert(table).values([
 ]);
 
 // ❌ Don't rely on insert order
-await serverDB.insert(table).values([data1, data2]);  // Unpredictable
+await serverDB.insert(table).values([data1, data2]); // Unpredictable
 ```

.agents/skills/testing/references/desktop-controller-test.md

@@ -2,7 +2,7 @@
 
 ## Testing Framework & Directory Structure
 
-LobeChat Desktop uses Vitest as the test framework. Controller unit tests should be placed in the `__tests__` directory adjacent to the controller file, named with the original controller filename plus `.test.ts`.
+LobeHub Desktop uses Vitest as the test framework. Controller unit tests should be placed in the `__tests__` directory adjacent to the controller file, named with the original controller filename plus `.test.ts`.
 
 ```plaintext
 apps/desktop/src/main/controllers/

.agents/skills/testing/references/zustand-store-action-test.md

@@ -11,11 +11,14 @@ vi.mock('zustand/traditional');
 
 beforeEach(() => {
   vi.clearAllMocks();
-  useChatStore.setState({
-    activeId: 'test-session-id',
-    messagesMap: {},
-    loadingIds: [],
-  }, false);
+  useChatStore.setState(
+    {
+      activeId: 'test-session-id',
+      messagesMap: {},
+      loadingIds: [],
+    },
+    false,
+  );
 
   vi.spyOn(messageService, 'createMessage').mockResolvedValue('new-message-id');
 
@@ -132,6 +135,7 @@ it('should fetch data', async () => {
 ```
 
 **Key points for SWR:**
+
 - DO NOT mock useSWR - let it use real implementation
 - Only mock service methods (fetchers)
 - Use `waitFor` for async operations

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

@@ -0,0 +1,123 @@
+---
+name: trpc-router
+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
+
+## File Location
+
+- Routers: `src/server/routers/lambda/<domain>.ts`
+- Helpers: `src/server/routers/lambda/_helpers/`
+- Schemas: `src/server/routers/lambda/_schema/`
+
+## Router Structure
+
+### Imports
+
+```typescript
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+
+import { SomeModel } from '@/database/models/some';
+import { authedProcedure, router } from '@/libs/trpc/lambda';
+import { serverDatabase } from '@/libs/trpc/lambda/middleware';
+```
+
+### Middleware: Inject Models into ctx
+
+**Always use middleware to inject models into `ctx`** instead of creating `new Model(ctx.serverDB, ctx.userId)` inside every procedure.
+
+```typescript
+const domainProcedure = authedProcedure.use(serverDatabase).use(async (opts) => {
+  const { ctx } = opts;
+  return opts.next({
+    ctx: {
+      fooModel: new FooModel(ctx.serverDB, ctx.userId),
+      barModel: new BarModel(ctx.serverDB, ctx.userId),
+    },
+  });
+});
+```
+
+Then use `ctx.fooModel` in procedures:
+
+```typescript
+// Good
+const model = ctx.fooModel;
+
+// Bad - don't create models inside procedures
+const model = new FooModel(ctx.serverDB, ctx.userId);
+```
+
+**Exception**: When a model needs a different `userId` (e.g., watchdog iterating over multiple users' tasks), create it inline.
+
+### Procedure Pattern
+
+```typescript
+export const fooRouter = router({
+  // Query
+  find: domainProcedure.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => {
+    try {
+      const item = await ctx.fooModel.findById(input.id);
+      if (!item) throw new TRPCError({ code: 'NOT_FOUND', message: 'Not found' });
+      return { data: item, success: true };
+    } catch (error) {
+      if (error instanceof TRPCError) throw error;
+      console.error('[foo:find]', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to find item',
+      });
+    }
+  }),
+
+  // Mutation
+  create: domainProcedure.input(createSchema).mutation(async ({ input, ctx }) => {
+    try {
+      const item = await ctx.fooModel.create(input);
+      return { data: item, message: 'Created', success: true };
+    } catch (error) {
+      if (error instanceof TRPCError) throw error;
+      console.error('[foo:create]', error);
+      throw new TRPCError({
+        cause: error,
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to create',
+      });
+    }
+  }),
+});
+```
+
+### Aggregated Detail Endpoint
+
+For views that need multiple related data, create a single `detail` procedure that fetches everything in parallel:
+
+```typescript
+detail: domainProcedure.input(idInput).query(async ({ input, ctx }) => {
+  const item = await resolveOrThrow(ctx.fooModel, input.id);
+
+  const [children, related] = await Promise.all([
+    ctx.fooModel.findChildren(item.id),
+    ctx.barModel.findByFooId(item.id),
+  ]);
+
+  return {
+    data: { ...item, children, related },
+    success: true,
+  };
+}),
+```
+
+This avoids the CLI or frontend making N sequential requests.
+
+## Conventions
+
+- Return shape: `{ data, success: true }` for queries, `{ data?, message, success: true }` for mutations
+- Error handling: re-throw `TRPCError`, wrap others with `console.error` + new `TRPCError`
+- Input validation: use `zod` schemas, define at file top
+- Router name: `export const fooRouter = router({ ... })`
+- Procedure names: alphabetical order within the router object
+- Log prefix: `[domain:procedure]` format, e.g. `[task:create]`

.agents/skills/typescript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typescript
-description: TypeScript code style and optimization guidelines. Use when writing TypeScript code (.ts, .tsx, .mts files), reviewing code quality, or implementing type-safe patterns. Triggers on TypeScript development, type safety questions, or code style discussions.
+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
@@ -14,6 +14,9 @@ description: TypeScript code style and optimization guidelines. Use when writing
 - Prefer `as const satisfies XyzInterface` over plain `as const`
 - Prefer `@ts-expect-error` over `@ts-ignore` over `as any`
 - Avoid meaningless null/undefined parameters; design strict function contracts
+- Prefer ES module augmentation (`declare module '...'`) over `namespace`; do not introduce `namespace`-based extension patterns
+- When a type needs extensibility, expose a small mergeable interface at the source type and let each feature/plugin augment it locally instead of centralizing all extension fields in one registry file
+- For package-local extensibility patterns like `PipelineContext.metadata`, define the metadata fields next to the processor/provider/plugin that reads or writes them
 
 ## Async Patterns
 
@@ -22,6 +25,17 @@ description: TypeScript code style and optimization guidelines. Use when writing
 - Use promise-based variants: `import { readFile } from 'fs/promises'`
 - Use `Promise.all`, `Promise.race` for concurrent operations where safe
 
+## 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
 
 - Prefer object destructuring
@@ -50,3 +64,4 @@ description: TypeScript code style and optimization guidelines. Use when writing
 - Never log user private information (API keys, etc.)
 - Don't use `import { log } from 'debug'` directly (logs to console)
 - Use `console.error` in catch blocks instead of debug package
+- Always log the error in `.catch()` callbacks — silent `.catch(() => fallback)` swallows failures and makes debugging impossible

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

@@ -0,0 +1,389 @@
+# Cloud Project Workflow Configuration
+
+This document covers cloud-specific workflow configurations and patterns for the lobehub-cloud project.
+
+## Overview
+
+The lobehub-cloud project extends the open-source lobehub codebase with cloud-specific features. Workflows can be implemented in either:
+
+1. **Lobehub (open-source)** - Available to all users
+2. **Lobehub-cloud (proprietary)** - Cloud-specific business logic
+
+---
+
+## Directory Structure
+
+### Lobehub Submodule (Open-source)
+
+```
+lobehub/
+└── src/
+    ├── app/(backend)/api/workflows/
+    │   ├── memory-user-memory/       # Memory extraction workflows
+    │   └── agent-eval-run/            # Benchmark evaluation workflows
+    └── server/workflows/
+        ├── agentEvalRun/
+        └── ...
+```
+
+### Lobehub-cloud (Proprietary)
+
+```
+lobehub-cloud/
+└── src/
+    ├── app/(backend)/api/workflows/
+    │   ├── welcome-placeholder/       # Cloud-only: AI placeholder generation
+    │   ├── agent-welcome/            # Cloud-only: Agent welcome messages
+    │   ├── agent-eval-run/           # Re-export from lobehub
+    │   └── memory-user-memory/       # Re-export from lobehub
+    └── server/workflows/
+        ├── welcomePlaceholder/
+        ├── agentWelcome/
+        └── agentEvalRun/             # Re-export from lobehub
+```
+
+---
+
+## Cloud-Specific Patterns
+
+### Pattern 1: Cloud-Only Workflows
+
+**Use Case**: Features exclusive to cloud users (AI generation, premium features)
+
+**Example**: `welcome-placeholder`, `agent-welcome`
+
+**Implementation**:
+
+- Implement directly in `lobehub-cloud/src/app/(backend)/api/workflows/`
+- No need for re-exports
+- Can use cloud-specific packages and services
+
+**Structure**:
+
+```
+lobehub-cloud/src/
+├── app/(backend)/api/workflows/
+│   └── feature-name/
+│       ├── process-items/route.ts
+│       ├── paginate-items/route.ts
+│       └── execute-item/route.ts
+└── server/workflows/
+    └── featureName/
+        └── index.ts
+```
+
+---
+
+### Pattern 2: Re-export from Lobehub
+
+**Use Case**: Workflows implemented in open-source but also used in cloud
+
+**Example**: `agent-eval-run`, `memory-user-memory`
+
+**Why Re-export?**
+
+- Cloud deployment needs to serve these endpoints
+- Lobehub submodule code is not directly accessible in cloud routes
+- Allows cloud-specific overrides if needed in the future
+
+#### Re-export Implementation
+
+**Step 1**: Implement workflow in lobehub submodule
+
+```typescript
+// lobehub/src/app/(backend)/api/workflows/feature/layer/route.ts
+import { serve } from '@upstash/workflow/nextjs';
+
+export const { POST } = serve<Payload>(
+  async (context) => {
+    // Implementation
+  },
+  { flowControl: { ... } }
+);
+```
+
+**Step 2**: Create re-export in lobehub-cloud
+
+```typescript
+// lobehub-cloud/src/app/(backend)/api/workflows/feature/layer/route.ts
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature/layer/route';
+```
+
+**Important**: Use `lobehub/src/...` path, NOT `@/...` to avoid circular imports.
+
+#### Re-export Directory Structure
+
+```bash
+# Create directories
+mkdir -p lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-1
+mkdir -p lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-2
+mkdir -p lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-3
+
+# Create re-export files
+echo "export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature-name/layer-1/route';" > \
+  lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-1/route.ts
+
+echo "export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature-name/layer-2/route';" > \
+  lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-2/route.ts
+
+echo "export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature-name/layer-3/route';" > \
+  lobehub-cloud/src/app/(backend)/api/workflows/feature-name/layer-3/route.ts
+```
+
+---
+
+## TypeScript Path Mappings
+
+The cloud project uses tsconfig path mappings to override lobehub code:
+
+```json
+// lobehub-cloud/tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*", "./lobehub/src/*"]
+    }
+  }
+}
+```
+
+**Resolution Order**:
+
+1. `./src/*` (cloud code) - checked first
+2. `./lobehub/src/*` (open-source) - fallback
+
+This allows cloud to override specific modules while using lobehub defaults.
+
+---
+
+## Workflow Class Location
+
+### Cloud-Only Workflows
+
+Place workflow class in cloud:
+
+```
+lobehub-cloud/src/server/workflows/featureName/index.ts
+```
+
+### Shared Workflows
+
+Place workflow class in lobehub, re-export in cloud if needed:
+
+```
+lobehub/src/server/workflows/featureName/index.ts
+```
+
+---
+
+## Environment Variables
+
+Both lobehub and cloud workflows require:
+
+```bash
+# Required for all workflows
+APP_URL=https://your-app.com # Base URL for workflow endpoints
+QSTASH_TOKEN=qstash_xxx      # QStash authentication token
+
+# Optional (for custom QStash URL)
+QSTASH_URL=https://custom-qstash.com # Custom QStash endpoint
+```
+
+**Cloud-Specific**:
+
+```bash
+# Cloud database (for monetization features)
+CLOUD_DATABASE_URL=postgresql://...
+
+# Cloud-specific services
+REDIS_URL=redis://...
+```
+
+---
+
+## Best Practices
+
+### 1. Decide: Cloud or Open-Source?
+
+**Implement in Lobehub if**:
+
+- Feature is useful for all LobeHub users
+- No proprietary business logic
+- Can be open-sourced
+
+**Implement in Cloud if**:
+
+- Premium/paid feature
+- Uses cloud-specific services
+- Contains proprietary algorithms
+
+### 2. Re-export Pattern
+
+✅ **Do**:
+
+```typescript
+// Simple re-export
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature/route';
+```
+
+❌ **Don't**:
+
+```typescript
+// Avoid circular imports with @/ path
+export { POST } from '@/app/(backend)/api/workflows/feature/route'; // ❌
+```
+
+### 3. Keep Workflow Logic in Lobehub
+
+For shared features:
+
+- Implement core logic in `lobehub/` (open-source)
+- Only override if cloud needs different behavior
+- Use re-exports for cloud deployment
+
+### 4. Directory Naming
+
+Follow consistent naming across lobehub and cloud:
+
+```
+# Both should use same structure
+lobehub/src/app/(backend)/api/workflows/feature-name/
+lobehub-cloud/src/app/(backend)/api/workflows/feature-name/
+```
+
+---
+
+## Migration Guide
+
+### Moving Workflow from Cloud to Lobehub
+
+**Step 1**: Copy workflow to lobehub
+
+```bash
+cp -r lobehub-cloud/src/app/(backend)/api/workflows/feature \
+      lobehub/src/app/(backend)/api/workflows/
+```
+
+**Step 2**: Remove cloud-specific dependencies
+
+- Replace cloud services with generic interfaces
+- Remove proprietary business logic
+- Update imports to use lobehub paths
+
+**Step 3**: Create re-exports in cloud
+
+```typescript
+// lobehub-cloud/src/app/(backend)/api/workflows/feature/*/route.ts
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature/*/route';
+```
+
+**Step 4**: Move workflow class to lobehub
+
+```bash
+mv lobehub-cloud/src/server/workflows/feature \
+  lobehub/src/server/workflows/
+```
+
+**Step 5**: Update cloud imports
+
+```typescript
+// Change from
+import { Workflow } from '@/server/workflows/feature';
+
+// To
+import { Workflow } from 'lobehub/src/server/workflows/feature';
+```
+
+---
+
+## Examples
+
+### Cloud-Only Workflow: welcome-placeholder
+
+**Location**: `lobehub-cloud/src/app/(backend)/api/workflows/welcome-placeholder/`
+
+**Why Cloud-Only**: Uses proprietary AI generation service and Redis caching
+
+**Structure**:
+
+```
+lobehub-cloud/
+├── src/app/(backend)/api/workflows/welcome-placeholder/
+│   ├── process-users/route.ts
+│   ├── paginate-users/route.ts
+│   └── generate-user/route.ts
+└── src/server/workflows/welcomePlaceholder/
+    └── index.ts
+```
+
+### Re-exported Workflow: agent-eval-run
+
+**Location**:
+
+- Implementation: `lobehub/src/app/(backend)/api/workflows/agent-eval-run/`
+- Re-export: `lobehub-cloud/src/app/(backend)/api/workflows/agent-eval-run/`
+
+**Why Re-export**: Core feature available in open-source, also used by cloud
+
+**Cloud Re-export Files**:
+
+```typescript
+// lobehub-cloud/src/app/(backend)/api/workflows/agent-eval-run/run-benchmark/route.ts
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/agent-eval-run/run-benchmark/route';
+
+// lobehub-cloud/src/app/(backend)/api/workflows/agent-eval-run/paginate-test-cases/route.ts
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/agent-eval-run/paginate-test-cases/route';
+
+// ... (all layers)
+```
+
+---
+
+## Troubleshooting
+
+### Circular Import Error
+
+**Error**: `Circular definition of import alias 'POST'`
+
+**Cause**: Using `@/` path in re-export within cloud codebase
+
+**Solution**: Use `lobehub/src/` path instead
+
+```typescript
+// ❌ Wrong
+export { POST } from '@/app/(backend)/api/workflows/feature/route';
+
+// ✅ Correct
+export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature/route';
+```
+
+### Workflow Not Found (404)
+
+**Cause**: Missing re-export in cloud
+
+**Solution**: Create re-export files for all workflow layers
+
+```bash
+# Check if re-export exists
+ls lobehub-cloud/src/app/\(backend\)/api/workflows/feature-name/
+
+# If missing, create re-exports
+mkdir -p lobehub-cloud/src/app/\(backend\)/api/workflows/feature-name/layer
+echo "export { POST } from 'lobehub/src/app/(backend)/api/workflows/feature-name/layer/route';" > lobehub-cloud/src/app/\(backend\)/api/workflows/feature-name/layer/route.ts
+```
+
+### Type Errors After Moving to Lobehub
+
+**Cause**: Cloud-specific types or services used in lobehub code
+
+**Solution**:
+
+1. Extract cloud-specific logic to cloud-only wrapper
+2. Use dependency injection for services
+3. Define generic interfaces in lobehub
+
+---
+
+## Related Documentation
+
+- [SKILL.md](../SKILL.md) - Standard workflow patterns

.agents/skills/vercel-react-best-practices/SKILL.md

@@ -1,125 +0,0 @@
----
-name: vercel-react-best-practices
-description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
-license: MIT
-metadata:
-  author: vercel
-  version: "1.0.0"
----
-
-# Vercel React Best Practices
-
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
-
-## When to Apply
-
-Reference these guidelines when:
-- Writing new React components or Next.js pages
-- Implementing data fetching (client or server-side)
-- Reviewing code for performance issues
-- Refactoring existing React/Next.js code
-- Optimizing bundle size or load times
-
-## Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
-
-## Quick Reference
-
-### 1. Eliminating Waterfalls (CRITICAL)
-
-- `async-defer-await` - Move await into branches where actually used
-- `async-parallel` - Use Promise.all() for independent operations
-- `async-dependencies` - Use better-all for partial dependencies
-- `async-api-routes` - Start promises early, await late in API routes
-- `async-suspense-boundaries` - Use Suspense to stream content
-
-### 2. Bundle Size Optimization (CRITICAL)
-
-- `bundle-barrel-imports` - Import directly, avoid barrel files
-- `bundle-dynamic-imports` - Use next/dynamic for heavy components
-- `bundle-defer-third-party` - Load analytics/logging after hydration
-- `bundle-conditional` - Load modules only when feature is activated
-- `bundle-preload` - Preload on hover/focus for perceived speed
-
-### 3. Server-Side Performance (HIGH)
-
-- `server-cache-react` - Use React.cache() for per-request deduplication
-- `server-cache-lru` - Use LRU cache for cross-request caching
-- `server-serialization` - Minimize data passed to client components
-- `server-parallel-fetching` - Restructure components to parallelize fetches
-- `server-after-nonblocking` - Use after() for non-blocking operations
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR for automatic request deduplication
-- `client-event-listeners` - Deduplicate global event listeners
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
-- `rerender-memo` - Extract expensive work into memoized components
-- `rerender-dependencies` - Use primitive dependencies in effects
-- `rerender-derived-state` - Subscribe to derived booleans, not raw values
-- `rerender-functional-setstate` - Use functional setState for stable callbacks
-- `rerender-lazy-state-init` - Pass function to useState for expensive values
-- `rerender-transitions` - Use startTransition for non-urgent updates
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
-- `rendering-content-visibility` - Use content-visibility for long lists
-- `rendering-hoist-jsx` - Extract static JSX outside components
-- `rendering-svg-precision` - Reduce SVG coordinate precision
-- `rendering-hydration-no-flicker` - Use inline script for client-only data
-- `rendering-activity` - Use Activity component for show/hide
-- `rendering-conditional-render` - Use ternary, not && for conditionals
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-batch-dom-css` - Group CSS changes via classes or cssText
-- `js-index-maps` - Build Map for repeated lookups
-- `js-cache-property-access` - Cache object properties in loops
-- `js-cache-function-results` - Cache function results in module-level Map
-- `js-cache-storage` - Cache localStorage/sessionStorage reads
-- `js-combine-iterations` - Combine multiple filter/map into one loop
-- `js-length-check-first` - Check array length before expensive comparison
-- `js-early-exit` - Return early from functions
-- `js-hoist-regexp` - Hoist RegExp creation outside loops
-- `js-min-max-loop` - Use loop for min/max instead of sort
-- `js-set-map-lookups` - Use Set/Map for O(1) lookups
-- `js-tosorted-immutable` - Use toSorted() for immutability
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-event-handler-refs` - Store event handlers in refs
-- `advanced-use-latest` - useLatest for stable callback refs
-
-## How to Use
-
-Read individual rule files for detailed explanations and code examples:
-
-```
-rules/async-parallel.md
-rules/bundle-barrel-imports.md
-rules/_sections.md
-```
-
-Each rule file contains:
-- Brief explanation of why it matters
-- Incorrect code example with explanation
-- Correct code example with explanation
-- Additional context and references
-
-## Full Compiled Document
-
-For the complete guide with all rules expanded: `AGENTS.md`

.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md

@@ -1,55 +0,0 @@
----
-title: Store Event Handlers in Refs
-impact: LOW
-impactDescription: stable subscriptions
-tags: advanced, hooks, refs, event-handlers, optimization
----
-
-## Store Event Handlers in Refs
-
-Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
-
-**Incorrect (re-subscribes on every render):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  useEffect(() => {
-    window.addEventListener(event, handler)
-    return () => window.removeEventListener(event, handler)
-  }, [event, handler])
-}
-```
-
-**Correct (stable subscription):**
-
-```tsx
-function useWindowEvent(event: string, handler: (e) => void) {
-  const handlerRef = useRef(handler)
-  useEffect(() => {
-    handlerRef.current = handler
-  }, [handler])
-
-  useEffect(() => {
-    const listener = (e) => handlerRef.current(e)
-    window.addEventListener(event, listener)
-    return () => window.removeEventListener(event, listener)
-  }, [event])
-}
-```
-
-**Alternative: use `useEffectEvent` if you're on latest React:**
-
-```tsx
-import { useEffectEvent } from 'react'
-
-function useWindowEvent(event: string, handler: (e) => void) {
-  const onEvent = useEffectEvent(handler)
-
-  useEffect(() => {
-    window.addEventListener(event, onEvent)
-    return () => window.removeEventListener(event, onEvent)
-  }, [event])
-}
-```
-
-`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md

@@ -1,49 +0,0 @@
----
-title: useLatest for Stable Callback Refs
-impact: LOW
-impactDescription: prevents effect re-runs
-tags: advanced, hooks, useLatest, refs, optimization
----
-
-## useLatest for Stable Callback Refs
-
-Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
-
-**Implementation:**
-
-```typescript
-function useLatest<T>(value: T) {
-  const ref = useRef(value)
-  useLayoutEffect(() => {
-    ref.current = value
-  }, [value])
-  return ref
-}
-```
-
-**Incorrect (effect re-runs on every callback change):**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearch(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query, onSearch])
-}
-```
-
-**Correct (stable effect, fresh callback):**
-
-```tsx
-function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
-  const [query, setQuery] = useState('')
-  const onSearchRef = useLatest(onSearch)
-
-  useEffect(() => {
-    const timeout = setTimeout(() => onSearchRef.current(query), 300)
-    return () => clearTimeout(timeout)
-  }, [query])
-}
-```

.agents/skills/vercel-react-best-practices/rules/async-api-routes.md

@@ -1,38 +0,0 @@
----
-title: Prevent Waterfall Chains in API Routes
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: api-routes, server-actions, waterfalls, parallelization
----
-
-## Prevent Waterfall Chains in API Routes
-
-In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
-
-**Incorrect (config waits for auth, data waits for both):**
-
-```typescript
-export async function GET(request: Request) {
-  const session = await auth()
-  const config = await fetchConfig()
-  const data = await fetchData(session.user.id)
-  return Response.json({ data, config })
-}
-```
-
-**Correct (auth and config start immediately):**
-
-```typescript
-export async function GET(request: Request) {
-  const sessionPromise = auth()
-  const configPromise = fetchConfig()
-  const session = await sessionPromise
-  const [config, data] = await Promise.all([
-    configPromise,
-    fetchData(session.user.id)
-  ])
-  return Response.json({ data, config })
-}
-```
-
-For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

.agents/skills/vercel-react-best-practices/rules/async-defer-await.md

@@ -1,80 +0,0 @@
----
-title: Defer Await Until Needed
-impact: HIGH
-impactDescription: avoids blocking unused code paths
-tags: async, await, conditional, optimization
----
-
-## Defer Await Until Needed
-
-Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
-
-**Incorrect (blocks both branches):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  const userData = await fetchUserData(userId)
-  
-  if (skipProcessing) {
-    // Returns immediately but still waited for userData
-    return { skipped: true }
-  }
-  
-  // Only this branch uses userData
-  return processUserData(userData)
-}
-```
-
-**Correct (only blocks when needed):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  if (skipProcessing) {
-    // Returns immediately without waiting
-    return { skipped: true }
-  }
-  
-  // Fetch only when needed
-  const userData = await fetchUserData(userId)
-  return processUserData(userData)
-}
-```
-
-**Another example (early return optimization):**
-
-```typescript
-// Incorrect: always fetches permissions
-async function updateResource(resourceId: string, userId: string) {
-  const permissions = await fetchPermissions(userId)
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-
-// Correct: fetches only when needed
-async function updateResource(resourceId: string, userId: string) {
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  const permissions = await fetchPermissions(userId)
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-```
-
-This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.

.agents/skills/vercel-react-best-practices/rules/async-dependencies.md

@@ -1,36 +0,0 @@
----
-title: Dependency-Based Parallelization
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: async, parallelization, dependencies, better-all
----
-
-## Dependency-Based Parallelization
-
-For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
-
-**Incorrect (profile waits for config unnecessarily):**
-
-```typescript
-const [user, config] = await Promise.all([
-  fetchUser(),
-  fetchConfig()
-])
-const profile = await fetchProfile(user.id)
-```
-
-**Correct (config and profile run in parallel):**
-
-```typescript
-import { all } from 'better-all'
-
-const { user, config, profile } = await all({
-  async user() { return fetchUser() },
-  async config() { return fetchConfig() },
-  async profile() {
-    return fetchProfile((await this.$.user).id)
-  }
-})
-```
-
-Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

.agents/skills/vercel-react-best-practices/rules/async-parallel.md

@@ -1,28 +0,0 @@
----
-title: Promise.all() for Independent Operations
-impact: CRITICAL
-impactDescription: 2-10× improvement
-tags: async, parallelization, promises, waterfalls
----
-
-## Promise.all() for Independent Operations
-
-When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
-
-**Incorrect (sequential execution, 3 round trips):**
-
-```typescript
-const user = await fetchUser()
-const posts = await fetchPosts()
-const comments = await fetchComments()
-```
-
-**Correct (parallel execution, 1 round trip):**
-
-```typescript
-const [user, posts, comments] = await Promise.all([
-  fetchUser(),
-  fetchPosts(),
-  fetchComments()
-])
-```

.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md

@@ -1,99 +0,0 @@
----
-title: Strategic Suspense Boundaries
-impact: HIGH
-impactDescription: faster initial paint
-tags: async, suspense, streaming, layout-shift
----
-
-## Strategic Suspense Boundaries
-
-Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
-
-**Incorrect (wrapper blocked by data fetching):**
-
-```tsx
-async function Page() {
-  const data = await fetchData() // Blocks entire page
-  
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <DataDisplay data={data} />
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct (wrapper shows immediately, data streams in):**
-
-```tsx
-function Page() {
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <Suspense fallback={<Skeleton />}>
-          <DataDisplay />
-        </Suspense>
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-
-async function DataDisplay() {
-  const data = await fetchData() // Only blocks this component
-  return <div>{data.content}</div>
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
-
-**Alternative (share promise across components):**
-
-```tsx
-function Page() {
-  // Start fetch immediately, but don't await
-  const dataPromise = fetchData()
-  
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <Suspense fallback={<Skeleton />}>
-        <DataDisplay dataPromise={dataPromise} />
-        <DataSummary dataPromise={dataPromise} />
-      </Suspense>
-      <div>Footer</div>
-    </div>
-  )
-}
-
-function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise) // Unwraps the promise
-  return <div>{data.content}</div>
-}
-
-function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise) // Reuses the same promise
-  return <div>{data.summary}</div>
-}
-```
-
-Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
-
-**When NOT to use this pattern:**
-
-- Critical data needed for layout decisions (affects positioning)
-- SEO-critical content above the fold
-- Small, fast queries where suspense overhead isn't worth it
-- When you want to avoid layout shift (loading → content jump)
-
-**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md

@@ -1,59 +0,0 @@
----
-title: Avoid Barrel File Imports
-impact: CRITICAL
-impactDescription: 200-800ms import cost, slow builds
-tags: bundle, imports, tree-shaking, barrel-files, performance
----
-
-## Avoid Barrel File Imports
-
-Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
-
-Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
-
-**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
-
-**Incorrect (imports entire library):**
-
-```tsx
-import { Check, X, Menu } from 'lucide-react'
-// Loads 1,583 modules, takes ~2.8s extra in dev
-// Runtime cost: 200-800ms on every cold start
-
-import { Button, TextField } from '@mui/material'
-// Loads 2,225 modules, takes ~4.2s extra in dev
-```
-
-**Correct (imports only what you need):**
-
-```tsx
-import Check from 'lucide-react/dist/esm/icons/check'
-import X from 'lucide-react/dist/esm/icons/x'
-import Menu from 'lucide-react/dist/esm/icons/menu'
-// Loads only 3 modules (~2KB vs ~1MB)
-
-import Button from '@mui/material/Button'
-import TextField from '@mui/material/TextField'
-// Loads only what you use
-```
-
-**Alternative (Next.js 13.5+):**
-
-```js
-// next.config.js - use optimizePackageImports
-module.exports = {
-  experimental: {
-    optimizePackageImports: ['lucide-react', '@mui/material']
-  }
-}
-
-// Then you can keep the ergonomic barrel imports:
-import { Check, X, Menu } from 'lucide-react'
-// Automatically transformed to direct imports at build time
-```
-
-Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
-
-Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
-
-Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md

@@ -1,31 +0,0 @@
----
-title: Conditional Module Loading
-impact: HIGH
-impactDescription: loads large data only when needed
-tags: bundle, conditional-loading, lazy-loading
----
-
-## Conditional Module Loading
-
-Load large data or modules only when a feature is activated.
-
-**Example (lazy-load animation frames):**
-
-```tsx
-function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
-  const [frames, setFrames] = useState<Frame[] | null>(null)
-
-  useEffect(() => {
-    if (enabled && !frames && typeof window !== 'undefined') {
-      import('./animation-frames.js')
-        .then(mod => setFrames(mod.frames))
-        .catch(() => setEnabled(false))
-    }
-  }, [enabled, frames, setEnabled])
-
-  if (!frames) return <Skeleton />
-  return <Canvas frames={frames} />
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.

.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md

@@ -1,49 +0,0 @@
----
-title: Defer Non-Critical Third-Party Libraries
-impact: MEDIUM
-impactDescription: loads after hydration
-tags: bundle, third-party, analytics, defer
----
-
-## Defer Non-Critical Third-Party Libraries
-
-Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
-
-**Incorrect (blocks initial bundle):**
-
-```tsx
-import { Analytics } from '@vercel/analytics/react'
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
-  )
-}
-```
-
-**Correct (loads after hydration):**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const Analytics = dynamic(
-  () => import('@vercel/analytics/react').then(m => m.Analytics),
-  { ssr: false }
-)
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
-  )
-}
-```

.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md

@@ -1,35 +0,0 @@
----
-title: Dynamic Imports for Heavy Components
-impact: CRITICAL
-impactDescription: directly affects TTI and LCP
-tags: bundle, dynamic-import, code-splitting, next-dynamic
----
-
-## Dynamic Imports for Heavy Components
-
-Use `next/dynamic` to lazy-load large components not needed on initial render.
-
-**Incorrect (Monaco bundles with main chunk ~300KB):**
-
-```tsx
-import { MonacoEditor } from './monaco-editor'
-
-function CodePanel({ code }: { code: string }) {
-  return <MonacoEditor value={code} />
-}
-```
-
-**Correct (Monaco loads on demand):**
-
-```tsx
-import dynamic from 'next/dynamic'
-
-const MonacoEditor = dynamic(
-  () => import('./monaco-editor').then(m => m.MonacoEditor),
-  { ssr: false }
-)
-
-function CodePanel({ code }: { code: string }) {
-  return <MonacoEditor value={code} />
-}
-```

.agents/skills/vercel-react-best-practices/rules/bundle-preload.md

@@ -1,50 +0,0 @@
----
-title: Preload Based on User Intent
-impact: MEDIUM
-impactDescription: reduces perceived latency
-tags: bundle, preload, user-intent, hover
----
-
-## Preload Based on User Intent
-
-Preload heavy bundles before they're needed to reduce perceived latency.
-
-**Example (preload on hover/focus):**
-
-```tsx
-function EditorButton({ onClick }: { onClick: () => void }) {
-  const preload = () => {
-    if (typeof window !== 'undefined') {
-      void import('./monaco-editor')
-    }
-  }
-
-  return (
-    <button
-      onMouseEnter={preload}
-      onFocus={preload}
-      onClick={onClick}
-    >
-      Open Editor
-    </button>
-  )
-}
-```
-
-**Example (preload when feature flag is enabled):**
-
-```tsx
-function FlagsProvider({ children, flags }: Props) {
-  useEffect(() => {
-    if (flags.editorEnabled && typeof window !== 'undefined') {
-      void import('./monaco-editor').then(mod => mod.init())
-    }
-  }, [flags.editorEnabled])
-
-  return <FlagsContext.Provider value={flags}>
-    {children}
-  </FlagsContext.Provider>
-}
-```
-
-The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md

@@ -1,74 +0,0 @@
----
-title: Deduplicate Global Event Listeners
-impact: LOW
-impactDescription: single listener for N components
-tags: client, swr, event-listeners, subscription
----
-
-## Deduplicate Global Event Listeners
-
-Use `useSWRSubscription()` to share global event listeners across component instances.
-
-**Incorrect (N instances = N listeners):**
-
-```tsx
-function useKeyboardShortcut(key: string, callback: () => void) {
-  useEffect(() => {
-    const handler = (e: KeyboardEvent) => {
-      if (e.metaKey && e.key === key) {
-        callback()
-      }
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  }, [key, callback])
-}
-```
-
-When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
-
-**Correct (N instances = 1 listener):**
-
-```tsx
-import useSWRSubscription from 'swr/subscription'
-
-// Module-level Map to track callbacks per key
-const keyCallbacks = new Map<string, Set<() => void>>()
-
-function useKeyboardShortcut(key: string, callback: () => void) {
-  // Register this callback in the Map
-  useEffect(() => {
-    if (!keyCallbacks.has(key)) {
-      keyCallbacks.set(key, new Set())
-    }
-    keyCallbacks.get(key)!.add(callback)
-
-    return () => {
-      const set = keyCallbacks.get(key)
-      if (set) {
-        set.delete(callback)
-        if (set.size === 0) {
-          keyCallbacks.delete(key)
-        }
-      }
-    }
-  }, [key, callback])
-
-  useSWRSubscription('global-keydown', () => {
-    const handler = (e: KeyboardEvent) => {
-      if (e.metaKey && keyCallbacks.has(e.key)) {
-        keyCallbacks.get(e.key)!.forEach(cb => cb())
-      }
-    }
-    window.addEventListener('keydown', handler)
-    return () => window.removeEventListener('keydown', handler)
-  })
-}
-
-function Profile() {
-  // Multiple shortcuts will share the same listener
-  useKeyboardShortcut('p', () => { /* ... */ }) 
-  useKeyboardShortcut('k', () => { /* ... */ })
-  // ...
-}
-```

.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md

@@ -1,71 +0,0 @@
----
-title: Version and Minimize localStorage Data
-impact: MEDIUM
-impactDescription: prevents schema conflicts, reduces storage size
-tags: client, localStorage, storage, versioning, data-minimization
----
-
-## Version and Minimize localStorage Data
-
-Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
-
-**Incorrect:**
-
-```typescript
-// No version, stores everything, no error handling
-localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
-const data = localStorage.getItem('userConfig')
-```
-
-**Correct:**
-
-```typescript
-const VERSION = 'v2'
-
-function saveConfig(config: { theme: string; language: string }) {
-  try {
-    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
-  } catch {
-    // Throws in incognito/private browsing, quota exceeded, or disabled
-  }
-}
-
-function loadConfig() {
-  try {
-    const data = localStorage.getItem(`userConfig:${VERSION}`)
-    return data ? JSON.parse(data) : null
-  } catch {
-    return null
-  }
-}
-
-// Migration from v1 to v2
-function migrate() {
-  try {
-    const v1 = localStorage.getItem('userConfig:v1')
-    if (v1) {
-      const old = JSON.parse(v1)
-      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
-      localStorage.removeItem('userConfig:v1')
-    }
-  } catch {}
-}
-```
-
-**Store minimal fields from server responses:**
-
-```typescript
-// User object has 20+ fields, only store what UI needs
-function cachePrefs(user: FullUser) {
-  try {
-    localStorage.setItem('prefs:v1', JSON.stringify({
-      theme: user.preferences.theme,
-      notifications: user.preferences.notifications
-    }))
-  } catch {}
-}
-```
-
-**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
-
-**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.

.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md

@@ -1,48 +0,0 @@
----
-title: Use Passive Event Listeners for Scrolling Performance
-impact: MEDIUM
-impactDescription: eliminates scroll delay caused by event listeners
-tags: client, event-listeners, scrolling, performance, touch, wheel
----
-
-## Use Passive Event Listeners for Scrolling Performance
-
-Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
-
-**Incorrect:**
-
-```typescript
-useEffect(() => {
-  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
-  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-  
-  document.addEventListener('touchstart', handleTouch)
-  document.addEventListener('wheel', handleWheel)
-  
-  return () => {
-    document.removeEventListener('touchstart', handleTouch)
-    document.removeEventListener('wheel', handleWheel)
-  }
-}, [])
-```
-
-**Correct:**
-
-```typescript
-useEffect(() => {
-  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
-  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
-  
-  document.addEventListener('touchstart', handleTouch, { passive: true })
-  document.addEventListener('wheel', handleWheel, { passive: true })
-  
-  return () => {
-    document.removeEventListener('touchstart', handleTouch)
-    document.removeEventListener('wheel', handleWheel)
-  }
-}, [])
-```
-
-**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
-
-**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.

.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md

@@ -1,56 +0,0 @@
----
-title: Use SWR for Automatic Deduplication
-impact: MEDIUM-HIGH
-impactDescription: automatic deduplication
-tags: client, swr, deduplication, data-fetching
----
-
-## Use SWR for Automatic Deduplication
-
-SWR enables request deduplication, caching, and revalidation across component instances.
-
-**Incorrect (no deduplication, each instance fetches):**
-
-```tsx
-function UserList() {
-  const [users, setUsers] = useState([])
-  useEffect(() => {
-    fetch('/api/users')
-      .then(r => r.json())
-      .then(setUsers)
-  }, [])
-}
-```
-
-**Correct (multiple instances share one request):**
-
-```tsx
-import useSWR from 'swr'
-
-function UserList() {
-  const { data: users } = useSWR('/api/users', fetcher)
-}
-```
-
-**For immutable data:**
-
-```tsx
-import { useImmutableSWR } from '@/lib/swr'
-
-function StaticContent() {
-  const { data } = useImmutableSWR('/api/config', fetcher)
-}
-```
-
-**For mutations:**
-
-```tsx
-import { useSWRMutation } from 'swr/mutation'
-
-function UpdateButton() {
-  const { trigger } = useSWRMutation('/api/user', updateUser)
-  return <button onClick={() => trigger()}>Update</button>
-}
-```
-
-Reference: [https://swr.vercel.app](https://swr.vercel.app)

.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md

@@ -1,57 +0,0 @@
----
-title: Batch DOM CSS Changes
-impact: MEDIUM
-impactDescription: reduces reflows/repaints
-tags: javascript, dom, css, performance, reflow
----
-
-## Batch DOM CSS Changes
-
-Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
-
-**Incorrect (interleaved reads and writes force reflows):**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
-  element.style.width = '100px'
-  const width = element.offsetWidth  // Forces reflow
-  element.style.height = '200px'
-  const height = element.offsetHeight  // Forces another reflow
-}
-```
-
-**Correct (batch writes, then read once):**
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
-  // Batch all writes together
-  element.style.width = '100px'
-  element.style.height = '200px'
-  element.style.backgroundColor = 'blue'
-  element.style.border = '1px solid black'
-  
-  // Read after all writes are done (single reflow)
-  const { width, height } = element.getBoundingClientRect()
-}
-```
-
-**Better: use CSS classes**
-
-```css
-.highlighted-box {
-  width: 100px;
-  height: 200px;
-  background-color: blue;
-  border: 1px solid black;
-}
-```
-
-```typescript
-function updateElementStyles(element: HTMLElement) {
-  element.classList.add('highlighted-box')
-
-  const { width, height } = element.getBoundingClientRect()
-}
-```
-
-Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.

.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md

@@ -1,80 +0,0 @@
----
-title: Cache Repeated Function Calls
-impact: MEDIUM
-impactDescription: avoid redundant computation
-tags: javascript, cache, memoization, performance
----
-
-## Cache Repeated Function Calls
-
-Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
-
-**Incorrect (redundant computation):**
-
-```typescript
-function ProjectList({ projects }: { projects: Project[] }) {
-  return (
-    <div>
-      {projects.map(project => {
-        // slugify() called 100+ times for same project names
-        const slug = slugify(project.name)
-        
-        return <ProjectCard key={project.id} slug={slug} />
-      })}
-    </div>
-  )
-}
-```
-
-**Correct (cached results):**
-
-```typescript
-// Module-level cache
-const slugifyCache = new Map<string, string>()
-
-function cachedSlugify(text: string): string {
-  if (slugifyCache.has(text)) {
-    return slugifyCache.get(text)!
-  }
-  const result = slugify(text)
-  slugifyCache.set(text, result)
-  return result
-}
-
-function ProjectList({ projects }: { projects: Project[] }) {
-  return (
-    <div>
-      {projects.map(project => {
-        // Computed only once per unique project name
-        const slug = cachedSlugify(project.name)
-        
-        return <ProjectCard key={project.id} slug={slug} />
-      })}
-    </div>
-  )
-}
-```
-
-**Simpler pattern for single-value functions:**
-
-```typescript
-let isLoggedInCache: boolean | null = null
-
-function isLoggedIn(): boolean {
-  if (isLoggedInCache !== null) {
-    return isLoggedInCache
-  }
-  
-  isLoggedInCache = document.cookie.includes('auth=')
-  return isLoggedInCache
-}
-
-// Clear cache when auth changes
-function onAuthChange() {
-  isLoggedInCache = null
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md

@@ -1,28 +0,0 @@
----
-title: Cache Property Access in Loops
-impact: LOW-MEDIUM
-impactDescription: reduces lookups
-tags: javascript, loops, optimization, caching
----
-
-## Cache Property Access in Loops
-
-Cache object property lookups in hot paths.
-
-**Incorrect (3 lookups × N iterations):**
-
-```typescript
-for (let i = 0; i < arr.length; i++) {
-  process(obj.config.settings.value)
-}
-```
-
-**Correct (1 lookup total):**
-
-```typescript
-const value = obj.config.settings.value
-const len = arr.length
-for (let i = 0; i < len; i++) {
-  process(value)
-}
-```

.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md

@@ -1,70 +0,0 @@
----
-title: Cache Storage API Calls
-impact: LOW-MEDIUM
-impactDescription: reduces expensive I/O
-tags: javascript, localStorage, storage, caching, performance
----
-
-## Cache Storage API Calls
-
-`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
-
-**Incorrect (reads storage on every call):**
-
-```typescript
-function getTheme() {
-  return localStorage.getItem('theme') ?? 'light'
-}
-// Called 10 times = 10 storage reads
-```
-
-**Correct (Map cache):**
-
-```typescript
-const storageCache = new Map<string, string | null>()
-
-function getLocalStorage(key: string) {
-  if (!storageCache.has(key)) {
-    storageCache.set(key, localStorage.getItem(key))
-  }
-  return storageCache.get(key)
-}
-
-function setLocalStorage(key: string, value: string) {
-  localStorage.setItem(key, value)
-  storageCache.set(key, value)  // keep cache in sync
-}
-```
-
-Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
-
-**Cookie caching:**
-
-```typescript
-let cookieCache: Record<string, string> | null = null
-
-function getCookie(name: string) {
-  if (!cookieCache) {
-    cookieCache = Object.fromEntries(
-      document.cookie.split('; ').map(c => c.split('='))
-    )
-  }
-  return cookieCache[name]
-}
-```
-
-**Important (invalidate on external changes):**
-
-If storage can change externally (another tab, server-set cookies), invalidate cache:
-
-```typescript
-window.addEventListener('storage', (e) => {
-  if (e.key) storageCache.delete(e.key)
-})
-
-document.addEventListener('visibilitychange', () => {
-  if (document.visibilityState === 'visible') {
-    storageCache.clear()
-  }
-})
-```

.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md

@@ -1,32 +0,0 @@
----
-title: Combine Multiple Array Iterations
-impact: LOW-MEDIUM
-impactDescription: reduces iterations
-tags: javascript, arrays, loops, performance
----
-
-## Combine Multiple Array Iterations
-
-Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
-
-**Incorrect (3 iterations):**
-
-```typescript
-const admins = users.filter(u => u.isAdmin)
-const testers = users.filter(u => u.isTester)
-const inactive = users.filter(u => !u.isActive)
-```
-
-**Correct (1 iteration):**
-
-```typescript
-const admins: User[] = []
-const testers: User[] = []
-const inactive: User[] = []
-
-for (const user of users) {
-  if (user.isAdmin) admins.push(user)
-  if (user.isTester) testers.push(user)
-  if (!user.isActive) inactive.push(user)
-}
-```

.agents/skills/vercel-react-best-practices/rules/js-early-exit.md

@@ -1,50 +0,0 @@
----
-title: Early Return from Functions
-impact: LOW-MEDIUM
-impactDescription: avoids unnecessary computation
-tags: javascript, functions, optimization, early-return
----
-
-## Early Return from Functions
-
-Return early when result is determined to skip unnecessary processing.
-
-**Incorrect (processes all items even after finding answer):**
-
-```typescript
-function validateUsers(users: User[]) {
-  let hasError = false
-  let errorMessage = ''
-  
-  for (const user of users) {
-    if (!user.email) {
-      hasError = true
-      errorMessage = 'Email required'
-    }
-    if (!user.name) {
-      hasError = true
-      errorMessage = 'Name required'
-    }
-    // Continues checking all users even after error found
-  }
-  
-  return hasError ? { valid: false, error: errorMessage } : { valid: true }
-}
-```
-
-**Correct (returns immediately on first error):**
-
-```typescript
-function validateUsers(users: User[]) {
-  for (const user of users) {
-    if (!user.email) {
-      return { valid: false, error: 'Email required' }
-    }
-    if (!user.name) {
-      return { valid: false, error: 'Name required' }
-    }
-  }
-
-  return { valid: true }
-}
-```

.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md

@@ -1,45 +0,0 @@
----
-title: Hoist RegExp Creation
-impact: LOW-MEDIUM
-impactDescription: avoids recreation
-tags: javascript, regexp, optimization, memoization
----
-
-## Hoist RegExp Creation
-
-Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
-
-**Incorrect (new RegExp every render):**
-
-```tsx
-function Highlighter({ text, query }: Props) {
-  const regex = new RegExp(`(${query})`, 'gi')
-  const parts = text.split(regex)
-  return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Correct (memoize or hoist):**
-
-```tsx
-const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
-
-function Highlighter({ text, query }: Props) {
-  const regex = useMemo(
-    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
-    [query]
-  )
-  const parts = text.split(regex)
-  return <>{parts.map((part, i) => ...)}</>
-}
-```
-
-**Warning (global regex has mutable state):**
-
-Global regex (`/g`) has mutable `lastIndex` state:
-
-```typescript
-const regex = /foo/g
-regex.test('foo')  // true, lastIndex = 3
-regex.test('foo')  // false, lastIndex = 0
-```

.agents/skills/vercel-react-best-practices/rules/js-index-maps.md

@@ -1,37 +0,0 @@
----
-title: Build Index Maps for Repeated Lookups
-impact: LOW-MEDIUM
-impactDescription: 1M ops to 2K ops
-tags: javascript, map, indexing, optimization, performance
----
-
-## Build Index Maps for Repeated Lookups
-
-Multiple `.find()` calls by the same key should use a Map.
-
-**Incorrect (O(n) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
-  return orders.map(order => ({
-    ...order,
-    user: users.find(u => u.id === order.userId)
-  }))
-}
-```
-
-**Correct (O(1) per lookup):**
-
-```typescript
-function processOrders(orders: Order[], users: User[]) {
-  const userById = new Map(users.map(u => [u.id, u]))
-
-  return orders.map(order => ({
-    ...order,
-    user: userById.get(order.userId)
-  }))
-}
-```
-
-Build map once (O(n)), then all lookups are O(1).
-For 1000 orders × 1000 users: 1M ops → 2K ops.

.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md

@@ -1,49 +0,0 @@
----
-title: Early Length Check for Array Comparisons
-impact: MEDIUM-HIGH
-impactDescription: avoids expensive operations when lengths differ
-tags: javascript, arrays, performance, optimization, comparison
----
-
-## Early Length Check for Array Comparisons
-
-When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
-
-In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
-
-**Incorrect (always runs expensive comparison):**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
-  // Always sorts and joins, even when lengths differ
-  return current.sort().join() !== original.sort().join()
-}
-```
-
-Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
-
-**Correct (O(1) length check first):**
-
-```typescript
-function hasChanges(current: string[], original: string[]) {
-  // Early return if lengths differ
-  if (current.length !== original.length) {
-    return true
-  }
-  // Only sort when lengths match
-  const currentSorted = current.toSorted()
-  const originalSorted = original.toSorted()
-  for (let i = 0; i < currentSorted.length; i++) {
-    if (currentSorted[i] !== originalSorted[i]) {
-      return true
-    }
-  }
-  return false
-}
-```
-
-This new approach is more efficient because:
-- It avoids the overhead of sorting and joining the arrays when lengths differ
-- It avoids consuming memory for the joined strings (especially important for large arrays)
-- It avoids mutating the original arrays
-- It returns early when a difference is found

.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md

@@ -1,82 +0,0 @@
----
-title: Use Loop for Min/Max Instead of Sort
-impact: LOW
-impactDescription: O(n) instead of O(n log n)
-tags: javascript, arrays, performance, sorting, algorithms
----
-
-## Use Loop for Min/Max Instead of Sort
-
-Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
-
-**Incorrect (O(n log n) - sort to find latest):**
-
-```typescript
-interface Project {
-  id: string
-  name: string
-  updatedAt: number
-}
-
-function getLatestProject(projects: Project[]) {
-  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
-  return sorted[0]
-}
-```
-
-Sorts the entire array just to find the maximum value.
-
-**Incorrect (O(n log n) - sort for oldest and newest):**
-
-```typescript
-function getOldestAndNewest(projects: Project[]) {
-  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
-  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
-}
-```
-
-Still sorts unnecessarily when only min/max are needed.
-
-**Correct (O(n) - single loop):**
-
-```typescript
-function getLatestProject(projects: Project[]) {
-  if (projects.length === 0) return null
-  
-  let latest = projects[0]
-  
-  for (let i = 1; i < projects.length; i++) {
-    if (projects[i].updatedAt > latest.updatedAt) {
-      latest = projects[i]
-    }
-  }
-  
-  return latest
-}
-
-function getOldestAndNewest(projects: Project[]) {
-  if (projects.length === 0) return { oldest: null, newest: null }
-  
-  let oldest = projects[0]
-  let newest = projects[0]
-  
-  for (let i = 1; i < projects.length; i++) {
-    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
-    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
-  }
-  
-  return { oldest, newest }
-}
-```
-
-Single pass through the array, no copying, no sorting.
-
-**Alternative (Math.min/Math.max for small arrays):**
-
-```typescript
-const numbers = [5, 2, 8, 1, 9]
-const min = Math.min(...numbers)
-const max = Math.max(...numbers)
-```
-
-This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.

.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md

@@ -1,24 +0,0 @@
----
-title: Use Set/Map for O(1) Lookups
-impact: LOW-MEDIUM
-impactDescription: O(n) to O(1)
-tags: javascript, set, map, data-structures, performance
----
-
-## Use Set/Map for O(1) Lookups
-
-Convert arrays to Set/Map for repeated membership checks.
-
-**Incorrect (O(n) per check):**
-
-```typescript
-const allowedIds = ['a', 'b', 'c', ...]
-items.filter(item => allowedIds.includes(item.id))
-```
-
-**Correct (O(1) per check):**
-
-```typescript
-const allowedIds = new Set(['a', 'b', 'c', ...])
-items.filter(item => allowedIds.has(item.id))
-```

.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md

@@ -1,57 +0,0 @@
----
-title: Use toSorted() Instead of sort() for Immutability
-impact: MEDIUM-HIGH
-impactDescription: prevents mutation bugs in React state
-tags: javascript, arrays, immutability, react, state, mutation
----
-
-## Use toSorted() Instead of sort() for Immutability
-
-`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
-
-**Incorrect (mutates original array):**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
-  // Mutates the users prop array!
-  const sorted = useMemo(
-    () => users.sort((a, b) => a.name.localeCompare(b.name)),
-    [users]
-  )
-  return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Correct (creates new array):**
-
-```typescript
-function UserList({ users }: { users: User[] }) {
-  // Creates new sorted array, original unchanged
-  const sorted = useMemo(
-    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
-    [users]
-  )
-  return <div>{sorted.map(renderUser)}</div>
-}
-```
-
-**Why this matters in React:**
-
-1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
-2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
-
-**Browser support (fallback for older browsers):**
-
-`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
-
-```typescript
-// Fallback for older browsers
-const sorted = [...items].sort((a, b) => a.value - b.value)
-```
-
-**Other immutable array methods:**
-
-- `.toSorted()` - immutable sort
-- `.toReversed()` - immutable reverse
-- `.toSpliced()` - immutable splice
-- `.with()` - immutable element replacement