@gaonjs/cli 0.42.0 → 0.42.2

package/dist/commands/test.js

@@ -165,7 +165,11 @@ export async function runTestCommand(args = [], opts = {}) {
     const passthrough = [...scopeExtras, ...args];
     let cmd;
     let spawnArgs;
-    if (hasTestScript(cwd)) {
+    // 결정 271(F5): 스캐폴드 `"test": "gaon test"` 가 정본이라, gaon test 가 그 스크립트를
+    // 다시 실행하면 무한 재귀다. 재진입(GAON_TEST_ACTIVE) 이면 사용자 스크립트를 건너뛰고
+    // 내장 vitest 경로로 폴백해 재귀를 끊는다 — 프로비저닝·프리픽스는 위/아래에서 유지된다.
+    const reentrant = process.env.GAON_TEST_ACTIVE === '1';
+    if (hasTestScript(cwd) && !reentrant) {
         // 결정 170 W1: pnpm 하드코딩 대신 프로젝트 선언 pm 으로 test 스크립트 실행
         // (npm/yarn 스캐폴드 대응 · 공유 `pm.ts` 단일 소스). passthrough(필터 등)는
         // pnpm·npm 은 `--` 로, yarn(classic)은 `--` 없이 전달 — scriptRunArgs 가 처리.
@@ -194,7 +198,13 @@ export async function runTestCommand(args = [], opts = {}) {
     // 붙으면 테스트가 쓰는 스트림/subject 가 `GAON_TEST_JOBS`·`test.gaon.jobs.>` 로
     // 갈려, 개발용 `gaon work` 가 떠 있어도 서로 잡을 훔치지 않는다. 사용자가 이미
     // 값을 세팅했으면 존중한다(고급 · 다중 테스트 컨텍스트 분리).
-    const testEnv = { ...process.env, GAON_STREAM_PREFIX: process.env.GAON_STREAM_PREFIX ?? 'test' };
+    // GAON_TEST_ACTIVE: 자식(사용자 test 스크립트가 `gaon test` 여도)이 재진입을 감지해
+    // 사용자 스크립트를 재실행하지 않고 내장 vitest 로 가도록 하는 재귀 차단 센티넬(결정 271).
+    const testEnv = {
+        ...process.env,
+        GAON_STREAM_PREFIX: process.env.GAON_STREAM_PREFIX ?? 'test',
+        GAON_TEST_ACTIVE: '1',
+    };
     if (json) {
         writeOut(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
     }

package/dist/templates/project/AGENTS.md.tpl

@@ -76,9 +76,11 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
    `router.delete(...)` 등). REST + `fetch()` 는 **API 앱(JWT) 전용**.
 7. **한 액션은 한 종류 응답만** (render 또는 JSON 또는 redirect —
    혼용 금지 · doctor response-mixing).
-8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`·
-   `messages.d.ts`(3축 · `locales/` 있을 때 · 결정 158) 는 `gaon check`/
-   `gaon dev` 가 재생성한다.
+8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`routes.manifest.ts`
+   (routes 축 = 타입 브리지 + api() 런타임 매니페스트 2파일 · 결정 127)·
+   `tables.d.ts`·`messages.d.ts`(3축 · `locales/` 있을 때 · 결정 158)·`env.d.ts`
+   (`.env` 스캔 · 프론트 앱 · 결정 198) 는 `gaon check`/`gaon dev`/`gaon gen` 이
+   재생성한다.
 
 ### 2.1 파일 네이밍 표 (2026-07-24 승인 · 벤치마크 R1 실측 고정)
 
@@ -134,7 +136,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 21. `async-offload` — 컨트롤러 액션 인라인의 무거운/외부 작업(메일 SDK·이미지 처리 sharp/jimp·외부 HTTP)이 응답을 지연 (`domain/jobs/` 잡 + `.later()` 로 빼라 · JSON/API 앱 외부 호출·빠른 내부 호출은 오탐 방지로 제외) (결정 102·103 · 경고)
 22. `page-layout-breakpoint` — 페이지 파일이 레이아웃 브레이크포인트(`sm:flex-row`·`md:grid-cols-2` 등)를 직접 사용(반응형은 UI 킷 블록이 책임 · `PageShell` 등으로 감싸라 · 킷에 없는 표현이면 그대로 둬도 됨 · 표시/타이포/여백 반응형은 오탐 방지로 제외) (결정 107 · 안내 경고)
 23. `link-button-nesting` — `<Link><Button>…</Button></Link>` 이중 감싸기(`<a><button>` 중첩 · HTML 비준수·접근성 결함 · 버튼 모양 링크는 `<Button href="…">` 한 표면을 쓰라 · Link 직계 자식 Button 만 검출) (결정 113 · 경고)
-24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon check --fix` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
+24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon doctor --fix --yes` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
 25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134 · `agents/data.md`)
 26. `no-import-meta-env` — `.vue`(SFC) `<script>` 에서 `import.meta.env` 직접 사용 = **에러**. SFC 는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부한다(`gaon check` red). 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로 읽으라(VITE_* 접두 제거·타입드 · `.gaon/env.d.ts` 는 `.env` 스캔 생성) — 템플릿 프로즈·주석의 언급은 오탐 제외 (결정 198 · `agents/frontend.md` §9)
 27. `locale-parity` — `locales/` 의 로케일 간 키 부분 누락 = **경고**. 어떤 키가 특정 로케일에만 빠지면 `messages.d.ts`(기준 로케일 기준)는 컴파일을 통과하고, 런타임에 그 로케일 사용자는 fallback(대개 다른 언어) 번역을 조용히 본다. 검사가 로케일 간 키 diff 를 계산해 빠진 파일·키를 짚는다(`--json` 은 `detail.missing` 으로 구조화). 로케일이 0·1개면 무소음 (결정 216 · `agents/i18n.md`)
@@ -208,7 +210,8 @@ gaon doctor       # 정적 검사 27종 (§2.2)
 | `gaon new <name>` | 프로젝트 스캐폴드 |
 | `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·**serve·work·hub 자동 기동**·**코드 변경 감시·재시작** · 결정 211) |
 | `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) — **감시 없음** · 배포 배치용(`gaon dev` 가 개발 중엔 셋을 내장 기동) · 웹은 `PORT`, 허브는 `GAON_HUB_PORT` |
-| `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
+| `gaon g <type> <name>` | 스캐폴드: `auth`·`ui-kit`·`controller`·`model`·`page`·`job`·`app` |
+| `gaon gen` / `build` | `gen` = `.gaon` 타입 브리지 + api() 런타임 매니페스트만 재생성(서버·검사 없이) · `build` = 멀티 앱 프론트 프로덕션 빌드(`gaon gen` + `apps/*` 순회 · 앱별 `dist/<앱>`·base=`/<앱>/`) · 결정 127·146 |
 | `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
 | `gaon check` / `test` / `doctor` | 검증 루프 |
 | `gaon console` | 프로젝트 컨텍스트 REPL |

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

@@ -82,6 +82,10 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
 - **이름** — `options.name` 으로 명시하거나, 생략하면 `domain/jobs/`
   파일 로더가 **파일명**으로 채운다(`assignName`). 이름을 얻기 전까지
   `.later()` 등을 호출하면 에러 — 파일로 두거나 `name` 을 직접 준다.
+- **파일당 잡 하나(결정 271)** — 같은 파일에 `job()` 을 둘 이상 두면 파일명
+  유추가 충돌한다. 이제 **등록 시 throw**(조용한 덮어쓰기 = 발행이 엉뚱한
+  핸들러로 가던 무신호 버그 봉합) — 각각 `name` 을 다르게 주거나 파일을 나눈다.
+  리스너(`on()`)도 동형 — 같은 파일에 여럿 두면 `id` 를 다르게 준다(durable 충돌).
 - **옵션** — `queue`(기본 `'default'`) · `retries`(기본 3) ·
   `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
 - **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
@@ -108,7 +112,7 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
 
   ```ts
   async create() {
-    const user = await User.create(this.params(User.registerForm))
+    const user = await User.create(this.params(User.form))
     await SendWelcomeMail.later(user.id)      // 컨트롤러에서 발행
     return this.redirect('/dashboard')
   }
@@ -204,9 +208,10 @@ export const PlaceOrder = service(async (input: { name: string }) => {
 - 아웃박스 테이블(`_gaon_outbox`)은 코어 내장이며 `gaon serve`·`gaon work`
   기동 시 보장된다(결정 144 · nats 설정이 있을 때).
 - 발행 완료 행은 릴레이가 **자동 정리(purge)** 한다 — 기본 7일 보존 후 삭제
-  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격은 `gaon work` 의
-  `outboxRetentionMs`·`outboxPurgeIntervalMs` 로 조정한다(운영 상세는
-  `docs/guides/operations.md`). 미발행 행은 절대 삭제되지 않는다.
+  (결정 78). 수동 cleanup 코드를 쓰지 말 것. 보존 기간·간격은 `runWork()` 의
+  프로그래매틱 옵션 `outboxRetentionMs`·`outboxPurgeIntervalMs` 로 조정한다(`gaon
+  work` CLI 플래그가 아니다 · 운영 상세는 `docs/guides/operations.md`). 미발행 행은
+  절대 삭제되지 않는다.
 
 ### 5. 스케줄러
 
@@ -368,7 +373,9 @@ export const SendWelcomeMail = job(async (userId: bigint) => {
 ```ts
 // apps/web/controllers/registration.ts — 컨트롤러는 잡 발행만 (직접 발송 금지)
 async create() {
-  const user = await RegisterUser.call(this.params(RegisterUser.form))
+  // 서비스는 모델 폼이 없다 — 컨트롤러가 모델 스키마 폼(`User.form.pick(...)`)으로
+  // 검증한 입력을 서비스에 넘긴다(폼 표면 = 모델 소속 · 결정 104).
+  const user = await RegisterUser.call(this.params(User.form.pick('name', 'email')))
   await SendWelcomeMail.later(user.id)
   return this.redirect('/dashboard')
 }

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

@@ -168,7 +168,7 @@ export const posts = table('posts', {
 ### 4. 체이닝 전체 (`packages/data/src/model.ts`)
 
 체이닝 표면은 아래 표가 **전부**다. 표에 없는 메서드
-(`destroy`·`findBy`·`paginate`·`order`·해시 인자
+(`destroy`·`findBy`·`order`·해시 인자
 `where({...})` 같은 다른 ORM 관습)를 추측해서 쓰지 말 것 — 표
 바깥의 쿼리는 §5 `Post.query()` 탈출구로 내려간다.
 
@@ -725,7 +725,7 @@ diff/migrate/status/seed 는 `--db` 를 생략하면 **등록된 전 커넥션
 ```ts
 // domain/seed.ts
 import { seed } from 'gaonjs/data'
-import { User } from './models/User'
+import { User } from './models/User.js'
 
 export default seed(async () => {
   await User.create({ email: 'admin@example.com', name: 'Admin' })
@@ -815,9 +815,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 
 ## 알려진 함정
 
-- **체이닝 표 밖 메서드 추측 금지** — `destroy`·`findBy`·`paginate`·
-  `order`·해시 인자 `where({...})` 는 없다. 단건 삭제는 `rec.delete()`,
-  벌크는 `deleteAll()` (결정 31).
+- **체이닝 표 밖 메서드 추측 금지** — `destroy`·`findBy`·
+  `order`·해시 인자 `where({...})` 는 없다(페이지네이션은 표 안 `paginate`
+  · 결정 119). 단건 삭제는 `rec.delete()`, 벌크는 `deleteAll()` (결정 31).
 - **`find(id)` 는 없으면 throw** — undefined 를 원하면
   `where('id', '=', id).first()`.
 - **관계 대상은 문자열 테이블명** — 모델 객체를 넘기면 순환 참조.

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

@@ -70,6 +70,10 @@ const props = pageProps<'web:posts#index'>()
   의 `Link`(`<Link href="/posts">글 목록</Link>`), 코드에서의 이동은
   `router.visit(url)`. **외부 URL(`https://…`)·`target="_blank"` 만 `<a>`** 를
   유지한다. 내부 경로 일반 앵커는 doctor **internal-anchor** 가 잡는다(결정 96).
+- **페이지 제목 = `Head`(결정 271)** — 문서 `<title>` 은 `gaonjs/vue` 의 `Head` 로
+  설정한다: `<Head title="글 목록" />`. `createGaonApp({ title })` 조합자가 이 값을
+  받아 `글 목록 · 사이트명` 처럼 꾸민다. `document.title` 수동 조작·`@inertiajs`
+  직접 import 금지(결정 64) — 정본 표면은 `Head` 뿐이다.
 - **`shared/` 밖에서만 사용** — `shared/` 안 `pageProps` 사용은 §4 대칭 표에서
   금지 (라우트를 모른다는 순수 규칙).
 
@@ -398,6 +402,10 @@ async function runSearch(q: string) {
 
 - **`usePage()`·`defineProps<T>()` 로 pageProps 대체 금지** — Serialized
   경계 우회로 타입 안전 붕괴.
+- **`pageProps()`·`useShared()` 는 setup 컨텍스트 전용** — `<script setup>` 최상위
+  (또는 컴포저블)에서 호출해야 `usePage()` inject 가 성립한다(`pageProps.ts`). 이벤트
+  핸들러·`await` 뒤·setup 밖에서 부르면 inject 가 없어 깨진다. setup 에서 한 번 잡아
+  (반응형 프록시라 그대로) 쓴다.
 - **`api()` 에 제네릭 인자 직접 붙이지 않는다** — key 리터럴이 타입을
   결정한다.
 - **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출·domain 값 import 금지** —
@@ -448,6 +456,8 @@ async function runSearch(q: string) {
 | 결정 25 (E-5) | 컴포저블·레이아웃 관례 · 프론트 로직 배치 3규칙 · 자동 import 금지 |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 |
 | 결정 46 | doctor page-filename(페이지 PascalCase)·model/column 검사 3종 |
+| 결정 64 | 폼 API = `gaonjs/vue` `useForm`·`router`(@inertiajs 직접 import 금지) · HTML 폼 불가 메서드(DELETE 등)는 `router.delete()` · Inertia=SPA+서버 라우팅(`agents/web.md` §4) |
+| 결정 99 | `pageProps()` 반환 = usePage().props 얇은 반응형 프록시(매 접근 최신) · 구조분해=스냅샷이라 변수로 받아 `props.x` 로 접근 |
 | 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · 실 상태 · 코드 블록) |
 | 결정 70 | auth 통합 = 수동(`gaon g auth` 는 랜딩·nav 를 안 건드림 · Rails 관례) |
 | 결정 71 | HUB 카드 실 introspection(jobs=스트림 pending · channels=프레즌스 실 접속자 · 과대 약속 금지) |
@@ -464,9 +474,12 @@ async function runSearch(q: string) {
 | 결정 166 | `api()` CSRF 자동 부착 = data-page `props.csrf`(결정 116 과 같은 단일 출처) · `<meta name="csrf-token">` 은 레거시 폴백(§2 · `packages/vue/src/api.ts`) |
 | 결정 150 | 앱 전역 공유 키 확장 — `app.config` sharedProps 등록 → useShared 로 읽기(코어 3종 고정 · 선언 병합 타입 · hidden 미유출 · `agents/web.md` §4.2) |
 | 결정 119 | `Pagination` 블록이 `chain.paginate()` 결과에 정합(`:page`·`:pageCount` 필드 그대로 · 매핑 0 · `agents/data.md`) |
+| 결정 128 | `useChannel` 자동 재연결(지수 백오프 1s·2s·5s·10s·지터 · `onReconnect` 로 놓친 데이터 따라잡기 · 미인가 4401 은 재연결 안 함 · `agents/realtime.md` §4) |
 | 결정 198 | 클라 환경변수 접근자 `env`(gaonjs/vue · `.vue` 의 import.meta.env TS1470 회피) · VITE_* 접두만 노출·접두 제거 · `.gaon/env.d.ts`(.env 스캔) 타입 브리지 · doctor no-import-meta-env(§9) |
 | 결정 206 | UI 킷 §8 슬롯·props 요약표(카탈로그가 이름만이라 소스 열람 유발 · O-2 해소) · named slot 비대칭 명시(PageHeader `#actions` 복수 vs EmptyState `#action` 단수) |
 | 결정 213 | i18n Vue 소비 = 서버 주도 render props/sharedProps 만 · `t()`·`useT()` 클라 미노출(`agents/i18n.md` §5) |
+| 결정 217 | doctor `shared-purity`(구 shared-composable-purity 개명) — `shared/` 의 .ts 컴포저블 + .vue 컴포넌트 순수성(pageProps/api 호출·domain 값 import 금지 · §7) |
+| 결정 271 | W4 표면 정합 — `Head` 재수출(`gaonjs/vue` · `<Head title>` 제목 조합자 발화) 외 표면/최적화 4건(§12 결정 271) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |
 
 ## `@gaonjs/seal` 켠 앱의 프론트

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

@@ -9,8 +9,10 @@
 ### 1. 카탈로그와 `t()`
 
 번역 문자열은 프로젝트 루트 `locales/<로케일>.json` 에 둔다(중첩 JSON = 점 표기
-키). `t('key')` 로 현재 요청 로케일의 문자열을 얻는다 — 어디서든(컨트롤러·서비스·
-잡·메일) 쓸 수 있다.
+키). `t('key')` 는 **현재 요청 로케일**의 문자열을 얻는다 — 요청 컨텍스트 안
+(컨트롤러·서비스)에서 자동으로 따라간다. **요청 밖(잡·크론·스크립트)에는 요청
+로케일이 없어 항상 fallback** 이므로, 로케일을 명시적으로 실어 `runWithLanguage`
+로 감싼다(메일은 `deliver(data, { locale })` 로 대칭 · §정본 예시).
 
 ```json
 // locales/ko.json
@@ -81,9 +83,11 @@ export default defineConfig({
 없는 앱(랜딩·API)에서도·앱 간에도 유지된다.
 
 ```ts
-// 컨트롤러 — 언어 전환 라우트
-async setLocale() {
-  this.setLocale((this.request.params as { lng: string }).lng)
+// 컨트롤러 — 언어 전환 라우트 (액션명은 컨텍스트 메서드 this.setLocale 과 겹치지 않게)
+async switchLocale() {
+  // 입력은 정본 this.params — raw this.request.params + cast 대신 통합 입력 접근자.
+  const { lng } = this.params({ _row: {} as { lng: string } })
+  this.setLocale(lng)
   return this.redirect(this.request.headers.referer ?? '/')
 }
 ```
@@ -205,16 +209,28 @@ CSS 가 올바른 언어를 안다). 비-i18n 프로젝트는 템플릿 정적
 ## 정본 예시
 
 ```ts
-// domain/services/greet.ts — 서비스·잡에서도 t() 는 요청 로케일을 쓴다.
+// domain/services/greet.ts — 서비스는 요청 컨텍스트 안이라 t() 가 요청 로케일을 쓴다.
 import { t } from 'gaonjs/i18n'
 export function greetLine(name: string): string {
   return t('greeting', { name })
 }
 ```
 
+```ts
+// domain/jobs/sendDigest.ts — 잡은 `gaon work`(별도 프로세스)라 요청 컨텍스트가 없다.
+// 로케일을 페이로드에 실어 runWithLanguage 로 감싼다(안 그러면 t() 는 fallback).
+import { job } from 'gaonjs/async'
+import { runWithLanguage, t } from 'gaonjs/i18n'
+
+export const SendDigest = job(async ({ userId, locale }: { userId: bigint; locale: string }) => {
+  const line = runWithLanguage(locale, () => t('greeting', { name: '가온' }))
+  // …line 으로 메일/알림 조립
+})
+```
+
 `t()` 는 요청 컨텍스트(ALS)의 로케일을 자동으로 따라간다 — 로케일을 인자로
-넘기고 다니지 않는다. 요청 밖(크론·스크립트)이나 특정 로케일로 강제하려면
-`runWithLanguage(lng, () => t('key'))`.
+넘기고 다니지 않는다. **요청 밖(잡·크론·스크립트)** 이나 특정 로케일로 강제하려면
+`runWithLanguage(lng, () => t('key'))` — 잡은 로케일을 페이로드에 담아 넘긴다(위 예).
 
 ## 알려진 함정
 
@@ -222,8 +238,10 @@ export function greetLine(name: string): string {
   `gaon.config.ts` 에 `i18n` 이 있어야 배선된다(결정 159). 설정만 하면 자동.
 - **키를 손으로 `string` 으로 넓히지 말 것** — `.gaon/messages.d.ts`(결정 158)가
   키를 타입으로 좁혀 준다. `gaon check` 가 없는 키를 잡는다.
-- **로케일을 함수 인자로 실어 나르지 말 것** — `t()` 는 ALS 로 요청 로케일을 안다.
-  전환은 `this.setLocale`, 특정 로케일 강제는 `runWithLanguage`.
+- **요청 코드에선 로케일을 함수 인자로 실어 나르지 말 것** — `t()` 는 ALS 로 요청
+  로케일을 안다. 전환은 `this.setLocale`, 특정 로케일 강제는 `runWithLanguage`. **예외:
+  잡·크론(요청 밖)은 요청 로케일이 없으므로** 로케일을 페이로드에 담아 `runWithLanguage`
+  로 감싼다(§정본 예시 · 메일 `deliver(data,{locale})` 와 동형).
 - **메일은 요청 로케일이 아니라 수신자 로케일** — `deliver(data, { locale })` 로
   명시한다(`agents/mail.md` · 결정 160).
 - **검증 실패 문안도 로케일화된다** — 예약 namespace `validation.<code>`(예 `validation.required`)

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

@@ -190,21 +190,25 @@ URL 조립(`<앱 프리픽스>/gaon/ws/<채널명>` · ws/wss 자동)·봉투(`{
 import { useChannel } from 'gaonjs/vue'
 
 export function useRoom(roomId: number) {
-  // messages(반응형)·status·send·connect·close 를 돌려준다. 마운트에 접속.
-  const { messages, status, send } = useChannel('room', {
+  // messages·members(반응형)·status·send·connect·close 를 돌려준다. 마운트에 접속.
+  const { messages, members, status, send } = useChannel('room', {
     params: { room: roomId },
     onMessage: (data) => { /* 서버가 broadcast/send 한 데이터 */ },
-    onPresence: (delta) => { /* 접속자 join/leave */ },
+    // members = 현재 접속자 **전체 명단**. 스냅샷·들어옴·나감을 하나로 반영하므로
+    // 델타를 손으로 병합하지 않는다. 반응형이라 template 에서 그대로 렌더해도 된다.
+    onPresence: (members) => { /* 접속자 명단이 바뀔 때마다 전체 명단으로 호출 */ },
     onReconnect: () => { /* 재연결됨 — 놓친 데이터를 Inertia partial reload 로 따라잡기 */ },
   })
-  return { messages, status, send }
+  return { messages, members, status, send }
 }
 ```
 
 - **보내기** — `send(data)` 가 `{ t:'msg', data }` 봉투로 감싸 보낸다(서버 `onMessage`
   정답 경로). 날 페이로드를 직접 보내면 서버가 안 흘린다.
-- **받기** — `msg` 프레임은 `messages` 에 축적 + `onMessage` 호출, `presence` 는
-  `onPresence`. 그 외는 `onFrame`.
+- **받기** — `msg` 프레임은 `messages` 에 축적 + `onMessage` 호출. 접속자 프레임(초기
+  스냅샷 + 이후 들어옴/나감)은 하나의 **명단**으로 합쳐져 반응형 `members` 에 반영되고
+  `onPresence(members)` 로도 통지된다(결정 272 · 콜백만으로 항상 최신 명단 · 델타 병합
+  불요). 그 외 종류는 `onFrame`(저수준 탈출구).
 - **자동 재연결(결정 128 · 기본 켬)** — 소켓이 끊기면(서버 재시작·네트워크 blip)
   useChannel 이 **지수 백오프**(1s·2s·5s·10s · 이후 10s 반복 · 지터)로 자동 재접속한다.
   새 소켓은 서버가 다시 인가하고 프레즌스 스냅샷을 다시 밀어주므로 접속자 목록이
@@ -311,7 +315,9 @@ export default channel({
   연결에만 전달 · 결정 227). `sendToUsers` 는 그 **채널에 접속한** 유저만
   대상이다 — 접속 안 한(오프라인) 유저는 `0` 도달로 반환된다.
 - **자기 자신의 join 델타** — 클라이언트는 자기 `presence:join` 델타도
-  스냅샷과 별개로 받는다(멱등이라 무해). 필요하면 자기 `id` 로 필터.
+  스냅샷과 별개로 받는다. `useChannel` 은 `members` 를 `id` 로 키잉해 이 중복을
+  **멱등**으로 흡수하므로 명단이 불어나지 않는다(결정 272). 직접 `new WebSocket`
+  을 쓰는 탈출구에서는 스스로 `id` 로 dedup 한다.
 - **테스트에서 NATS·허브 목업 금지** (§9) — 실 인프라
   (`agents/testing.md`).
 
@@ -329,6 +335,7 @@ export default channel({
 | 결정 257 | 채널 `onMessage`/`onLeave` throw 는 그 연결만 마감(§2.4) — 사용자 핸들러 예외가 unhandledRejection 으로 serve 를 죽이지 않는다(HTTP 500 대칭 · 에러 프레임 + 연결 종료) |
 | 결정 259 | 허브 디스커버리 endpoint 는 소유 리더만 삭제(§5) — addr 일치 + revision CAS · standby 종료·리더 교대가 활성 endpoint 를 지우지 않음(재접속 서버 허브 발견 보존) |
 | 결정 260 | 리스 TTL 역할별 독립(§5) — 허브·스케줄러가 `gaon_lease_<역할>` 별도 버킷 · 공유 버킷 MaxAge 플래핑 제거 |
+| 결정 272 | `useChannel` 접속자 명단 조립(§4) — `onPresence(members)` 가 스냅샷+join+leave 를 하나의 전체 명단으로 반영 · 반응형 `members` Ref 추가(`messages` 대칭) · id 키 멱등 · 종전엔 스냅샷만 `onPresence`(`data`=undefined)·델타는 `onFrame` 으로만 흘러 문서대로 짠 접속자 목록이 조용히 빈 채 남던 결함 |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

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

@@ -82,7 +82,7 @@ void createGaonApp({ pages, layouts, /* ... */ sealClient })
   vite** 가 번들하도록 `main.ts` 에서 **app-side 정적 import** 로 주입한다. (과거 `@gaonjs/vue` 안의
   **변수-specifier 동적 import** 는 vite 가 번들하지 못해 실 브라우저 마운트가 blank 로 깨졌다 — **폐기**.)
 - **doctor 가 지킨다**: `seal-security` 가 `seal: true` 인데 main.ts 배선이 없으면 **에러 + 수리 안내**를 내고,
-  `gaon check --fix` 의 `seal-client-wiring` fixer 가 배선을 자동 생성한다. 개발자·AI 멘탈모델은 여전히
+  `gaon doctor --fix --yes` 의 `seal-client-wiring` fixer 가 배선을 자동 생성한다. 개발자·AI 멘탈모델은 여전히
   "seal: true 한 줄" 이고, 배선 누락은 doctor 가 즉시 잡는다(§7.5.3 에러=수리 안내서). 런타임도 봉인 문서를
   배선 없이 받으면 정확한 수리 메시지로 throw 한다(blank 대신).
 - 미설치로 `seal: true` 를 켜면 **부팅 에러**(수리 안내). `masterSecret` 설정 표면은 없다 — 미끼 literal
@@ -170,7 +170,7 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 
 ## 알려진 함정
 
-1. **main.ts 배선 누락** → 봉인 문서를 브라우저가 못 열어 화면 blank. → `gaon check`(`seal-security`)가 잡고 `--fix` 가 배선. 런타임도 수리 안내 throw.
+1. **main.ts 배선 누락** → 봉인 문서를 브라우저가 못 열어 화면 blank. → `gaon check`(`seal-security`)가 잡고 `gaon doctor --fix --yes` 가 배선. 런타임도 수리 안내 throw.
 2. **변수-specifier 동적 import** (`const s='@gaonjs/seal/client'; import(s)`) — vite 가 번들 못 해 프로덕션 blank. **폐기됨** — app-side 정적 주입만.
 3. **전역 CSP 완화 금지** — `'wasm-unsafe-eval'` 은 seal 앱 응답에만. 비-seal 앱 strict CSP 유지.
 4. **"seal 켰으니 검증 느슨" = 가짜 안심** — 서버 방어층(§0) 전부 유지. seal 은 이유가 못 된다.

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

@@ -60,6 +60,13 @@
 - **로그인은 세션 ID 를 재생성하고 로그아웃은 세션을 파기한다 (결정 254)**:
   `this.auth.login`/`logout` 이 자동 처리한다(session fixation 방어). 스캐폴드는
   `await this.auth.login(user)` 형태다 — 손으로 세션을 조작하지 않는다.
+- **가입 이메일은 유니크다 (결정 256)**: `gaon g auth` 스키마의 `email` 은
+  `t.string().max(255).unique()` — DDL UNIQUE 로 물성화돼 중복 가입을 DB 층에서
+  막는다(무결성 backstop). 가입 컨트롤러는 그 위에 **pre-check**(`if (await
+  User.where('email','=',email).first()) …`)를 깔아 중복 시 raw DB 500 대신
+  친절한 폼 에러(`props.error` → Alert)로 마감한다(유니크 제약이 TOCTOU 레이스의
+  backstop). 유니크 없이 두면 중복 가입이 조용히 성공하고 로그인 `.first()` 가
+  비결정이 된다.
 - **비-web 앱은 시큐어 기본이다** (결정 155): `gaon g auth --app admin` 은
   **공개 회원가입(registration)을 깔지 않는다** — 관리 앱에 공개 가입이 열리고
   로그인한 일반 고객이 관리 화면을 보던 위험 기본을 구조적으로 막는다. 대신 보호

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

@@ -31,6 +31,9 @@
   안 생기며, 테스트가 남긴 잡을 개발 워커가 처리하지도 않는다 — **테스트 전에
   워커를 내릴 필요가 없다.** (직접 `vitest` 로 돌리면 이 격리가 없어 개발 스택과
   섞이니 `gaon test` 를 쓴다.)
+- **스캐폴드 `package.json` 의 `"test"` 스크립트가 곧 `gaon test`(결정 271)** — 그래서
+  `pnpm test`(또는 `npm test`)도 정본 하네스를 그대로 탄다. `"vitest run"` 으로 바꾸면
+  프로비저닝·스트림 격리가 사라지니 두지 말 것.
 - SQLite 는 Docker 가 불가능한 환경의 폴백으로만 남고 공식 경로가
   아니다.
 

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

@@ -257,9 +257,12 @@ async create() {
 | `required` | — | 필수 컬럼 누락 |
 | `too_long` | `{ max, len }` | `.max(n)` 초과 |
 | `not_allowed` | `{ value, allowed }` | enum 밖 값 |
-| `not_integer` | `{ value }` | bigint 변환 실패 |
+| `not_number` | `{ value }` | number·numeric(decimal) 변환 실패 |
+| `not_integer` | `{ value }` | 정수(integer·smallint·bigint) 변환 실패 |
 | `not_boolean` | `{ value }` | boolean 변환 실패 |
 | `not_date` | `{ value }` | 날짜 변환 실패 |
+| `not_uuid` | `{ value }` | uuid 형식 아님 |
+| `invalid` | — | 그 외 coerce 예외(비-CoerceError) |
 
 ```json
 // locales/en.json — 앱이 검증 문안을 로케일별로 준다(i18next {{max}} 보간).
@@ -337,7 +340,10 @@ declare module 'gaonjs/vue' {
   interface GaonSharedProps { locale: string; theme: string }
 }
 // 페이지에서
-const { locale, theme } = useShared()   // 타입 안전 · 반응형
+const shared = useShared()              // 객체로 잡으면 반응형 — 매 접근이 최신 props 를 읽는다
+shared.locale                            // 로그인/로그아웃·플래시로 서버가 새 값을 주면 즉시 갱신
+// 구조분해 const { locale } = useShared() 는 그 시점 값을 한 번 읽는 **스냅샷**(반응성 없음).
+// 반응성이 필요하면 객체(shared.locale)로 접근한다(pageProps 결정 99 와 같은 계약).
 ```
 
 - **코어 3종(currentUser·csrf·flash)은 예약** — `sharedProps` 가 이 이름을 반환하면
@@ -411,7 +417,9 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
 
 - 세션 쿠키가 기본, JWT 는 **API 앱 전용 옵션** (v0.11 확정).
 - 세션은 앱별 완전 분리 (Fastify 캡슐화 스코프): 쿠키 이름(`<app>_sid`) ·
-  서명 secret · Redis 키 prefix · 쿠키 path 가 앱 단위로 갇힌다.
+  서명 secret · Redis 키 prefix 가 앱 단위로 갇힌다. (쿠키 path 는 `/` 고정 —
+  프리픽스·서브도메인 양쪽 접근에 쿠키가 실리려면 정적 path 가 `/` 여야 한다 ·
+  결정 142. 분리는 위 세 축으로 완성된다.)
 - 스캐폴드는 `gaon g auth` — 로그인/회원가입 컨트롤러·페이지·라우트 일습.
 - **로그인 필요 액션의 정답 = `this.requireAuth()`** (결정 57). notFound 처럼
   예외로 마감하지만, **`if` 가드 자체가 없다**는 게 핵심:

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

@@ -15,7 +15,7 @@
     "hub": "gaon hub",
     "check": "gaon check",
     "doctor": "gaon doctor",
-    "test": "vitest run"
+    "test": "gaon test"
   },
   "dependencies": {
     "gaonjs": "{{GAONJS_VERSION}}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.42.0",
+  "version": "0.42.2",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -27,13 +27,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.15.2",
-    "@gaonjs/config": "0.17.7",
+    "@gaonjs/async": "0.15.3",
+    "@gaonjs/config": "0.18.0",
     "@gaonjs/core": "0.2.4",
-    "@gaonjs/data": "0.17.2",
-    "@gaonjs/i18n": "0.2.3",
-    "@gaonjs/mail": "0.3.1",
-    "@gaonjs/web": "0.20.2"
+    "@gaonjs/i18n": "0.2.4",
+    "@gaonjs/data": "0.17.3",
+    "@gaonjs/mail": "0.3.3",
+    "@gaonjs/web": "0.20.4"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""