fix benchmark table issue

* init plan

* 📝 docs: update SPA plan for dev mode Worker cross-origin handling

- Clarified the handling of Worker cross-origin issues in dev mode, emphasizing the need for `workerPatch` to wrap cross-origin URLs as blob URLs.
- Enhanced the explanation of the dev mode's resource URL rewriting process for better understanding.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: Phase 1 - 环境变量整治

- Fix Pyodide env var mismatch (NEXT_PUBLIC_PYPI_INDEX_URL → pythonEnv.NEXT_PUBLIC_PYODIDE_PIP_INDEX_URL)
- Consolidate python.ts to use pythonEnv instead of direct process.env
- Remove NEXT_PUBLIC_ prefix from server-side MARKET_BASE_URL (5 files)

* 🏗️ chore: Phase 2 - Vite 工程搭建

- Add vite.config.ts with dual build (desktop/mobile via MOBILE env)
- Add index.html SPA template with __SERVER_CONFIG__ placeholder
- Add entry.desktop.tsx and entry.mobile.tsx SPA entry points
- Add dev:spa, dev:spa:mobile, build:spa, build:spa:copy scripts
- Install @vitejs/plugin-react and linkedom

* ♻️ refactor: Phase 3 - 第一方包 Next.js 解耦

- Replace next/link with <a> in builtin-tool-web-browsing (4 files, external links)
- Replace next/image with <img> in builtin-tool-agent-builder/InstallPlugin.tsx
- Add Vite import.meta.env compat for isDesktop in const/version.ts, builtin-tool-gtd, builtin-tool-group-management

* ♻️ refactor: Phase 4a - Auth 页面改用直接 next/navigation 和 next/link

- 9 auth files: @/libs/next/navigation → next/navigation
- 5 auth files: @/libs/next/Link → next/link
- Auth pages remain in Next.js App Router, need direct Next.js imports

* ♻️ refactor: Phase 4b - Next.js 抽象层替换为 react-router-dom/vanilla React

- navigation.ts: useRouter/usePathname/useSearchParams/useParams → react-router-dom
- navigation.ts: redirect/notFound → custom error throws
- navigation.ts: useServerInsertedHTML → no-op for SPA
- Link.tsx: next/link → react-router-dom Link adapter (href→to, external→<a>)
- Image.tsx: next/image → <img> wrapper with fill/style support
- dynamic.tsx: next/dynamic → React.lazy + Suspense wrapper

* ✨ feat: Phase 5 - 新建 SPAGlobalProvider

- Create SPAServerConfig type (analyticsConfig, clientEnv, theme, featureFlags, locale)
- Add window.__SERVER_CONFIG__ and __MOBILE__ to global.d.ts
- Create SPAGlobalProvider (client-only Provider tree mirroring GlobalProvider)
- Includes AuthProvider for user session support
- Update entry.desktop.tsx and entry.mobile.tsx to wrap with SPAGlobalProvider

* ♻️ refactor: add SPA catch-all route handler with Vite dev proxy

- Create (spa)/[[...path]]/route.ts for serving SPA HTML
- Dev mode: proxy Vite dev server, rewrite asset URLs, inject Worker patch
- Prod mode: read pre-built HTML templates
- Build SPAServerConfig with analytics, theme, clientEnv, featureFlags
- Update middleware to pass SPA routes through to catch-all

* ♻️ refactor: skip auth checks for SPA routes in middleware

SPA pages are all public (no sensitive data in HTML).
Auth is handled client-side by SPAGlobalProvider's AuthProvider.
Only Next.js auth routes and API endpoints go through session checks.

* ♻️ refactor: replace Next.js-specific analytics with vanilla JS

- Google.tsx: replace @next/third-parties/google with direct gtag script
- ReactScan.tsx: replace react-scan/monitoring/next with generic script
- Desktop.tsx: replace next/script with native script injection

* ♻️ refactor: migrate @t3-oss/env-nextjs to @t3-oss/env-core

Replace framework-specific env validation with framework-agnostic version.
Add clientPrefix where client schemas exist.

* ♻️ refactor: replace next-mdx-remote/rsc with react-markdown

Use client-side react-markdown for MDX rendering instead of
Next.js RSC-dependent next-mdx-remote.

* 🔧 chore: update build scripts and Dockerfile for SPA integration

- build:docker now includes SPA build + copy steps
- dev defaults to Vite SPA, dev:next for Next.js backend
- Dockerfile copies public/spa/ assets for production
- Add public/spa/ to .gitignore (build artifact)

* 🗑️ chore: remove old Next.js route segment files and serwist PWA

- Delete [variants] page.tsx, error.tsx, not-found.tsx, loading.tsx
- Delete root loading.tsx and empty [[...path]] directory
- Delete unused loaders directory
- Remove @serwist/next PWA wrapper from Next.js config

* plan2

* ✨ feat: add locale detection script to index.html for SPA dev mode

* ♻️ refactor: remove locale and theme from SPAServerConfig

* ✨ feat: add [locale] segment with force-static and SEO meta generation

* ♻️ refactor: remove theme/locale reads from SPAGlobalProvider

* ✨ feat: set vite base to /spa/ for production builds

* ✨ feat: auto-generate spaHtmlTemplates from vite build output

* 🔧 chore: register dev:next task in turbo.json for parallel dev startup

* ♻️ refactor: rename (spa) route group to spa segment, rewrite SPA routes via middleware

* ✨ feat: add Vite-compatible i18n/locale modules with import.meta.glob and resolve aliases

* 🔧 fix: use custom Vite plugin for module redirects instead of resolve.alias

* very important

* build

* 🔧 chore: update build scripts and clean up Vite configuration by removing unused plugin and code

Signed-off-by: Innei <tukon479@gmail.com>

* 🗑️ refactor: remove all electron modifier scripts

Modifiers are no longer needed with Vite SPA renderer build.

* ✨ feat: add Vite renderer entry to electron-vite config

Add renderer build configuration to electron-vite, replacing the old
Next.js shadow workspace build flow. Delete buildNextApp.mts and
moveNextExports.ts, update package.json scripts accordingly.

* ✨ feat: add .desktop suffix files for eager i18n loading

Create 4 .desktop files that use import.meta.glob({ eager: true })
for synchronous locale access in Electron desktop builds, replacing
the async lazy-loading used in web SPA builds.

* 🔧 refactor: adapt Electron main process for Vite renderer

Replace nextExportDir with rendererDir, update protocol from
app://next to app://renderer, simplify file resolution to SPA
fallback pattern, update _next/ asset paths to /assets/.

* 🔧 chore: update electron-builder files config for Vite renderer

Replace dist/next references with dist/renderer, remove Next.js
specific exclusion rules no longer applicable to Vite output.

* 🗑️ chore: remove @ast-grep/napi dependency

No longer needed after removing electron modifier scripts.

* 🔧 refactor: unify isDesktop to __ELECTRON__ compile-time constant

Remove NEXT_PUBLIC_IS_DESKTOP_APP and VITE_IS_DESKTOP_APP env vars.
Unify isDesktop in @lobechat/const using __ELECTRON__ defined by Vite.
Re-export from builtin-tool packages. Scripts use DESKTOP_BUILD.

* update

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: use electron-vite ELECTRON_RENDERER_URL instead of hardcoded port 3015

Replace hardcoded http://localhost:3015 with process.env.ELECTRON_RENDERER_URL
injected by electron-vite dev server. Clean up stale Next.js references.

* 🐛 fix: use local renderer-entry shim to resolve Vite root path issue

HTML entry ../../src/entry.desktop.tsx resolves to /src/entry.desktop.tsx
in URL space, which Vite cannot find within apps/desktop/ root. Add a
local shim that imports across root via module resolver instead.

* 🔧 refactor: extract shared renderer Vite config into sharedRendererConfig

Deduplicate plugins (nodeModuleStub, platformResolve, tsconfigPaths) and
define (__MOBILE__, __ELECTRON__, process.env) between root vite.config.ts
and electron.vite.config.ts renderer section.

* 🔧 refactor: move all renderer plugins and optimizeDeps into shared config

sharedRendererPlugins now includes react, codeInspectorPlugin alongside
nodeModuleStub, platformResolve, tsconfigPaths. Add sharedOptimizeDeps
for pre-bundling list. Both root and electron configs consume shared only.

* 🐛 fix: set electron renderer root to monorepo root for correct glob resolution

import.meta.glob with absolute paths (e.g. /node_modules/antd/...) resolved
within apps/desktop/ instead of monorepo root. Change renderer root to ROOT_DIR,
add electronDesktopHtmlPlugin middleware to rewrite / to /apps/desktop/index.html,
and remove the now-unnecessary renderer-entry.ts shim.

* desktop vite !!

Signed-off-by: Innei <tukon479@gmail.com>

* sync import !!

Signed-off-by: Innei <tukon479@gmail.com>

* clean ci!!

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: update SPA path structure and clean up dependencies

- Changed the path in .gitignore and related files from [locale] to [variants] for SPA templates.
- Updated index.html to set body height to 100%.
- Cleaned up package.json by removing unused dependencies and reorganizing devDependencies.
- Refactored RendererUrlManager to use a constant for SPA entry HTML path.
- Removed obsolete route.ts file from the SPA structure.
- Adjusted proxy configuration to reflect the new SPA path structure.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: update build script to include mobile SPA build

- Modified the build script in package.json to add the mobile SPA build step.
- Ensured the build process accommodates both desktop and mobile SPA versions.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: update build scripts and improve file encoding consistency

- Modified the build script in package.json to ensure the SPA copy step runs after the build.
- Updated file encoding in generateSpaTemplates.mts from 'utf-8' to 'utf8' for consistency.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 fix: correct Blob import syntax and update global server config type

- Fixed the Blob import syntax in route.ts to ensure proper module loading.
- Updated the global server configuration type in global.d.ts for improved type safety.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 test: update RendererUrlManager test to reflect new file path

- Modified the mock implementation in RendererUrlManager.test.ts to check for the updated file path '/mock/export/out/apps/desktop/index.html'.
- Adjusted the expected resolved path in the test to match the new structure.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: remove catch-all example file and update imports

- Deleted the catch-all example file `catch-all.eg.ts` to streamline the codebase.
- Updated import paths in `ClientResponsiveLayout.tsx` and `ClientResponsiveContent/index.tsx` to use the new dynamic import location.
- Added type declarations for HTML templates in `spaHtmlTemplates.d.ts`.
- Adjusted `tsconfig.json` to include the updated file structure.
- Enhanced type definitions in `global.d.ts` and fixed locale loading in `locale.vite.ts`.

Signed-off-by: Innei <tukon479@gmail.com>

* e2e

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: remove unused build script for Vercel deployment

- Deleted the `build:vercel` script from package.json to streamline the build process.
- Ensured the remaining build scripts are organized and relevant.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 config: update Vite build input for mobile support

- Changed the build input path in vite.config.ts to conditionally use 'index.mobile.html' for mobile builds, enhancing support for mobile SPA versions.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 feat: add compatibility checks for import maps and cascade layers

- Implemented functions to check for browser support of import maps and CSS cascade layers.
- Redirected users to a compatibility page if their browser does not support the required features.
- Updated the build script in package.json to use the experimental analyze command for better performance.

Signed-off-by: Innei <tukon479@gmail.com>

* chore: rename

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 feat: refactor authentication layout and introduce global providers

- Created a new `RootLayout` component to streamline the layout structure.
- Removed the old layout file for variants and integrated necessary features into the new layout.
- Added `AuthGlobalProvider` to manage authentication context and server configurations.
- Introduced language and theme selection components for enhanced user experience.
- Updated various components to utilize the new context and improve modularity.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 config: exclude build artifacts from serverless functions

- Updated the `next.config.ts` to exclude SPA, desktop, and mobile build artifacts from serverless functions.
- Added paths for `public/spa/**`, `dist/**`, `apps/desktop/build/**`, and `packages/database/migrations/**` to the exclusion list.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 config: refine exclusion of build artifacts from serverless functions

- Updated `next.config.ts` to specify exclusion paths for desktop and mobile build artifacts.
- Changed exclusions from `dist/**` and `apps/desktop/build/**` to `dist/desktop/**`, `dist/mobile/**`, and `apps/desktop/**` for better clarity and organization.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 fix: update BrowserRouter basename for local development

- Modified the `ClientRouter` component to conditionally set the `basename` of `BrowserRouter` based on the `__DEBUG_PROXY__` variable, improving local development experience.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 feat: implement mobile SPA workflow and S3 asset management

- Added a new workflow for building and uploading mobile SPA assets to S3, including environment variable configurations in `.env.example`.
- Updated `package.json` to include a new script for the mobile SPA workflow.
- Enhanced the Vite configuration to support dynamic CDN base paths.
- Refactored the template generation script to handle mobile HTML templates more effectively.
- Introduced new modules for uploading assets to S3 and generating mobile HTML templates.

Signed-off-by: Innei <tukon479@gmail.com>

* 🐛 fix: extract origin from MOBILE_S3_PUBLIC_DOMAIN to prevent double key prefix

* 🔧 fix: update mobile HTML template to use the latest asset versions

- Modified the mobile HTML template to reference the updated JavaScript asset version for improved functionality.
- Ensured consistency in the template structure while maintaining existing styles and scripts.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: update dependencies and refine service worker integration

