@gaonjs/cli 0.33.0 → 0.34.0

package/dist/messages-gen.js

@@ -0,0 +1,24 @@
+// @gaonjs/cli · .gaon/messages.d.ts 생성기 (결정 158 · 13차 W2)
+//
+// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 세 번째 축(메시지). locales/
+// 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
+// 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
+// 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
+/**
+ * locales/ 카탈로그에서 .gaon/messages.d.ts 를 생성한다. 카탈로그가 없거나 비어
+ * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
+ * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ */
+export function generateMessagesDts(localesDir, out) {
+    if (!existsSync(localesDir))
+        return false;
+    const resources = loadLocales(localesDir);
+    if (Object.keys(resources).length === 0)
+        return false;
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, renderMessagesDts(resources), 'utf8');
+    return true;
+}

package/dist/templates/auth/Login.vue.tpl

@@ -45,10 +45,7 @@ const form = useForm({ email: '', password: '', _csrf: shared.csrf })
           </FormField>
           <Button type="submit" class="w-full" :disabled="form.processing">로그인</Button>
         </Form>
-        <p class="mt-4 text-center text-sm text-muted-foreground">
-          계정이 없으신가요?
-          <Link href="{{URL_PREFIX}}/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</Link>
-        </p>
+        {{SIGNUP_LINK}}
       </CardContent>
     </Card>
   </div>

package/dist/templates/auth/dashboard.secure.controller.ts.tpl

@@ -0,0 +1,14 @@
+// 보호 라우트 예시(관리 앱) — gaon g auth --app {{APP_NAME}}. 로그인 + 역할로 지킨다(§7 · 결정 145·155).
+import { controller } from 'gaonjs/web'
+
+export default controller({
+  // GET {{URL_PREFIX}}/dashboard — 로그인만으론 부족한 관리 화면. 역할(role)로 인가한다.
+  async show() {
+    const user = this.requireAuth() // 인증(401): 로그인 여부
+    // 인가(403): 로그인한 일반 사용자는 막는다. domain/schema/users.ts 에 role 컬럼을 두고
+    // (예: role: t.string().default('user')) 아래를 실제 역할 규칙으로 바꾸세요.
+    // 지금은 role !== 'admin' 이면 403 — 관리 앱에 로그인 고객이 들어오는 위험 기본을 막는다.
+    this.authorize((user as { role?: string }).role === 'admin')
+    return this.render('Dashboard', {})
+  },
+})

package/dist/templates/project/.env.example.tpl

@@ -18,6 +18,12 @@ STORAGE_BUCKET={{PROJECT_NAME}}
 STORAGE_ACCESS_KEY={{PROJECT_NAME}}
 STORAGE_SECRET_KEY={{PROJECT_NAME}}_secret
 
+# 메일(§7 · M8) — docker-compose.yaml 의 mailpit 서비스와 정합(dev = MailPit sink · UI :8025).
+# 운영은 실 SMTP 호스트·자격증명·SMTP_SECURE=true 로 교체한다.
+SMTP_HOST=127.0.0.1
+SMTP_PORT=1025
+MAIL_FROM=no-reply@{{PROJECT_NAME}}.test
+
 # 세션 · 쿠키 서명 비밀 (32자 이상, 운영은 반드시 교체).
 SESSION_SECRET=change-me-to-a-32-char-random-secret!!
 COOKIE_SECRET=change-me-too-32-char-random-secret!!

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

@@ -27,6 +27,8 @@ v0.15+errata→v0.16→v0.17 · 결정 31~89)이며, 관례 문서는 **2층 구
 | 잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄 | `agents/async.md` |
 | 채널 · 프레즌스 · 허브 | `agents/realtime.md` |
 | 파일 스토리지 (`Storage.put/url` · s3Disk · presigned · CSP 자동 배선) | `agents/storage.md` |
+| 다국어 (`t()` · 카탈로그 · 요청별 로케일 · `this.setLocale` · 메시지 키 타입) | `agents/i18n.md` |
+| 메일 (`mail()` · `deliver(data, { locale })` · MailPit · 발송 경로) | `agents/mail.md` |
 | 테스트 작성·실행 (실 인프라 · `expectJobProcessed`) | `agents/testing.md` |
 | 보안 기본값 · 탈출구(v-html · raw SQL) 사용 | `agents/security.md` |
 | 페이로드 봉인 (`@gaonjs/seal` · wire/문서/WS 암호화 · 선택 플러그인) | `agents/seal.md` |
@@ -191,7 +193,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 작업마다 실행한다:
 
 ```bash
-gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
+gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
 gaon doctor       # 정적 검사 24종 (§2.2)
 ```

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

@@ -84,7 +84,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 ## 3. 개발 검증 루프 (작업마다 실행)
 
 ```bash
-gaon check                        # .gaon 재생성 후 타입 검사 (CI 정합)
+gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
 gaon doctor                       # 정적 검사 24종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```

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

