From f520b54ca5ecae8a06e0860da76dff5dc04cafe6 Mon Sep 17 00:00:00 2001
From: imbytecat <imbytecat@gmail.com>
Date: Sat, 25 Apr 2026 14:11:21 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=90=8C=E6=AD=A5=20embed-migr?=
 =?UTF-8?q?ations=20=E4=B8=8E=20sql.d.ts=EF=BC=8C=E4=BF=AE=E9=99=88?=
 =?UTF-8?q?=E6=97=A7=E6=8F=8F=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CLI 帮助块与 Layout migrate.ts 注释从 "from ./drizzle" 改为 "embedded migrations"
- 补 src/sql.d.ts（with { type: 'text' } SQL 导入的载体）到 Layout
- 补 patches/（patchedDependencies 用途）到 Layout
---
 AGENTS.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index af27f75..47554f7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,7 +56,7 @@ Before committing: `bun run fix && bun run typecheck && bun run test`. No CI, no
 
 ```
 ./server [serve]   # default — start the HTTP server
-./server migrate   # apply migrations from ./drizzle
+./server migrate   # apply embedded migrations
 ./server --help
 ```
 
@@ -137,7 +137,7 @@ src/
 │   └── queries/                # per-feature query hooks: keys, options, `useInvalidate<Feature>` helpers
 ├── cli/                        # CLI subcommands (loaded lazily by bin.ts via citty)
 │   ├── serve.ts                # `./server serve` — imports the Nitro bridge on demand
-│   ├── migrate.ts              # `./server migrate` — drizzle migrate against ./drizzle
+│   ├── migrate.ts              # `./server migrate` — applies embedded migrations via public `db.execute(sql)` + `db.transaction()`
 │   ├── _serve-nitro.mjs        # bridge: `import('../../.output/server/index.mjs')`
 │   └── _serve-nitro.d.mts      # types for the bridge (build output has no .d.ts)
 ├── routes/
@@ -166,12 +166,14 @@ src/
 ├── components/                 # non-route UI primitives (PascalCase, arrow const)
 ├── env.ts                      # t3-oss env validation
 ├── router.tsx                  # QueryClient + setupRouterSsrQueryIntegration
+├── sql.d.ts                    # ambient `declare module '*.sql'` — load-bearing for `with { type: 'text' }` imports in migrations.gen.ts
 ├── styles.css                  # Tailwind v4 entry
 └── routeTree.gen.ts            # auto-generated, do not edit
 bin.ts                          # citty entry (root) — keep imports minimal (see "CLI" section)
 compile.ts                      # `bun build --compile` driver; resolves --target; sets minify/bytecode/sourcemap
 embed-migrations.ts             # codegen: scans ./drizzle/meta/_journal.json → src/server/db/migrations.gen.ts
 drizzle/                        # SQL migrations (source of truth for `db:generate`; not shipped in binary)
+patches/                        # Bun `patchedDependencies` — patches `@tanstack/start-plugin-core` to drop the `@rsbuild/core` mis-import (see `package.json`)
 ```
 
 Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not via a Nitro config file.