From 22363279c880eceee68a8d08aa032f63ee67e519 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Wed, 1 Apr 2026 23:24:23 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80=20AGENTS.md=20?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84=E5=B9=B6=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E5=86=85=E5=AE=B9=E5=91=88=E7=8E=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 313 ++++++++++++------------------------------------------
 1 file changed, 66 insertions(+), 247 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 49196a4..df6f207 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,300 +1,119 @@
 # AGENTS.md - AI Coding Agent Guidelines
 
-Guidelines for AI agents working in this project.
-
 ## Project Overview
 
-> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
+> **This project uses [Bun](https://bun.sh) exclusively. Do NOT use Node.js / npm / yarn / pnpm. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands.**
 
 - **Framework**: TanStack Start (React 19 SSR, file-based routing)
-- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
-- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
-- **Language**: TypeScript (strict mode)
-- **Styling**: Tailwind CSS v4
+- **Runtime/PM**: Bun (see `mise.toml`) — **NOT Node.js / npm / yarn / pnpm**
+- **Language**: TypeScript (strict mode) | **Styling**: Tailwind CSS v4
 - **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
-- **State**: TanStack Query v5
-- **RPC**: ORPC (contract-first, type-safe)
-- **Build**: Vite + Nitro
+- **State**: TanStack Query v5 | **RPC**: ORPC (contract-first) | **Build**: Vite + Nitro
 
-## Build / Lint / Test Commands
+## Commands
 
 ```bash
-# Development
 bun run dev                    # Vite dev server (localhost:3000)
-bun run db:studio              # Drizzle Studio GUI
-
-# Build
 bun run build                  # Production build → .output/
-bun run compile                # Compile to standalone binary (current platform, depends on build)
-bun run compile:darwin         # Compile for macOS (arm64 + x64)
-bun run compile:darwin:arm64   # Compile for macOS arm64
-bun run compile:darwin:x64     # Compile for macOS x64
-bun run compile:linux          # Compile for Linux (x64 + arm64)
-bun run compile:linux:arm64    # Compile for Linux arm64
-bun run compile:linux:x64      # Compile for Linux x64
-bun run compile:windows        # Compile for Windows (default: x64)
-bun run compile:windows:x64    # Compile for Windows x64
-
-# Code Quality
-bun run fix                    # Biome auto-fix
+bun run compile                # Compile to standalone binary (current platform)
+bun run fix                    # Biome auto-fix (lint + format)
 bun run typecheck              # TypeScript check
-
-# Database (Drizzle)
-bun run db:generate            # Generate migrations from schema
-bun run db:migrate             # Run migrations
-bun run db:push                # Push schema directly (dev only)
-
-# Testing (not yet configured)
-bun test path/to/test.ts       # Run single test
-bun test -t "pattern"          # Run tests matching pattern
+bun run db:push                # Push schema to dev DB (dev only, fast iteration)
+bun run db:generate            # Generate migration SQL files (for production)
+bun run db:migrate             # Apply migrations (production deployment)
+bun run db:studio              # Drizzle Studio GUI
+bun test path/to/test.ts       # Run single test (not yet configured)
 ```
 
-## Code Style (TypeScript)
+## Code Style
 
-### Formatting (Biome)
-- **Indent**: 2 spaces | **Line endings**: LF
-- **Quotes**: Single `'` | **Semicolons**: Omit (ASI)
-- **Arrow parentheses**: Always `(x) => x`
-
-### Imports
-Biome auto-organizes. Order: 1) External packages → 2) Internal `@/*` aliases → 3) Type imports (`import type { ... }`)
+**Formatting (Biome):** 2-space indent, LF, single quotes, no semicolons, always arrow parens `(x) => x`
 
+**Imports** — Biome auto-organizes: 1) External → 2) `@/*` aliases → 3) `import type`
 ```typescript
 import { createFileRoute } from '@tanstack/react-router'
-import { z } from 'zod'
 import { db } from '@/server/db'
 import type { ReactNode } from 'react'
 ```
 