@@ -253,6 +253,38 @@ export default schedule((s) => {
 프로세스 3종(serve·work·hub) 중 하나. SIGTERM/SIGINT 에 graceful
 drain — 스케줄러 리더를 반납하고 진행 중인 잡을 완료한 뒤 종료한다.
 
+### 7. 분산 락 (`lock()`) (결정 147)
+
+**동시 실행을 막아야 하면 `lock(key, fn)`** — 같은 `key` 에 대해 전
+인스턴스를 통틀어 동시 1개의 `fn` 만 임계구역에 들인다. **로컬 뮤텍스는
+반정본이다** — 멀티 인스턴스(워커 여러 대·serve 여러 대)에서는 프로세스마다
+따로 놀아 무의미하다(결정 88 ①). 그래서 백엔드는 Redis 다: 설정에 `redis`
+가 있으면 `gaon serve` 가 분산 락을 자동 배선한다. **`redis` 미설정 상태로
+`lock()` 을 부르면 로컬 뮤텍스로 조용히 떨어지지 않고 수리 안내와 함께
+throw** 한다.
+
+```ts
+import { lock } from 'gaonjs/async'
+
+// 일 1회 집계가 인스턴스 여러 대에서 중복 실행되지 않게.
+await lock('report:daily', async () => {
+  await buildDailyReport()
+})
+
+// 이미 다른 인스턴스가 돌고 있으면 스킵(대기하지 않음).
+await lock('sync:external', syncNow, { onBusy: 'skip' })
+```
+
+- **기본 정책은 대기**(`onBusy:'wait'`) — 홀더가 놓을 때까지 기다렸다가
+  들어간다. `acquireTimeoutMs`(기본 10s)를 넘기면 `LockTimeoutError`.
+  `onBusy:'skip'` 이면 즉시 포기하고 `fn` 을 실행하지 않는다(반환값
+  `undefined`).
+- **TTL 로 데드락을 막는다**(`ttlMs` 기본 30s) — 홀더가 크래시해도 TTL
+  만료 뒤 자동 해제된다. `fn` 이 TTL 보다 오래 돌면 워치독이 자동으로
+  락을 연장하므로 임계구역을 뺏기지 않는다.
+- **키는 호출자가 정한다** — 락 범위(자원 단위)를 `key` 로 표현한다.
+  프레임웍이 로케일 등 변이 축을 자동으로 섞지 않는다.
+
 ## 정본 예시
 
 회원 가입 → 환영 메일 비동기 발송 세로 조각 (§7 원문 예시):
@@ -298,11 +330,16 @@ async create() {
   발행은 `afterCommit()` 또는 아웃박스로.
 - **테스트에서 NATS 목업 금지** (§9) — 실 JetStream 에 접속한다
   (`agents/testing.md`).
+- **동시 실행 방지에 로컬 뮤텍스·플래그 금지** (결정 147) — `let running = false`
+  같은 프로세스 로컬 가드는 멀티 인스턴스에서 안 먹는다. `lock(key, fn)` 을
+  쓴다. `redis` 미설정이면 `lock()` 이 수리 안내로 throw 하니 조용한 파손이
+  없다.
 
 ## 관련 결정 번호
 
 | 결정 | 내용 |
 |---|---|
+| 결정 147 | 분산 락 `lock(key, fn)` (Redis 백엔드 · 로컬 뮤텍스 반정본 · TTL 데드락 방지 · 워치독) |
 | 결정 102 | 비동기 배치 One Way 판단표 (동기 인라인 vs 잡/이벤트/스케줄 · 서두 표) |
 | 결정 103 | doctor `async-offload` 검사 (컨트롤러 인라인 메일·이미지·외부 HTTP 경고) |
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |

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

@@ -300,8 +300,10 @@ methods: {
   **앞**에서 끝낸다. `withCount` 는 예외로 `include` 와 같은 자리에 실린다.
 - `groupBy` 이후는 `GroupChain` — 결과가 그룹 행이라 `first`/`all` 대신
   집계 함수가 종단이고, 레코드가 아니라 `include`·`select` 도 없다.
-- `join`/`leftJoin` 이후는 `JoinChain` — 반환은 자기 Rec 이라
-  `include`·집계 그룹은 없고 스칼라 집계·`select`(자기 컬럼)·`pluck` 만.
+- `join`/`leftJoin` 이후는 `JoinChain` — 반환은 자기 Rec 이라 `include`·집계 그룹은
+  없지만 `where`/`whereAny`/`orWhere`/`orderBy`/`distinct`/`limit`/`offset`·스칼라 집계·
+  `select`(자기 컬럼)·`pluck`·`first`/`all`/**`paginate`** 는 이어진다. 그래서 **텍스트
+  검색(whereAny)+관계 필터(join)+페이지네이션을 한 체인으로** 조립할 수 있다(읽기 조합).
 - `select()` 이후엔 `include` 도 없다 (부분 행에 관계를 붙이지 않는다).
 - 스코프(§8)는 `Chain` 의 어느 지점에서든 재호출 가능
   (`Post.where(...).published()` 도 됨).
@@ -490,6 +492,12 @@ export const Post = model(posts, {
 (필수 강제 · 스키마 밖 키 제거 = 대량 할당 차단)까지 한다. 컨트롤러 쪽
 사용법(폼 모양 판단·라우트 파라미터 병합)은 `agents/web.md` §3 이 정본이다.
 
+**컬럼 제약(`.max(n)`·enum)도 쓰기 전 서버측에서 검증한다**(결정 153) —
+`t.string().max(200)` 을 넘긴 값이 200자를 넘거나 enum 허용값 밖이면 DB 에
+닿기 전에 `ValidationError` → **422(폼 에러)** 로 마감한다. 초과 입력이 DB
+제약 위반(varchar 길이·CHECK)으로 **raw 500** 에 새지 않는다. 클라이언트
+`.max`(HTML)만 믿지 말고 서버 폼 검증이 정본 방어층이다.
+
 **일부 컬럼만 검증해서 받으려면 `pick()`** — 지정한 컬럼만 담은 **새 폼**을
 돌려준다(원 폼 불변). 컬럼 타입·검증·기본값 정보가 그대로 따라오므로,
 "검증되는 부분 폼"이 필요할 때 애드혹 `{ _row: {} as T }`(검증 없음) 대신 쓴다.
@@ -514,6 +522,29 @@ async create() {
   동적 default(`now()`·`gen_random_uuid()`·bigserial)는 채우지 않고 DB 가 채운다.
 - `omit`·`extend`·`merge` 는 **없다** — 폼 변형은 `pick()` 하나가 The One Way.
 
+### 8.2 캐시 — 명시 TTL 만 (`cache` · `.withCache` · 결정 148)
+
+비싼 조회·계산 결과를 **명시 TTL** 로 캐시한다. `gaonjs/data` 에서 온다.
+
+```ts
+import { cache } from 'gaonjs/data'
+
+// 키가 있으면 캐시 값, 없으면 fn 을 돌려 60초 캐시.
+const stats = await cache.remember('stats:home', 60, () => computeHomeStats())
+await cache.forget('stats:home')          // 명시 무효화
+
+// 쿼리 종단 헬퍼 — all()/first() 결과를 캐시(키는 쿼리에서 자동 도출).
+const top = await Post.published().latest().limit(5).withCache(30).all()
+```
+
+- **자동 무효화는 없다** — 쓰기(`create`/`update`/`delete`)가 캐시를
+  **지우지 않는다**. 정합이 복잡하고 틀리면 조용한 stale 을 낳기 때문이다.
+  신선도가 중요하면 **짧은 TTL** 을 쓰거나 `cache.forget(key)` 로 명시
+  무효화한다. `.withCache` 결과는 TTL 만료로만 갱신된다(자동 퍼지 없음).
+- **키는 호출자가 정한다** — 로케일·사용자 등 변이 축은 **키에 직접 넣는다**
+  (`` `page:${locale}` ``). 프레임웍이 변이 축을 자동으로 섞지 않는다.
+- 백엔드는 Redis 가 기본(설정에 `redis` 있으면 자동), 메모리는 dev/테스트/폴백.
+
 ### 9. 서비스 (`service()`) — 트랜잭션 작업 흐름 (정본 §5.3 · `packages/data/src/service.ts`)
 
 로직 배치의 One Way 규칙은 루트 `AGENTS.md` 판단표가 정본이다 (정본 §5.3):
@@ -569,6 +600,13 @@ gaon db seed          # domain/seed.ts 실행 (전 커넥션)
 diff/migrate/status/seed 는 `--db` 를 생략하면 **등록된 전 커넥션을 순회**한다
 (결정 139). `gaon db diff`(내부 `_gaon_*` 테이블은 계획에서 제외 · 결정 138).
 
+> **db 명령은 프로젝트 로컬로 실행하라(`npx gaon ...` · 결정 156).** `gaon db seed` 는
+> 모델 레이어를 거치므로, 전역 설치 CLI 와 프로젝트가 `@gaonjs/data` 를 각각 로드하면
+> 커넥션 레지스트리가 갈려 "main 미등록" 으로 죽을 수 있다(dual package hazard). 프레임웍이
+> 프로젝트 인스턴스에 자동 재등록해 대부분 자동 복구하지만, 확실히 하려면 프로젝트 로컬
+> 실행(`npx gaon` · package.json 스크립트)이 정본이다. migrate/diff/status 는 모델을 안 거쳐
+> 무관하다.
+
 **기본은 스키마 우선이다.** `domain/schema/*.ts` 를 고치고 `gaon db migrate`
 하면 diff 가 차이를 계산해 반영한다. 여기에 **손작성 마이그레이션 파일**이
 1급으로 합쳐진다(결정 39 · 합성형): `migrate` 는 ① `db/migrations/*.ts` 를
@@ -751,6 +789,11 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   안전(오타 방지)이고, 값은 op 에 맞는 타입이다. `whereAny` 로 표현 못 하는 복합 논리(컬럼별
   다른 op·중첩 그룹)는 `Post.query()` Kysely 탈출구(§5)로 내려간다 — `whereGroup` 같은 범용
   그룹핑 API 는 없다(선택지 증식 회피 · 결정 118).
+- **캐시를 "쓰면 자동으로 지워진다"고 기대하면 함정** (결정 148) — `cache`·`.withCache`
+  는 **자동 무효화가 없다**. `create` 후에도 같은 `cache.remember`/`.withCache` 키는 TTL
+  만료 전까지 stale 을 준다. 신선도가 중요하면 짧은 TTL 이나 `cache.forget(key)`. 자동
+  퍼지를 흉내 내려고 쓰기마다 forget 을 흩뿌리지 말 것(정합 복잡·조용한 stale 위험이 기각
+  사유였다).
 
 ## 관련 결정 번호
 
@@ -772,4 +815,6 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 115 | 원자 프리미티브 increment·decrement·touch·toggle(Rec) + incrementAll·decrementAll(Chain) · read-modify-write 금지(§4) |
 | 결정 118 | `whereAny(cols, op, val)` — 다중 컬럼 동일 조건 OR 를 괄호로 묶어 AND 안전 결합(§8·정본 예시·함정) · 범용 그룹핑(whereGroup) 은 기각(복합 논리는 Kysely 탈출구) |
 | 결정 119 | `paginate(page, perPage)` — 체인 종단 `{rows,total,page,pageCount,perPage}` · 클램프·개수 number 내장 · UI 킷 Pagination 정합 · 손 조립(쿼리 2회·count 캐스팅·페이지 수학)은 반정본 · GroupChain 미탑재(행 목록 전용) |
+| 결정 148 | 캐시 헬퍼 `cache.remember`/`forget`·쿼리 `.withCache(ttl)` — 명시 TTL 만 · **자동 무효화 없음**(쓰기 자동 퍼지 기각 · 조용한 stale 방지) · Redis 기본·메모리 폴백(§8.2) |
+| 결정 153 | `Model.form` 컬럼 제약(`.max`·enum) 쓰기 전 서버측 검증 → 422(폼 에러) · DB 제약 위반 raw 500 방지(§8.1 · `this.params`) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |

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

@@ -46,8 +46,9 @@ const props = pageProps<'web:posts#index'>()
   컴파일 에러 · 결정 117). 레이아웃·컴포넌트에서 라우트를 모른 채 읽을 때 특히 유용하다:
   ```vue
   import { useShared } from 'gaonjs/vue'
-  const shared = useShared()            // { currentUser, csrf, flash } · 반응형
+  const shared = useShared()            // { currentUser, csrf, flash, ...앱 키 } · 반응형
   // <template> 에서 shared.currentUser?.name · shared.csrf · shared.flash.success
+  // 앱이 app.config sharedProps 로 등록한 키(locale·theme 등)도 같은 자리에서 읽힌다(결정 150).
   ```
   `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽히지만, 라우트 키가 필요 없는
   `useShared()` 가 정본 표면이다(임의 라우트 키를 빌려 currentUser 를 읽던 우회 트릭을 없앤다).
@@ -403,6 +404,7 @@ async function runSearch(q: string) {
 | 결정 109 | 서버 스키마 검증 실패 → `form.errors.<field>` 자동 반영(303 back + 플래시 · `agents/web.md` §4.1) |
 | 결정 113 | 버튼 모양 링크 = `<Button href>`(Link 로 Button 감싸지 않음 · `<a><button>` 중첩 방지 · doctor link-button-nesting) |
 | 결정 116 | 공유 prop(currentUser·csrf·flash) 자동 주입 · `useShared()` 로 읽기(라우트 키 불요 · `agents/web.md`) |
+| 결정 150 | 앱 전역 공유 키 확장 — `app.config` sharedProps 등록 → useShared 로 읽기(코어 3종 고정 · 선언 병합 타입 · hidden 미유출 · `agents/web.md` §4.2) |
 | 결정 119 | `Pagination` 블록이 `chain.paginate()` 결과에 정합(`:page`·`:pageCount` 필드 그대로 · 매핑 0 · `agents/data.md`) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |
 

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

@@ -0,0 +1,107 @@
+# agents/i18n.md — 다국어 (`t()` · 요청별 로케일 · 메시지 키 타입)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/i18n` (파사드 import 는 `gaonjs/i18n`).
+
+## 정본 규칙
+
+### 1. 카탈로그와 `t()`
+
+번역 문자열은 프로젝트 루트 `locales/<로케일>.json` 에 둔다(중첩 JSON = 점 표기
+키). `t('key')` 로 현재 요청 로케일의 문자열을 얻는다 — 어디서든(컨트롤러·서비스·
+잡·메일) 쓸 수 있다.
+
+```json
+// locales/ko.json
+{ "greeting": "안녕하세요, {{name}}님", "nav": { "home": "홈" } }
+// locales/en.json
+{ "greeting": "Hello, {{name}}", "nav": { "home": "Home" } }
+```
+
+```ts
+import { t } from 'gaonjs/i18n'
+t('greeting', { name: '가온' })   // 요청 로케일이 ko 면 "안녕하세요, 가온님"
+t('nav.home')                     // 중첩은 점 표기
+```
+
+| 표면 | 시그니처 | 비고 |
+|---|---|---|
+| 번역 | `t(key, params?)` | 키는 카탈로그에서 타입 검사(아래 §4) · params 는 `{{name}}` 보간 |
+| 현재 언어 | `currentLanguage(): string` | 요청 로케일 |
+| 지원 언어 | `languages(): string[]` | 설정된 supportedLngs |
+| 고정 번역 | `runWithLanguage(lng, fn)` | fn 안의 t() 가 그 언어(메일·비요청 경로 · §mail) |
+
+### 2. 요청별 로케일 자동 협상 (결정 159)
+
+`gaon.config.ts` 에 `i18n` 설정이 있으면 `gaon serve`/`gaon dev` 가 **매 요청**
+로케일을 협상해 `t()` 가 그 언어로 번역한다 — 앱이 손으로 배선할 필요가 없다
+(자동 · opt-in 아님). 우선순위 기본값 **세션 > 쿠키 > 헤더**(명시 선택이 브라우저
+기본을 이긴다). 지원 안 하는 로케일은 `fallbackLng`.
+
+```ts
+// gaon.config.ts
+export default defineConfig({
+  i18n: {
+    fallbackLng: 'ko',
+    supportedLngs: ['ko', 'en', 'ja'],   // 생략 시 locales/ 폴더 하위 언어들
+    // dir: 'locales',                     // 생략 시 'locales'
+    // detect: { cookieName: 'gaon_locale', priority: ['session', 'cookie', 'header'] },  // 기본값
+  },
+})
+```
+
+### 3. 로케일 전환 — `this.setLocale()` (결정 159)
+
+사용자가 언어를 바꾸면 `this.setLocale(lng)` 로 저장한다 — `gaon_locale` 쿠키
+(세션이 있으면 세션에도)에 심어 **다음 요청부터 유지**된다. 쿠키 기반이라 세션
+없는 앱(랜딩·API)에서도·앱 간에도 유지된다.
+
+```ts
+// 컨트롤러 — 언어 전환 라우트
+async setLocale() {
+  this.setLocale((this.request.params as { lng: string }).lng)
+  return this.redirect(this.request.headers.referer ?? '/')
+}
+```
+
+### 4. 메시지 키 타입 — `.gaon/messages.d.ts` (결정 158)
+
+`gaon gen`/`gaon dev`/`gaon check` 가 `locales/` 카탈로그를 읽어
+`.gaon/messages.d.ts`(키 유니온)를 생성한다(routes·tables 와 같은 `.gaon`
+파이프라인의 3번째 축). 그러면 `t('없는키')` 가 **컴파일 에러**로 잡힌다 —
+카탈로그에 없는 키·오타가 `gaon check` 에서 걸린다(카탈로그가 없으면 키는
+`string` 폴백). 이 파일은 자동 생성이니 직접 수정하지 않는다.
+
+## 정본 예시
+
+```ts
+// domain/services/greet.ts — 서비스·잡에서도 t() 는 요청 로케일을 쓴다.
+import { t } from 'gaonjs/i18n'
+export function greetLine(name: string): string {
+  return t('greeting', { name })
+}
+```
+
+`t()` 는 요청 컨텍스트(ALS)의 로케일을 자동으로 따라간다 — 로케일을 인자로
+넘기고 다니지 않는다. 요청 밖(크론·스크립트)이나 특정 로케일로 강제하려면
+`runWithLanguage(lng, () => t('key'))`.
+
+## 알려진 함정
+
+- **`i18n` 설정이 없으면 `t()` 는 항상 fallback** — 요청별 로케일 협상은
+  `gaon.config.ts` 에 `i18n` 이 있어야 배선된다(결정 159). 설정만 하면 자동.
+- **키를 손으로 `string` 으로 넓히지 말 것** — `.gaon/messages.d.ts`(결정 158)가
+  키를 타입으로 좁혀 준다. `gaon check` 가 없는 키를 잡는다.
+- **로케일을 함수 인자로 실어 나르지 말 것** — `t()` 는 ALS 로 요청 로케일을 안다.
+  전환은 `this.setLocale`, 특정 로케일 강제는 `runWithLanguage`.
+- **메일은 요청 로케일이 아니라 수신자 로케일** — `deliver(data, { locale })` 로
+  명시한다(`agents/mail.md` · 결정 160).
+
+## 관련 결정 번호
+
+| 결정 | 요지 |
+|---|---|
+| §7 (v0.15) | i18n 배터리 · locales/ 카탈로그 · t() |
+| 결정 158 (13차 W2) | `.gaon/messages.d.ts` 키 타입 브리지 — 없는 키 컴파일 에러 |
+| 결정 159 (13차 W1) | 요청별 로케일 자동 협상(wireGaon onRequest) · `this.setLocale` · detect 설정 |

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

@@ -0,0 +1,92 @@
+# agents/mail.md — 메일 (`mail()` · `deliver` · 로케일 · MailPit)
+
+> 골격: **정본 규칙 → 정본 예시 → 알려진 함정 → 관련 결정 번호** (결정 40 · 2층 구조).
+> 루트 `AGENTS.md` 는 코어 요약만 담는다 — 시그니처·표·예시의 정본은 이 파일이다.
+> 대상 패키지: `@gaonjs/mail` (파사드 import 는 `gaonjs/mail`).
+
+## 정본 규칙
+
+### 1. `domain/mails/` + `mail()`
+
+메일은 `domain/mails/<이름>.ts` 에 `mail()` 로 정의한다(모델·잡과 같은 함수/객체
+스타일 · 데코레이터 금지). 파일을 두면 등록이고 파일명이 곧 이름이다. build 함수는
+데이터를 받아 메시지(`to`·`subject`·`html`/`text`·`from?`)를 만든다.
+
+```ts
+// domain/mails/welcome.ts
+import { mail } from 'gaonjs/mail'
+import { t } from 'gaonjs/i18n'
+
+export const WelcomeMail = mail<{ name: string; email: string }>((u) => ({
+  to: u.email,
+  subject: t('mail.welcome.subject', { name: u.name }),
+  html: `<h1>${t('mail.welcome.body')}</h1>`,
+}))
+```
+
+| 표면 | 시그니처 | 비고 |
+|---|---|---|
+| 정의 | `mail<T>((data) => MailMessage)` | 파일명 = 이름 |
+| 발송 | `def.deliver(data, { locale?, to? })` | 설정된 SMTP 로 보냄 |
+| 미리보기 | `def.render(data, { locale? })` | 발송 없이 메시지만(테스트·미리보기) |
+
+### 2. 로케일 메일 — `deliver(data, { locale })` (결정 160)
+
+다국어 메일은 발송 시 **수신자 로케일**을 명시한다 — `deliver(data, { locale })`
+가 그 언어 컨텍스트로 렌더해 build 본문의 `t()` 가 그 로케일로 번역된다. 수신자
+로케일은 앱이 `recipient.locale` 로 넘긴다(프레임웍이 모델 구조를 알지 않는다).
+`locale` 생략 시 현재 요청 로케일(없으면 fallback).
+
+```ts
+await WelcomeMail.deliver({ name: user.name, email: user.email }, { locale: user.locale })
+// to 옵션으로 수신자를 데이터 밖에서 덮어쓸 수도 있다:
+await WelcomeMail.deliver(data, { locale: 'ja', to: 'ops@example.com' })
+```
+
+### 3. 발송 경로 — 잡/`afterCommit` 으로 (요청 경로 아님)
+
+메일 발송은 느린 외부 I/O 다 — **요청 액션 안에서 직접 `deliver` 하지 않는다**
+(비동기 배치 판단표 · `agents/async.md`). 커밋 뒤 발송이면 서비스 `afterCommit`,
+그 외에는 잡(`domain/jobs/`)으로 빼서 `.later()` 로 발행한다. `gaon doctor` 의
+`async-offload` 가 컨트롤러의 메일 SDK 직접 import 를 경고한다.
+
+### 4. 개발 = MailPit 싱크
+
+`gaon dev` 의 compose 가 MailPit 을 띄운다(SMTP 캡처 + 웹 UI `:8025`) — 개발 중
+보낸 메일은 실제로 나가지 않고 MailPit 수신함에서 확인한다. 스캐폴드 `gaon.config.ts`
+·`.env.example` 에 mail 블록이 이미 있어(결정 160) `cp .env.example .env` 후 바로 돈다.
+운영은 `SMTP_HOST`·자격증명·`SMTP_SECURE=true` 로 교체(같은 코드).
+
+## 정본 예시
+
+```ts
+// domain/jobs/sendWelcome.ts — 발송은 잡으로(요청 경로 보호 · async.md).
+import { job } from 'gaonjs/async'
+import { WelcomeMail } from '../mails/welcome.js'
+import { User } from '../models/User.js'
+
+export const SendWelcome = job(async (userId: bigint) => {
+  const user = await User.where('id', '=', userId).first()
+  if (user) await WelcomeMail.deliver(user, { locale: user.locale })
+})
+
+// 서비스에서: afterCommit(() => SendWelcome.later(user.id))
+```
+
+## 알려진 함정
+
+- **요청 액션에서 직접 `deliver` 금지** — 느린 SMTP 가 응답을 세운다. 잡/`afterCommit`
+  으로 뺀다(`agents/async.md` 판단표 · doctor `async-offload`).
+- **메일 로케일 ≠ 요청 로케일** — 메일은 요청과 다른 컨텍스트(잡)에서 나갈 수 있다.
+  `deliver(data, { locale: recipient.locale })` 로 **명시**한다(결정 160).
+- **from 이 없으면 발송 에러** — 메시지에 `from` 을 주거나 `configureMailer({ defaultFrom })`
+  (스캐폴드 config 의 `MAIL_FROM`)를 설정한다.
+- **레이아웃 상속은 v1 에 없다** — 공통 레이아웃은 v1.1 백로그(결정 160). v1 은 각
+  메일이 자기 html 을 낸다.
+
+## 관련 결정 번호
+
+| 결정 | 요지 |
+|---|---|
+| §7 (v0.15) | 메일 배터리 · `domain/mails/` · MailPit dev sink |
+| 결정 160 (13차 W3) | `deliver(data, { locale, to })` 로케일 인지 · 스캐폴드 mail 블록 · 레이아웃 v1.1 백로그 |

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

@@ -134,6 +134,13 @@ URL 조립(`<앱 프리픽스>/gaon/ws/<채널명>` · ws/wss 자동)·봉투(`{
 을 손으로 짜지 말 것(라이프사이클·봉투를 재구현하다 실수한다). 세션 앱은 쿠키로
 자동 인증, JWT 앱은 `params: { access_token }`.
 
+**앱 프리픽스는 자동이다(결정 154).** 서버는 채널 WS 를 `<앱 프리픽스>/gaon/ws/:channel`
+에 등록하고, `useChannel` 은 그 앱 번들의 `import.meta.env.BASE_URL`(= vite base = 앱
+프리픽스 · 에셋 base 와 단일 소스 · 결정 146)을 읽어 같은 프리픽스로 붙는다: web('/') →
+`/gaon/ws/<name>`, admin('/admin/') → `/admin/gaon/ws/<name>`. **서브앱도 `opts.path` 를
+손으로 넘길 필요가 없다** — `opts.path` 는 표준 vite base 를 안 쓰는 특수 배포용 **탈출구**
+로만 남는다(명시하면 그대로 쓴다). 프리픽스를 손으로 넣던 옛 관례는 폐기됐다.
+
 ```ts
 // apps/web/composables/useRoom.ts — 컴포저블에 래핑(agents/frontend.md §3.2)
 import { useChannel } from 'gaonjs/vue'
@@ -247,6 +254,7 @@ export default channel({
 | E-2 | 웹서버 ↔ 허브 = TCP 지속 연결 · NATS = broadcast 전용 |
 | §7 (v0.15) | 실시간 v1 포함 — 채널·프레즌스·허브 · KV 영속 · 리스 리더 선출 HA |
 | 결정 126 | 서버 개시 `broadcast(name, data)`(`gaonjs/async`) — 컨트롤러·서비스·잡에서 클라 메시지 없이 채널 발화 · authorize 재실행 없음 · seal 재봉인 자동 |
+| 결정 154 | `useChannel` 앱 프리픽스 자동 주입 — `import.meta.env.BASE_URL`(vite base·에셋 base 단일 소스) 로 `<프리픽스>/gaon/ws/<name>` · `opts.path` 는 탈출구 · 프리픽스 앱 실시간 무한 재연결 제거(§4) |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

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

@@ -51,6 +51,13 @@
   자동으로 붙이고, 세션 secret 을 **앱별 env** `<APP>_SESSION_SECRET`(예:
   `ADMIN_SESSION_SECRET`)로 분리 배선한다(결정 141 · 앱별 세션 완전 분리).
   운영 배포 시 그 env 를 web 과 **다르게** 설정할 것.
+- **비-web 앱은 시큐어 기본이다** (결정 155): `gaon g auth --app admin` 은
+  **공개 회원가입(registration)을 깔지 않는다** — 관리 앱에 공개 가입이 열리고
+  로그인한 일반 고객이 관리 화면을 보던 위험 기본을 구조적으로 막는다. 대신 보호
+  라우트에 **역할 게이트**(`this.requireAuth()` + `this.authorize(user.role === 'admin')`
+  · 결정 145)를 예시로 깔고, `domain/schema/users.ts` 에 `role` 컬럼을 두라고 안내한다.
+  관리자는 직접 만들거나 승격한다(공개 가입 라우트 없음). web 앱은 현행대로 공개 가입 O.
+  공개 비-web 앱이 필요하면 `--public` 로 공개 가입을 opt-in 한다.
 - CSRF: 세션 앱은 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 CSRF
   강제. `api()` 클라이언트는 `<meta name="csrf-token">` 을 자동으로
   읽어 `X-CSRF-Token` 헤더에 붙인다 (`packages/vue/src/api.ts:184`).
@@ -61,14 +68,33 @@
   라우트가 있는데 `app.config.ts` 에 session 이 없으면 `gaon doctor` 의
   `csrf-wiring` 이 경고한다(JWT/API 앱은 토큰 인증이라 CSRF 대상 제외).
 - JWT 는 API 앱 전용 옵션. 세션 쿠키가 기본 (v0.15 §7 · v0.11 확정).
-- **인증(requireAuth) 과 인가(authorize) 는 별개 축** (결정 145):
-  - `this.requireAuth()` = **로그인 여부** — 비로그인이면 401(세션 앱은 로그인 페이지 리다이렉트).
-  - `this.authorize(condition)` = **권한 여부** — 조건이 거짓이면 **403**. 존재 자체를
-    숨겨야 하면 `this.authorize(condition, { notFound: true })` → 404. 조건은 호출자가
-    계산한다(예: `this.authorize(this.currentUser?.role === 'admin')`) — v1 은 정책 객체·
-    역할 DSL 을 두지 않는다(리치 authz 는 v1.1 백로그).
+- **인증·인가는 3층이다** (결정 145 · 149):
+  - **① 인증 `this.requireAuth()`** = **로그인 여부** — 비로그인이면 401(세션 앱은
+    로그인 페이지 리다이렉트).
+  - **② 저수준 인가 `this.authorize(condition)`** = **권한 여부** — 조건이 거짓이면
+    **403**. 존재 자체를 숨겨야 하면 `this.authorize(condition, { notFound: true })` → 404.
+    조건은 호출자가 계산한다(예: `this.authorize(this.currentUser?.role === 'admin')`).
+    일회성 규칙·탈출구다.
+  - **③ 정책 객체 `policy()` + `this.can`** (결정 149) — **재사용할 인가 규칙**을 리소스별
+    "액션 → 조건 함수"로 묶는다. 가드는 저수준 authorize 로 수렴한다:
+
+    ```ts
+    // domain/policies/post.ts
+    export const PostPolicy = policy({
+      update: (user, post: PostRec) => post.authorId === user.id,
+      destroy: (user, post: PostRec) => user.role === 'admin' || post.authorId === user.id,
+    })
+    // 컨트롤러
+    this.authorize(this.can(PostPolicy, 'update', post))   // 거부 → 403
+    if (this.can(PostPolicy, 'destroy', post)) { /* 템플릿·분기에도 */ }
+    ```
+
+    정책은 **값 객체를 그대로 넘긴다**(문자열 레지스트리 아님 · 액션·리소스 타입 검사).
+    `this.can` 은 순수 boolean(비로그인 = 거부). 저수준 `authorize(cond)` 는 그대로 살아
+    있다 — 정책은 그 위 편의층이다.
   - 실시간 채널의 `authorize` 는 **구독 인가 전용**(§realtime) — HTTP 인가는 `this.authorize`.
-  - 손으로 403 을 throw 하거나 인가를 `notFound()` 로 우회하지 말 것 — `this.authorize` 가 The One Way.
+  - 손으로 403 을 throw 하거나 인가를 `notFound()` 로 우회하지 말 것 — `this.authorize`
+    (재사용은 `policy`)가 The One Way.
 
 ### 3. 시크릿
 
@@ -179,3 +205,6 @@ const rows = await Post.query()
 | 결정 93 (W2) | 기본 web 앱 세션 기본 배선 = CSRF 기본 켬 실태 · doctor `csrf-wiring` 경고 |
 | 결정 120 | 클라이언트 IP 신뢰 = `web.clientIp` direct/proxy/header · 헤더는 신뢰 홉 전제에서만 · IP 는 약한 신호(인가 금지) · `this.request.ip` 단일 산출(§6 · `agents/web.md` §4.4) |
 | 결정 122 | hidden 계약은 관계(`include`/지연) 행에도 적용 — render props 로 나가는 모든 값은 `serializeProps` 통과 후 hidden 컬럼명 부재 |
+| 결정 145 | 인가 프리미티브 `this.authorize(cond)` — 거짓 → 403(존재 은닉 시 404) · 인증(401)과 별개 축 · 저수준 탈출구 |
+| 결정 149 | 인가 정책 객체 `policy()` + `this.can` — 재사용 규칙을 리소스별 액션→조건으로 묶음 · 값 객체(레지스트리 아님) · 가드는 `authorize(can(...))` 로 수렴 · authorize(cond) 무회귀(§2) |
+| 결정 155 | `gaon g auth --app <비-web>` 시큐어 기본 — 공개 회원가입 미생성 + 역할 게이트(authorize) 예시 · web=공개가입 · `--public` opt-in(§2) |

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

@@ -106,6 +106,12 @@ DB 테스트는 손으로 커넥션을 배선하지 않는다 — `gaon test`
   수동 `configureJobs` 는 필요 없다. `expectJobProcessed` 는 **자기 nats 만** 임시로
   쓰고 끝나면 하네스 배선을 복원하므로, 그 nats 를 `close()` 해도 다음 테스트의
   `.later()` 가 깨지지 않는다(결정 143).
+- `connectTestDatabase` 는 **아웃박스 트랜잭션 래퍼도 배선**한다(결정 152 · `config.nats`
+  있을 때) — serve·work 의 wireGaon 과 같이. 그래서 `service()` 본문의 `emit()` 이 같은
+  트랜잭션으로 `_gaon_outbox` 에 적재되고, **서비스가 롤백되면 적재도 취소**된다(결정 144
+  의 "롤백=미발행" 보장이 테스트에서도 참). 이 배선이 없던 때는 테스트의 emit 이 즉시발행
+  경로로 새 그 보장이 **공허하게 통과**했다 — 아웃박스 롤백을 단언하는 테스트는 표준
+  하네스로 그대로 돈다(수동 `setServiceTxWrapper` 불필요).
 
 스캐폴드가 심어 주는 `test/setup.ts`(수정 불필요):
 

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

@@ -259,6 +259,37 @@ async create() {
   }
   ```
 
+#### 앱 전역 공유 키 확장 — `app.config` 의 `sharedProps` (결정 150)
+
+코어 3종 위에 **앱이 임의 공유 키를 얹을 수 있다**(locale·theme 등). 매 컨트롤러가
+손으로 넘기는 대신 `app.config.ts` 의 `sharedProps` 로 한 번 등록하면 그 앱의 **모든**
+렌더에 자동 주입된다.
+
+```ts
+// apps/web/app.config.ts
+export default defineAppConfig({
+  sharedProps: (ctx) => ({ locale: ctx.session?.locale ?? 'en', theme: 'dark' }),
+})
+```
+
+읽는 쪽은 타입 브리지를 **선언 병합**으로 확장한다(코어 3종은 고정 · 앱 키만 추가):
+
+```ts
+// shared/gaon-shared.d.ts (또는 아무 .d.ts)
+import 'gaonjs/vue'
+declare module 'gaonjs/vue' {
+  interface GaonSharedProps { locale: string; theme: string }
+}
+// 페이지에서
+const { locale, theme } = useShared()   // 타입 안전 · 반응형
+```
+
+- **코어 3종(currentUser·csrf·flash)은 예약** — `sharedProps` 가 이 이름을 반환하면
+  렌더가 throw 한다(코어 계약 보호). 다른 이름을 쓴다.
+- 값은 렌더 경계의 `serializeProps` 를 그대로 통과한다 — **hidden 컬럼은 안 샌다**(결정 122).
+- 변이 축(로케일·사용자 등)은 `sharedProps` 함수가 `ctx` 로 계산한다 — 프레임웍이 자동으로
+  섞지 않는다.
+
 ### 4.3 읽기 조합은 컨트롤러 인라인 조립하지 않는다 (§5.3 · 결정 114)
 
 컨트롤러 액션에 허용되는 쿼리는 **스코프 체인 한 줄**까지다. 검색·태그 필터처럼
@@ -466,6 +497,7 @@ export default controller({
 | 결정 114 | 여러 모델 조합 읽기는 이름 붙임(정적 메서드/서비스) · 컨트롤러는 스코프 체인 한 줄까지(§4.3 · `agents/data.md` §8) |
 | 결정 116 | 공유 prop(currentUser·csrf·flash) 자동 주입 · `this.flash(k,v)` · 페이지는 `useShared()`(§4.2) |
 | 결정 117 | render props 에 예약 공유 키 = 컴파일 에러 + 런타임 방어(자동 주입값 조용한 덮어쓰기 금지 · §4.2) |
+| 결정 150 | 앱 전역 공유 키 확장 — `app.config` sharedProps → 모든 렌더 자동 주입 · 코어 3종 예약(덮으면 throw) · 선언 병합 타입 · hidden 미유출 · useShared 로 읽기(§4.2) |
 | 결정 119 | 목록 액션 페이지네이션 = `chain.paginate(page, perPage)` 종단(§4.3 · `agents/data.md`) · 손 조립 반정본 · result 통째로 render props 안전 |
 | 결정 120 | 클라이언트 IP = `this.request.ip`(별도 표면 없음) · `web.clientIp` direct/proxy/header 로 rate limit·로깅과 같은 산출 배선(§4.4 · `agents/security.md`) |
 | 결정 133 | 멀티파트 업로드(`this.file()`) CSRF 는 `x-csrf-token` 헤더로만 — 바디 `_csrf` 는 스트리밍 파싱이라 검사 시점에 없다(§3 · 헤더 부재 시 403 + 수리 안내) |

package/dist/templates/project/gaon.config.ts.tpl

@@ -40,6 +40,20 @@ export default defineConfig({
       }
     : undefined,
 
+  // 메일(§7 · M8). SMTP — dev = MailPit(compose · 캡처 sink · UI :8025), 운영 = 실 SMTP.
+  // env 미설정이면 배선 안 함(다른 배터리 동형). 다국어 메일은 deliver(data, { locale }) —
+  // 수신자 로케일로 렌더된다(결정 160). domain/mails/*.ts 의 mail() 본문 t() 가 그 언어로.
+  mail: process.env.SMTP_HOST
+    ? {
+        host: process.env.SMTP_HOST,
+        port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : 1025,
+        secure: process.env.SMTP_SECURE === 'true',
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS,
+        defaultFrom: process.env.MAIL_FROM ?? 'no-reply@{{PROJECT_NAME}}.test',
+      }
+    : undefined,
+
   // 웹 서버 리슨 옵션. --port · env PORT 로 덮을 수 있다.
   web: {
     port: process.env.PORT ? Number(process.env.PORT) : 3000,