@gaonjs/cli 0.15.0 → 0.21.2

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,12 @@ 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` 뿐이다.
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 
@@ -160,8 +166,13 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
 이 엔드포인트는 `gaon dev` 에서만 등록되고(운영 빌드엔 없음), 404 면 컴포저블이
 `available=false` 로 우아하게 degrade 한다.
 
-- **스타일은 SFC `<style scoped>` + CSS 변수** — 스캐폴드에 Tailwind 를 넣지
-  않는다(의존성 경량 · 결정 69). 유틸 클래스 대신 scoped CSS 로 캡슐화.
+- **HUB 카드는 실 introspection(결정 71)** — jobs = JetStream 스트림 대기(pending)
+  수 · channels = 프레즌스 KV 권위의 채널별 실 접속자 수. 조회 실패·미접속을 0/true
+  로 가장하지 않는다(과대 약속 금지) — 버킷·스트림 미생성이면 각각 null 로 degrade.
+- **스타일은 Tailwind 유틸 + UI 킷(결정 74·75)** — 스캐폴드는 Tailwind
+  (`tailwind.config.ts`·`postcss.config.js`·`apps/<앱>/style.css`)를 편입한다.
+  랜딩·auth 페이지는 Tailwind 유틸과 UI 킷 컴포넌트(§8)로 그린다(결정 69 의
+  scoped-CSS 미편입 방침은 결정 74 로 뒤집혔다).
 - **auth 링크는 수동(결정 70)** — `gaon g auth` 는 auth 페이지·라우트만 신설하고
   랜딩·레이아웃 nav 를 편집하지 않는다. 헤더에 로그인 링크를 두려면 `Default.vue`
   의 nav 에 `<a href="/session/new">로그인</a>` 을 직접 추가한다(Rails 관례).
@@ -169,6 +180,55 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
   ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
   소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
 
+### 8. UI 킷 (결정 74·75 · shadcn 참조 · 복사-소유)
+
+`gaon new` 는 기본 앱에 UI 킷을 심고(배터리 포함), `gaon g ui-kit [--app <앱>]`
+로 다른 앱에도 추가한다. 컴포넌트는 **프로젝트에 복사된 여러분 코드**다 — npm
+의존이 아니라 파일이므로 자유롭게 고친다(shadcn 방식). 외부 런타임 의존이 없다
+(clsx·tailwind-merge·cva·reka-ui 미도입 · `cn` 은 자작 · Dialog/Sheet 는 Teleport+
+Transition 자작).
+
+배치·import:
+
+```
+apps/<앱>/lib/utils.ts            # cn() — 조건부 클래스 병합
+apps/<앱>/components/ui/*.vue      # Button·Input·Label·Badge·Card…·Alert…·Form…·Dialog·Sheet
+```
+
+```vue
+<script setup lang="ts">
+import Button from '../../components/ui/Button.vue'   // 앱 로컬 · 상대 경로
+import Card from '../../components/ui/Card.vue'
+import CardContent from '../../components/ui/CardContent.vue'
+</script>
+
+<template>
+  <Card>
+    <CardContent>
+      <Button variant="default">저장</Button>       <!-- variant·size 로 모양 선택 -->
+    </CardContent>
+  </Card>
+</template>
+```
+
+- **폼은 UI 킷 Form + gaonjs `useForm`(결정 64)** — `Form` 은 얇은 `<form>` 래퍼로
+  `@submit` 을 `useForm` 의 `post/put/delete` 로 넘긴다. vee-validate 를 끌어오지
+  않는다(검증·상태는 `useForm`). `FormField label error` + `FormMessage` 로 라벨·
+  오류를 붙이고, `:error="form.errors.<field>"` 로 서버 검증을 표시한다.
+- **`class` 는 폴스루로 병합** — 단일 루트 컴포넌트는 `<Button class="w-full">` 처럼
+  넘긴 클래스가 루트로 흘러간다(별도 `class` prop 선언 없음). `cn` 은 충돌 클래스
+  자동 해소를 하지 않는다 — 오버라이드가 잦으면 tailwind-merge 를 설치해 `cn` 만 교체.
+- **디자인 토큰은 `style.css` 한 곳(결정 74)** — 컴포넌트는 `bg-primary`·
+  `text-muted-foreground` 같은 의미 토큰만 쓰고, 실색은 `apps/<앱>/style.css` 의
+  `:root`/`.dark` CSS 변수에서 바꾼다(다크 모드 = `<html class="dark">`).
+- **멀티앱은 앱마다 배선이 따로다(결정 76)** — `gaon g app admin` 은 새 앱에
+  프론트 배선(`apps/admin/{style.css,main.ts,index.html}`)을 web 앱과 동등하게
+  함께 심는다. 그래서 `gaon g ui-kit --app admin` 으로 심은 UI 킷이 Tailwind
+  유틸을 그대로 받는다(`g ui-kit --app` 은 배선이 없으면 멱등으로 보정한다).
+  `tailwind.config.ts`·`postcss.config.js` 는 프로젝트 루트 공유(앱마다 두지
+  않는다). 앱이 UI 킷을 import 하는데 그 앱에 `style.css` 배선이 없으면 doctor
+  **ui-kit-wiring** 이 경고한다.
+
 ## 정본 예시
 
 ```vue
@@ -204,7 +264,20 @@ async function runSearch(q: string) {
 - **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출 금지** — doctor
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
-  `Inertia.post()` (`agents/web.md` §4).
+  `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
+- **`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** 이 잡는다
@@ -221,6 +294,10 @@ async function runSearch(q: string) {
 | 결정 25 (E-5) | 컴포저블·레이아웃 관례 · 프론트 로직 배치 3규칙 · 자동 import 금지 |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 |
 | 결정 46 | doctor page-filename(페이지 PascalCase)·model/column 검사 3종 |
-| 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · Tailwind 미편입 · scoped CSS) |
+| 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · 실 상태 · 코드 블록) |
 | 결정 70 | auth 통합 = 수동(`gaon g auth` 는 랜딩·nav 를 안 건드림 · Rails 관례) |
+| 결정 71 | HUB 카드 실 introspection(jobs=스트림 pending · channels=프레즌스 실 접속자 · 과대 약속 금지) |
+| 결정 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) |
 | 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 캡슐화 스코프): 쿠키

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

@@ -275,6 +275,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` 을 따로
+  깔지 말 것(코어 내장).
 
 ## 관련 결정 번호
 

package/dist/templates/project/apps/web/composables/useGaonHealth.ts.tpl

@@ -28,7 +28,9 @@ export interface HealthDatabase {
 export interface HealthHub {
   configured: boolean
   connected?: boolean
+  // jobs: JetStream 스트림 대기 수 · channels: 채널별 실 접속자 수(결정 71).
   streams?: { stream: string; waiting: number | null }[]
+  channels?: { channel: string; members: number }[] | null
   error?: string
 }
 export interface HealthDoctor {

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

@@ -6,114 +6,39 @@
 // 레이아웃은 shared 에 두지 않는다(E-5 §2.3) — 앱마다 레이아웃이 다른 것이
 // 정상이고, 공용 조각(로고·푸터 등) 만 shared/components 로 뽑는다.
 //
-// 다크 헤더 + 라이트 본문(결정 69). 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
-//
-// 결정 70(auth = 수동): gaon g auth 는 이 nav 를 건드리지 않는다. 로그인 링크를
-// 헤더에 두려면 아래 nav 에 <a href="/session/new">로그인</a> 을 직접 추가한다.
+// 다크 헤더 + 라이트 본문(결정 69). 스타일은 Tailwind 유틸(결정 74) — 다크
+// 헤더는 본문 테마와 무관하게 항상 어둡게 두려고 브랜드 색을 명시값으로 박는다.
+// 버전은 스캐폴드 시점 gaonjs 버전이 박힌다.
 
 // package.json 의 gaonjs 의존 범위(예: ^0.9.2)에서 캐럿·틸드를 벗겨 표기.
 const version = '{{GAONJS_VERSION}}'.replace(/^[\^~]/, '')
 </script>
 
 <template>
-  <div class="gaon-layout">
-    <header class="gaon-header">
-      <a class="gaon-brand" href="/">
-        <span class="gaon-brand-mark">가온</span>
-        <span class="gaon-brand-word">GAONJS</span>
-        <span class="gaon-brand-ver">v{{ version }}</span>
+  <div class="flex min-h-screen flex-col bg-background text-foreground">
+    <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">
+        <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>
-      <nav class="gaon-nav">
-        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer">문서</a>
-        <a href="https://github.com/gaonjs" target="_blank" rel="noreferrer">GitHub</a>
+      <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>
       </nav>
     </header>
 
-    <main class="gaon-main">
+    <main class="w-full flex-1">
       <slot />
     </main>
 
-    <footer class="gaon-footer">
+    <footer class="border-t border-border px-6 py-5 text-center text-muted-foreground">
       <small>{{PROJECT_NAME}} · Powered by
-        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer">Gaon</a></small>
+        <a href="https://gaonjs.dev" target="_blank" rel="noreferrer" class="text-[#4f8cff] no-underline">Gaon</a></small>
     </footer>
   </div>
 </template>
-
-<style scoped>
-.gaon-layout {
-  min-height: 100vh;
-  display: flex;
-  flex-direction: column;
-  background: #ffffff;
-  color: #1b1f24;
-  font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-}
-
-/* 다크 헤더 — 본문 테마와 무관하게 브랜드 바는 어둡게. */
-.gaon-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 1rem;
-  padding: 0.85rem 1.5rem;
-  background: #0d1117;
-  color: #e6edf3;
-  border-bottom: 1px solid #21262d;
-}
-.gaon-brand {
-  display: inline-flex;
-  align-items: baseline;
-  gap: 0.55rem;
-  text-decoration: none;
-  color: inherit;
-}
-.gaon-brand-mark {
-  display: inline-block;
-  padding: 0.15rem 0.45rem;
-  border-radius: 6px;
-  background: linear-gradient(135deg, #4f8cff, #7c5cff);
-  color: #fff;
-  font-weight: 700;
-  font-size: 0.8rem;
-  letter-spacing: 0.02em;
-}
-.gaon-brand-word {
-  font-weight: 700;
-  letter-spacing: 0.08em;
-  font-size: 0.95rem;
-}
-.gaon-brand-ver {
-  font-size: 0.72rem;
-  color: #8b949e;
-  font-variant-numeric: tabular-nums;
-}
-.gaon-nav {
-  display: flex;
-  gap: 1.1rem;
-  font-size: 0.85rem;
-}
-.gaon-nav a {
-  color: #c9d1d9;
-  text-decoration: none;
-}
-.gaon-nav a:hover {
-  color: #fff;
-}
-
-.gaon-main {
-  flex: 1;
-  width: 100%;
-}
-
-.gaon-footer {
-  padding: 1.25rem 1.5rem;
-  text-align: center;
-  color: #6a737d;
-  border-top: 1px solid #eaecef;
-}
-.gaon-footer a {
-  color: #4f8cff;
-  text-decoration: none;
-}
-</style>

package/dist/templates/project/apps/web/main.ts.tpl

@@ -9,6 +9,10 @@
 // import.meta.glob 으로 만든다. 심볼 출처가 코드에 그대로 보인다.
 import { createGaonApp } from 'gaonjs/vue'
 
+// 전역 스타일 — Tailwind 레이어 + 디자인 토큰(결정 74). 부수효과 import 라
+// 번들에 CSS 가 실린다. 앱마다 하나(관례 = 배치).
+import './style.css'
+
 // 페이지는 지연 로드(코드 스플리팅) — 큰 앱에서도 첫 페이지 로딩이 빠르다.
 // eager 로 바꿔도 되지만, One Way 의 기본은 지연 로드다.
 const pages = import.meta.glob('./pages/**/*.vue')