- Removed outdated dependencies related to Serwist from package.json and tsconfig.json.
- Added vite-plugin-pwa to enhance PWA capabilities in the Vite configuration.
- Updated service worker registration logic in the PWA installation component.
- Introduced a new local development proxy route for debugging purposes.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: refactor development scripts and remove Turbo configuration

- Updated the `dev` script in `package.json` to use a new startup sequence script for improved development workflow.
- Removed the outdated `turbo.json` configuration file as it is no longer needed.
- Introduced `devStartupSequence.mts` to manage the startup of Next.js and Vite processes concurrently.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 feat: update entry points and introduce debug proxy for local development

- Changed the main entry point in `index.html` from `entry.desktop.tsx` to `entry.web.tsx` for improved web compatibility.
- Added an `initialize.ts` file to enable `immer`'s `enableMapSet` functionality.
- Introduced a new `__DEBUG_PROXY__` variable in global types to support local development proxy features.
- Implemented a debug proxy route to facilitate local development with dynamic HTML injection and script handling.
- Removed outdated mobile routing components to streamline the codebase.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: replace BrowserRouter with RouterProvider for improved routing

- Updated entry points for desktop, mobile, and web to utilize RouterProvider and createAppRouter for better routing management.
- Removed the deprecated renderRoutes function in favor of a more streamlined router configuration.
- Enhanced router setup to support error boundaries and dynamic routing.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: remove direct access handling for SPA routes in proxy configuration

- Eliminated the handling of direct access to pre-rendered SPA pages in the proxy configuration.
- Simplified the request processing logic by removing checks for SPA routes, streamlining the middleware response flow.

Signed-off-by: Innei <tukon479@gmail.com>

* update

* 🔧 refactor: enhance Worker instantiation logic in mobile HTML template

* 🐛 fix: remove duplicate waitForPageWorkspaceReady calls in page CRUD e2e steps

* 🔧 refactor: simplify createTracePayload function by using btoa for base64 encoding

* 🔧 refactor: specify locales in import.meta.glob for dayjs and antd

* 🔧 refactor: replace Node.js Buffer with web-compatible btoa for base64 encoding in file upload

* 🐛 fix: disable consistent-type-imports rule for mdx files to prevent eslint crash

* 🔧 refactor: add height style to root div for consistent layout

* 🔧 refactor: replace btoa with Buffer for base64 encoding in trace and file upload handling

* 🔧 refactor: extract nextjsOnlyRoutes to a separate file for better organization

* 🔧 refactor: enable Immer MapSet plugin in tests for better state management

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 refactor: integrate sharedRollupOutput configuration and increase cache size for better performance

Signed-off-by: Innei <tukon479@gmail.com>

* 🗑️ chore: remove obsolete desktop.routes.test.ts file as it is no longer needed

Signed-off-by: Innei <tukon479@gmail.com>

* 🐛 fix: use cross-env for env vars in npm scripts (Windows CI)

Co-authored-by: Cursor <cursoragent@cursor.com>

* 🔧 chore: update Dockerfile for web-only build and adjust npm scripts to use pnpm

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: enhance Dockerfile prebuild process with environment checks and add new dependencies

- Updated Dockerfile to include environment checks before removing desktop-only code.
- Added new dependencies in package.json: @aws-sdk/client-bedrock-runtime, @opentelemetry/auto-instrumentations-node, @opentelemetry/resources, @opentelemetry/sdk-metrics, and ajv.
- Configured Rollup to exclude @aws-sdk/client-bedrock-runtime from the SPA bundle.
- Introduced dockerPrebuild.mts script for environment variable validation and information logging.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: enhance Vite and Electron configurations with environment loading and trace encoding improvements

- Updated Vite and Electron configurations to load environment variables using loadEnv.
- Modified trace encoding in utils to use TextEncoder for better compatibility.
- Adjusted sharedRendererConfig to expose only necessary public environment variables.

Signed-off-by: Innei <tukon479@gmail.com>

* 🗑️ chore: remove plans directory (migrated to discussion)

* ♻️ refactor: inject NEXT_PUBLIC_* env per key in Vite define

Co-authored-by: Cursor <cursoragent@cursor.com>

* ✨ feat: add loading screen with animation to enhance user experience

- Introduced a loading screen with a brand logo and animations for better visual feedback during loading times.
- Implemented CSS styles for the loading screen and animations in index.html.
- Removed the loading screen from the DOM once the layout is ready using useLayoutEffect in SPAGlobalProvider.

Signed-off-by: Innei <tukon479@gmail.com>

* 🗑️ chore: remove unnecessary external dependency from Vite configuration

- Eliminated the external dependency '@aws-sdk/client-bedrock-runtime' from the Vite configuration to streamline the build process for the SPA bundle.

Signed-off-by: Innei <tukon479@gmail.com>

* ✨ feat: add web app manifest link in index.html and enable PWA support in Vite configuration

- Added a link to the web app manifest in index.html to enhance PWA capabilities.
- Enabled manifest support in Vite configuration for improved service worker functionality.

Signed-off-by: Innei <tukon479@gmail.com>

* 🔧 chore: update link rel attributes for improved SEO and consistency

- Modified link rel attributes in multiple components to remove 'noreferrer' and standardize to 'nofollow'.
- Adjusted imports in PageContent components for better organization.

Signed-off-by: Innei <tukon479@gmail.com>

* update provider

* ✨ feat: enhance loading experience and update package dependencies

- Added a loading screen with animations and a brand logo in index.html for improved user feedback during loading times.
- Introduced CSS styles for the loading screen and animations.
- Updated package.json files across multiple packages to include "@lobechat/const" as a dependency.

Signed-off-by: Innei <tukon479@gmail.com>

* fix: update proxy

Signed-off-by: Innei <tukon479@gmail.com>

* 🗑️ chore: remove GlobalLayout and Locale components

- Deleted GlobalLayout and Locale components from the GlobalProvider directory to streamline the codebase.
- This removal is part of a refactor to simplify the layout structure and improve maintainability.

Signed-off-by: Innei <tukon479@gmail.com>

* chore: clean up console logs and improve component structure

- Removed unnecessary console log statements from AgentForkTag components in both agent and community directories to enhance code cleanliness.
- Refactored UserAgentList component for better readability by restructuring the useUserDetailContext hook and adjusting the layout of Flexbox components.

Signed-off-by: Innei <tukon479@gmail.com>

* chore: remove console log from MemoryAnalysis component

* chore: update mobile HTML template with new asset links

- Replaced the previous asset links in the mobile HTML template with updated versions to ensure the latest resources are utilized.
- Adjusted the link rel attributes for module preloading to enhance performance and loading efficiency.

Signed-off-by: Innei <tukon479@gmail.com>

* fix: correct variable assignment in createClientTaskThread integration test

- Updated the assignment of the second parent message in the createClientTaskThread integration test to improve clarity and ensure proper data handling.
- Changed the variable name from 'secondParentMsg' to 'inserted' for better context before extracting the first message from the inserted results.

Signed-off-by: Innei <tukon479@gmail.com>

* refactor: simplify authentication check in define-config

- Removed the dependency on the isDesktop variable in the authentication check to streamline the logic.
- Enhanced the clarity of the redirection process for protected routes by focusing solely on the isLoggedIn status.

Signed-off-by: Innei <tukon479@gmail.com>

* ✨ feat(dev): enhance local development setup with debug proxy instructions

- Added detailed instructions for starting the development environment in CLAUDE.md, including commands for SPA and full-stack modes.
- Updated README.md and README.zh-CN.md to reflect new commands and the debug proxy URL for local development.
- Introduced a Vite plugin to print the debug proxy URL upon server start, facilitating easier local development against the production backend.
- Corrected the debug proxy route in entry.web.tsx and define-config.ts for consistency.

This improves the developer experience by providing clear guidance and tools for local development.

Signed-off-by: Innei <tukon479@gmail.com>

* optimize perf

* optimize perf

* optimize perf

* remove speedy plugin

* add dayjs vendor

* Revert "remove speedy plugin"

This reverts commit bf986afeb1.

---------

Signed-off-by: Innei <tukon479@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

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

@@ -79,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/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/`

.agents/skills/drizzle/SKILL.md

@@ -115,6 +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.
@@ -129,14 +214,27 @@ bun run db:generate:client
 
 ### Migration Best Practices
 
+All migration SQL must be **idempotent** (safe to re-run):
+
 ```sql
--- ✅ Idempotent operations
+-- ✅ Tables: IF NOT EXISTS
+CREATE TABLE IF NOT EXISTS "agent_eval_runs" (...);
+
+-- ✅ Columns: IF NOT EXISTS / IF EXISTS
 ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "avatar" text;
-DROP TABLE IF EXISTS "old_table";
+ALTER TABLE "users" DROP COLUMN IF EXISTS "old_field";
+
+-- ✅ Foreign keys: DROP IF EXISTS + ADD (no IF NOT EXISTS for constraints)
+ALTER TABLE "t" DROP CONSTRAINT IF EXISTS "t_fk";
+ALTER TABLE "t" ADD CONSTRAINT "t_fk" FOREIGN KEY ("col") REFERENCES "ref"("id") ON DELETE cascade;
+
+-- ✅ Indexes: IF NOT EXISTS
 CREATE INDEX IF NOT EXISTS "users_email_idx" ON "users" ("email");
 
--- ❌ Non-idempotent
+-- ❌ Non-idempotent (will fail on re-run)
+CREATE TABLE "agent_eval_runs" (...);
 ALTER TABLE "users" ADD COLUMN "avatar" text;
+ALTER TABLE "t" ADD CONSTRAINT "t_fk" FOREIGN KEY ...;
 ```
 
 Rename migration files meaningfully: `0046_meaningless.sql` → `0046_user_add_avatar.sql`

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

@@ -24,27 +24,57 @@ Rename auto-generated filename to be meaningful:
 
 ## Step 3: Use Idempotent Clauses (Defensive Programming)
 
-Always use defensive clauses to make migrations idempotent:
+Always use defensive clauses to make migrations idempotent (safe to re-run):
+
+### CREATE TABLE
 
 ```sql
--- ✅ Good: Idempotent operations
+-- ✅ 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;
-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
+-- ❌ 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");
 ```
-
-## 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/i18n/SKILL.md

@@ -3,7 +3,7 @@ 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)
 - Framework: react-i18next

.agents/skills/microcopy/SKILL.md

@@ -25,6 +25,10 @@ Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not j
 | 资源       | Resource      |
 | 库         | Library       |
 | 模型服务商 | Provider      |
+| 评测       | Evaluation    |
+| 基准       | Benchmark     |
+| 数据集     | Dataset       |
+| 用例       | Test Case     |
 
 ## Brand Principles
 

.agents/skills/pr/SKILL.md

@@ -0,0 +1,55 @@
+---
+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 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 log --oneline origin/canary..HEAD` — commit history for PR title
+   - `git diff --stat --stat-count=20 origin/canary..HEAD` — change summary
+
+2. **Push if needed**:
+   - No upstream: `git push -u origin $(git branch --show-current)`
+   - Has upstream: `git push origin $(git branch --show-current)`
+
+3. **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
+
+4. **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
+
+5. **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
+
+- **Release impact**: PR titles with `✨ feat/` or `🐛 fix` trigger releases — use carefully
+- **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,7 +3,7 @@ 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
 

.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,7 +3,7 @@ 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
 

.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/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,127 +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,35 +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,37 +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>

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

@@ -1,24 +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,37 +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,48 +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,34 +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,44 +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,78 +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,74 +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>

.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,68 +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,50 +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

.agents/skills/vercel-react-best-practices/rules/rendering-activity.md

@@ -1,26 +0,0 @@
----
-title: Use Activity Component for Show/Hide
-impact: MEDIUM
-impactDescription: preserves state/DOM
-tags: rendering, activity, visibility, state-preservation
----
-
-## Use Activity Component for Show/Hide
-
-Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
-
-**Usage:**
-
-```tsx
-import { Activity } from 'react';
-
-function Dropdown({ isOpen }: Props) {
-  return (
-    <Activity mode={isOpen ? 'visible' : 'hidden'}>
-      <ExpensiveMenu />
-    </Activity>
-  );
-}
-```
-
-Avoids expensive re-renders and state loss.

.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md

@@ -1,38 +0,0 @@
----
-title: Animate SVG Wrapper Instead of SVG Element
-impact: LOW
-impactDescription: enables hardware acceleration
-tags: rendering, svg, css, animation, performance
----
-
-## Animate SVG Wrapper Instead of SVG Element
-
-Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
-
-**Incorrect (animating SVG directly - no hardware acceleration):**
-
-```tsx
-function LoadingSpinner() {
-  return (
-    <svg className="animate-spin" width="24" height="24" viewBox="0 0 24 24">
-      <circle cx="12" cy="12" r="10" stroke="currentColor" />
-    </svg>
-  );
-}
-```
-
-**Correct (animating wrapper div - hardware accelerated):**
-
-```tsx
-function LoadingSpinner() {
-  return (
-    <div className="animate-spin">
-      <svg width="24" height="24" viewBox="0 0 24 24">
-        <circle cx="12" cy="12" r="10" stroke="currentColor" />
-      </svg>
-    </div>
-  );
-}
-```
-
-This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.

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

