docs: 新增 README，AGENTS 同步至当前架构

- README: 用户向 quick-start、scripts 表、add-a-feature checklist、deploy 流程
- AGENTS:
  - 修订 stale 文案（VITE_APP_TITLE/experimental_defaults/.gitkeep/route 组件风格）
  - 新增 Testing 段（bun test 约定）和 Endpoints 段（/, /health, /api/*）
  - Layout 补 logger.ts、health.ts、components/、styles.css、根 drizzle/
  - 追加 10 条 room-to-grow 纪律（client query / middleware / interceptor / 测试等扩展边界）

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know.
+Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know. Pair this with `README.md` (user-facing quick-start + add-a-feature checklist + deploy flow).
 
 ## Stack & runtime
 
@@ -17,6 +17,7 @@ bun run build        # bunx --bun vite build → .output/
 bun run compile      # bun compile.ts → out/server-<target> (standalone CLI binary)
 bun run cli <cmd>    # bun bin.ts <cmd>  — run a CLI subcommand in source (dev)
 bun run typecheck    # tsc --noEmit
+bun run test         # bun test  — runs all *.test.ts files (colocated with source)
 bun run fix          # biome check --write  (lint + format + organize imports)
 bun run db:push      # dev only — push schema to DB, no migration file
 bun run db:generate  # produce SQL migration files in ./drizzle
@@ -26,7 +27,7 @@ bun run db:studio    # Drizzle Studio
 
 Cross-compile targets live under `compile:{linux,darwin,windows}[:arch]`. `compile.ts` accepts `--target bun-<os>-<arch>`; default derives from host.
 
-Before committing: `bun run fix && bun run typecheck`. No CI, no pre-commit hooks, no lint-staged — so these are on you.
+Before committing: `bun run fix && bun run typecheck && bun run test`. No CI, no pre-commit hooks, no lint-staged — so these are on you.
 
 ## Drizzle (v0.x — critical)
 
@@ -46,7 +47,7 @@ Before committing: `bun run fix && bun run typecheck`. No CI, no pre-commit hook
 - Every table must spread `...generatedFields` from `src/server/db/fields.ts` (`id` UUIDv7 via `$defaultFn(uuidv7)`, `createdAt`, `updatedAt` with `$onUpdateFn`). `generatedFieldKeys` (hand-written `as const`) feeds `createInsertSchema(...).omit(...)`.
 - `src/server/db/index.ts` exports a module-level `const db = drizzle(...)` — not a lazy singleton. On Bun this is a long-lived process, so top-level side effects are fine and requested. Don't reintroduce `getDB/closeDB` ceremony; the Nitro shutdown plugin calls `db.$client.end()` directly. (Cloudflare Workers would need per-request init — we don't support that deployment target.)
 - `drizzle.config.ts` runs outside Vite — `@/*` path aliases do NOT resolve there. It currently does `import { env } from './src/env'` (relative). Preserve that.
-- The `./drizzle/` migrations directory is gitignored-by-absence right now (no migrations yet). Migrations are applied via the CLI (`./server migrate`, see "CLI & single-binary deploy" below), NOT at server startup. Dev uses `db:push`. Don't mix `push` and `migrate` on the same DB.
+- The `./drizzle/` migrations directory ships empty with a `.gitkeep`. Migrations are applied via the CLI (`./server migrate`, see "CLI & single-binary deploy" below), NOT at server startup. Dev uses `db:push`. Don't mix `push` and `migrate` on the same DB.
 
 ## CLI & single-binary deploy
 
@@ -77,19 +78,31 @@ Contract → Router → Handler → Client, all type-safe from a single contract
   ```
   Barrel-aggregated in `contracts/index.ts` as `export const contract = { todo }`.
 - Routers (`src/server/api/routers/*.router.ts`) import `db` directly from `@/server/db` in their handlers. There is **no `middlewares/` directory** by default — `db` doesn't need one (module-level const). When you actually need per-request context (auth, tenant, rate-limit), create `src/server/api/middlewares/<name>.middleware.ts` with `os.middleware(...)` and extend `BaseContext` in `context.ts`.
-- **Interceptors are attached at the handler level, not in `server.ts` and not on `os`.** Both `src/routes/api/rpc.$.ts` (`RPCHandler`) and `src/routes/api/$.ts` (`OpenAPIHandler`) register `[onError(logError)]` (server) and `[onError(handleValidationError)]` (client). The validation interceptor rewrites `BAD_REQUEST + ValidationError` into `INPUT_VALIDATION_FAILED` (422) and output validation errors into `OUTPUT_VALIDATION_FAILED`.
+- **Interceptors are attached at the handler level, not in `server.ts` and not on `os`.** Both `src/routes/api/rpc.$.ts` (`RPCHandler`) and `src/routes/api/$.ts` (`OpenAPIHandler`) register `[onError(logError)]` (server) and `[onError(handleValidationError)]` (client). The validation interceptor rewrites `BAD_REQUEST + ValidationError` into `INPUT_VALIDATION_FAILED` (422) and output validation errors into `OUTPUT_VALIDATION_FAILED`. `logError` calls `logger.error` from `@/server/logger` — never `console.*` directly.
 - OpenAPI/Scalar: docs at `/api/docs`, spec at `/api/spec.json` (handler prefix `/api`, plugin paths `/docs` and `/spec.json`).
 - **SSR isomorphism** (`src/client/orpc.ts`): `createIsomorphicFn().server(createRouterClient(...)).client(new RPCLink(...))`. Server branch reads `getRequestHeaders()` for context; client branch POSTs to `${origin}/api/rpc`.
-- **Global mutation invalidation** uses `experimental_defaults` in `createTanstackQueryUtils(...)` — currently invalidates `orpc.todo.list.key()` on every `todo.{create,update,remove}` success. Add new features here rather than in each mutation site.
+- **Mutation invalidation is colocated at the call site** via `mutationOptions({ onSuccess })`, not in `src/client/orpc.ts`. `orpc` in `src/client/orpc.ts` is a plain `createTanstackQueryUtils(client)` — no `experimental_defaults`. Per-feature query helpers live in `src/client/queries/<feature>.ts` (e.g. `useInvalidateTodos`); routes/components compose those hooks rather than holding query keys inline. See `src/client/queries/todo.ts` + `src/routes/index.tsx` for the canonical shape.
 - SSR prefetch in route loaders: `await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())`. Components use `useSuspenseQuery(orpc.feature.list.queryOptions())`.
 
 ## Code style (Biome)
 
-- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` — so React components must be `const Foo = () => {...}` not `function Foo() {}`. Also `noReactPropAssignments: "error"`.
+- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` (covers function *expressions* only). Also `noReactPropAssignments: "error"`.
+- **Route components use `function Foo()` declarations**, placed below the `Route` config so the file reads top-down (route on top, component below). This is the official TanStack Router/Start pattern and relies on hoisting — `const Foo = () => {}` would TDZ-error when referenced from `createFileRoute({ component: Foo })` above it. Inline arrows are fine for trivial leaf components (e.g. plain redirect routes). Non-route components (UI primitives in `src/components/`) use `const Foo = () => {}`.
 - Imports are auto-organized into two groups (external, then `@/*`), each alphabetical, with `import type` interleaved (NOT a separate group). `bun run fix` handles this; don't hand-sort.
 - Files: utils `kebab-case.ts`, components `PascalCase.tsx`.
 - `routeTree.gen.ts` is generated — ignored by Biome, never edit.
 
+## Testing
+
+`bun test` runs all `*.test.ts` files. Tests are colocated next to the source they exercise (e.g. `src/server/api/contracts/todo.contract.test.ts`). Use `import { describe, expect, test } from 'bun:test'`. The `@/*` alias resolves in tests via tsconfig paths. No Vitest, no Jest, no separate test config — keep it that way unless you need a browser/JSDOM environment.
+
+## Endpoints
+
+- `/` — Todos UI (file route).
+- `/health` — bare `GET` returning `ok` (200, `text/plain`). Liveness only — no DB check, so it stays green even when Postgres is down. Add a separate `/ready` if you ever need readiness.
+- `/api/rpc` — ORPC RPC handler (POST).
+- `/api/*` — ORPC OpenAPI handler. Docs at `/api/docs`, spec at `/api/spec.json`.
+
 ## TypeScript
 
 Strict mode, plus `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `noImplicitOverride`. No `as any` / `@ts-ignore` / `@ts-expect-error`.
@@ -98,7 +111,7 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../<file>` (example
 
 ## Env
 
-`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`). Client needs `VITE_` prefix (`VITE_APP_TITLE` optional). Never commit `.env`.
+`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`). `client: {}` is empty by default — any client-side env must be `VITE_`-prefixed. Never commit `.env`.
 
 ## Docker / deploy
 
@@ -111,33 +124,44 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../<file>` (example
 
 ```
 src/
-├── client/orpc.ts              # isomorphic ORPC client + experimental_defaults invalidation
+├── client/
+│   ├── orpc.ts                 # isomorphic ORPC client + TanStack Query utils (no global invalidation defaults)
+│   └── 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
 │   ├── _serve-nitro.mjs        # bridge: `import('../../.output/server/index.mjs')`
 │   └── _serve-nitro.d.mts      # types for the bridge (build output has no .d.ts)
-├── routes/api/
+├── routes/
+│   ├── __root.tsx              # root route + RootDocument shell
+│   ├── index.tsx               # Todos UI
+│   ├── health.ts               # GET /health → "ok" (no DB)
+│   └── api/
 │       ├── $.ts                # OpenAPI + Scalar; interceptors registered here
 │       └── rpc.$.ts            # RPC; interceptors registered here
 ├── server/
+│   ├── logger.ts               # the only log entrypoint — wrap before swapping to pino/otel
 │   ├── api/
 │   │   ├── server.ts           # the ONLY place to build `os`
 │   │   ├── context.ts          # BaseContext (add per-request fields when you add middlewares)
-│   │   ├── interceptors.ts     # logError, handleValidationError
+│   │   ├── interceptors.ts     # logError (→ logger), handleValidationError
 │   │   ├── types.ts            # Router{Client,Inputs,Outputs} derived from Contract
-│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract)
+│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract); colocated *.test.ts
 │   │   └── routers/            # os.* handlers (barrel: router) — import db directly
 │   ├── db/
 │   │   ├── index.ts            # module-level `export const db = drizzle({...})`
 │   │   ├── fields.ts           # generatedFields (id/createdAt/updatedAt) + generatedFieldKeys
 │   │   └── schema/             # pgTable definitions; also put `relations()` here when adding
 │   └── plugins/
-│       └── shutdown.ts         # SIGINT/SIGTERM → db.$client.end() with 500ms delay
+│       └── shutdown.ts         # SIGINT/SIGTERM → db.$client.end() with 500ms delay (prod only)
+├── components/                 # non-route UI primitives (PascalCase, arrow const)
 ├── env.ts                      # t3-oss env validation
 ├── router.tsx                  # QueryClient + setupRouterSsrQueryIntegration
+├── 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
+drizzle/                        # SQL migrations (.gitkeep until first `bun run db:generate`)
 ```
 
 Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not via a Nitro config file.
@@ -154,3 +178,18 @@ Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not v
 - Don't use `drizzle-orm/bun-sql`.
 - Don't use `@/*` aliases in `drizzle.config.ts`.
 - Don't commit `.env`.
+
+## Room-to-grow rules (discipline for the first real feature)
+
+These keep the starter from setting bad precedents as it grows. Append, don't restructure.
+
+1. Per-feature client query code — keys, options, `useInvalidate<Feature>` helpers — lives in `src/client/queries/<feature>.ts`. Routes/components compose these hooks; they don't hold query keys inline.
+2. Mutation invalidation stays explicit at the mutation call site (`mutationOptions({ onSuccess })`) or in a feature query helper. Do not reintroduce global `experimental_defaults` or any implicit cache policy.
+3. Client state defaults to route/component local state. Create a store (zustand or equivalent) only when state is shared across routes or needs persistence.
+4. Middlewares (`src/server/api/middlewares/<name>.middleware.ts`) derive request-scoped context or gate access. They do NOT orchestrate business flow, hold side effects, or replace handlers/services.
+5. Interceptors (`src/server/api/interceptors.ts`) do cross-cutting error logging, transport normalization, and validation rewrites. They do NOT read business data.
+6. One file per Drizzle table. Relations live in the same file and are exported as `<entity>Relations`. No global `relations.ts`.
+7. One router file per feature (`routers/<feature>.router.ts`). Only introduce `routers/<domain>/index.ts` when a domain grows past ~5 router files or needs shared domain helpers.
+8. All server-side logging goes through `src/server/logger.ts`. Do not call `console.error/info/warn` directly from business code.
+9. CLI subcommand modules keep top-level imports to `citty` + Node built-ins. Env, db, and server code are `await import(...)`-ed inside `run()` (see `bin.ts` comment for why).
+10. Every new business feature ships with at least one `bun test` covering a contract schema, a pure helper, or a router behavior.

README.md

@@ -0,0 +1,61 @@
+# fullstack-starter
+
+Opinionated single-binary fullstack starter. Bun + TanStack Start (React 19 SSR) + ORPC (contract-first) + Drizzle + PostgreSQL, deployed as one compiled executable.
+
+> Agent notes and non-obvious invariants live in [AGENTS.md](./AGENTS.md). Read it before making structural changes.
+
+## Quick start
+
+```bash
+cp .env.example .env
+bun install
+bun run db:push     # dev: sync schema without migration files
+bun run dev         # http://localhost:3000
+```
+
+RPC endpoint: `/api/rpc` · OpenAPI docs: `/api/docs` · Spec: `/api/spec.json` · Liveness: `/health`.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `bun run dev` | Vite dev server on port 3000 (strict) |
+| `bun run build` | Build to `.output/` |
+| `bun run compile` | Single-binary `out/server-<target>` via `bun build --compile` |
+| `bun run cli <cmd>` | Run a CLI subcommand in source (`serve`, `migrate`) |
+| `bun run typecheck` | `tsc --noEmit` |
+| `bun run fix` | Biome lint + format + organize imports |
+| `bun run db:push` | Dev-only schema sync (no migration files) |
+| `bun run db:generate` | Write SQL migrations to `./drizzle` |
+| `bun run db:migrate` | Apply migrations locally via drizzle-kit |
+| `bun run db:studio` | Drizzle Studio |
+
+Cross-compile: `bun run compile:{linux,darwin,windows}[:arch]`.
+
+## Add a feature (e.g. `post`)
+
+Contract-first, additive. Create or touch files in this order:
+
+1. `src/server/db/schema/post.ts` — define `postTable`, spread `...generatedFields`.
+2. `src/server/db/schema/index.ts` — `export * from './post'`.
+3. `src/server/api/contracts/post.contract.ts` — derive Zod from the table via `drizzle-zod`.
+4. `src/server/api/contracts/index.ts` — add `post` to the `contract` object.
+5. `src/server/api/routers/post.router.ts` — implement `os.post.*.handler(...)`.
+6. `src/server/api/routers/index.ts` — add `post` to the `router` object.
+7. `src/routes/<page>.tsx` — UI with `useSuspenseQuery` + loader `ensureQueryData`; invalidate affected list queries in mutation `onSuccess` handlers.
+8. `bun run db:generate` — emit SQL migrations to `./drizzle`.
+
+## Deploy
+
+Always **migrate-then-serve**. Migrations are an explicit deploy step, never a server startup hook.
+
+```bash
+./server migrate   # applies ./drizzle against $DATABASE_URL
+./server           # starts HTTP server (default subcommand)
+```
+
+`Dockerfile` copies `./drizzle/` next to the binary. `compose.yaml` models the pattern with a one-shot `migrate` service that `app` depends on (`service_completed_successfully`). On Kubernetes: run `./server migrate` as an initContainer or Helm `pre-upgrade` Job.
+
+```bash
+docker compose up --build
+```