-### TypeScript Strictness
-- `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`, `verbatimModuleSyntax: true`
-- Use `@/*` path aliases (maps to `src/*`)
+**TypeScript:** `strict: true`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`. Use `@/*` path aliases (→ `src/*`).
 
-### Naming Conventions
-| Type | Convention | Example |
-|------|------------|---------|
-| Files (utils) | kebab-case | `auth-utils.ts` |
-| Files (components) | PascalCase | `UserProfile.tsx` |
-| Components | PascalCase arrow | `const Button = () => {}` |
-| Functions | camelCase | `getUserById` |
-| Constants | UPPER_SNAKE | `MAX_RETRIES` |
-| Types/Interfaces | PascalCase | `UserProfile` |
+**Naming:** Files (utils): `kebab-case.ts` | Files (components): `PascalCase.tsx` | Components: `const Button = () => {}` | Functions: `camelCase` | Constants: `UPPER_SNAKE` | Types: `PascalCase`
 
-### React Patterns
-- Components: arrow functions (enforced by Biome)
-- Routes: TanStack Router file conventions (`export const Route = createFileRoute(...)`)
-- Data fetching: `useSuspenseQuery(orpc.feature.list.queryOptions())`
+**React:** Arrow function components (Biome enforced). Routes: `export const Route = createFileRoute(...)`. Data: `useSuspenseQuery(orpc.feature.list.queryOptions())`
 
-### Error Handling
-- Use `try-catch` for async operations; throw descriptive errors
-- ORPC: Use `ORPCError` with proper codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`)
-- Never use empty catch blocks
+**Errors:** `try-catch` for async; `ORPCError` with codes (`NOT_FOUND`, `INPUT_VALIDATION_FAILED`). Never empty catch blocks.
 
 ## ORPC Pattern
 
-### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
-```typescript
-import { oc } from '@orpc/contract'
-import { createSelectSchema } from 'drizzle-orm/zod'
-import { z } from 'zod'
-import { featureTable } from '@/server/db/schema'
+**1. Contract** (`src/server/api/contracts/feature.contract.ts`) — Zod schemas for input/output
+**2. Router** (`src/server/api/routers/feature.router.ts`) — Handler implementations using `os.feature.list.use(db).handler(...)`
+**3. Register** — Export from `contracts/index.ts` and `routers/index.ts`
+**4. Client** — `useSuspenseQuery(orpc.feature.list.queryOptions())` / `useMutation(orpc.feature.create.mutationOptions())`
 
-const selectSchema = createSelectSchema(featureTable)
+## Database (Drizzle ORM v1 beta)
 
-export const list = oc.input(z.void()).output(z.array(selectSchema))
-export const create = oc.input(insertSchema).output(selectSchema)
-```
+- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`) | **Validation**: `drizzle-orm/zod` (NOT `drizzle-zod`)
+- **Relations**: `defineRelations()` in `src/server/db/relations.ts` (RQBv2 — `drizzle()` only needs `{ relations }`)
+- **Query style**: RQBv2 object syntax — `orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`
+- **Schema**: All tables must include `id` (UUIDv7), `createdAt`, `updatedAt` (see `src/server/db/fields.ts`)
 
-### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
-```typescript
-import { ORPCError } from '@orpc/server'
-import { db } from '../middlewares'
-import { os } from '../server'
+### Database Workflow
+- **Local dev**: `db:push` — fast iteration, no migration files needed
+- **Production**: `db:generate` → review SQL → `db:migrate` — versioned, auditable
+- **Never mix** `push` and `migrate` on the same database instance
+- `drizzle/` migration directory is committed to Git
 
-export const list = os.feature.list.use(db).handler(async ({ context }) => {
-  return await context.db.query.featureTable.findMany({
-    orderBy: { createdAt: 'desc' },
-  })
-})
-```
-
-### 3. Register in Index Files
-```typescript
-// src/server/api/contracts/index.ts
-import * as feature from './feature.contract'
-export const contract = { feature }
-
-// src/server/api/routers/index.ts
-import * as feature from './feature.router'
-export const router = os.router({ feature })
-```
-
-### 4. Use in Components
-```typescript
-import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
-import { orpc } from '@/client/orpc'
-
-const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
-const mutation = useMutation(orpc.feature.create.mutationOptions())
-```
-
-## Database (Drizzle ORM v1 beta + postgres-js)
-
-- **ORM**: Drizzle ORM `1.0.0-beta` (RQBv2)
-- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
-- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
-- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts` (contains schema info, so `drizzle()` only needs `{ relations }`)
-- **Query style**: RQBv2 object syntax (`orderBy: { createdAt: 'desc' }`, `where: { id: 1 }`)
-
-### Schema Definition
-```typescript
-import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
-import { sql } from 'drizzle-orm'
-
-export const myTable = pgTable('my_table', {
-  id: uuid().primaryKey().default(sql`uuidv7()`),
-  name: text().notNull(),
-  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
-})
-```
-
-### Relations (RQBv2)
-```typescript
-// src/server/db/relations.ts
-import { defineRelations } from 'drizzle-orm'
-import * as schema from './schema'
-
-export const relations = defineRelations(schema, (r) => ({
-  // Define relations here using r.one / r.many / r.through
-}))
-```
-
-### DB Instance
-```typescript
-// src/server/db/index.ts
-import { drizzle } from 'drizzle-orm/postgres-js'
-import { relations } from '@/server/db/relations'
-// In RQBv2, relations already contain schema info — no separate schema import needed
-
-const db = drizzle({
-  connection: env.DATABASE_URL,
-  relations,
-})
-```
-
-### RQBv2 Query Examples
-```typescript
-// Object-style orderBy (NOT callback style)
-const todos = await db.query.todoTable.findMany({
-  orderBy: { createdAt: 'desc' },
-})
-
-// Object-style where
-const todo = await db.query.todoTable.findFirst({
-  where: { id: someId },
-})
-```
+### ⚠️ drizzle.config.ts Caveat
+`drizzle.config.ts` runs outside Vite — **`@/*` path aliases do not work**. Use relative imports (`./src/env`).
 
 ## Environment Variables
 
-- Use `@t3-oss/env-core` with Zod validation in `src/env.ts`
+- Validated via `@t3-oss/env-core` + Zod in `src/env.ts`
 - Server vars: no prefix | Client vars: `VITE_` prefix required
 - Never commit `.env` files
 
-```typescript
-// src/env.ts
-import { createEnv } from '@t3-oss/env-core'
-import { z } from 'zod'
-
-export const env = createEnv({
-  server: {
-    DATABASE_URL: z.string().url(),
-  },
-  clientPrefix: 'VITE_',
-  client: {
-    VITE_API_URL: z.string().optional(),
-  },
-})
-```
-
 ## Development Principles
 
-> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
-
-1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks "just in case".
-2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart. This includes updating code snippets in docs when imports, APIs, or patterns change.
-3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns in the same codebase.
+1. **No backward compatibility** — Rapid iteration. Always use latest API/patterns. No deprecated fallbacks.
+2. **Always sync documentation** — Code changes → immediately update `AGENTS.md` and related docs.
+3. **Forward-only migration** — Fully adopt new APIs when upgrading. No mixing old/new patterns.
 
 ## Critical Rules
 
-**DO:**
-- Run `bun run fix` before committing
-- Use `@/*` path aliases (not relative imports)
-- Include `createdAt`/`updatedAt` on all tables
-- Use `ORPCError` with proper codes
-- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
-- Use RQBv2 object syntax for `orderBy` and `where`
-- Update `AGENTS.md` and other docs whenever code patterns change
+**DO:** `bun run fix` before committing | `@/*` path aliases | `createdAt`/`updatedAt` on all tables | `ORPCError` with proper codes | `drizzle-orm/zod` for validation | RQBv2 object syntax | Update docs with code changes
 
-**DON'T:**
-- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
-- Edit `src/routeTree.gen.ts` (auto-generated)
-- Use `as any`, `@ts-ignore`, `@ts-expect-error`
-- Commit `.env` files
-- Use empty catch blocks `catch(e) {}`
-- Import from `drizzle-zod` (use `drizzle-orm/zod` instead)
-- Use RQBv1 callback-style `orderBy` / old `relations()` API
-- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
-- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
-- Import `os` from `@orpc/server` in middleware — use `@/server/api/server` (the local typed instance)
-- Leave docs out of sync with code changes
+**DON'T:** `npm`/`npx`/`node`/`yarn`/`pnpm` | Edit `routeTree.gen.ts` | `as any`/`@ts-ignore`/`@ts-expect-error` | Commit `.env` | Empty catch blocks | Import from `drizzle-zod` | RQBv1 callback-style API | `drizzle-orm/bun-sql` driver | Pass `schema` to `drizzle()` | Import `os` from `@orpc/server` in middleware (use `@/server/api/server`) | Leave docs out of sync
 
 ## Git Workflow
 
-1. Make changes following style guide
-2. `bun run fix` - auto-format and lint
-3. `bun run typecheck` - verify types
-4. `bun run dev` - test locally
-5. Commit with descriptive message
+1. Make changes → 2. `bun run fix` → 3. `bun run typecheck` → 4. `bun run dev` (test) → 5. Commit
 
 ## Directory Structure
 
 ```
-.
-├── src/
-│   ├── client/                # Client-side code
-│   │   └── orpc.ts            # ORPC client + TanStack Query utils (single entry point)
-│   ├── components/            # React components
-│   ├── routes/                # TanStack Router file routes
-│   │   ├── __root.tsx         # Root layout
-│   │   ├── index.tsx          # Home page
-│   │   └── api/
-│   │       ├── $.ts           # OpenAPI handler + Scalar docs
-│   │       ├── health.ts      # Health check endpoint
-│   │       └── rpc.$.ts       # ORPC RPC handler
-│   ├── server/                # Server-side code
-│   │   ├── api/               # ORPC layer
-│   │   │   ├── contracts/     # Input/output schemas (Zod)
-│   │   │   ├── middlewares/   # Middleware (db provider, auth)
-│   │   │   ├── routers/       # Handler implementations
-│   │   │   ├── interceptors.ts # Shared error interceptors
-│   │   │   ├── context.ts     # Request context
-│   │   │   ├── server.ts      # ORPC server instance
-│   │   │   └── types.ts       # Type exports
-│   │   └── db/
-│   │       ├── schema/        # Drizzle table definitions
-│   │       ├── fields.ts      # Shared field builders (id, createdAt, updatedAt)
-│   │       ├── relations.ts   # Drizzle relations (defineRelations, RQBv2)
-│   │       └── index.ts       # Database instance (postgres-js driver)
-│   ├── env.ts                 # Environment variable validation
-│   ├── router.tsx             # Router configuration
-│   ├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
-│   └── styles.css             # Tailwind entry
-├── biome.json                 # Linting/formatting config
-├── compile.ts                 # Cross-platform binary compilation script
-├── drizzle.config.ts          # Drizzle Kit config
-├── vite.config.ts             # Vite + TanStack Start + Nitro config
-├── tsconfig.json              # TypeScript config
-└── package.json               # Dependencies and scripts
+src/
+├── client/orpc.ts             # ORPC client + TanStack Query utils
+├── components/                # React components
+├── routes/                    # TanStack Router file routes
+│   ├── __root.tsx             # Root layout
+│   └── api/                   # API routes (OpenAPI, health, RPC)
+├── server/
+│   ├── api/
+│   │   ├── contracts/         # ORPC input/output schemas (Zod)
+│   │   ├── routers/           # ORPC handler implementations
+│   │   ├── middlewares/       # Middleware (db, auth)
+│   │   ├── interceptors.ts    # Shared error interceptors
+│   │   ├── context.ts         # Request context
+│   │   ├── server.ts          # ORPC server instance
+│   │   └── types.ts           # Type exports
+│   └── db/
+│       ├── schema/            # Drizzle table definitions
+│       ├── fields.ts          # Shared field builders
+│       ├── relations.ts       # Drizzle relations (RQBv2)
+│       └── index.ts           # Database instance
+├── env.ts                     # Environment variable validation
+├── router.tsx                 # Router configuration
+├── routeTree.gen.ts           # Auto-generated (DO NOT EDIT)
+└── styles.css                 # Tailwind entry
 ```