@lobehub/lobehub 2.0.0-next.353 → 2.0.0-next.354

package/GEMINI.md

@@ -1,64 +1,72 @@
 # GEMINI.md
 
-This document serves as a shared guideline for all team members when using Gemini CLI in this repository.
+Guidelines for using Gemini CLI in this LobeChat repository.
 
 ## Tech Stack
 
-read @.cursor/rules/project-introduce.mdc
-
-## Directory Structure
-
-read @.cursor/rules/project-structure.mdc
+- Next.js 16 + React 19 + TypeScript
+- SPA inside Next.js with `react-router-dom`
+- `@lobehub/ui`, antd for components; antd-style for CSS-in-JS
+- react-i18next for i18n; zustand for state management
+- SWR for data fetching; TRPC for type-safe backend
+- Drizzle ORM with PostgreSQL; Vitest for testing
+
+## Project Structure
+
+```
+lobe-chat/
+├── apps/desktop/           # Electron desktop app
+├── packages/               # Shared packages (@lobechat/*)
+│   ├── database/           # Database schemas, models, repositories
+│   ├── agent-runtime/      # Agent runtime
+│   └── ...
+├── src/
+│   ├── app/                # Next.js app router
+│   ├── store/              # Zustand stores
+│   ├── services/           # Client services
+│   ├── server/             # Server services and routers
+│   └── ...
+└── e2e/                    # E2E tests (Cucumber + Playwright)
+```
 
 ## Development
 
 ### Git Workflow
 
-- use rebase for git pull
-- git commit message should prefix with gitmoji
-- git branch name format template: <type>/<feature-name>
-- use .github/PULL_REQUEST_TEMPLATE.md to generate pull request description
-- PR titles starting with `✨ feat/` or `🐛 fix` will trigger the release workflow upon merge. Only use these prefixes for significant user-facing feature changes or bug fixes
+- Use rebase for `git pull`
+- Commit messages: prefix with gitmoji
+- Branch format: `<type>/<feature-name>`
+- PR titles with `✨ feat/` or `🐛 fix` trigger releases
 
 ### Package Management
 
-This repository adopts a monorepo structure.
-
-- Use `pnpm` as the primary package manager for dependency management
-- Use `bun` to run npm scripts
-- Use `bunx` to run executable npm packages
-
-### TypeScript Code Style Guide
-
-see @.cursor/rules/typescript.mdc
+- `pnpm` for dependency management
+- `bun` to run npm scripts
+- `bunx` for executable npm packages
 
 ### Testing
 
-- **Required Rule**: read `.cursor/rules/testing-guide/testing-guide.mdc` before writing tests
-- **Command**:
-  - web: `bunx vitest run --silent='passed-only' '[file-path-pattern]'`
-  - packages(eg: database): `cd packages/database && bunx vitest run --silent='passed-only' '[file-path-pattern]'`
-
-**Important**:
-
-- wrap the file path in single quotes to avoid shell expansion
-- Never run `bun run test` etc to run tests, this will run all tests and cost about 10mins
-- If trying to fix the same test twice, but still failed, stop and ask for help.
+```bash
+# Run specific test (NEVER run `bun run test` - takes ~10 minutes)
+bunx vitest run --silent='passed-only' '[file-path]'
 
-### Typecheck
+# Database package
+cd packages/database && bunx vitest run --silent='passed-only' '[file]'
+```
 
-- use `bun run type-check` to check type errors.
+- Tests must pass type check: `bun run type-check`
+- After 2 failed fix attempts, stop and ask for help
 
 ### i18n
 
-- **Keys**: Add to `src/locales/default/namespace.ts`
-- **Dev**: Translate `locales/zh-CN/namespace.json` and `locales/en-US/namespace.json` locales file only for dev preview
-- DON'T run `pnpm i18n`, let CI auto handle it
+- Add keys to `src/locales/default/namespace.ts`
+- For dev preview: translate `locales/zh-CN/` and `locales/en-US/`
+- Don't run `pnpm i18n` - CI handles it
 
-## 🚨 Quality Checks
+## Quality Checks
 
-**MANDATORY**: After completing code changes, always run `mcp__vscode-mcp__get_diagnostics` on the modified files to identify any errors introduced by your changes and fix them.
+**MANDATORY**: After completing code changes, run diagnostics on modified files to identify and fix any errors.
 