@@ -1,32 +0,0 @@
----
-title: Use Explicit Conditional Rendering
-impact: LOW
-impactDescription: prevents rendering 0 or NaN
-tags: rendering, conditional, jsx, falsy-values
----
-
-## Use Explicit Conditional Rendering
-
-Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
-
-**Incorrect (renders "0" when count is 0):**
-
-```tsx
-function Badge({ count }: { count: number }) {
-  return <div>{count && <span className="badge">{count}</span>}</div>;
-}
-
-// When count = 0, renders: <div>0</div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```
-
-**Correct (renders nothing when count is 0):**
-
-```tsx
-function Badge({ count }: { count: number }) {
-  return <div>{count > 0 ? <span className="badge">{count}</span> : null}</div>;
-}
-
-// When count = 0, renders: <div></div>
-// When count = 5, renders: <div><span class="badge">5</span></div>
-```

.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md

@@ -1,38 +0,0 @@
----
-title: CSS content-visibility for Long Lists
-impact: HIGH
-impactDescription: faster initial render
-tags: rendering, css, content-visibility, long-lists
----
-
-## CSS content-visibility for Long Lists
-
-Apply `content-visibility: auto` to defer off-screen rendering.
-
-**CSS:**
-
-```css
-.message-item {
-  content-visibility: auto;
-  contain-intrinsic-size: 0 80px;
-}
-```
-
-**Example:**
-
-```tsx
-function MessageList({ messages }: { messages: Message[] }) {
-  return (
-    <div className="overflow-y-auto h-screen">
-      {messages.map((msg) => (
-        <div key={msg.id} className="message-item">
-          <Avatar user={msg.author} />
-          <div>{msg.content}</div>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-For 1000 messages, browser skips layout/paint for \~990 off-screen items (10× faster initial render).

.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md

@@ -1,36 +0,0 @@
----
-title: Hoist Static JSX Elements
-impact: LOW
-impactDescription: avoids re-creation
-tags: rendering, jsx, static, optimization
----
-
-## Hoist Static JSX Elements
-
-Extract static JSX outside components to avoid re-creation.
-
-**Incorrect (recreates element every render):**
-
-```tsx
-function LoadingSkeleton() {
-  return <div className="animate-pulse h-20 bg-gray-200" />;
-}
-
-function Container() {
-  return <div>{loading && <LoadingSkeleton />}</div>;
-}
-```
-
-**Correct (reuses same element):**
-
-```tsx
-const loadingSkeleton = <div className="animate-pulse h-20 bg-gray-200" />;
-
-function Container() {
-  return <div>{loading && loadingSkeleton}</div>;
-}
-```
-
-This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.

.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md

@@ -1,72 +0,0 @@
----
-title: Prevent Hydration Mismatch Without Flickering
-impact: MEDIUM
-impactDescription: avoids visual flicker and hydration errors
-tags: rendering, ssr, hydration, localStorage, flicker
----
-
-## Prevent Hydration Mismatch Without Flickering
-
-When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
-
-**Incorrect (breaks SSR):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
-  // localStorage is not available on server - throws error
-  const theme = localStorage.getItem('theme') || 'light';
-
-  return <div className={theme}>{children}</div>;
-}
-```
-
-Server-side rendering will fail because `localStorage` is undefined.
-
-**Incorrect (visual flickering):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
-  const [theme, setTheme] = useState('light');
-
-  useEffect(() => {
-    // Runs after hydration - causes visible flash
-    const stored = localStorage.getItem('theme');
-    if (stored) {
-      setTheme(stored);
-    }
-  }, []);
-
-  return <div className={theme}>{children}</div>;
-}
-```
-
-Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
-
-**Correct (no flicker, no hydration mismatch):**
-
-```tsx
-function ThemeWrapper({ children }: { children: ReactNode }) {
-  return (
-    <>
-      <div id="theme-wrapper">{children}</div>
-      <script
-        dangerouslySetInnerHTML={{
-          __html: `
-            (function() {
-              try {
-                var theme = localStorage.getItem('theme') || 'light';
-                var el = document.getElementById('theme-wrapper');
-                if (el) el.className = theme;
-              } catch (e) {}
-            })();
-          `,
-        }}
-      />
-    </>
-  );
-}
-```
-
-The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
-
-This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md

@@ -1,28 +0,0 @@
----
-title: Optimize SVG Precision
-impact: LOW
-impactDescription: reduces file size
-tags: rendering, svg, optimization, svgo
----
-
-## Optimize SVG Precision
-
-Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
-
-**Incorrect (excessive precision):**
-
-```svg
-<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
-```
-
-**Correct (1 decimal place):**
-
-```svg
-<path d="M 10.3 20.8 L 30.9 40.2" />
-```
-
-**Automate with SVGO:**
-
-```bash
-npx svgo --precision=1 --multipass icon.svg
-```

.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md

@@ -1,39 +0,0 @@
----
-title: Defer State Reads to Usage Point
-impact: MEDIUM
-impactDescription: avoids unnecessary subscriptions
-tags: rerender, searchParams, localStorage, optimization
----
-
-## Defer State Reads to Usage Point
-
-Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
-
-**Incorrect (subscribes to all searchParams changes):**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
-  const searchParams = useSearchParams();
-
-  const handleShare = () => {
-    const ref = searchParams.get('ref');
-    shareChat(chatId, { ref });
-  };
-
-  return <button onClick={handleShare}>Share</button>;
-}
-```
-
-**Correct (reads on demand, no subscription):**
-
-```tsx
-function ShareButton({ chatId }: { chatId: string }) {
-  const handleShare = () => {
-    const params = new URLSearchParams(window.location.search);
-    const ref = params.get('ref');
-    shareChat(chatId, { ref });
-  };
-
-  return <button onClick={handleShare}>Share</button>;
-}
-```

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

@@ -1,45 +0,0 @@
----
-title: Narrow Effect Dependencies
-impact: LOW
-impactDescription: minimizes effect re-runs
-tags: rerender, useEffect, dependencies, optimization
----
-
-## Narrow Effect Dependencies
-
-Specify primitive dependencies instead of objects to minimize effect re-runs.
-
-**Incorrect (re-runs on any user field change):**
-
-```tsx
-useEffect(() => {
-  console.log(user.id);
-}, [user]);
-```
-
-**Correct (re-runs only when id changes):**
-
-```tsx
-useEffect(() => {
-  console.log(user.id);
-}, [user.id]);
-```
-
-**For derived state, compute outside effect:**
-
-```tsx
-// Incorrect: runs on width=767, 766, 765...
-useEffect(() => {
-  if (width < 768) {
-    enableMobileMode();
-  }
-}, [width]);
-
-// Correct: runs only on boolean transition
-const isMobile = width < 768;
-useEffect(() => {
-  if (isMobile) {
-    enableMobileMode();
-  }
-}, [isMobile]);
-```

.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md

@@ -1,29 +0,0 @@
----
-title: Subscribe to Derived State
-impact: MEDIUM
-impactDescription: reduces re-render frequency
-tags: rerender, derived-state, media-query, optimization
----
-
-## Subscribe to Derived State
-
-Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
-
-**Incorrect (re-renders on every pixel change):**
-
-```tsx
-function Sidebar() {
-  const width = useWindowWidth(); // updates continuously
-  const isMobile = width < 768;
-  return <nav className={isMobile ? 'mobile' : 'desktop'} />;
-}
-```
-
-**Correct (re-renders only when boolean changes):**
-
-```tsx
-function Sidebar() {
-  const isMobile = useMediaQuery('(max-width: 767px)');
-  return <nav className={isMobile ? 'mobile' : 'desktop'} />;
-}
-```

.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md

@@ -1,77 +0,0 @@
----
-title: Use Functional setState Updates
-impact: MEDIUM
-impactDescription: prevents stale closures and unnecessary callback recreations
-tags: react, hooks, useState, useCallback, callbacks, closures
----
-
-## Use Functional setState Updates
-
-When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
-
-**Incorrect (requires state as dependency):**
-
-```tsx
-function TodoList() {
-  const [items, setItems] = useState(initialItems);
-
-  // Callback must depend on items, recreated on every items change
-  const addItems = useCallback(
-    (newItems: Item[]) => {
-      setItems([...items, ...newItems]);
-    },
-    [items],
-  ); // ❌ items dependency causes recreations
-
-  // Risk of stale closure if dependency is forgotten
-  const removeItem = useCallback((id: string) => {
-    setItems(items.filter((item) => item.id !== id));
-  }, []); // ❌ Missing items dependency - will use stale items!
-
-  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />;
-}
-```
-
-The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
-
-**Correct (stable callbacks, no stale closures):**
-
-```tsx
-function TodoList() {
-  const [items, setItems] = useState(initialItems);
-
-  // Stable callback, never recreated
-  const addItems = useCallback((newItems: Item[]) => {
-    setItems((curr) => [...curr, ...newItems]);
-  }, []); // ✅ No dependencies needed
-
-  // Always uses latest state, no stale closure risk
-  const removeItem = useCallback((id: string) => {
-    setItems((curr) => curr.filter((item) => item.id !== id));
-  }, []); // ✅ Safe and stable
-
-  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />;
-}
-```
-
-**Benefits:**
-
-1. **Stable callback references** - Callbacks don't need to be recreated when state changes
-2. **No stale closures** - Always operates on the latest state value
-3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
-4. **Prevents bugs** - Eliminates the most common source of React closure bugs
-
-**When to use functional updates:**
-
-- Any setState that depends on the current state value
-- Inside useCallback/useMemo when state is needed
-- Event handlers that reference state
-- Async operations that update state
-
-**When direct updates are fine:**
-
-- Setting state to a static value: `setCount(0)`
-- Setting state from props/arguments only: `setName(newName)`
-- State doesn't depend on previous value
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.

.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md

@@ -1,56 +0,0 @@
----
-title: Use Lazy State Initialization
-impact: MEDIUM
-impactDescription: wasted computation on every render
-tags: react, hooks, useState, performance, initialization
----
-
-## Use Lazy State Initialization
-
-Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
-
-**Incorrect (runs on every render):**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
-  // buildSearchIndex() runs on EVERY render, even after initialization
-  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items));
-  const [query, setQuery] = useState('');
-
-  // When query changes, buildSearchIndex runs again unnecessarily
-  return <SearchResults index={searchIndex} query={query} />;
-}
-
-function UserProfile() {
-  // JSON.parse runs on every render
-  const [settings, setSettings] = useState(JSON.parse(localStorage.getItem('settings') || '{}'));
-
-  return <SettingsForm settings={settings} onChange={setSettings} />;
-}
-```
-
-**Correct (runs only once):**
-
-```tsx
-function FilteredList({ items }: { items: Item[] }) {
-  // buildSearchIndex() runs ONLY on initial render
-  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items));
-  const [query, setQuery] = useState('');
-
-  return <SearchResults index={searchIndex} query={query} />;
-}
-
-function UserProfile() {
-  // JSON.parse runs only on initial render
-  const [settings, setSettings] = useState(() => {
-    const stored = localStorage.getItem('settings');
-    return stored ? JSON.parse(stored) : {};
-  });
-
-  return <SettingsForm settings={settings} onChange={setSettings} />;
-}
-```
-
-Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
-
-For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

.agents/skills/vercel-react-best-practices/rules/rerender-memo.md

@@ -1,44 +0,0 @@
----
-title: Extract to Memoized Components
-impact: MEDIUM
-impactDescription: enables early returns
-tags: rerender, memo, useMemo, optimization
----
-
-## Extract to Memoized Components
-
-Extract expensive work into memoized components to enable early returns before computation.
-
-**Incorrect (computes avatar even when loading):**
-
-```tsx
-function Profile({ user, loading }: Props) {
-  const avatar = useMemo(() => {
-    const id = computeAvatarId(user);
-    return <Avatar id={id} />;
-  }, [user]);
-
-  if (loading) return <Skeleton />;
-  return <div>{avatar}</div>;
-}
-```
-
-**Correct (skips computation when loading):**
-
-```tsx
-const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
-  const id = useMemo(() => computeAvatarId(user), [user]);
-  return <Avatar id={id} />;
-});
-
-function Profile({ user, loading }: Props) {
-  if (loading) return <Skeleton />;
-  return (
-    <div>
-      <UserAvatar user={user} />
-    </div>
-  );
-}
-```
-
-**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.

.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md

@@ -1,40 +0,0 @@
----
-title: Use Transitions for Non-Urgent Updates
-impact: MEDIUM
-impactDescription: maintains UI responsiveness
-tags: rerender, transitions, startTransition, performance
----
-
-## Use Transitions for Non-Urgent Updates
-
-Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
-
-**Incorrect (blocks UI on every scroll):**
-
-```tsx
-function ScrollTracker() {
-  const [scrollY, setScrollY] = useState(0);
-  useEffect(() => {
-    const handler = () => setScrollY(window.scrollY);
-    window.addEventListener('scroll', handler, { passive: true });
-    return () => window.removeEventListener('scroll', handler);
-  }, []);
-}
-```
-
-**Correct (non-blocking updates):**
-
-```tsx
-import { startTransition } from 'react';
-
-function ScrollTracker() {
-  const [scrollY, setScrollY] = useState(0);
-  useEffect(() => {
-    const handler = () => {
-      startTransition(() => setScrollY(window.scrollY));
-    };
-    window.addEventListener('scroll', handler, { passive: true });
-    return () => window.removeEventListener('scroll', handler);
-  }, []);
-}
-```

.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -1,73 +0,0 @@
----
-title: Use after() for Non-Blocking Operations
-impact: MEDIUM
-impactDescription: faster response times
-tags: server, async, logging, analytics, side-effects
----
-
-## Use after() for Non-Blocking Operations
-
-Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
-
-**Incorrect (blocks response):**
-
-```tsx
-import { logUserAction } from '@/app/utils';
-
-export async function POST(request: Request) {
-  // Perform mutation
-  await updateDatabase(request);
-
-  // Logging blocks the response
-  const userAgent = request.headers.get('user-agent') || 'unknown';
-  await logUserAction({ userAgent });
-
-  return new Response(JSON.stringify({ status: 'success' }), {
-    status: 200,
-    headers: { 'Content-Type': 'application/json' },
-  });
-}
-```
-
-**Correct (non-blocking):**
-
-```tsx
-import { after } from 'next/server';
-import { headers, cookies } from 'next/headers';
-import { logUserAction } from '@/app/utils';
-
-export async function POST(request: Request) {
-  // Perform mutation
-  await updateDatabase(request);
-
-  // Log after response is sent
-  after(async () => {
-    const userAgent = (await headers()).get('user-agent') || 'unknown';
-    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous';
-
-    logUserAction({ sessionCookie, userAgent });
-  });
-
-  return new Response(JSON.stringify({ status: 'success' }), {
-    status: 200,
-    headers: { 'Content-Type': 'application/json' },
-  });
-}
-```
-
-The response is sent immediately while logging happens in the background.
-
-**Common use cases:**
-
-- Analytics tracking
-- Audit logging
-- Sending notifications
-- Cache invalidation
-- Cleanup tasks
-
-**Important notes:**
-
-- `after()` runs even if the response fails or redirects
-- Works in Server Actions, Route Handlers, and Server Components
-
-Reference: <https://nextjs.org/docs/app/api-reference/functions/after>

.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md

@@ -1,41 +0,0 @@
----
-title: Cross-Request LRU Caching
-impact: HIGH
-impactDescription: caches across requests
-tags: server, cache, lru, cross-request
----
-
-## Cross-Request LRU Caching
-
-`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
-
-**Implementation:**
-
-```typescript
-import { LRUCache } from 'lru-cache';
-
-const cache = new LRUCache<string, any>({
-  max: 1000,
-  ttl: 5 * 60 * 1000, // 5 minutes
-});
-
-export async function getUser(id: string) {
-  const cached = cache.get(id);
-  if (cached) return cached;
-
-  const user = await db.user.findUnique({ where: { id } });
-  cache.set(id, user);
-  return user;
-}
-
-// Request 1: DB query, result cached
-// Request 2: cache hit, no DB query
-```
-
-Use when sequential user actions hit multiple endpoints needing the same data within seconds.
-
-**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
-
-**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
-
-Reference: <https://github.com/isaacs/node-lru-cache>

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

