@gaonjs/cli 0.18.0 → 0.23.0

package/dist/templates/project/agents/data.md.tpl

@@ -193,8 +193,8 @@ export const posts = table('posts', {
 | `pluck` | `(col)` | `Promise<Row[col][]>` | 단일 컬럼 배열 · 정렬·limit·offset 반영 |
 | `select` | `(['a', 'b'])` | `SelectChain<Row, K>` | 부분 컬럼 — `first`/`all` 이 `Pick<Row, K>` **plain 행** 반환 (메서드·관계·update 없음) |
 | `include` | `(...rels)` | `IncludedChain` | 관계 eager 로드 — **4종 전부**(belongsTo·hasMany·hasOne·belongsToMany, §1.1). **N+1 방지**: 관계당 쿼리 1회 (belongsToMany 는 피벗 `inner join` 1회) · 행 수와 무관. doctor 의 **n-plus-one** 검사가 include 미사용 · loop 안 관계 호출을 감지한다 |
-| `updateAll` | `(patch)` | `Promise<bigint>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수 반환. limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
-| `deleteAll` | `()` | `Promise<bigint>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
+| `updateAll` | `(patch)` | `Promise<number>` | **벌크 갱신** (M2C) — where 조건만 반영 · 영향 행 수(number · 결정 90). limit·offset·orderBy 가 걸려 있으면 **throw** (Postgres `UPDATE ... LIMIT` 미지원 — 행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`) |
+| `deleteAll` | `()` | `Promise<number>` | **벌크 삭제** (M2C) — 규칙은 updateAll 과 동일. 빈 where = 전체 삭제 (이름이 위험을 드러냄) |
 
 **집계·조인 그룹** (`Chain` · M2E · 결정 34):
 
@@ -218,18 +218,35 @@ export const posts = table('posts', {
 | 메서드 | 시그니처 | 반환 | 비고 |
 |---|---|---|---|
 | `create` | `(data)` | `Promise<Rec>` | `t.id()`·`t.timestamps()`·`.default()` 컬럼은 입력에서 선택적 (`InsertOf`) |
-| `batchInsert` | `(rows)` | `Promise<Rec[]>` | **벌크 삽입** (M2F · 결정 35) — 여러 row 를 **단일 INSERT 문**(원자적)으로 · 넣은 순서대로 Rec 반환. 빈 배열은 DB 무접촉 `[]`. beforeCreate 훅은 각 row 에 적용 |
-| `insertOrIgnore` | `(row \| rows)` | `Promise<Rec[]>` | **멱등 삽입** (M2F) — `ON CONFLICT DO NOTHING` · UNIQUE/PK 충돌 행은 건너뛰고 **실제로 삽입된 Rec 만** 반환. 충돌 대상 인자 없음(어떤 UNIQUE/PK 든 충돌 시 건너뜀) |
-| `upsert` | `(row \| rows, { onConflict?, update? })` | `Promise<Rec[]>` | **있으면 갱신 없으면 삽입** (M2F) — `ON CONFLICT DO UPDATE`. `onConflict` 생략 = 기본 키(`id`) 자동(없으면 throw) · `update` 생략(`'exclude'`) = 입력 컬럼에서 충돌 기준·`id` 뺀 나머지를 `excluded` 로 덮음 · 갱신 대상 없으면 DO NOTHING |
+| `batchInsert` | `(rows)` | `Promise<BulkResult>` | **벌크 삽입** (M2F · 결정 35 → BulkResult 결정 90) — 여러 row 를 **단일 INSERT 문**(원자적)으로 · `{ count }`(삽입 행 수) 반환. 빈 배열은 DB 무접촉 `{ count: 0 }`. beforeCreate 훅은 각 row 에 적용 |
+| `insertOrIgnore` | `(row \| rows)` | `Promise<BulkResult>` | **멱등 삽입** (M2F) — 충돌 행은 건너뛰고 `count` = **실제로 삽입된 행 수**(PG=`ON CONFLICT DO NOTHING` · MySQL=`INSERT IGNORE`). 충돌 대상 인자 없음(어떤 UNIQUE/PK 든 충돌 시 건너뜀) |
+| `upsert` | `(row \| rows, { onConflict?, update? })` | `Promise<BulkResult>` | **있으면 갱신 없으면 삽입** (M2F) — PG=`ON CONFLICT DO UPDATE` · MySQL=`ON DUPLICATE KEY UPDATE`. `count` = 처리된 입력 행 수(삽입+갱신 · 갱신 대상 없으면 실 삽입 수). `onConflict` 생략 = 기본 키(`id`) 자동(없으면 throw) · `update` 생략(`'exclude'`) = 입력 컬럼에서 충돌 기준·`id` 뺀 나머지를 덮음 |
 | `find` | `(id)` | `Promise<Rec>` | 없으면 **throw** — undefined 를 허용하려면 `where('id', '=', id).first()` |
 | `query` | `()` | Kysely `SelectQueryBuilder` | §5 탈출구 |
 
-> 벌크 삽입 3종(`batchInsert`·`insertOrIgnore`·`upsert`)은 **RETURNING 을
-> 지원하는 커넥션(Postgres)** 에서만 된다 — 삽입/무시/갱신된 행 집합을
-> 정확히 복원할 수 있는 방언이 RETURNING 뿐이라, 비 RETURNING 커넥션에서는
-> 어림하지 않고 수리 안내와 함께 **throw** 한다(결정 35 · §7.5.3). 삽입 계열은
+> 벌크 3종은 **전 방언 통일 `BulkResult`**(`{ count, meta? }`)를 돌려준다(결정 90 ·
+> 원안의 "비 RETURNING 방언 throw" 폐기). `count` 는 **처리된 입력 행 수**로 방언
+> 무관 같은 의미다 — MySQL upsert 의 원시 `affectedRows`(삽입 1·갱신 2·무변경 0/1)를
+> 그대로 노출하지 않고 정규화한다. 방언 원시값이 필요하면 `meta`(PG `returnedIds` ·
+> MySQL `firstInsertId`·`affectedRows`)를 쓴다. **행 자체가 필요하면**: 소량은
+> `create()`(단건 · 전 방언 Rec 반환), 대량은 유니크 키로 재조회 — **id 범위 추정
+> 재조회는 금지**(MySQL auto-increment 는 동시 삽입에서 연속 보장이 없다). 삽입 계열은
 > `create` 처럼 루트 전용 — `where` 필터와 무관하므로 체인 종단이 아니다.
 
+**개수·집계 반환 타입 — 영역별로 다르다** (결정 90·91 · 헷갈리지 말 것):
+
+| 영역 | 반환 타입 | 근거 |
+|---|---|---|
+| 쓰기 개수 (`BulkResult.count` · `updateAll` · `deleteAll`) | `number` | 처리 행 수 — 2^53 초과 실무 없음 · JSON 직렬화 |
+| 읽기 집계 `count()` | `bigint` | E-4 정본 |
+| 읽기 집계 `sum()` · `avg()` | `string` | 무손실(정밀도 보존) |
+| 읽기 집계 `min()` · `max()` | 컬럼 타입 따름 | E-4 정본 |
+
+> **왜 sum/avg 가 `number` 가 아닌가**: 양 방언 실측 결과 집계 체인은 이미 방언
+> 일관이라(silent split 없음) 고칠 문제가 없고, `string→number` 강제는 2^53 초과
+> 합계에서 **정밀도를 잃는**(lossy) breaking 이라 "어림 금지" 원칙에 어긋나 기각했다
+> (결정 91). 쓰기 개수(number)와 읽기 집계(string/bigint)는 축이 다르다.
+
 **레코드(`Rec`) 내장** (`model.ts:47-52`):
 
 - `rec.update(patch)` — `Partial<Row>` 부분 갱신, 갱신된 Rec 반환.
@@ -546,14 +563,15 @@ const slim = await Post.select(['id', 'title']).all()  // Pick<Row, 'id' | 'titl
 // 삭제 — 단건은 레코드, 벌크는 deleteAll (M2C)
 const post = await Post.find(id)
 await post.delete()
-const removed = await Post.where('published', '=', false).deleteAll()   // bigint
+const removed = await Post.where('published', '=', false).deleteAll()   // number
 const touched = await Post.where('authorId', '=', me.id).updateAll({ published: true })
 
-// 벌크 삽입·UPSERT — 루트 전용 (M2F · 결정 35)
-const seeded = await Post.batchInsert(rows)          // 단일 INSERT 문 · Rec[] (순서 보존)
-const fresh = await Post.insertOrIgnore(rows)         // 충돌 건너뜀 · 실 삽입만
-await Post.upsert(rows, { onConflict: 'slug', update: ['title', 'body'] })
+// 벌크 삽입·UPSERT — 루트 전용 (M2F · 결정 35 → BulkResult 결정 90 · 전 방언 통일)
+const seeded = await Post.batchInsert(rows)          // { count } (삽입 행 수)
+const fresh = await Post.insertOrIgnore(rows)         // { count } (실 삽입만 · 충돌 건너뜀)
+const { count } = await Post.upsert(rows, { onConflict: 'slug', update: ['title', 'body'] })
 await Post.upsert({ id, title, body })                // onConflict 생략 = 기본 키(id)
+// 삽입된 행이 필요하면: 소량은 create(), 대량은 유니크 키로 재조회 (id 범위 추정 금지)
 ```
 
 ## 알려진 함정
@@ -568,6 +586,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   `foreignKey`/`otherKey` 를 명시한다.
 - **`updateAll`/`deleteAll` 에 limit·offset·orderBy 가 걸려 있으면 throw** —
   행을 좁히려면 `pluck('id')` → `whereIn('id', ids)`.
+- **벌크 3종은 행이 아니라 `{ count }` 를 준다** (결정 90) — 반환을 `Rec[]` 처럼
+  다루지 말 것. 삽입된 행이 필요하면 소량은 `create()`, 대량은 유니크 키 재조회.
+  `throw` 하던 옛 계약(비 RETURNING 방언)은 폐기 — MySQL 도 그냥 `count` 를 준다.
 - **loop 안 관계 lazy 호출 = N+1** — doctor **n-plus-one** 검사가 잡는다.
   목록은 `include()` 로.
 - **스키마 파일명은 camelCase** — 테이블 `posts_tags` → 파일 `postsTags.ts`
@@ -588,8 +609,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 31 | `rec.delete()` 명명(destroy 아님) · 파라미터 스코프 (M2C) |
 | 결정 33 | 관계 선언 위치(컬럼 + relations) · 문자열 테이블명 (M2D) |
 | 결정 34 | 집계·조인 그룹(groupBy·having·distinct·withCount·join) (M2E) |
-| 결정 35 | 벌크 삽입 3종(batchInsert·insertOrIgnore·upsert) (M2F) |
+| 결정 35 | 벌크 삽입 3종(batchInsert·insertOrIgnore·upsert) (M2F) → **결정 90 으로 개정** |
 | 결정 39 | 마이그레이션 합성형(파일 replay → 스키마 diff · no-auto-drop) |
+| 결정 90 | 벌크 3종 `BulkResult`(count+meta) 전 방언 통일 · updateAll/deleteAll bigint→number (W14) |
 | 결정 43 | 네이밍 정본화 · DB 네이밍 SSOT(§1.2 · 테이블 snake · 컬럼 camel) |
 | 결정 46 | doctor 컬럼(column-casing)·모델/페이지 파일명 검사 3종 |
 | 결정 47 | `gaon g model` 다단어 테이블명 snake_case(마지막 단어 복수) |

package/dist/templates/project/agents/frontend.md.tpl

@@ -36,6 +36,19 @@ const props = pageProps<'web:posts#index'>()
   액션 → `'web:posts#index'`.
 - **파사드는 `gaonjs/vue`** — `@gaonjs/vue` (스코프)·`@inertiajs/vue3` (내부 의존)
   로 import 하지 않는다.
+- **Gaon 은 `vue-router` 를 쓰지 않는다** — 라우팅은 **Inertia = SPA + 서버
+  라우팅**이라 클라이언트 라우터 라이브러리가 없다. `vue-router`·`react-router`
+  를 install/import 하지 말 것(`createRouter`·`useRoute`·`useRouter`·`<RouterLink>`
+  전부 없음 · CLAUDE.md 규칙 12). 페이지 전환은 `gaonjs/vue` 의 `router`
+  (`router.visit(url)`·`router.get/post/delete`), 폼은 `useForm(...)` (결정 64).
+  라우트 정의는 서버의 `apps/<앱>/routes.ts` 뿐이다.
+- **앱 내부 이동 = `Link`(선언적) 또는 `router.visit`(프로그램적) — 내부 경로
+  일반 `<a>` 금지** (결정 96). 내부 경로로 가는 `<a href="/...">` 는 클릭마다
+  전체 문서를 다시 로드해 Inertia SPA 상태(스크롤·폼 입력·채널 구독)가 초기화된다
+  (첫 실사용 블로그에서 "메인 경로" 풀 리로드로 관측). 선언적 링크는 `gaonjs/vue`
+  의 `Link`(`<Link href="/posts">글 목록</Link>`), 코드에서의 이동은
+  `router.visit(url)`. **외부 URL(`https://…`)·`target="_blank"` 만 `<a>`** 를
+  유지한다. 내부 경로 일반 앵커는 doctor **internal-anchor** 가 잡는다(결정 96).
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 
@@ -169,7 +182,8 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
   scoped-CSS 미편입 방침은 결정 74 로 뒤집혔다).
 - **auth 링크는 수동(결정 70)** — `gaon g auth` 는 auth 페이지·라우트만 신설하고
   랜딩·레이아웃 nav 를 편집하지 않는다. 헤더에 로그인 링크를 두려면 `Default.vue`
-  의 nav 에 `<a href="/session/new">로그인</a>` 을 직접 추가한다(Rails 관례).
+  의 nav 에 `<Link href="/session/new">로그인</Link>` 을 직접 추가한다(내부 이동은
+  `Link` · 일반 `<a>` 는 풀 리로드 · 결정 96).
 - **auth 페이지 경로 = `pages/Auth/`(PascalCase)** — `gaon g auth` 는 `Auth/Login.vue`
   ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
   소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
@@ -259,6 +273,23 @@ async function runSearch(q: string) {
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
   `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
+- **내부 경로 일반 `<a href="/...">` 금지** — 클릭마다 전체 문서를 다시
+  로드해 SPA 상태가 초기화된다. 앱 내부 이동은 `gaonjs/vue` 의 `Link`
+  (`<Link href="/...">`) 또는 `router.visit(...)`, 외부 URL·`target="_blank"`
+  만 `<a>` (결정 96 · doctor **internal-anchor**).
+- **`vue-router` import 금지** — Gaon 은 클라이언트 라우터가 없다(Inertia =
+  SPA + 서버 라우팅). `import { useRouter } from 'vue-router'` 는 존재하지 않는
+  의존을 끌어와 컴파일 실패한다 — 전환은 `gaonjs/vue` 의 `router`, 라우트 정의는
+  `apps/<앱>/routes.ts`(§1).
+- **로그아웃은 `router.delete('/session')`** — `?_method=DELETE` 폼 override(Rails/
+  Laravel 관례)는 Gaon 에서 안 통한다(Inertia 는 실 DELETE 를 보낸다 · 컴파일은
+  통과해도 런타임 조용히 파손). 로그아웃 링크/버튼은 `router.delete(...)` 또는
+  `useForm(...).delete(...)` 로 한다(결정 64 · 절대 규칙 6). `_method` 사용은 doctor
+  **method-override** 가 잡는다(결정 89).
+- **채널 구독은 `useChannel()`** — 실시간 클라이언트는 `gaonjs/vue` 의
+  `useChannel(name, opts)` 가 정본(결정 87). `new WebSocket` 을 손으로 짜면
+  URL(`/gaon/ws/<채널>`)·봉투(`{ t:'msg', data }`)·라이프사이클을 재구현하다
+  틀린다(`agents/realtime.md` §4). 구독 래핑은 컴포저블에.
 - **레이아웃을 shared 에 두지 않는다** — 앱별이 정상.
 - **페이지 파일명은 PascalCase** — `pages/Posts/Index.vue`(폴더 세그먼트도
   Route 이름). 소문자(`posts/index.vue`)는 doctor **page-filename** 이 잡는다
@@ -281,4 +312,5 @@ async function runSearch(q: string) {
 | 결정 74 | Tailwind 스캐폴드 편입(tailwind.config.ts·postcss.config.js·style.css · 결정 69 scoped-CSS 방침 뒤집기) |
 | 결정 75 | shadcn 식 UI 킷(`gaon g ui-kit` · 복사-소유 · Vue 3 신작 · 외부 런타임 의존 0) |
 | 결정 76 | 멀티앱 UI 킷 배선 자동화(`g app`·`g ui-kit --app` 이 앱별 Tailwind 배선 동봉·멱등 보정 · doctor ui-kit-wiring) |
+| 결정 96 | 앱 내부 이동 = `Link`(선언적)/`router.visit`(프로그램적) · 내부 경로 일반 `<a>` 금지(풀 리로드) · `Link` 재수출 · doctor internal-anchor |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |

package/dist/templates/project/agents/realtime.md.tpl

@@ -89,29 +89,36 @@ const members = await ctx.presence()
 - leave 는 best-effort 이고, 서버가 죽으면 허브가 그 서버의 멤버 전원을
   **즉시** 정리한다 (TCP `close`).
 
-### 4. 클라이언트 (WebSocket)
+### 4. 클라이언트 (`useChannel` · 결정 87)
 
-브라우저는 표준 WebSocket 으로 채널에 접속한다. 세션 앱은 세션 쿠키로,
-JWT 앱은 쿼리(`access_token`)로 인증한다.
-
-**경로는 `<앱 프리픽스>/gaon/ws/<채널명>`** 이고, 보내는 프레임은 `{ t: 'msg',
-data }` **봉투** 다 — 날 페이로드를 그대로 보내면 서버가 `onMessage` 로
-흘리지 않는다. 받는 프레임도 같은 모양(`t` 로 종류를 가른다).
+**정본 = `gaonjs/vue` 의 `useChannel(name, opts)`.** 채널 구독의 One Way 다 —
+URL 조립(`<앱 프리픽스>/gaon/ws/<채널명>` · ws/wss 자동)·봉투(`{ t:'msg', data }`)
+감싸기/풀기·마운트 접속·언마운트 정리·반응형 상태를 한 번에 준다. `new WebSocket`
+을 손으로 짜지 말 것(라이프사이클·봉투를 재구현하다 실수한다). 세션 앱은 쿠키로
+자동 인증, JWT 앱은 `params: { access_token }`.
 
 ```ts
-// 브라우저측 — 채널 구독 래핑은 컴포저블에 (agents/frontend.md)
-// web 앱(프리픽스 /)의 room 채널 = /gaon/ws/room. admin 앱이면 /admin/gaon/ws/room.
-const ws = new WebSocket(`wss://example.com/gaon/ws/room?room=42`)
-ws.onmessage = (ev) => {
-  const frame = JSON.parse(ev.data)      // { t: 'msg' | 'presence' | ... , data }
-  if (frame.t === 'msg') {
-    // 서버가 broadcast/send 한 데이터
-  }
+// apps/web/composables/useRoom.ts — 컴포저블에 래핑(agents/frontend.md §3.2)
+import { useChannel } from 'gaonjs/vue'
+
+export function useRoom(roomId: number) {
+  // messages(반응형)·status·send·connect·close 를 돌려준다. 마운트에 접속.
+  const { messages, status, send } = useChannel('room', {
+    params: { room: roomId },
+    onMessage: (data) => { /* 서버가 broadcast/send 한 데이터 */ },
+    onPresence: (delta) => { /* 접속자 join/leave */ },
+  })
+  return { messages, status, send }
 }
-// 보낼 때도 봉투로 감싼다 — 이래야 채널의 onMessage 가 호출된다.
-ws.send(JSON.stringify({ t: 'msg', data: { text: '안녕하세요' } }))
 ```
 
+- **보내기** — `send(data)` 가 `{ t:'msg', data }` 봉투로 감싸 보낸다(서버 `onMessage`
+  정답 경로). 날 페이로드를 직접 보내면 서버가 안 흘린다.
+- **받기** — `msg` 프레임은 `messages` 에 축적 + `onMessage` 호출, `presence` 는
+  `onPresence`. 그 외는 `onFrame`.
+- **탈출구** — 표준 WebSocket 이 필요하면 `new WebSocket('<프리픽스>/gaon/ws/<채널명>')`
+  을 직접 쓸 수 있다(봉투·라이프사이클을 스스로 책임진다). 기본 경로는 `useChannel`.
+
 ### 5. 허브 프로세스 (`gaon hub`)
 
 허브는 접속자 목록의 단일 권위이자 서버 간 중계다.

package/dist/templates/project/agents/security.md.tpl

@@ -7,12 +7,21 @@
 
 ### 1. 보안 기본값 = fail-closed (v0.15 §2.5.1)
 
-**CORS · rate limit · CSRF 는 코어에서 기본 켬.** 끄는 것은 명시적
-설정으로만 (v0.15 §2.5.1 원문 근거).
+**CORS · rate limit · CSRF · 보안 응답 헤더는 코어에서 기본 켬.** 끄는 것은
+명시적 설정으로만 (v0.15 §2.5.1 원문 근거).
 
 보안 결함 = 보안이 선택 설치면 설치 안 한 앱의 기본값이 무방비가
 된다. Rails/Laravel 이 증명한 원칙이다 (§2.5.1).
 
+- **보안 응답 헤더 (결정 86)** — 코어가 모든 응답에 CSP·HSTS(HTTPS 한정)·
+  `X-Content-Type-Options: nosniff`·`X-Frame-Options: SAMEORIGIN`·
+  `Referrer-Policy: strict-origin-when-cross-origin`·`Cross-Origin-Opener-Policy`
+  를 자동으로 붙인다. 기본 CSP 는 Inertia SPA + vite 스택에서 안 깨지게 튜닝돼
+  있다(`script-src 'self'`·인라인 스타일 허용·`connect-src ... ws: wss:` 로
+  realtime 허용). 끄거나 조정은 `createApp({ security: { securityHeaders: … } })`
+  — `false` 로 전부 끔, `{ contentSecurityPolicy: '…' | false, hsts: false }` 로 조정.
+  `helmet` 등 라이브러리를 따로 깔지 말 것(코어 내장 · 라이브러리 미의존).
+
 ### 2. 세션·CSRF·JWT
 
 - 세션은 앱별 완전 분리 (v0.15 §7 · Fastify 캡슐화 스코프): 쿠키
@@ -21,6 +30,12 @@
 - CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF
   강제. `api()` 클라이언트는 `<meta name="csrf-token">` 을 자동으로
   읽어 `X-CSRF-Token` 헤더에 붙인다 (`packages/vue/src/api.ts:184`).
+- **CSRF 는 세션 위에 얹힌다 — 세션이 없으면 CSRF 도 없다 (결정 93).**
+  세션이 있어야 토큰을 저장·검증할 곳이 생긴다. `gaon new` 기본 web 앱은
+  `app.config.ts` 에 세션을 **기본 배선**해 규칙 8(기본 켬)이 실태가 되게
+  한다 — 폼(POST)을 추가하는 순간 CSRF 가 이미 켜져 있다. 앱에 비-GET
+  라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
+  `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
 - JWT 는 API 앱 전용 옵션. 세션 쿠키가 기본 (v0.15 §7 · v0.11 확정).
 
 ### 3. 시크릿
@@ -90,3 +105,4 @@ const rows = await Post.query()
 | §2.5.1 (v0.15) | 보안 기본값 fail-closed (CORS·rate limit·CSRF 기본 켬) |
 | 결정 24 (E-3 §5) | `this.params` 고정 우선순위 — 파라미터 오염 차단 |
 | §7 (v0.15) | 세션 앱별 분리 · JWT 는 API 앱 전용 |
+| 결정 93 (W2) | 기본 web 앱 세션 기본 배선 = CSRF 기본 켬 실태 · doctor `csrf-wiring` 경고 |

package/dist/templates/project/agents/web.md.tpl

@@ -100,6 +100,47 @@ export default controller({
 - 기본 경로는 여전히 `this.params` 하나(The One Way) — 스캐폴드·문서·
   기본 예시는 `this.params` 만 쓴다 (E-3 §5.3 원문).
 
+**폼 모양 두 가지 — 스키마 파생 vs 애드혹 (라우트 파라미터는 둘 다 자동 병합 · 결정 95):**
+
+라우트 파라미터·body·query 병합은 폼 모양과 무관하게 항상 일어난다 —
+`this.params(...)` 에 넘기는 폼은 **결과 타입**만 정한다. 그래서 `/posts/:id`
+같은 라우트 파라미터와 폼 필드를 **한 번의 `this.params` 로 함께** 받는다.
+
+- **① 스키마 파생 폼 `this.params(Model.form)`** — 정본. 모델 컬럼 타입으로
+  런타임 강제 변환·검증(대량 할당 차단)까지 한다. 라우트 파라미터는 **키 이름이
+  컬럼과 같으면** 자동으로 그 자리에 들어간다. 그래서 라우트를 컬럼명에 맞춰
+  짓는 게 관례다:
+
+  ```ts
+  // routes: r.post('/posts/:postId/comments', 'comments#create')
+  // 스키마 comments 에 postId·author·body 컬럼이 있으면:
+  async create() {
+    // :postId 는 라우트에서, author·body 는 body 에서 — 한 번에 검증까지.
+    const data = this.params(Comment.form)   // { postId, author, body, ... } (검증됨)
+    const comment = await Comment.create(data)
+    return this.redirect(`/posts/${String(data.postId)}`)
+  }
+  ```
+
+- **② 애드혹 폼 `this.params({ _row: {} as { ... } })`** — 전용 모델이 없거나
+  받을 필드를 **정확히** 고를 때. 라우트 파라미터·폼 필드를 자유롭게 섞어 타입을
+  못박는다. 단 **런타임 스키마 검증은 없다**(타입만 · 컬럼 정의가 없어 coerce
+  스킵) — 필요하면 값 검사를 직접 하거나 ①로 간다:
+
+  ```ts
+  // routes: r.post('/posts/:id/comments', 'comments#create')
+  async create() {
+    // :id(라우트) + author·body(폼) 를 한 폼 모양으로.
+    const { id, author, body } = this.params({
+      _row: {} as { id: string; author: string; body: string },
+    })
+    // ...
+  }
+  ```
+
+  ①이 검증까지 주므로 **모델이 있으면 ①을 먼저 고른다**. ②는 로그인 폼처럼
+  전용 테이블이 없는 입력의 탈출구다.
+
 ### 4. 데이터 경로 판단 — 루트 판단표가 정본
 
 데이터가 필요할 때는 루트 `AGENTS.md` 의 데이터 경로 4종 판단표를 따른다
@@ -275,6 +316,11 @@ export default controller({
 - **`@gaonjs/*` 스코프 직접 import 금지** — 파사드 `gaonjs/*` 만.
 - **bigint PK 를 render props 로 흘릴 때는 `String(p.id)` 정규화**
   (결정 37 · 상세는 `agents/frontend.md`).
+- **정적 파일(robots.txt·favicon.ico·이미지 등)은 `apps/<앱>/static/`** 에 둔다
+  (결정 85) — 앱 prefix 아래로 서빙된다(web→`/robots.txt`, admin→`/admin/robots.txt`).
+  라우트·`/assets/*` 가 항상 우선하므로 라우트와 같은 경로에 두면 가려진다
+  (doctor **static-collision** 가 경고). 정적 서빙에 `@fastify/static` 을 따로
+  깔지 말 것(코어 내장).
 
 ## 관련 결정 번호
 
@@ -285,4 +331,5 @@ export default controller({
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 — `agents/async.md`) |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 (`agents/frontend.md`) |
 | 결정 59 | 인증 배선 = `app.config.ts` 의 `session`+`auth(loadUser)` — 없으면 currentUser 영구 null |
+| 결정 95 (W4) | 폼 모양 2종 — 스키마 파생 `Model.form`(검증) vs 애드혹 `{ _row }`(타입만) · 라우트 파라미터는 둘 다 자동 병합 |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/project/apps/web/app.config.ts.tpl

@@ -0,0 +1,14 @@
+// 앱 설정 — apps/web/app.config.ts. 보안 기본값(세션 + CSRF)을 표준 부팅
+// (gaon dev / gaon serve)에 배선한다. 잘 지은 app.config 는 거의 비어 있어야
+// 하지만(§1.1), 세션은 CSRF 토큰 저장소의 토대라 기본으로 켠다.
+//
+// 규칙 8(§2.5.1): CORS·rate limit·CSRF 는 코어에서 **기본 켬** — 끄는 것은
+// 명시적 설정으로만. 세션이 있어야 상태 변경 요청(POST/PUT/PATCH/DELETE)에
+// CSRF 토큰 검증이 걸린다. 세션 스토어는 루트 gaon.config.ts 의 redis(REDIS_URL)
+// 를 wireGaon 이 주입한다(결정 93).
+import { defineAppConfig } from 'gaonjs/config'
+
+export default defineAppConfig({
+  // secret 은 32자 이상 — .env 의 SESSION_SECRET 로 주입한다(운영은 반드시 교체).
+  session: { secret: process.env.SESSION_SECRET ?? 'dev-only-session-secret-change-me-now!!' },
+})

package/dist/templates/project/apps/web/layouts/Default.vue.tpl

@@ -9,6 +9,10 @@
 // 다크 헤더 + 라이트 본문(결정 69). 스타일은 Tailwind 유틸(결정 74) — 다크
 // 헤더는 본문 테마와 무관하게 항상 어둡게 두려고 브랜드 색을 명시값으로 박는다.
 // 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
+//
+// 결정 96: 앱 내부 이동은 `Link`(선언적) — `<a href="/">` 는 전체 문서
+// 리로드라 SPA 가 깨진다. 외부 URL 만 `<a>`(문서·GitHub).
+import { Link } from 'gaonjs/vue'
 
 // package.json 의 gaonjs 의존 범위(예: ^0.9.2)에서 캐럿·틸드를 벗겨 표기.
 const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
@@ -19,13 +23,13 @@ const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
     <header
       class="flex items-center justify-between gap-4 border-b border-[#21262d] bg-[#0d1117] px-6 py-3.5 text-[#e6edf3]"
     >
-      <a href="/" class="inline-flex items-baseline gap-2.5 text-inherit no-underline">
+      <Link href="/" class="inline-flex items-baseline gap-2.5 text-inherit no-underline">
         <span
           class="inline-block rounded-md bg-gradient-to-br from-[#4f8cff] to-[#7c5cff] px-1.5 py-0.5 text-xs font-bold tracking-wide text-white"
         >가온</span>
         <span class="text-[0.95rem] font-bold tracking-[0.08em]">GAONJS</span>
         <span class="text-xs tabular-nums text-[#8b949e]">v{{ version }}</span>
-      </a>
+      </Link>
       <nav class="flex gap-[1.1rem] text-sm">
         <a href="https://gaonjs.dev" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">문서</a>
         <a href="https://github.com/gaonjs" target="_blank" rel="noreferrer" class="text-[#c9d1d9] no-underline hover:text-white">GitHub</a>

package/dist/templates/project/apps/web/static/robots.txt.tpl

@@ -0,0 +1,4 @@
+# {{PROJECT_NAME}} · 정적 파일 폴더 (결정 85) — 이 폴더의 파일은 앱 루트로 서빙된다.
+# 예: 이 robots.txt 는 /robots.txt 로, static/img/logo.png 은 /img/logo.png 으로.
+User-agent: *
+Disallow:

package/dist/templates/project/compose.prod.yaml.tpl

@@ -0,0 +1,98 @@
+# {{PROJECT_NAME}} 운영 스택 — 웹·워커·허브 3종 프로세스 + 실 인프라.
+#
+# 개발 스택(docker-compose.yaml)과 달리 앱 이미지(Dockerfile)를 빌드해 serve·work·
+# hub 를 별도 서비스로 띄운다(운영 프로세스 3종 · CLAUDE.md §2 · 결정 60). 인프라는
+# 실 pg·redis·nats(목업 금지 §9). 시크릿은 env 로 주입한다 — 이 파일에 값을 박지 말 것.
+#
+# 기동:  docker compose -f compose.prod.yaml up -d --build
+# 정지:  docker compose -f compose.prod.yaml down
+name: {{PROJECT_NAME}}-prod
+
+x-app-env: &app-env
+  DATABASE_URL: postgres://{{PROJECT_NAME}}:${DB_PASSWORD:?set DB_PASSWORD}@postgres:5432/{{PROJECT_NAME}}
+  REDIS_URL: redis://redis:6379
+  NATS_URL: nats://nats:4222
+  COOKIE_SECRET: ${COOKIE_SECRET:?set COOKIE_SECRET (32+ chars)}
+  NODE_ENV: production
+
+services:
+  # 웹 프로세스(gaon serve). node:cluster 워커 수는 WEB_CONCURRENCY 로(기본 1).
+  web:
+    build: .
+    command: ["pnpm", "serve"]
+    environment:
+      <<: *app-env
+      PORT: "3000"
+      WEB_CONCURRENCY: "${WEB_CONCURRENCY:-1}"
+    ports:
+      - "3000:3000"
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  # 워커 프로세스(gaon work) — 잡·리스너·스케줄러·아웃박스 릴레이.
+  worker:
+    build: .
+    command: ["pnpm", "work"]
+    environment: *app-env
+    depends_on:
+      postgres: { condition: service_healthy }
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  # 허브 프로세스(gaon hub) — 리더만 bind, 프레즌스 단일 권위(결정 60 · §7).
+  hub:
+    build: .
+    command: ["pnpm", "hub"]
+    environment:
+      <<: *app-env
+      GAON_HUB_PORT: "4001"
+      GAON_HUB_ADVERTISE: "hub:4001"
+    depends_on:
+      nats: { condition: service_healthy }
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: {{PROJECT_NAME}}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
+      POSTGRES_DB: {{PROJECT_NAME}}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U {{PROJECT_NAME}} -d {{PROJECT_NAME}}"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redisdata:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+  nats:
+    image: nats:2.10-alpine
+    command: ["-js", "-sd", "/data", "-m", "8222"]
+    volumes:
+      - natsdata:/data
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8222/healthz"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+
+volumes:
+  pgdata:
+  redisdata:
+  natsdata:

package/dist/templates/project/package.json.tpl

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "packageManager": "pnpm@10.27.0",
   "engines": {
     "node": ">=22"
   },

package/dist/work.js

@@ -44,6 +44,8 @@ function emitHuman(e) {
             return undefined;
         case 'relay':
             return `  ↪ 아웃박스 릴레이 — ${e.count}건 발행`;
+        case 'purge':
+            return `  🧹 아웃박스 정리 — ${e.count}건 삭제(보존 기간 초과)`;
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.18.0",
+  "version": "0.23.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.5.0",
-    "@gaonjs/core": "0.2.0",
-    "@gaonjs/config": "0.4.1",
-    "@gaonjs/web": "0.6.1",
-    "@gaonjs/mail": "0.1.1",
-    "@gaonjs/data": "0.8.4"
+    "@gaonjs/async": "0.6.1",
+    "@gaonjs/data": "0.9.1",
+    "@gaonjs/web": "0.7.1",
+    "@gaonjs/core": "0.2.1",
+    "@gaonjs/config": "0.5.2",
+    "@gaonjs/mail": "0.1.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""