-## Rules Index
+## Skills (Auto-loaded)
 
-Some useful project rules are listed in @.cursor/rules/rules-index.mdc
+Skills are available in `.agents/skills/` directory. See CLAUDE.md for the full list.

package/changelog/v1.json

@@ -1,4 +1,13 @@
 [
+  {
+    "children": {
+      "improvements": [
+        "Migrate AI Rules to Claude Code Skills."
+      ]
+    },
+    "date": "2026-01-23",
+    "version": "2.0.0-next.354"
+  },
   {
     "children": {},
     "date": "2026-01-23",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/lobehub",
-  "version": "2.0.0-next.353",
+  "version": "2.0.0-next.354",
   "description": "LobeHub - an open-source,comprehensive AI Agent framework that supports speech synthesis, multimodal, and extensible Function Call plugin system. Supports one-click free deployment of your private ChatGPT/LLM web application.",
   "keywords": [
     "framework",

package/src/features/FileViewer/Renderer/PDF/index.tsx

@@ -2,12 +2,11 @@
 
 import { Flexbox } from '@lobehub/ui';
 import { Fragment, memo, useCallback, useState } from 'react';
-import { Document, Page, pdfjs } from 'react-pdf';
 import 'react-pdf/dist/Page/AnnotationLayer.css';
 import 'react-pdf/dist/Page/TextLayer.css';
 
 import NeuralNetworkLoading from '@/components/NeuralNetworkLoading';
-import '@/libs/pdfjs/worker';
+import { Document, Page, pdfjs } from '@/libs/pdfjs';
 import { lambdaQuery } from '@/libs/trpc/client';
 
 import HighlightLayer from './HighlightLayer';
@@ -71,7 +70,7 @@ const PDFViewer = memo<PDFViewerProps>(({ url, fileId }) => {
           onLoadSuccess={onDocumentLoadSuccess}
           options={options}
         >
-          {Array.from({ length: numPages }, (el, index) => {
+          {Array.from({ length: numPages }, (_, index) => {
             const width = containerWidth ? Math.min(containerWidth, maxWidth) : maxWidth;
 
             return (

package/src/features/ShareModal/SharePdf/PdfPreview.tsx

@@ -7,10 +7,9 @@ import { createStaticStyles, cx } from 'antd-style';
 import { ChevronLeft, ChevronRight, Expand, FileText } from 'lucide-react';
 import { memo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Document, Page } from 'react-pdf';
 
 import { useIsMobile } from '@/hooks/useIsMobile';
-import '@/libs/pdfjs/worker';
+import { Document, Page } from '@/libs/pdfjs';
 
 import { containerStyles } from '../style';
 

package/src/libs/pdfjs/index.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import type { ComponentProps } from 'react';
+import { Document as PdfDocument, Page as PdfPage, pdfjs } from 'react-pdf';
+
+const workerSrc = `https://registry.npmmirror.com/pdfjs-dist/${pdfjs.version}/files/build/pdf.worker.min.mjs`;
+
+function ensureWorker() {
+  if (!pdfjs.GlobalWorkerOptions.workerSrc) {
+    pdfjs.GlobalWorkerOptions.workerSrc = workerSrc;
+  }
+}
+
+export type DocumentProps = ComponentProps<typeof PdfDocument>;
+export type PageProps = ComponentProps<typeof PdfPage>;
+
+export const Document = (props: DocumentProps) => {
+  ensureWorker();
+  return <PdfDocument {...props} />;
+};
+
+
+
+
+export {Page, pdfjs} from 'react-pdf';

package/src/store/test-coverage.md

@@ -35,7 +35,7 @@ All 40 action files in the store now have comprehensive test coverage!
 
 All store action tests should follow the patterns documented in:
 
-- **Main Guide**: `@.cursor/rules/testing-guide/zustand-store-action-test.mdc`
+- **Main Guide**: `.agents/skills/testing/references/zustand-store-action-test.md`
 
 Key principles:
 
@@ -141,7 +141,7 @@ For files with multiple action files to test, use the Task tool to create subage
 **Example subagent prompt**:
 
 ```
-Write comprehensive tests for src/store/discover/slices/plugin/action.ts following @.cursor/rules/testing-guide/zustand-store-action-test.mdc.
+Write comprehensive tests for src/store/discover/slices/plugin/action.ts following .agents/skills/testing/references/zustand-store-action-test.md.
 
 Requirements:
 1. Write tests covering all actions in the file
@@ -315,7 +315,7 @@ Create 5 subagents, one for each action file:
 Task({
   subagent_type: 'general-purpose',
   description: 'Test plugin action',
-  prompt: `Write comprehensive tests for src/store/discover/slices/plugin/action.ts following @.cursor/rules/testing-guide/zustand-store-action-test.mdc.
+  prompt: `Write comprehensive tests for src/store/discover/slices/plugin/action.ts following .agents/skills/testing/references/zustand-store-action-test.md.
 
 Requirements:
 1. Write tests covering all actions (usePluginCategories, usePluginDetail, usePluginList, usePluginIdentifiers)
@@ -330,7 +330,7 @@ DO NOT commit changes or update test-coverage.md.`,
 Task({
   subagent_type: 'general-purpose',
   description: 'Test mcp action',
-  prompt: `Write comprehensive tests for src/store/discover/slices/mcp/action.ts following @.cursor/rules/testing-guide/zustand-store-action-test.mdc.
+  prompt: `Write comprehensive tests for src/store/discover/slices/mcp/action.ts following .agents/skills/testing/references/zustand-store-action-test.md.
 
 Requirements:
 1. Write tests covering all actions (useFetchMcpDetail, useFetchMcpList, useMcpCategories)
@@ -561,7 +561,7 @@ bunx eslint src/store/[domain]/
 - 25 action files already have comprehensive tests (62.5% coverage)
 - 742 tests written across 80 test files
 - Well-tested stores: agent, chat (partial), file (partial), image, session, tool, user, global, aiInfra (partial)
-- Following zustand testing best practices from `@.cursor/rules/testing-guide/zustand-store-action-test.mdc`
+- Following zustand testing best practices from `.agents/skills/testing/references/zustand-store-action-test.md`
 
 ## Notes
 

package/.cursor/rules/add-provider-doc.mdc

@@ -1,183 +0,0 @@
----
-description: Complete guide for adding a new AI provider documentation to LobeChat
-alwaysApply: false
----
-
-# Adding New AI Provider Documentation
-
-This document provides a step-by-step guide for adding documentation for a new AI provider to LobeChat, based on the complete workflow used for adding providers like BFL (Black Forest Labs) and FAL.
-
-## Overview
-
-Adding a new provider requires creating both user-facing documentation and technical configuration files. The process involves:
-
-1. Creating usage documentation (EN + CN)
-2. Adding environment variable documentation (EN + CN)
-3. Updating Docker configuration files
-4. Updating .env.example file
-5. Preparing image resources
-
-## Step 1: Create Provider Usage Documentation
-
-Create user-facing documentation that explains how to use the new provider.
-
-### Required Files
-
-Create both English and Chinese versions:
-- `docs/usage/providers/{provider-name}.mdx` (English)
-- `docs/usage/providers/{provider-name}.zh-CN.mdx` (Chinese)
-
-### Documentation Structure
-
-Follow the structure and format used in existing provider documentation. For reference, see:
-- `docs/usage/providers/fal.mdx` (English template)
-- `docs/usage/providers/fal.zh-CN.mdx` (Chinese template)
-
-### Key Requirements
-
-- **Images**: Prepare 5-6 screenshots showing the process
-- **Cover Image**: Create or obtain a cover image for the provider
-- **Accurate URLs**: Use real registration and dashboard URLs
-- **Service Type**: Specify whether it's for image generation, text generation, etc.
-- **Pricing Warning**: Include pricing information callout
-
-### Important Notes
-
-- **🔒 API Key Security**: Never include real API keys in documentation. Always use placeholder format (e.g., `bfl-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`)
-- **🖼️ Image Hosting**: Use LobeHub's CDN for all images: `hub-apac-1.lobeobjects.space`
-
-## Step 2: Update Environment Variables Documentation
-
-Add the new provider's environment variables to the self-hosting documentation.
-
-### Files to Update
-
-- `docs/self-hosting/environment-variables/model-provider.mdx` (English)
-- `docs/self-hosting/environment-variables/model-provider.zh-CN.mdx` (Chinese)
-
-### Content to Add
-
-Add two sections for each provider:
-
-```markdown
-### `{PROVIDER}_API_KEY`
-
-- Type: Required
-- Description: This is the API key you applied for in the {Provider Name} service.
-- Default: -
-- Example: `{api-key-format-example}`
-
-### `{PROVIDER}_MODEL_LIST`
-
-- Type: Optional
-- Description: Used to control the {Provider Name} model list. Use `+` to add a model, `-` to hide a model, and `model_name=display_name` to customize the display name of a model. Separate multiple entries with commas. The definition syntax follows the same rules as other providers' model lists.
-- Default: `-`
-- Example: `-all,+{model-id-1},+{model-id-2}={display-name}`
-
-The above example disables all models first, then enables `{model-id-1}` and `{model-id-2}` (displayed as `{display-name}`).
-
-[model-list]: /docs/self-hosting/advanced/model-list
-```
-
-### Important Notes
-
-- **API Key Format**: Use proper UUID format for examples (e.g., `12345678-1234-1234-1234-123456789abc`)
-- **Real Model IDs**: Use actual model IDs from the codebase, not placeholders
-- **Consistent Naming**: Follow the pattern `{PROVIDER}_API_KEY` and `{PROVIDER}_MODEL_LIST`
-
-## Step 3: Update Docker Configuration Files
-
-Add environment variables to all Docker configuration files to ensure the provider works in containerized deployments.
-
-### Files to Update
-
-All Dockerfile variants must be updated:
-- `Dockerfile`
-- `Dockerfile.database`
-- `Dockerfile.pglite`
-
-### Changes Required
-
-Add the new provider's environment variables at the **end** of the ENV section, just before the final line:
-
-```dockerfile
-# Previous providers...
-    # 302.AI
-    AI302_API_KEY="" AI302_MODEL_LIST="" \
-    # {New Provider 1}
-    {PROVIDER1}_API_KEY="" {PROVIDER1}_MODEL_LIST="" \
-    # {New Provider 2}
-    {PROVIDER2}_API_KEY="" {PROVIDER2}_MODEL_LIST=""
-```
-
-### Important Rules
-
-- **Position**: Add new providers at the **end** of the list
-- **Ordering**: When adding multiple providers, use alphabetical order (e.g., FAL before BFL)
-- **Consistency**: Maintain identical ordering across all Dockerfile variants
-- **Format**: Follow the pattern `{PROVIDER}_API_KEY="" {PROVIDER}_MODEL_LIST="" \`
-
-## Step 4: Update .env.example File
-
-Add example configuration entries to help users understand how to configure the provider locally.
-
-### File to Update
-
-- `.env.example`
-
-### Content to Add
-
-Add new sections before the "Market Service" section:
-
-```bash
-### {Provider Name} ###
-
-# {PROVIDER}_API_KEY={provider-prefix}-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
-
-### Format Guidelines
-
-- **Section Header**: Use `### {Provider Name} ###` format
-- **Commented Example**: Use `#` to comment out the example
-- **Key Format**: Use appropriate prefix for the provider (e.g., `bfl-`, `fal-`, `sk-`)
-- **Position**: Add before the Market Service section
-- **Spacing**: Maintain consistent spacing with existing entries
-
-## Step 5: Image Resources
-
-Prepare all necessary image resources for the documentation.
-
-### Required Images
-
-1. **Cover Image**: Provider logo or branded image
-2. **API Dashboard Screenshots**: 3-4 screenshots showing API key creation process
-3. **LobeChat Configuration Screenshots**: 2-3 screenshots showing provider setup in LobeChat
-
-### Image Guidelines
-
-- **Quality**: Use high-resolution screenshots
-- **Consistency**: Maintain consistent styling across all screenshots
-- **Privacy**: Remove or blur any sensitive information
-- **Format**: Use PNG format for screenshots
-- **Hosting**: Use LobeHub's CDN (`hub-apac-1.lobeobjects.space`) for all images
-
-## Checklist
-
-Before submitting your provider documentation:
-
-- [ ] Created both English and Chinese usage documentation
-- [ ] Added environment variable documentation (EN + CN)
-- [ ] Updated all 3 Dockerfile variants with consistent ordering
-- [ ] Updated .env.example with proper key format
-- [ ] Prepared all required screenshots and images
-- [ ] Used actual model IDs from the codebase
-- [ ] Verified no real API keys are included in documentation
-- [ ] Used LobeHub CDN for all image hosting
-- [ ] Tested the documentation for clarity and accuracy
-
-## Reference
-
-This guide was created based on the implementation of BFL (Black Forest Labs) provider documentation. For a complete example, refer to:
-- Commits: `d2da03e1a` (documentation) and `6a2e95868` (environment variables)
-- Files: `docs/usage/providers/bfl.mdx`, `docs/usage/providers/bfl.zh-CN.mdx`
-- PR: Current branch `tj/feat/bfl-docs`

package/.cursor/rules/add-setting-env.mdc

@@ -1,175 +0,0 @@
----
-description: Guide for adding environment variables to configure user settings
-alwaysApply: false
----
-
-# Adding Environment Variable for User Settings
-
-Add server-side environment variables to configure default values for user settings.
-
-**Priority**: User Custom > Server Env Var > Hardcoded Default
-
-## Steps
-
-### 1. Define Environment Variable
-
-Create `src/envs/<domain>.ts`:
-
-```typescript
-import { createEnv } from '@t3-oss/env-nextjs';
-import { z } from 'zod';
-
-export const get<Domain>Config = () => {
-  return createEnv({
-    server: {
-      YOUR_ENV_VAR: z.coerce.number().min(MIN).max(MAX).optional(),
-    },
-    runtimeEnv: {
-      YOUR_ENV_VAR: process.env.YOUR_ENV_VAR,
-    },
-  });
-};
-
-export const <domain>Env = get<Domain>Config();
-```
-
-### 2. Update Type (Optional)
-
-**Skip this step if the domain field already exists in `GlobalServerConfig`.**
-
-Add to `packages/types/src/serverConfig.ts`:
-
-```typescript
-export interface GlobalServerConfig {
-  <domain>?: {
-    <settingName>?: <type>;
-  };
-}
-```
-
-**Prefer reusing existing types** from `packages/types/src/user/settings` with `PartialDeep`:
-
-```typescript
-import { User<Domain>Config } from './user/settings';
-
-export interface GlobalServerConfig {
-  <domain>?: PartialDeep<User<Domain>Config>;
-}
-```
-
-### 3. Assemble Server Config (Optional)
-
-**Skip this step if the domain field already exists in server config.**
-
-In `src/server/globalConfig/index.ts`:
-
-```typescript
-import { <domain>Env } from '@/envs/<domain>';
-import { cleanObject } from '@/utils/object';
-
-export const getServerGlobalConfig = async () => {
-  const config: GlobalServerConfig = {
-    // ...
-    <domain>: cleanObject({
-      <settingName>: <domain>Env.YOUR_ENV_VAR,
-    }),
-  };
-  return config;
-};
-```
-
-If the domain already exists, just add the new field to the existing `cleanObject()`:
-
-```typescript
-<domain>: cleanObject({
-  existingField: <domain>Env.EXISTING_VAR,
-  <settingName>: <domain>Env.YOUR_ENV_VAR, // Add this line
-}),
-```
-
-### 4. Merge to User Store (Optional)
-
-**Skip this step if the domain field already exists in `serverSettings`.**
-
-In `src/store/user/slices/common/action.ts`, add to `serverSettings`:
-
-```typescript
-const serverSettings: PartialDeep<UserSettings> = {
-  defaultAgent: serverConfig.defaultAgent,
-  <domain>: serverConfig.<domain>, // Add this line
-  // ...
-};
-```
-
-### 5. Update .env.example
-
-```bash
-# <Description> (range/options, default: X)
-# YOUR_ENV_VAR=<example>
-```
-
-### 6. Update Documentation
-
-Update both English and Chinese documentation:
-- `docs/self-hosting/environment-variables/basic.mdx`
-- `docs/self-hosting/environment-variables/basic.zh-CN.mdx`
-
-Add new section or subsection with environment variable details (type, description, default, example, range/constraints).
-
-## Type Reuse
-
-**Prefer reusing existing types** from `packages/types/src/user/settings` instead of defining inline types in `serverConfig.ts`.
-
-```typescript
-// ✅ Good - reuse existing type
-import { UserImageConfig } from './user/settings';
-
-export interface GlobalServerConfig {
-  image?: PartialDeep<UserImageConfig>;
-}
-
-// ❌ Bad - inline type definition
-export interface GlobalServerConfig {
-  image?: {
-    defaultImageNum?: number;
-  };
-}
-```
-
-## Example: AI_IMAGE_DEFAULT_IMAGE_NUM
-
-```typescript
-// src/envs/image.ts
-export const getImageConfig = () => {
-  return createEnv({
-    server: {
-      AI_IMAGE_DEFAULT_IMAGE_NUM: z.coerce.number().min(1).max(20).optional(),
-    },
-    runtimeEnv: {
-      AI_IMAGE_DEFAULT_IMAGE_NUM: process.env.AI_IMAGE_DEFAULT_IMAGE_NUM,
-    },
-  });
-};
-
-// packages/types/src/serverConfig.ts
-import { UserImageConfig } from './user/settings';
-
-export interface GlobalServerConfig {
-  image?: PartialDeep<UserImageConfig>;
-}
-
-// src/server/globalConfig/index.ts
-image: cleanObject({
-  defaultImageNum: imageEnv.AI_IMAGE_DEFAULT_IMAGE_NUM,
-}),
-
-// src/store/user/slices/common/action.ts
-const serverSettings: PartialDeep<UserSettings> = {
-  image: serverConfig.image,
-  // ...
-};
-
-// .env.example
-# AI_IMAGE_DEFAULT_IMAGE_NUM=4
-```
-

package/.cursor/rules/cursor-rules.mdc

@@ -1,28 +0,0 @@
----
-description: cursor rules writing and optimization guide
-globs: 
-alwaysApply: false
----
-当你编写或修改 Cursor Rule 时，请遵循以下准则：
-
-- 当你知道 rule 的文件名时，使用 `read_file` 而不是 `fetch_rules` 去读取它们，它们都在项目根目录的 `.cursor/rules/` 文件夹下
-
-- 代码示例
-  - 示例应尽量精简，仅保留演示核心
-  - 删除与示例无关的导入/导出语句，但保留必要的导入
-  - 同一文件存在多个示例时，若前文已演示模块导入，后续示例可省略重复导入
-  - 无需书写 `export`
-  - 可省略与演示无关或重复的 props、配置对象属性、try/catch、CSS 等代码
-  - 删除无关注释，保留有助理解的注释
-
-- 格式
-  - 修改前请先确认原始文档语言，并保持一致
-  - 无序列表统一使用 `-`
-  - 列表末尾的句号是多余的
-  - 非必要不使用加粗、行内代码等样式，Rule 主要供 LLM 阅读
-  - 避免中英文逐句对照。若括号内容为示例而非翻译，可保留
-
-- Review
-  - 修正 Markdown 语法问题
-  - 纠正错别字
-  - 指出示例与说明不一致之处

package/.cursor/rules/db-migrations.mdc

@@ -1,46 +0,0 @@
----
-globs: packages/database/migrations/**/*
-alwaysApply: false
----
-
-# Database Migrations Guide
-
-## Step1: Generate migrations
-
-```bash
-bun run db:generate
-```
-
-this step will generate following files:
-
-- packages/database/migrations/0046_meaningless_file_name.sql
-- packages/database/migrations/0046_meaningless_file_name.sql
-
-and update the following files:
-
-- packages/database/migrations/meta/\_journal.json
-- packages/database/src/core/migrations.json
-- docs/development/database-schema.dbml
-
-## Step2: optimize the migration sql fileName
-
-the migration sql file name is randomly generated, we need to optimize the file name to make it more readable and meaningful. For example, `0046_meaningless_file_name.sql` -> `0046_user_add_avatar_column.sql`
-
-## Step3: Defensive Programming - Use Idempotent Clauses
-
-Always use defensive clauses to make migrations idempotent:
-
-```sql
--- ✅ Good: Idempotent operations
-ALTER TABLE "users" ADD COLUMN IF NOT EXISTS "avatar" text;
-DROP TABLE IF EXISTS "old_table";
-CREATE INDEX IF NOT EXISTS "users_email_idx" ON "users" ("email");
-ALTER TABLE "posts" DROP COLUMN IF EXISTS "deprecated_field";
-
--- ❌ Bad: Non-idempotent operations
-ALTER TABLE "users" ADD COLUMN "avatar" text;
-DROP TABLE "old_table";
-CREATE INDEX "users_email_idx" ON "users" ("email");
-```
-
-**Important**: After modifying migration SQL (e.g., adding `IF NOT EXISTS` clauses), run `bun run db:generate:client` to update the hash in `packages/database/src/core/migrations.json`.