@@ -1,76 +0,0 @@
----
-title: Per-Request Deduplication with React.cache()
-impact: MEDIUM
-impactDescription: deduplicates within request
-tags: server, cache, react-cache, deduplication
----
-
-## Per-Request Deduplication with React.cache()
-
-Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
-
-**Usage:**
-
-```typescript
-import { cache } from 'react';
-
-export const getCurrentUser = cache(async () => {
-  const session = await auth();
-  if (!session?.user?.id) return null;
-  return await db.user.findUnique({
-    where: { id: session.user.id },
-  });
-});
-```
-
-Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
-
-**Avoid inline objects as arguments:**
-
-`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
-
-**Incorrect (always cache miss):**
-
-```typescript
-const getUser = cache(async (params: { uid: number }) => {
-  return await db.user.findUnique({ where: { id: params.uid } });
-});
-
-// Each call creates new object, never hits cache
-getUser({ uid: 1 });
-getUser({ uid: 1 }); // Cache miss, runs query again
-```
-
-**Correct (cache hit):**
-
-```typescript
-const getUser = cache(async (uid: number) => {
-  return await db.user.findUnique({ where: { id: uid } });
-});
-
-// Primitive args use value equality
-getUser(1);
-getUser(1); // Cache hit, returns cached result
-```
-
-If you must pass objects, pass the same reference:
-
-```typescript
-const params = { uid: 1 };
-getUser(params); // Query runs
-getUser(params); // Cache hit (same reference)
-```
-
-**Next.js-Specific Note:**
-
-In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
-
-- Database queries (Prisma, Drizzle, etc.)
-- Heavy computations
-- Authentication checks
-- File system operations
-- Any non-fetch async work
-
-Use `React.cache()` to deduplicate these operations across your component tree.
-
-Reference: [React.cache documentation](https://react.dev/reference/react/cache)

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

@@ -1,83 +0,0 @@
----
-title: Parallel Data Fetching with Component Composition
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, composition
----
-
-## Parallel Data Fetching with Component Composition
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect (Sidebar waits for Page's fetch to complete):**
-
-```tsx
-export default async function Page() {
-  const header = await fetchHeader();
-  return (
-    <div>
-      <div>{header}</div>
-      <Sidebar />
-    </div>
-  );
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems();
-  return <nav>{items.map(renderItem)}</nav>;
-}
-```
-
-**Correct (both fetch simultaneously):**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader();
-  return <div>{data}</div>;
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems();
-  return <nav>{items.map(renderItem)}</nav>;
-}
-
-export default function Page() {
-  return (
-    <div>
-      <Header />
-      <Sidebar />
-    </div>
-  );
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader();
-  return <div>{data}</div>;
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems();
-  return <nav>{items.map(renderItem)}</nav>;
-}
-
-function Layout({ children }: { children: ReactNode }) {
-  return (
-    <div>
-      <Header />
-      {children}
-    </div>
-  );
-}
-
-export default function Page() {
-  return (
-    <Layout>
-      <Sidebar />
-    </Layout>
-  );
-}
-```

.agents/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -1,38 +0,0 @@
----
-title: Minimize Serialization at RSC Boundaries
-impact: HIGH
-impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
----
-
-## Minimize Serialization at RSC Boundaries
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect (serializes all 50 fields):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser(); // 50 fields
-  return <Profile user={user} />;
-}
-
-('use client');
-function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>; // uses 1 field
-}
-```
-
-**Correct (serializes only 1 field):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser();
-  return <Profile name={user.name} />;
-}
-
-('use client');
-function Profile({ name }: { name: string }) {
-  return <div>{name}</div>;
-}
-```

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

@@ -0,0 +1,151 @@
+---
+name: version-release
+description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. Provides guides for Minor Release and Patch Release workflows."
+---
+
+# Version Release Workflow
+
+## Overview
+
+The primary development branch is **canary**. All day-to-day development happens on canary. When releasing, canary is merged into main. After merge, `auto-tag-release.yml` automatically handles tagging, version bumping, creating a GitHub Release, and syncing back to the canary branch.
+
+Only two release types are used in practice (major releases are extremely rare and can be ignored):
+
+| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       |
+| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- |
+| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  |
+| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 |
+
+## Minor Release Workflow
+
+Used to publish a new minor version (e.g. v2.2.0), roughly every 4 weeks.
+
+### Steps
+
+1. **Create a release branch from canary**
+
+```bash
+git checkout canary
+git pull origin canary
+git checkout -b release/v{version}
+git push -u origin release/v{version}
+```
+
+2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x → 2.2.0)
+
+3. **Create a PR to main**
+
+```bash
+gh pr create \
+  --title "🚀 release: v{version}" \
+  --base main \
+  --head release/v{version} \
+  --body "## 📦 Release v{version} ..."
+```
+
+> \[!IMPORTANT]: The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
+
+4. **Automatic trigger after merge**: auto-tag-release detects the title format and uses the version number from the title to complete the release.
+
+### Scripts
+
+```bash
+bun run release:branch         # Interactive
+bun run release:branch --minor # Directly specify minor
+```
+
+## Patch Release Workflow
+
+Version number is automatically bumped by patch +1. There are 4 common scenarios:
+
+| Scenario            | Source Branch | Branch Naming                 | Description                                      |
+| ------------------- | ------------- | ----------------------------- | ------------------------------------------------ |
+| Weekly Release      | canary        | `release/weekly-{YYYYMMDD}`   | Weekly release train, canary → main              |
+| Bug Hotfix          | main          | `hotfix/v{version}-{hash}`    | Emergency bug fix                                |
+| New Model Launch    | canary        | Community PR merged directly  | New model launch, triggered by PR title prefix   |
+| DB Schema Migration | canary        | `release/db-migration-{name}` | Database migration, requires dedicated changelog |
+
+All scenarios auto-bump patch +1. Patch PR titles do not need a version number. See `reference/patch-release-scenarios.md` for detailed steps per scenario.
+
+### Scripts
+
+```bash
+bun run hotfix:branch # Hotfix scenario
+```
+
+## Auto-Release Trigger Rules (auto-tag-release.yml)
+
+After a PR is merged into main, CI determines whether to release based on the following priority:
+
+### 1. Minor Release (Exact Version)
+
+PR title matches `🚀 release: v{x.y.z}` → uses the version number from the title.
+
+### 2. Patch Release (Auto patch +1)
+
+Triggered by the following priority:
+
+- **Branch name match**: `hotfix/*` or `release/*` → triggers directly (skips title detection)
+- **Title prefix match**: PRs with the following title prefixes will trigger:
+  - `style` / `💄 style`
+  - `feat` / `✨ feat`
+  - `fix` / `🐛 fix`
+  - `refactor` / `♻️ refactor`
+  - `hotfix` / `🐛 hotfix` / `🩹 hotfix`
+  - `build` / `👷 build`
+
+### 3. No Trigger
+
+PRs that don't match any of the above conditions (e.g. `docs`, `chore`, `ci`, `test` prefixes) will not trigger a release when merged into main.
+
+## Post-Release Automated Actions
+
+1. **Bump package.json** — commits `🔖 chore(release): release version v{x.y.z} [skip ci]`
+2. **Create annotated tag** — `v{x.y.z}`
+3. **Create GitHub Release**
+4. **Dispatch sync-main-to-canary** — syncs main back to the canary branch
+
+## Claude Action Guide
+
+When the user requests a release:
+
+### Minor Release
+
+1. Read `package.json` to get the current version and compute the next minor version
+2. Create a `release/v{version}` branch from canary
+3. Push and create a PR — **title must be `🚀 release: v{version}`**
+4. Inform the user that merging the PR will automatically trigger the release
+
+### Patch Release
+
+Choose the appropriate workflow based on the scenario (see `reference/patch-release-scenarios.md`):
+
+- **Weekly Release**: Create a `release/weekly-{YYYYMMDD}` branch from canary, scan `git log main..canary` to write the changelog, title like `🚀 release: 20260222`
+- **Bug Hotfix**: Create a `hotfix/` branch from main, use a gitmoji prefix title (e.g. `🐛 fix: ...`)
+- **New Model Launch**: Community PRs trigger automatically via title prefix (`feat` / `style`), no extra steps needed
+- **DB Migration**: Create a `release/db-migration-{name}` branch from canary, write a dedicated migration changelog
+
+### Important Notes
+
+- **Do NOT manually modify the version in package.json** — CI will auto-bump it
+- **Do NOT manually create tags** — CI will create them automatically
+- The Minor Release PR title format is a hard requirement — incorrect format will not use the specified version number
+- Patch PRs do not need a version number — CI auto-bumps patch +1
+- All release PRs must include a user-facing changelog
+
+## Changelog Writing Guidelines
+
+All release PR bodies (both Minor and Patch) must include a user-facing changelog. Scan changes via `git log main..canary --oneline` or `git diff main...canary --stat`, then write following the format below.
+
+### Format Reference
+
+- Weekly Release: See `reference/changelog-example/weekly-release.md`
+- DB Migration: See `reference/changelog-example/db-migration.md`
+
+### Writing Tips
+
+- **User-facing**: Describe changes that users can perceive, not internal implementation details
+- **Clear categories**: Group by features, models/providers, desktop, stability/fixes, etc.
+- **Highlight key items**: Use `**bold**` for important feature names
+- **Credit contributors**: Collect all committers via `git log` and list alphabetically
+- **Flexible categories**: Choose categories based on actual changes — no need to force-fit all categories

.agents/skills/version-release/reference/changelog-example/db-migration.md

@@ -0,0 +1,18 @@
+# DB Schema Migration Changelog Example
+
+A changelog reference for database migration release PR bodies.
+
+---
+
+This release includes a **database schema migration** involving **5 new tables** for the Agent Evaluation Benchmark system.
+
+### Migration: Add Agent Evaluation Benchmark Tables
+
+- Added 5 new tables: `agent_eval_benchmarks`, `agent_eval_datasets`, `agent_eval_records`, `agent_eval_runs`, `agent_eval_run_topics`
+
+### Notes for Self-hosted Users
+
+- The migration runs automatically on application startup
+- No manual intervention required
+
+The migration owner: @arvinxx — responsible for this database schema change, reach out for any migration-related issues.

.agents/skills/version-release/reference/changelog-example/weekly-release.md

@@ -0,0 +1,46 @@
+# Patch Release (Weekly) Changelog Example
+
+A real-world changelog reference for weekly patch release PR bodies.
+
+---
+
+This release includes **82 commits** , Key updates are below.
+
+### New Features and Enhancements
+
+- Added **Agent Benchmark** support for more systematic agent performance evaluation.
+- Introduced the **video generation** feature end-to-end, including entry points, sidebar "new" badge support, and skeleton loading for topic switching.
+- Expanded memory capabilities: support for memory effort/tool permission configuration and improved timeout calculation for memory analysis tasks.
+- Added desktop editor support for image upload via file picker.
+
+### Models and Provider Expansion
+
+- Added a new provider: **Straico**.
+- Added/updated support for:
+  - Claude Sonnet 4.6
+  - Gemini 3.1 Pro Preview
+  - Qwen3.5 series
+  - Grok Imagine (`grok-imagine-image`)
+  - MiniMax 2.5
+- Added related i18n copy and model parameter adaptations.
+
+### Desktop Improvements
+
+- Integrated `electron-liquid-glass` (macOS Tahoe).
+- Improved DMG background assets and desktop release workflow.
+
+### Stability, Security, and UX Fixes
+
+- Fixed multiple video generation pipeline issues: precharge refund handling, webhook token verification, pricing parameter usage, asset cleanup, and type safety.
+- Fixed `sanitizeFileName` path traversal risks and added unit tests.
+- Fixed MCP media URL generation with duplicated `APP_URL` prefix.
+- Fixed Qwen3 embedding failures caused by batch-size limits.
+- Fixed multiple UI/interaction issues, including mobile header agent selector/topic count, ChatInput scrolling behavior, and tooltip stacking context.
+- Fixed missing `@napi-rs/canvas` native bindings in Docker standalone builds.
+- Improved GitHub Copilot authentication retry behavior and response error handling in edge cases.
+
+### Credits
+
+Huge thanks to these contributors (alphabetical):
+
+@AmAzing129 @Coooolfan @Innei @ONLY-yours @Zhouguanyang @arvinxx @eaten-cake @hezhijie0327 @nekomeowww @rdmclin2 @rivertwilight @sxjeru @tjx666

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

@@ -0,0 +1,118 @@
+# Patch Release Scenarios
+
+All Patch Release scenarios automatically bump the patch version (e.g. 2.1.31 → 2.1.32). PR titles do not need to include a version number.
+
+---
+
+## 1. Weekly Release (canary → main)
+
+The most common release type. Collects a week's worth of changes from canary and ships them to main.
+
+### Steps
+
+1. **Create release branch from canary**
+
+```bash
+git checkout canary
+git pull origin canary
+git checkout -b release/weekly-{YYYYMMDD}
+git push -u origin release/weekly-{YYYYMMDD}
+```
+
+2. **Scan changes and write changelog**
+
+```bash
+git log main..canary --oneline
+git diff main...canary --stat
+```
+
+Write a user-facing changelog following the format in `patch-release-changelog-example.md`.
+
+3. **Create PR to main** with the changelog as the PR body
+
+```bash
+gh pr create \
+  --title "🚀 release: {YYYYMMDD}" \
+  --base main \
+  --head release/weekly-{YYYYMMDD} \
+  --body-file changelog.md
+```
+
+4. **After merge**: auto-tag-release detects `release/*` branch → auto patch +1.
+
+---
+
+## 2. Bug Hotfix
+
+Emergency bug fix shipped directly from main.
+
+### Steps
+
+1. **Create hotfix branch from main**
+
+```bash
+git checkout main
+git pull --rebase origin main
+git checkout -b hotfix/v{version}-{short-hash}
+git push -u origin hotfix/v{version}-{short-hash}
+```
+
+2. **Create PR to main** with a gitmoji prefix title (e.g. `🐛 fix: description`)
+
+3. **After merge**: auto-tag-release detects `hotfix/*` branch → auto patch +1.
+
+### Script
+
+```bash
+bun run hotfix:branch
+```
+
+---
+
+## 3. New Model Launch
+
+New AI model or provider support, typically contributed via community PRs.
+
+### How it works
+
+- Community contributors submit PRs with titles like `✨ feat: add xxx model` or `💄 style: support xxx models`
+- These PR title prefixes (`feat` / `style`) are in the auto-tag trigger list
+- No special branch naming or manual release steps required — merging the PR triggers auto patch +1
+
+### When Claude is involved
+
+If asked to add model support, just create a normal feature PR. The title prefix will trigger the release automatically.
+
+---
+
+## 4. DB Schema Migration
+
+Database schema changes that need to be released independently. These require a dedicated changelog explaining the migration for self-hosted users.
+
+### Steps
+
+1. **Create release branch from canary**
+
+```bash
+git checkout canary
+git pull origin canary
+git checkout -b release/db-migration-{name}
+git push -u origin release/db-migration-{name}
+```
+
+2. **Write a migration-specific changelog** — See `db-migration-changelog-example.md` for the format. This should explain:
+   - What tables/columns are added, modified, or removed
+   - Whether the migration is backwards-compatible
+   - Any action required by self-hosted users
+
+3. **Create PR to main** with the migration changelog as the PR body
+
+```bash
+gh pr create \
+  --title "👷 build: {migration description}" \
+  --base main \
+  --head release/db-migration-{name} \
+  --body-file changelog.md
+```
+
+4. **After merge**: auto-tag-release detects `release/*` branch → auto patch +1.

.agents/skills/zustand/SKILL.md

@@ -3,7 +3,7 @@ name: zustand
 description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
 ---
 
-# LobeChat Zustand State Management
+# LobeHub Zustand State Management
 
 ## Action Type Hierarchy
 

.env.desktop

@@ -4,4 +4,4 @@ FEATURE_FLAGS=-check_updates,+pin_list
 KEY_VAULTS_SECRET=oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE=
 DATABASE_URL=postgresql://postgres@localhost:5432/postgres
 SEARCH_PROVIDERS=search1api
-NEXT_PUBLIC_IS_DESKTOP_APP=1
+DESKTOP_BUILD=true

.env.example

@@ -247,6 +247,18 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # DOC_S3_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 # DOC_S3_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+# #######################################
+# ### Mobile SPA S3 Workflow ############
+# #######################################
+
+# Used by `bun run workflow:mobile-spa` to build mobile SPA, upload assets to S3, and generate template
+# MOBILE_S3_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# MOBILE_S3_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# MOBILE_S3_BUCKET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# MOBILE_S3_ENDPOINT=https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# MOBILE_S3_REGION=auto
+# MOBILE_S3_PUBLIC_DOMAIN=https://cdn.example.com
+# MOBILE_S3_KEY_PREFIX=mobile/latest  # optional, S3 key path prefix
 
 # #######################################
 # #### S3 Object Storage Service ########
@@ -374,6 +386,12 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # Specify the Embedding model and Reranker model(unImplemented)
 # DEFAULT_FILES_CONFIG="embedding_model=openai/embedding-text-3-small,reranker_model=cohere/rerank-english-v3.0,query_mode=full_text"
 
+# Embedding batch size for processing (default: 50)
+# EMBEDDING_BATCH_SIZE=50
+
+# Embedding concurrency for parallel processing (default: 10)
+# EMBEDDING_CONCURRENCY=10
+
 # #######################################
 # ######### MCP Service Config ##########
 # #######################################

.eslintrc.js

@@ -1,63 +0,0 @@
-const config = require('@lobehub/lint').eslint;
-
-config.root = true;
-config.extends.push('plugin:@next/next/recommended-legacy');
-
-config.rules['unicorn/no-negated-condition'] = 0;
-config.rules['unicorn/prefer-type-error'] = 0;
-config.rules['unicorn/prefer-logical-operator-over-ternary'] = 0;
-config.rules['unicorn/no-null'] = 0;
-config.rules['unicorn/no-typeof-undefined'] = 0;
-config.rules['unicorn/explicit-length-check'] = 0;
-config.rules['unicorn/prefer-code-point'] = 0;
-config.rules['no-extra-boolean-cast'] = 0;
-config.rules['unicorn/no-useless-undefined'] = 0;
-config.rules['react/no-unknown-property'] = 0;
-config.rules['unicorn/prefer-ternary'] = 0;
-config.rules['unicorn/prefer-spread'] = 0;
-config.rules['unicorn/catch-error-name'] = 0;
-config.rules['unicorn/no-array-for-each'] = 0;
-config.rules['unicorn/prefer-number-properties'] = 0;
-config.rules['unicorn/prefer-query-selector'] = 0;
-config.rules['unicorn/no-array-callback-reference'] = 0;
-config.rules['unicorn/text-encoding-identifier-case'] = 0;
-config.rules['@typescript-eslint/no-use-before-define'] = 0;
-// FIXME: Linting error in src/app/[variants]/(main)/chat/features/Migration/DBReader.ts, the fundamental solution should be upgrading typescript-eslint
-config.rules['@typescript-eslint/no-useless-constructor'] = 0;
-config.rules['@next/next/no-img-element'] = 0;
-
-config.overrides = [
-  {
-    extends: ['plugin:mdx/recommended'],
-    files: ['*.mdx'],
-    rules: {
-      '@typescript-eslint/no-unused-vars': 1,
-      'micromark-extension-mdx-jsx': 0,
-      'no-undef': 0,
-      'react/jsx-no-undef': 0,
-      'react/no-unescaped-entities': 0,
-    },
-    settings: {
-      'mdx/code-blocks': false,
-    },
-  },
-  {
-    files: ['src/store/image/**/*', 'src/types/generation/**/*'],
-    rules: {
-      '@typescript-eslint/no-empty-interface': 0,
-      'sort-keys-fix/sort-keys-fix': 0,
-      'typescript-sort-keys/interface': 0,
-      'typescript-sort-keys/string-enum': 0,
-    },
-  },
-  // CLI scripts legitimately use process.exit() and async IIFE patterns
-  {
-    files: ['scripts/**/*'],
-    rules: {
-      'unicorn/no-process-exit': 0,
-      'unicorn/prefer-top-level-await': 0,
-    },
-  },
-];
-
-module.exports = config;

.github/scripts/pr-comment.js

@@ -2,8 +2,7 @@
  * Generate PR comment with download links for desktop builds
  * and handle comment creation/update logic
  */
-module.exports = async ({ github, context, releaseUrl, version, tag }) => {
-  // 用于识别构建评论的标识符
+const prComment = async ({ github, context, releaseUrl, artifactsUrl, version, tag }) => {
   const COMMENT_IDENTIFIER = '<!-- DESKTOP-BUILD-COMMENT -->';
 
   /**
@@ -69,7 +68,7 @@ module.exports = async ({ github, context, releaseUrl, version, tag }) => {
 **Version**: \`${version}\`
 **Build Time**: \`${new Date().toISOString()}\`
 
-📦 [View All Build Artifacts](${releaseUrl})
+📦 [Release Download](${releaseUrl}) · 📥 [Actions Artifacts](${artifactsUrl || `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`})
 
 
 ## Build Artifacts
@@ -88,7 +87,7 @@ ${assetTable}
 **Version**: \`${version}\`
 **Build Time**: \`${new Date().toISOString()}\`
 
-## 📦 [View All Build Artifacts](${releaseUrl})
+📦 [Release Download](${releaseUrl}) · 📥 [Actions Artifacts](${artifactsUrl || `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`})
 
 > Note: This is a temporary build for testing purposes only.
       `;
@@ -96,45 +95,41 @@ ${assetTable}
   };
 
   /**
-   * 查找并更新或创建PR评论
+   * Find and update or create the PR comment
    */
   const updateOrCreateComment = async () => {
-    // 生成评论内容
     const body = await generateCommentBody();
 
-    // 查找我们之前可能创建的评论
     const { data: comments } = await github.rest.issues.listComments({
       issue_number: context.issue.number,
       owner: context.repo.owner,
       repo: context.repo.repo,
     });
 
-    // 查找包含我们标识符的评论
     const buildComment = comments.find((comment) => comment.body.includes(COMMENT_IDENTIFIER));
 
     if (buildComment) {
-      // 如果找到现有评论，则更新它
       await github.rest.issues.updateComment({
         comment_id: buildComment.id,
         owner: context.repo.owner,
         repo: context.repo.repo,
         body: body,
       });
-      console.log(`已更新现有评论 ID: ${buildComment.id}`);
+      console.log(`Updated existing comment ID: ${buildComment.id}`);
       return { updated: true, id: buildComment.id };
     } else {
-      // 如果没有找到现有评论，则创建新评论
       const result = await github.rest.issues.createComment({
         issue_number: context.issue.number,
         owner: context.repo.owner,
         repo: context.repo.repo,
         body: body,
       });
-      console.log(`已创建新评论 ID: ${result.data.id}`);
+      console.log(`Created new comment ID: ${result.data.id}`);
       return { updated: false, id: result.data.id };
     }
   };
 
-  // 执行评论更新或创建
   return await updateOrCreateComment();
 };
+
+module.exports = prComment;

.github/workflows/auto-tag-release.yml

@@ -4,7 +4,7 @@ permissions:
   contents: write
 
 on:
-  pull_request:
+  pull_request_target:
     types: [closed]
     branches:
       - main
@@ -24,28 +24,91 @@ jobs:
           # Fetch full history for proper tagging
           fetch-depth: 0
 
-      - name: Check and extract version from PR title
-        id: extract-version
+      - name: Detect release PR (version from title)
+        id: release
         run: |
           PR_TITLE="${{ github.event.pull_request.title }}"
           echo "PR Title: $PR_TITLE"
 
-          # Match "🚀 release: v{x.x.x}" format
-          if [[ "$PR_TITLE" =~ ^🚀[[:space:]]+release:[[:space:]]*v([0-9]+\.[0-9]+\.[0-9]+.*)$ ]]; then
+          # Match "🚀 release: v{x.x.x}" format (strict semver: x.y.z with optional -prerelease or +build)
+          if [[ "$PR_TITLE" =~ ^🚀[[:space:]]+release:[[:space:]]*v([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?)$ ]]; then
             VERSION="${BASH_REMATCH[1]}"
             echo "version=$VERSION" >> $GITHUB_OUTPUT
             echo "should_tag=true" >> $GITHUB_OUTPUT
             echo "✅ Detected release PR, version: v$VERSION"
           else
             echo "should_tag=false" >> $GITHUB_OUTPUT
-            echo "⏭️ Not a release PR, skipping tag creation"
+            echo "⏭️ Not a release PR"
           fi
 
+      - name: Detect patch PR (branch first, title fallback)
+        id: patch
+        if: steps.release.outputs.should_tag != 'true'
+        run: |
+          HEAD_REF="${{ github.event.pull_request.head.ref }}"
+          PR_TITLE="${{ github.event.pull_request.title }}"
+          echo "Head ref: $HEAD_REF"
+          echo "PR Title: $PR_TITLE"
+
+          # Priority 1: hotfix/* or release/* branch always triggers, ignore PR title gate.
+          if [[ "$HEAD_REF" == hotfix/* ]] || [[ "$HEAD_REF" == release/* ]]; then
+            echo "should_tag=true" >> $GITHUB_OUTPUT
+            echo "✅ Detected auto-release PR from $HEAD_REF branch (title gate bypassed)"
+            exit 0
+          fi
+
+          # Priority 2: fallback to PR title prefix gate (legacy behavior).
+          if echo "$PR_TITLE" | grep -qiE '^(💄[[:space:]]*)?style(\(.+\))?:|^(✨[[:space:]]*)?feat(\(.+\))?:|^(🐛[[:space:]]*)?fix(\(.+\))?:|^(♻️[[:space:]]*)?refactor(\(.+\))?:|^((🐛|🩹)[[:space:]]*)?hotfix(\(.+\))?:|^(👷[[:space:]]*)?build(\(.+\))?:'; then
+            echo "should_tag=true" >> $GITHUB_OUTPUT
+            echo "✅ Detected patch PR from title prefix gate"
+          else
+            echo "should_tag=false" >> $GITHUB_OUTPUT
+            echo "⏭️ Not a patch PR (neither hotfix/release branch nor style/feat/fix/refactor/hotfix/build title prefix)"
+          fi
+
+      - name: Prepare main branch
+        if: steps.release.outputs.should_tag == 'true' || steps.patch.outputs.should_tag == 'true'
+        run: |
+          git checkout main
+          git pull --rebase origin main
+
+      - name: Resolve patch version (patch bump)
+        id: patch-version
+        if: steps.patch.outputs.should_tag == 'true'
+        run: |
+          CURRENT_VERSION="$(node -p "require('./package.json').version")"
+          echo "Current version: ${CURRENT_VERSION}"
+
+          # Coerce to stable base (e.g. 2.0.0-beta.1 -> 2.0.0), then bump patch (-> 2.0.1)
+          BASE_VERSION="$(npx -y semver@7 "${CURRENT_VERSION}" -c)"
+          if [ -z "${BASE_VERSION}" ]; then
+            echo "❌ Invalid version in package.json: ${CURRENT_VERSION}"
+            exit 1
+          fi
+
+          NEXT_VERSION="$(npx -y semver@7 -i patch "${BASE_VERSION}")"
+          echo "📦 Patch version: ${NEXT_VERSION}"
+          echo "version=${NEXT_VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Set context (release)
+        if: steps.release.outputs.should_tag == 'true'
+        run: |
+          echo "SHOULD_TAG=true" >> $GITHUB_ENV
+          echo "KIND=release" >> $GITHUB_ENV
+          echo "VERSION=${{ steps.release.outputs.version }}" >> $GITHUB_ENV
+
+      - name: Set context (patch)
+        if: steps.patch.outputs.should_tag == 'true'
+        run: |
+          echo "SHOULD_TAG=true" >> $GITHUB_ENV
+          echo "KIND=patch" >> $GITHUB_ENV
+          echo "VERSION=${{ steps.patch-version.outputs.version }}" >> $GITHUB_ENV
+
       - name: Check if tag already exists
-        if: steps.extract-version.outputs.should_tag == 'true'
+        if: env.SHOULD_TAG == 'true'
         id: check-tag
         run: |
-          VERSION="${{ steps.extract-version.outputs.version }}"
+          VERSION="${{ env.VERSION }}"
           if git rev-parse "v$VERSION" >/dev/null 2>&1; then
             echo "exists=true" >> $GITHUB_OUTPUT
             echo "⚠️ Tag v$VERSION already exists"
@@ -54,21 +117,59 @@ jobs:
             echo "✅ Tag v$VERSION does not exist, can create"
           fi
 
-      - name: Create Tag
-        if: steps.extract-version.outputs.should_tag == 'true' && steps.check-tag.outputs.exists == 'false'
+      - name: Bump package.json version (before tagging)
+        if: env.SHOULD_TAG == 'true' && steps.check-tag.outputs.exists == 'false'
+        id: bump-version
         run: |
-          VERSION="${{ steps.extract-version.outputs.version }}"
-          echo "🏷️ Creating tag: v$VERSION"
+          VERSION="${{ env.VERSION }}"
+          KIND="${{ env.KIND }}"
+          echo "📝 Bumping package.json version to: $VERSION"
+
+          # Validate VERSION is strict semver before writing
+          if ! npx -y semver@7 "$VERSION" >/dev/null 2>&1; then
+            echo "❌ Invalid semver version: $VERSION"
+            exit 1
+          fi
 
           # Configure git
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "lobehubbot"
+          git config --global user.email "i@lobehub.com"
 
-          # Get PR merge commit SHA
-          MERGE_SHA="${{ github.event.pull_request.merge_commit_sha }}"
+          # Update package.json using Node.js
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+            const target = '$VERSION';
+            if (pkg.version === target) {
+              console.log('✅ package.json already at version', target);
+              process.exit(0);
+            }
+            pkg.version = target;
+            fs.writeFileSync('./package.json', JSON.stringify(pkg, null, 2) + '\n');
+            console.log('✅ package.json updated to', target);
+          "
+
+          # Commit changes (if any) and push
+          git add package.json
+          COMMIT_MSG="🔖 chore(release): release version v$VERSION [skip ci]"
+          git commit -m "$COMMIT_MSG" || echo "Nothing to commit"
+          git push origin HEAD:main
+
+          # Output the SHA we will tag
+          echo "tag_sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Create Tag
+        if: env.SHOULD_TAG == 'true' && steps.check-tag.outputs.exists == 'false'
+        run: |
+          VERSION="${{ env.VERSION }}"
+          KIND="${{ env.KIND }}"
+          echo "🏷️ Creating tag: v$VERSION"
+
+          # Tag the bumped version commit SHA (not the PR merge commit SHA)
+          TAG_SHA="${{ steps.bump-version.outputs.tag_sha }}"
 
           # Create annotated tag with single line message
-          git tag -a "v$VERSION" "$MERGE_SHA" -m "🚀 release: v$VERSION | PR #${{ github.event.pull_request.number }} | Author: ${{ github.event.pull_request.user.login }}"
+          git tag -a "v$VERSION" "$TAG_SHA" -m "🚀 release: v$VERSION | PR #${{ github.event.pull_request.number }} | Author: ${{ github.event.pull_request.user.login }}"
 
           # Push tag
           git push origin "v$VERSION"
@@ -76,13 +177,13 @@ jobs:
           echo "✅ Tag v$VERSION created successfully!"
 
       - name: Create GitHub Release
-        if: steps.extract-version.outputs.should_tag == 'true' && steps.check-tag.outputs.exists == 'false'
+        if: env.SHOULD_TAG == 'true' && steps.check-tag.outputs.exists == 'false'
         uses: softprops/action-gh-release@v1
         with:
-          tag_name: v${{ steps.extract-version.outputs.version }}
-          name: 🚀 Release v${{ steps.extract-version.outputs.version }}
+          tag_name: v${{ env.VERSION }}
+          name: 🚀 Release v${{ env.VERSION }}
           body: |
-            ## 📦 Release v${{ steps.extract-version.outputs.version }}
+            ## 📦 Release v${{ env.VERSION }}
 
             This release was automatically published from PR #${{ github.event.pull_request.number }}.
 
@@ -95,14 +196,22 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
 
+      - name: Sync main to canary
+        if: env.SHOULD_TAG == 'true' && steps.check-tag.outputs.exists == 'false'
+        run: |
+          gh workflow run sync-main-to-canary.yaml
+          echo "✅ Dispatched sync-main-to-canary workflow"
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+
       - name: Output result
         run: |
-          if [ "${{ steps.extract-version.outputs.should_tag }}" == "true" ]; then
+          if [ "${{ env.SHOULD_TAG }}" == "true" ]; then
             if [ "${{ steps.check-tag.outputs.exists }}" == "true" ]; then
-              echo "⚠️ Result: Tag v${{ steps.extract-version.outputs.version }} already exists, skipping creation"
+              echo "⚠️ Result: Tag v${{ env.VERSION }} already exists, skipping creation"
             else
-              echo "✅ Result: Tag v${{ steps.extract-version.outputs.version }} created successfully!"
+              echo "✅ Result: Tag v${{ env.VERSION }} created successfully!"
             fi
           else
-            echo "ℹ️ Result: Not a release PR, no tag created"
+            echo "ℹ️ Result: Not a release/patch PR, no tag created"
           fi

.github/workflows/claude-auto-e2e-testing.yml

@@ -21,7 +21,7 @@ env:
   DATABASE_DRIVER: node
   KEY_VAULTS_SECRET: LA7n9k3JdEcbSgml2sxfw+4TV1AzaaFU5+R176aQz4s=
   AUTH_SECRET: e2e-test-secret-key-for-better-auth-32chars!
-  AUTH_EMAIL_VERIFICATION: "0"
+  AUTH_EMAIL_VERIFICATION: '0'
   S3_ACCESS_KEY_ID: e2e-mock-access-key
   S3_SECRET_ACCESS_KEY: e2e-mock-secret-key
   S3_BUCKET: e2e-mock-bucket
@@ -43,14 +43,13 @@ jobs:
           POSTGRES_PASSWORD: postgres
         options: >-
           --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
         ports:
           - 5432:5432
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
@@ -67,7 +66,7 @@ jobs:
       - name: Build application
         run: bun run build
         env:
-          SKIP_LINT: "1"
+          SKIP_LINT: '1'
 
       - name: Configure Git
         run: |
@@ -85,7 +84,7 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           github_token: ${{ secrets.GH_TOKEN }}
-          allowed_non_write_users: "*"
+          allowed_non_write_users: '*'
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           claude_args: |
             --allowedTools "Bash,Read,Edit,Write,Glob,Grep"

.github/workflows/claude-auto-testing.yml

@@ -28,8 +28,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2

.github/workflows/claude-dedupe-issues.yml

@@ -21,8 +21,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Copy security prompt
         run: |

.github/workflows/claude-translate-comments.yml

@@ -28,8 +28,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Configure Git
         run: |

.github/workflows/claude-translator.yml

@@ -32,8 +32,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Copy security prompt
         run: |

.github/workflows/claude.yml

@@ -27,8 +27,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
 
       - name: Copy security prompt
         run: |

.github/workflows/e2e.yml

@@ -39,7 +39,10 @@ jobs:
 
   e2e:
     needs: check-duplicate-run
-    if: needs.check-duplicate-run.outputs.should_skip != 'true'
+    if: >-
+      github.ref == 'refs/heads/main' ||
+      github.ref == 'refs/heads/canary' ||
+      needs.check-duplicate-run.outputs.should_skip != 'true'
     name: Test Web App
     runs-on: ubuntu-latest
     services:

.github/workflows/manual-build-desktop.yml

@@ -51,8 +51,6 @@ jobs:
       version: ${{ steps.set_version.outputs.version }}
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -103,8 +101,6 @@ jobs:
         os: [macos-latest, macos-15-intel]
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node & pnpm
         uses: ./.github/actions/setup-node-pnpm
@@ -181,8 +177,6 @@ jobs:
     runs-on: windows-2025
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup build environment
         uses: ./.github/actions/desktop-build-setup
@@ -227,8 +221,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node & pnpm
         uses: ./.github/actions/setup-node-pnpm

.github/workflows/pr-build-desktop.yml

@@ -26,8 +26,6 @@ jobs:
     steps:
       - name: Checkout base
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node & Bun
         uses: ./.github/actions/setup-node-bun
@@ -56,8 +54,6 @@ jobs:
       version: ${{ steps.set_version.outputs.version }}
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -96,8 +92,6 @@ jobs:
         os: [macos-latest, macos-15-intel, windows-2025, ubuntu-latest]
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node & pnpm
         uses: ./.github/actions/setup-node-pnpm
@@ -286,8 +280,6 @@ jobs:
       artifact_path: ${{ steps.set_path.outputs.path }}
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       # 下载合并后的构建产物
       - name: Download merged artifacts
@@ -340,21 +332,23 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # 在 PR 上添加评论，包含构建信息和下载链接
+      # Post comment on PR with build info, release download link, and Actions artifacts link
       - name: Comment on PR
         uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |
             const releaseUrl = "${{ steps.create_release.outputs.url }}";
+            const artifactsUrl = "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}";
             const prCommentGenerator = require('${{ github.workspace }}/.github/scripts/pr-comment.js');
 
             const result = await prCommentGenerator({
               github,
               context,
               releaseUrl,
+              artifactsUrl,
               version: "${{ needs.version.outputs.version }}",
               tag: "v${{ needs.version.outputs.version }}"
             });
 
-            console.log(`评论状态: ${result.updated ? '已更新' : '已创建'}, ID: ${result.id}`);
+            console.log(`Comment ${result.updated ? 'updated' : 'created'}, ID: ${result.id}`);

.github/workflows/pr-build-docker.yml

@@ -39,8 +39,6 @@ jobs:
 
       - name: Checkout PR branch
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -107,8 +105,6 @@ jobs:
     steps:
       - name: Checkout PR branch
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Download digests
         uses: actions/download-artifact@v7

.github/workflows/release-desktop-beta.yml

@@ -61,8 +61,6 @@ jobs:
     steps:
       - name: Checkout base
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -91,8 +89,6 @@ jobs:
         os: [macos-latest, macos-15-intel, windows-2025, ubuntu-latest]
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup build environment
         uses: ./.github/actions/desktop-build-setup

.github/workflows/release-desktop-canary.yml

@@ -0,0 +1,394 @@
+name: Release Desktop Canary
+
+# ============================================
+# Canary 自动发版工作流
+# ============================================
+# 触发条件:
+#   1. canary 分支有 push (合入 PR) 且 commit 前缀为 style/feat/fix/refactor/release (支持 gitmoji)
+#   2. 手动触发 (workflow_dispatch)
+#
+# 并发策略:
+#   同一 workflow 仅保留最新一次运行，自动取消排队中的旧 build
+#
+# 版本策略:
+#   基于最新 stable tag 的 patch+1, postfix 为递增序号
+#   格式: X.Y.(Z+1)-canary.N
+#   例: 当前 tag v2.1.28 → v2.1.29-canary.1, 下次 → v2.1.29-canary.2
+# ============================================
+
+on:
+  push:
+    branches:
+      - canary
+  workflow_dispatch:
+    inputs:
+      force:
+        description: 'Force build (skip commit message check)'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+permissions: read-all
+
+env:
+  NODE_VERSION: '24.11.1'
+
+jobs:
+  # ============================================
+  # 检查 commit 前缀并计算版本号
+  # ============================================
+  calculate-version:
+    name: Calculate Canary Version
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+      should_build: ${{ steps.check.outputs.should_build }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check commit message prefix
+        id: check
+        run: |
+          # 手动触发 + force 时跳过检查
+          if [ "${{ inputs.force }}" == "true" ]; then
+            echo "should_build=true" >> $GITHUB_OUTPUT
+            echo "🔧 Force build requested, skipping commit check"
+            exit 0
+          fi
+
+          # 手动触发 (无 force) 也直接构建
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            echo "should_build=true" >> $GITHUB_OUTPUT
+            echo "🔧 Manual trigger, proceeding with build"
+            exit 0
+          fi
+
+          # 获取本次 push 的 head commit message
+          commit_msg=$(git log -1 --pretty=%s HEAD)
+          echo "📝 Head commit: $commit_msg"
+
+          # 检查是否匹配 style/feat/fix/refactor/release 前缀 (支持 gitmoji 前缀)
+          if echo "$commit_msg" | grep -qiE '^(💄\s*)?style(\(.+\))?:|^(✨\s*)?feat(\(.+\))?:|^(🐛\s*)?fix(\(.+\))?:|^(♻️\s*)?refactor(\(.+\))?:|^(🚀\s*)?release(\(.+\))?:'; then
+            echo "should_build=true" >> $GITHUB_OUTPUT
+            echo "✅ Commit matches canary build trigger: $commit_msg"
+          else
+            echo "should_build=false" >> $GITHUB_OUTPUT
+            echo "⏭️ Commit does not match style/feat/fix/refactor/release prefix, skipping: $commit_msg"
+          fi
+
+      - name: Calculate canary version
+        if: steps.check.outputs.should_build == 'true'
+        id: version
+        run: |
+          # 获取最新的 stable tag (排除 nightly/canary/beta 等)
+          latest_tag=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
+
+          if [ -z "$latest_tag" ]; then
+            echo "❌ No stable tag found"
+            exit 1
+          fi
+
+          echo "📌 Latest stable tag: $latest_tag"
+
+          # 去掉 v 前缀，解析 major.minor.patch → a.b.c 取 c+1
+          base_version="${latest_tag#v}"
+          IFS='.' read -r major minor patch <<< "$base_version"
+          new_patch=$((patch + 1))
+          base_canary="${major}.${minor}.${new_patch}"
+
+          # postfix: 同 base 下已有 canary 标签的最大序号 + 1
+          max_seq=0
+          for t in $(git tag -l "v${base_canary}-canary.*" 2>/dev/null || true); do
+            seq=$(echo "$t" | grep -oE '[0-9]+$' || true)
+            if [ -n "$seq" ] && [ "$seq" -gt "$max_seq" ] 2>/dev/null; then
+              max_seq=$seq
+            fi
+          done
+          next_seq=$((max_seq + 1))
+
+          version="${base_canary}-canary.${next_seq}"
+          tag="v${version}"
+
+          echo "version=${version}" >> $GITHUB_OUTPUT
+          echo "tag=${tag}" >> $GITHUB_OUTPUT
+          echo "✅ Canary version: ${version}"
+          echo "🏷️ Tag: ${tag}"
+
+  # ============================================
+  # 代码质量检查
+  # ============================================
+  test:
+    name: Code quality check
+    needs: [calculate-version]
+    if: needs.calculate-version.outputs.should_build == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout base
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          package-manager-cache: false
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install deps
+        run: bun i
+
+      - name: Lint
+        run: bun run lint
+
+  # ============================================
+  # 多平台构建
+  # ============================================
+  build:
+    needs: [calculate-version, test]
+    if: needs.calculate-version.outputs.should_build == 'true'
+    name: Build Desktop App
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-15, macos-15-intel, windows-2025, ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup build environment
+        uses: ./.github/actions/desktop-build-setup
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Set package version
+        run: npm run workflow:set-desktop-version ${{ needs.calculate-version.outputs.version }} canary
+
+      # macOS 构建前清理 (修复 hdiutil 问题)
+      - name: Clean previous build artifacts (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          sudo rm -rf apps/desktop/release || true
+          sudo rm -rf apps/desktop/dist || true
+          sudo rm -rf /tmp/electron-builder* || true
+
+      # macOS 构建
+      - name: Build artifact on macOS
+        if: runner.os == 'macOS'
+        run: npm run desktop:package:app
+        env:
+          UPDATE_CHANNEL: canary
+          APP_URL: http://localhost:3015
+          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
+          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
+          CSC_LINK: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
+          CSC_KEY_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          CSC_FOR_PULL_REQUEST: true
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
+
+      # Windows 构建
+      - name: Build artifact on Windows
+        if: runner.os == 'Windows'
+        run: npm run desktop:package:app
+        env:
+          UPDATE_CHANNEL: canary
+          APP_URL: http://localhost:3015
+          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
+          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
+          TEMP: C:\temp
+          TMP: C:\temp
+
+      # Linux 构建
+      - name: Build artifact on Linux
+        if: runner.os == 'Linux'
+        run: npm run desktop:package:app
+        env:
+          UPDATE_CHANNEL: canary
+          APP_URL: http://localhost:3015
+          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
+          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
+
+      - name: Upload artifacts
+        uses: ./.github/actions/desktop-upload-artifacts
+        with:
+          artifact-name: release-${{ matrix.os }}
+          retention-days: 3
+
+  # ============================================
+  # 合并 macOS 多架构 latest-mac.yml 文件
+  # ============================================
+  merge-mac-files:
+    needs: [build]
+    name: Merge macOS Release Files
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          package-manager-cache: false
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          path: release
+          pattern: release-*
+          merge-multiple: true
+
+      - name: List downloaded artifacts
+        run: ls -R release
+
+      - name: Install yaml only for merge step
+        run: |
+          cd scripts/electronWorkflow
+          if [ ! -f package.json ]; then
+            echo '{"name":"merge-mac-release","private":true}' > package.json
+          fi
+          bun add --no-save yaml@2.8.1
+
+      - name: Merge latest-mac.yml files
+        run: bun run scripts/electronWorkflow/mergeMacReleaseFiles.js
+
+      - name: Upload artifacts with merged macOS files
+        uses: actions/upload-artifact@v6
+        with:
+          name: merged-release
+          path: release/
+          retention-days: 1
+
+  # ============================================
+  # 创建 Canary Release
+  # ============================================
+  publish-release:
+    needs: [merge-mac-files, calculate-version]
+    name: Publish Canary Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download merged artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: merged-release
+          path: release
+
+      - name: List final artifacts
+        run: ls -R release
+
+      - name: Create Canary Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ needs.calculate-version.outputs.tag }}
+          name: 'Desktop Canary ${{ needs.calculate-version.outputs.tag }}'
+          prerelease: true
+          body: |
+            ## 🐤 Canary Build — ${{ needs.calculate-version.outputs.tag }}
+
+            > Automated canary build from `canary` branch.
+
+            ### ⚠️ Important Notes
+
+            - **This is an automated canary build and is NOT intended for production use.**
+            - Canary builds are triggered by `build`/`fix`/`style` commits on the `canary` branch.
+            - May contain **unstable or incomplete changes**. **Use at your own risk.**
+            - It is strongly recommended to **back up your data** before using a canary build.
+
+            ### 📦 Installation
+
+            Download the appropriate installer for your platform from the assets below.
+
+            | Platform | File |
+            |----------|------|
+            | macOS (Apple Silicon) | `.dmg` (arm64) |
+            | macOS (Intel) | `.dmg` (x64) |
+            | Windows | `.exe` |
+            | Linux | `.AppImage` / `.deb` |
+          files: |
+            release/latest*
+            release/*.dmg*
+            release/*.zip*
+            release/*.exe*
+            release/*.AppImage
+            release/*.deb*
+            release/*.snap*
+            release/*.rpm*
+            release/*.tar.gz*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # ============================================
+  # 清理旧的 Canary Releases (保留最近 7 个)
+  # ============================================
+  cleanup-old-canaries:
+    needs: [publish-release]
+    name: Cleanup Old Canary Releases
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Delete old canary releases
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: releases } = await github.rest.repos.listReleases({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+
+            const canaryReleases = releases
+              .filter(r => r.tag_name.includes('-canary.'))
+              .sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
+
+            const toDelete = canaryReleases.slice(7);
+
+            for (const release of toDelete) {
+              console.log(`🗑️ Deleting old canary release: ${release.tag_name}`);
+
+              // Delete the release
+              await github.rest.repos.deleteRelease({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                release_id: release.id,
+              });
+
+              // Delete the tag
+              try {
+                await github.rest.git.deleteRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: `tags/${release.tag_name}`,
+                });
+              } catch (e) {
+                console.log(`⚠️ Could not delete tag ${release.tag_name}: ${e.message}`);
+              }
+            }
+
+            console.log(`✅ Cleanup complete. Kept ${Math.min(canaryReleases.length, 7)} canary releases, deleted ${toDelete.length}.`);

.github/workflows/release-desktop-nightly.yml

@@ -48,7 +48,6 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          fetch-tags: true
 
       - name: Check for code changes since last nightly
         id: changes
@@ -128,8 +127,6 @@ jobs:
     steps:
       - name: Checkout base
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -162,8 +159,6 @@ jobs:
         os: [macos-15, macos-15-intel, windows-2025, ubuntu-latest]
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup build environment
         uses: ./.github/actions/desktop-build-setup

.github/workflows/release-desktop-stable.yml

@@ -84,6 +84,8 @@ jobs:
     steps:
       - name: Check release info
         id: check
+        env:
+          RELEASE_BODY: ${{ github.event.release.body || '' }}
         run: |
           # 判断触发方式
           if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
@@ -100,7 +102,7 @@ jobs:
             version="${version#v}"
             echo "is_manual=false" >> $GITHUB_OUTPUT
             echo "version=${version}" >> $GITHUB_OUTPUT
-            release_body="${{ github.event.release.body }}"
+            release_body="${RELEASE_BODY:-}"
             {
               echo "release_notes<<EOF"
               printf '%s\n' "$release_body"
@@ -174,8 +176,6 @@ jobs:
       matrix: ${{ fromJson(needs.configure-build.outputs.matrix) }}
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Setup build environment
         uses: ./.github/actions/desktop-build-setup

.github/workflows/release-docker.yml

@@ -3,7 +3,7 @@ permissions:
   contents: read
 
 on:
-  workflow_dispatch:
+  workflow_dispatch: {}
   release:
     types: [published]
 
@@ -33,8 +33,6 @@ jobs:
 
       - name: Checkout base
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -93,8 +91,6 @@ jobs:
     steps:
       - name: Checkout base
         uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
 
       - name: Download digests
         uses: actions/download-artifact@v7

.github/workflows/release.yml

@@ -73,28 +73,22 @@ jobs:
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "📦 Release version: v$VERSION"
 
-      - name: Update package.json version
+      - name: Verify package.json version matches tag
         run: |
           VERSION="${{ steps.get-version.outputs.version }}"
-          echo "📝 Updating package.json version to: $VERSION"
-          # Update package.json using Node.js
+          echo "🔎 Checking package.json version equals tag: $VERSION"
           node -e "
             const fs = require('fs');
             const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
-            pkg.version = '$VERSION';
-            fs.writeFileSync('./package.json', JSON.stringify(pkg, null, 2) + '\\n');
-            console.log('✅ package.json updated');
+            const expected = '$VERSION';
+            const actual = pkg.version;
+            if (actual !== expected) {
+              console.error('❌ Version mismatch: package.json=' + actual + ' tag=' + expected);
+              process.exit(1);
+            }
+            console.log('✅ Version OK:', actual);
           "
 
-          # Commit changes
-          git config --global user.name "lobehubbot"
-          git config --global user.email "i@lobehub.com"
-          git add package.json
-          git commit -m "🔧 chore(release): bump version to v$VERSION [skip ci]" || echo "Nothing to commit"
-          git push origin HEAD:main
-        env:
-          GH_TOKEN: ${{ secrets.GH_TOKEN }}
-
       - name: Release
         run: bun run release
         env:

.github/workflows/sync-main-to-canary.yaml

@@ -1,6 +1,7 @@
 name: 🔄 Branch Synchronization
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - main
@@ -9,6 +10,10 @@ permissions:
   contents: write
   pull-requests: write
 
+concurrency:
+  group: sync-main-to-canary
+  cancel-in-progress: true
+
 jobs:
   sync-branches:
     runs-on: ubuntu-latest
@@ -17,30 +22,108 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          token: ${{ secrets.GH_TOKEN }}
 
       - name: Set up Git
         run: |
           git config --global user.name 'lobehubbot'
           git config --global user.email 'i@lobehub.com'
 
-      - name: Prepare sync branch
-        id: branch
-        run: |
-          echo "SYNC_BRANCH_MAIN_CANARY=sync/main-to-canary-$(date +'%Y%m%d')" >> $GITHUB_ENV
-
       - name: Sync main to canary
         if: github.ref == 'refs/heads/main'
         run: |
-          # Sync main to canary
-          git checkout main
-          SYNC_BRANCH_CANARY=${{ env.SYNC_BRANCH_MAIN_CANARY }}
-          git checkout -B $SYNC_BRANCH_CANARY
-          DIFF=$(git diff origin/canary...)
-          if [ -z "$DIFF" ]; then
+          # Find existing open sync PR by head branch prefix
+          EXISTING_PR=$(gh pr list --base canary --state open --json number,headRefName \
+            --jq '[.[] | select(.headRefName | startswith("sync/main-to-canary-"))][0] // empty')
+          EXISTING_PR_NUMBER=$(echo "$EXISTING_PR" | jq -r '.number // empty' 2>/dev/null)
+
+          # Refresh remote refs to avoid stale comparisons
+          git fetch origin canary main
+
+          # Check if there are actual changes to sync
+          if [ "$(git rev-parse origin/main)" = "$(git rev-parse origin/canary)" ]; then
             echo "No changes to sync"
             exit 0
           fi
-          git push origin $SYNC_BRANCH_CANARY -f
-          gh pr create --base canary --head $SYNC_BRANCH_CANARY --title "Sync main branch to canary branch" --body "Automatic sync" || exit 0
+
+          close_stale_pr() {
+            if [ -n "$EXISTING_PR_NUMBER" ]; then
+              gh pr close "$EXISTING_PR_NUMBER" --comment "Superseded by $1." --delete-branch || true
+            fi
+          }
+
+          # 1) Fast-forward: canary is ancestor of main → just move canary pointer
+          if git merge-base --is-ancestor origin/canary origin/main; then
+            echo "canary is ancestor of main, fast-forwarding"
+            git checkout canary
+            git reset --hard origin/main
+            if git push origin canary; then
+              close_stale_pr "fast-forward push"
+              exit 0
+            fi
+            echo "Fast-forward push failed, falling back to merge"
+          fi
+
+          # 2) Merge: canary has unique commits but no conflicts
+          git checkout canary
+          git reset --hard origin/canary
+          if git merge origin/main --no-edit; then
+            echo "Merge succeeded, pushing directly"
+            if git push origin canary; then
+              close_stale_pr "direct merge push"
+              exit 0
+            fi
+
+            # Direct push failed (e.g. non-fast-forward race), fall back to PR
+            echo "Direct push failed, falling back to PR"
+            SYNC_BRANCH="sync/main-to-canary-$(date +'%Y%m%d')-${GITHUB_RUN_ID}"
+            git checkout -B "$SYNC_BRANCH"
+            git push origin "$SYNC_BRANCH" -f
+            gh pr create \
+              --base canary \
+              --head "$SYNC_BRANCH" \
+              --title "🚀 release: sync main branch to canary" \
+              --body "Automatic sync from main to canary. Direct push failed, please merge this PR." || true
+            exit 0
+          fi
+
+          # 3) Conflicts: create or update PR for manual resolution
+          echo "Merge conflicts detected, creating PR"
+          git merge --abort
+
+          if [ -n "$EXISTING_PR_NUMBER" ]; then
+            gh pr comment "$EXISTING_PR_NUMBER" --body "New commits on \`main\`. Please pull latest \`origin/main\` into this branch to include them."
+            echo "Commented on existing PR #$EXISTING_PR_NUMBER"
+          else
+            SYNC_BRANCH="sync/main-to-canary-$(date +'%Y%m%d')-${GITHUB_RUN_ID}"
+            git checkout -B "$SYNC_BRANCH" origin/canary
+            if ! git merge origin/main --no-edit; then
+              git add -A
+              git commit --no-edit -m "chore: merge main into canary (has conflicts to resolve)"
+            fi
+            git push origin "$SYNC_BRANCH" -f
+
+            printf '%s\n' \
+              'Automatic sync from main to canary. Merge conflicts detected.' \
+              '' \
+              '**Resolution steps:**' \
+              '```bash' \
+              'git fetch origin' \
+              "git checkout $SYNC_BRANCH" \
+              'git merge origin/main' \
+              '# Resolve conflicts' \
+              'git add -A && git commit' \
+              'git push' \
+              '```' \
+              '' \
+              '> Do NOT merge canary into a main-based branch — always merge main INTO the canary-based branch to keep a clean commit graph.' \
+              > /tmp/pr-body.md
+
+            gh pr create \
+              --base canary \
+              --head "$SYNC_BRANCH" \
+              --title "🚀 release: sync main branch to canary" \
+              --body-file /tmp/pr-body.md
+          fi
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}

.github/workflows/verify-desktop-patch.yml

@@ -1,55 +0,0 @@
-name: Verify Desktop Patch
-
-on:
-  push:
-    branches:
-      - main
-      - next
-      - dev
-    paths:
-      - 'scripts/electronWorkflow/**'
-      - 'src/libs/next/config/**'
-      - 'src/app/**'
-      - 'src/layout/**'
-      - 'src/components/mdx/**'
-      - 'src/features/DevPanel/**'
-      - 'src/server/translation.ts'
-  pull_request:
-    paths:
-      - 'scripts/electronWorkflow/**'
-      - 'src/libs/next/config/**'
-      - 'src/app/**'
-      - 'src/layout/**'
-      - 'src/components/mdx/**'
-      - 'src/features/DevPanel/**'
-      - 'src/server/translation.ts'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-env:
-  NODE_VERSION: 24.11.1
-  BUN_VERSION: 1.2.23
-
-jobs:
-  verify:
-    name: Desktop patch smoke test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node & Bun
-        uses: ./.github/actions/setup-node-bun
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          bun-version: ${{ env.BUN_VERSION }}
-
-      - name: Install deps
-        run: bun i
-
-      - name: Verify desktop patch
-        run: bun scripts/electronWorkflow/modifiers/index.mts

.github/workflows/verify-electron-codemod.yml

@@ -1,64 +0,0 @@
-name: Verify Electron i18n Codemod
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-      - dev
-
-concurrency:
-  group: verify-electron-codemod-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-env:
-  NODE_VERSION: 24.11.1
-  BUN_VERSION: 1.2.23
-
-jobs:
-  verify-codemod:
-    name: Verify i18n codemod on temp workspace
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Enable Corepack
-        run: corepack enable
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          run_install: false
-
-      - name: Get pnpm store directory
-        id: pnpm-store
-        run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Cache pnpm store
-        uses: actions/cache@v5
-        with:
-          path: ${{ steps.pnpm-store.outputs.STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ env.NODE_VERSION }}-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-${{ env.NODE_VERSION }}-
-            ${{ runner.os }}-pnpm-store-
-
-      - name: Setup bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
-
-      - name: Install dependencies
-        run: pnpm install --node-linker=hoisted
-
-      - name: Run electron workflow modifiers
-        run: bun scripts/electronWorkflow/modifiers/index.mts

.gitignore

@@ -52,6 +52,7 @@ bun.lockb
 
 # Build outputs
 dist/
+public/spa/
 es/
 lib/
 .next/
@@ -83,6 +84,7 @@ public/sw*
 public/swe-worker*
 
 # Generated files
+src/app/spa/[variants]/[[...path]]/spaHtmlTemplates.ts
 public/*.js
 public/sitemap.xml
 public/sitemap-index.xml
@@ -127,4 +129,6 @@ out
 i18n-unused-keys-report.json
 .vitest-reports
 
-pnpm-lock.yaml
+pnpm-lock.yaml
+.turbo
+spaHtmlTemplates.ts

.npmrc

@@ -18,3 +18,4 @@ public-hoist-pattern[]=*stylelint*
 
 public-hoist-pattern[]=@auth/core
 public-hoist-pattern[]=pdfjs-dist
+public-hoist-pattern[]=@napi-rs/canvas-*

.vscode/settings.json

@@ -53,7 +53,8 @@
     "typescriptreact"
   ],
   "typescript.tsdk": "node_modules/typescript/lib",
-  "vitest.maximumConfigs": 20,
+  "vitest.disableWorkspaceWarning": true,
+  "vitest.maximumConfigs": 10,
   "workbench.editor.customLabels.patterns": {
     "**/app/**/[[]*[]]/[[]*[]]/page.tsx": "${dirname(2)}/${dirname(1)}/${dirname} • page component",
     "**/app/**/[[]*[]]/page.tsx": "${dirname(1)}/${dirname} • page component",

AGENTS.md

@@ -38,7 +38,8 @@ lobe-chat/
 
 ### Git Workflow
 
-- The current release branch is `next` until v2.0.0 is officially released
+- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
+- New branches should be created from `canary`; PRs should target `canary`
 - Use rebase for git pull
 - Git commit messages should prefix with gitmoji
 - Git branch name format: `username/feat/feature-name`

CLAUDE.md

@@ -31,8 +31,28 @@ lobe-chat/
 
 ## Development
 
+### Starting the Dev Environment
+
+```bash
+# SPA dev mode (frontend only, proxies API to localhost:3010)
+bun run dev:spa
+
+# Full-stack dev (Next.js + Vite SPA concurrently)
+bun run dev
+```
+
+After `dev:spa` starts, the terminal prints a **Debug Proxy** URL:
+
+```
+Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876
+```
+
+Open this URL to develop locally against the production backend (app.lobehub.com). The proxy page loads your local Vite dev server's SPA into the online environment, enabling HMR with real server config.
+
 ### Git Workflow
 
+- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
+- New branches should be created from `canary`; PRs should target `canary`
 - Use rebase for `git pull`
 - Commit messages: prefix with gitmoji
 - Branch format: `<type>/<feature-name>`

Dockerfile

@@ -94,6 +94,10 @@ RUN set -e && \
 
 COPY . .
 
+# Prebuild: env checks (checkDeprecatedAuth, checkRequiredEnvVars, printEnvInfo) then remove desktop-only code
+RUN pnpm exec tsx scripts/dockerPrebuild.mts
+RUN rm -rf src/app/desktop "src/app/(backend)/trpc/desktop"
+
 # run build standalone for docker version
 RUN npm run build:docker
 
@@ -116,6 +120,8 @@ COPY --from=base /distroless/ /
 # Automatically leverage output traces to reduce image size
 # https://nextjs.org/docs/advanced-features/output-file-tracing
 COPY --from=builder /app/.next/standalone /app/
+# Copy SPA assets (Vite build output)
+COPY --from=builder /app/public/spa /app/public/spa
 # Copy Next export output for desktop renderer
 COPY --from=builder /app/apps/desktop/dist/next /app/apps/desktop/dist/next
 

GEMINI.md

@@ -33,6 +33,8 @@ lobe-chat/
 
 ### Git Workflow
 
+- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
+- New branches should be created from `canary`; PRs should target `canary`
 - Use rebase for `git pull`
 - Commit messages: prefix with gitmoji
 - Branch format: `<type>/<feature-name>`

README.md

@@ -709,9 +709,14 @@ Or clone it for local development:
 $ git clone https://github.com/lobehub/lobe-chat.git
 $ cd lobe-chat
 $ pnpm install
-$ pnpm dev
+$ pnpm dev          # Full-stack (Next.js + Vite SPA)
+$ bun run dev:spa   # SPA frontend only (port 9876)
 ```
 
+> **Debug Proxy**: After running `dev:spa`, the terminal prints a proxy URL like
+> `https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876`.
+> Open it to develop locally against the production backend with HMR.
+
 If you would like to learn more details, please feel free to look at our [📘 Development Guide][docs-dev-guide].
 
 <div align="right">