@gaonjs/cli 0.63.1 → 0.64.0

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

@@ -32,26 +32,26 @@ blocking). 확신이 안 서면 "응답에 이 결과가 필요한가?" 만 묻
 
 각 배치의 정본 예시 (전체 시그니처·옵션은 아래 §1·§4·§5):
 
-```ts
+```ts fragment
 // 잡 — 응답과 분리해 발행 (메일·알림·이미지 처리 등). 컨트롤러/서비스에서:
 await SendWelcomeMail.later(user.id)   // domain/jobs/sendWelcomeMail.ts (§1)
 ```
 
-```ts
+```ts fragment
 // 파생 효과 — 커밋 뒤에만 나가야 하는 발행은 서비스 afterCommit (§4 아웃박스).
 // domain/services/registerUser.ts
 import { service, afterCommit } from 'gaonjs/service'   // service·afterCommit 는 같은 서브패스
 import { User } from '../models/User.js'
 import { ResizeAvatar } from '../jobs/resizeAvatar.js'
 
-export const RegisterUser = service(async (input: RegisterInput) => {
+export const RegisterUser = service(async (input: { name: string; email: string }) => {
   const user = await User.create(input)
   afterCommit(() => ResizeAvatar.later(user.id))  // 커밋 성공 후에만 발행
   return user
 })
 ```
 
-```ts
+```ts fragment
 // 주기 작업 — domain/schedule.ts · 대상은 항상 잡 (§5 · 인라인 함수 금지).
 export default schedule((s) => {
   s.cron('0 9 * * 1', SendWeeklyReport)  // 매주 월 09:00 · 리더 1인만
@@ -75,7 +75,7 @@ export const SendWelcomeMail = job(async (userId: bigint) => {
 }, { retries: 3 })
 ```
 
-```ts
+```ts fragment
 await SendWelcomeMail.later(user.id)        // 즉시 큐잉(인자 타입 그대로 추론)
 await SendWelcomeMail.in('10m', user.id)    // 지연 실행
 await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
@@ -191,7 +191,7 @@ export default on(OrderPlaced, ({ orderId }) => {
 
 이벤트 발행:
 
-```ts
+```ts fragment
 await OrderPlaced.emit({ orderId: 1n })
 ```
 
@@ -431,7 +431,7 @@ REPL 컨텍스트에 실제로 들어 있는 키는 넷이다:
 컨텍스트에 자동 노출하지는 않는다(결정 251 — 빈 스텁을 심어 배너로 약속하면 오도라
 아예 심지 않는다). 핸들이 필요하면 **직접 import** 한다(REPL 은 top-level await 허용):
 
-```ts
+```console
 // gaon> — 잡 하나를 큐에 넣는다
 const { closeDueAuctions } = await import('./domain/jobs/closeDueAuctions.ts')
 await closeDueAuctions.later({ auctionId: 42n })
@@ -454,7 +454,7 @@ await closeDueAuctions.later({ auctionId: 42n })
 상태로 `lock()` 을 부르면 로컬 뮤텍스로 조용히 떨어지지 않고 수리 안내와 함께
 throw** 한다(개발·테스트는 in-memory 백엔드로 폴백해 단일 프로세스에서 그대로 돈다).
 
-```ts
+```ts fragment
 import { lock } from 'gaonjs/async'
 
 // 일 1회 집계가 인스턴스 여러 대에서 중복 실행되지 않게.
@@ -489,7 +489,7 @@ export const SendWelcomeMail = job(async (userId: bigint) => {
 }, { retries: 3 })
 ```
 
-```ts
+```ts controller-action
 // apps/web/controllers/registration.ts — 컨트롤러는 잡 발행만 (직접 발송 금지)
 async create() {
   // 서비스는 모델 폼이 없다 — 컨트롤러가 모델 스키마 폼(`User.form.pick(...)`)으로

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

@@ -17,6 +17,7 @@ export const posts = table('posts', {
   title: t.string().max(200),
   body: t.text(),
   published: t.boolean().default(false),
+  viewCount: t.int().default(0),
   authorId: t.belongsTo('users'),      // FK + 관계를 한 줄로
   ...t.timestamps(),                   // createdAt, updatedAt
 })
@@ -42,6 +43,8 @@ import { table, t, hasMany, hasOne, belongsToMany } from 'gaonjs/data'
 export const posts = table('posts', {
   id: t.id(),
   title: t.string().max(200),
+  body: t.text(),
+  published: t.boolean().default(false),
   authorId: t.belongsTo('users'),          // 정방향(FK 보유) = 컬럼
   ...t.timestamps(),
 }, {
@@ -195,6 +198,9 @@ import 하면 순환 참조가 생기므로, 실제 연결은 부팅 시 프레
 표현할 수 없으니 아래 테이블 레벨 `unique` 를 쓴다:
 
 ```ts
+// domain/schema/orders.ts
+import { table, t } from 'gaonjs/data'
+
 export const orders = table('orders', {
   id: t.id(),
   auctionId: t.belongsTo('auctions').unique(),   // 1:1 — 경매당 주문 하나
@@ -212,11 +218,13 @@ export const watches = table(
 **테이블 레벨 복합 제약** (E-4 §4.2 · 인덱스 객체 확장 결정 273):
 
 ```ts
+// domain/schema/logs.ts
+import { table, t } from 'gaonjs/data'
+
 export const logs = table('logs', {
   userId: t.belongsTo('users'),
   status: t.enum(['active', 'archived'] as const),
   retries: t.int(),
-  createdAt: t.datetime(),
   meta: t.jsonb<Record<string, unknown>>().index(),   // 자동 gin
   ...t.timestamps(),
 }, {
@@ -252,6 +260,9 @@ export const logs = table('logs', {
 **선언적 파티셔닝** (결정 277 · PostgreSQL · 대용량 로그/이벤트/감사):
 
 ```ts
+// domain/schema/logs.ts
+import { table, t } from 'gaonjs/data'
+
 export const logs = table('logs', {
   id: t.id(),
   createdAt: t.datetime(),
@@ -427,11 +438,16 @@ export const logs = table('logs', {
 
 ```ts
 // domain/models/Post.ts — 조회수 카운터(원자 · 경쟁 조건 없음)
-methods: {
-  async recordView() {
-    return await this.increment('viewCount')   // NOT: this.update({ viewCount: this.viewCount + 1 })
+import { model } from 'gaonjs/data'
+import { posts } from '../schema/posts.js'
+
+export const Post = model(posts, {
+  methods: {
+    async recordView() {
+      return await this.increment('viewCount')   // NOT: this.update({ viewCount: this.viewCount + 1 })
+    },
   },
-}
+})
 ```
 
 **체인 상태 전이 주의** (`model.ts`):
@@ -461,7 +477,7 @@ methods: {
 
 실 구현 (E-4 (h) 정정 · `model.ts`):
 
-```ts
+```ts fragment
 // 조인·집계·CTE 등 복잡 쿼리
 const rows = await Post.query()
   .innerJoin('users', 'users.id', 'posts.authorId')
@@ -546,9 +562,11 @@ export default defineConfig({
 // domain/services/placeOrder.ts — main 커밋 성공 뒤에만 analytics 기록 (파일명 camelCase)
 import { service, afterCommit } from 'gaonjs/service'
 import { getConnection } from 'gaonjs/data'
+import { Order } from '../models/Order.js'
 
-export const PlaceOrder = service(async (input: { userId: string; total: number }) => {
-  const order = await Order.create({ userId: input.userId, total: input.total }) // main 트랜잭션
+export const PlaceOrder = service(async (input: { auctionId: bigint; buyerId: bigint; total: number }) => {
+  // 컬럼은 §1.1 의 orders 스키마 그대로 — total 은 analytics 쪽 파생값이다.
+  const order = await Order.create({ auctionId: input.auctionId, buyerId: input.buyerId }) // main 트랜잭션
 
   // 커넥션을 가로지르는 쓰기는 트랜잭션 밖 — 커밋 성공 뒤에만.
   afterCommit(async () => {
@@ -643,6 +661,9 @@ statics 가 필요하면 **반드시 위 3-제네릭 패턴** — 제네릭 없
 
 ```ts
 // gaon.config.ts — 문서형 커넥션은 adapter: 'mongodb' 로 SQL 과 나란히 선언한다.
+import { defineConfig } from 'gaonjs/config'
+import { env } from 'gaonjs/env'
+
 export default defineConfig({
   db: {
     main: { adapter: 'postgres', url: env('DATABASE_URL') },
@@ -763,7 +784,7 @@ export const Post = model(posts, {
 })
 ```
 
-```ts
+```ts fragment
 // 사용 — scope·체이닝·CRUD 가 그대로 이어진다
 const items = await Post.published().latest().limit(20).all()
 const both = await Post.published().recent().all()      // 스코프 조합
@@ -794,6 +815,10 @@ await post.publish()                                    // 인스턴스 메서
   관계를 그대로 호출한다.
 
 ```ts
+// domain/models/Post.ts — 스코프 + 관계를 쓰는 인스턴스 메서드
+import { model } from 'gaonjs/data'
+import { posts } from '../schema/posts.js'
+
 export const Post = model(posts, {
   scopes: {
     // 스코프는 컬럼만 다룬다 — 관계 조건이 필요하면 Post.query() 탈출구(§5)
@@ -862,7 +887,7 @@ export const Post = model(posts, {
 돌려준다(원 폼 불변). 컬럼 타입·검증·기본값 정보가 그대로 따라오므로,
 "검증되는 부분 폼"이 필요할 때 애드혹 `{ _row: {} as T }`(검증 없음) 대신 쓴다.
 
-```ts
+```ts controller-action
 // routes: r.post('/posts/:postId/comments', 'comments#create')
 // comments 스키마에서 postId·author·body 만 — :postId 는 라우트에서 자동 병합(결정 95).
 async create() {
@@ -886,7 +911,7 @@ async create() {
 
 비싼 조회·계산 결과를 **명시 TTL** 로 캐시한다. `gaonjs/data` 에서 온다.
 
-```ts
+```ts fragment
 import { cache } from 'gaonjs/data'
 
 // 키가 있으면 캐시 값, 없으면 fn 을 돌려 60초 캐시.
@@ -1090,7 +1115,7 @@ export default seed(async () => {
 
 ## 정본 예시
 
-```ts
+```ts fragment
 // 목록 + 필터 + 정렬 — 대표 패턴
 const posts = await Post
   .where('published', '=', true)

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

@@ -122,7 +122,7 @@ async function search(q: string) {
 (폼이 아니므로 `useForm` 이 아니고, `fetch()` 는 CSRF 미부착으로 403 — 아래
 함정). POST 라우트 `r.post('/posts/:id/like', 'posts#like')` 기준:
 
-```vue
+```vue fragment
 <script setup lang="ts">
 import { api, isApiError } from 'gaonjs/vue'
 
@@ -195,12 +195,17 @@ bigint PK(`t.id()`)를 페이지로 흘릴 때는 **컨트롤러 render props
 
 ```ts
 // apps/web/controllers/products.ts
-async index() {
-  const list = await Product.orderBy('createdAt', 'desc').limit(20).all()
-  return this.render('Products/Index', {
-    products: list.map((p) => ({ id: String(p.id), name: p.name, price: p.price })),
-  })
-}
+import { controller } from 'gaonjs/web'
+import { Product } from '../../../domain/models/Product.js'
+
+export default controller({
+  async index() {
+    const list = await Product.orderBy('createdAt', 'desc').limit(20).all()
+    return this.render('Products/Index', {
+      products: list.map((p) => ({ id: String(p.id), name: p.name, price: p.price })),
+    })
+  },
+})
 ```
 
 - **정규화 지점은 하나** — 컨트롤러. Vue 템플릿에서 `:key="String(p.id)"` 로 방어
@@ -310,7 +315,7 @@ shared/lib/utils.ts                # cn() — 조건부 클래스 병합
 shared/components/ui/*.vue          # 원자 + 블록 (전 앱 공용 순수 UI)
 ```
 
-```vue
+```vue fragment
 <script setup lang="ts">
 import Button from '@shared/components/ui/Button.vue'   // @shared = 프로젝트 shared/
 import Card from '@shared/components/ui/Card.vue'
@@ -420,7 +425,7 @@ import PageShell from '@shared/components/ui/PageShell.vue'
 `import.meta` 를 **TS1470** 로 거부하기 때문이다(`gaon check` red). 프레임웍이
 `import.meta.env` 를 대신 읽어 재노출하므로 페이지는 `import.meta` 를 안 쓴다.
 
-```vue
+```vue fragment
 <script setup lang="ts">
 import { env } from 'gaonjs/vue'
 

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

@@ -43,6 +43,8 @@ apps/
 
 ```ts
 // gaon.config.ts
+import { defineConfig } from 'gaonjs/config'
+
 export default defineConfig({
   i18n: { fallbackLng: 'ko', supportedLngs: ['ko', 'en'] },
 })
@@ -78,7 +80,13 @@ const props = pageProps<'web:posts#index'>()
 
 ```ts
 // apps/web/main.ts
+import { createGaonApp } from 'gaonjs/vue'
+import { routes } from './.gaon/routes.manifest.js'
 import { catalogs, fallbackLng } from './.gaon/messages.catalog.js'
+
+const pages = import.meta.glob('./pages/**/*.vue')
+const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
+
 void createGaonApp({ pages, layouts, routes, messages: { catalogs, fallbackLng } })
 ```
 
@@ -86,13 +94,21 @@ void createGaonApp({ pages, layouts, routes, messages: { catalogs, fallbackLng }
 
 ```ts
 // domain/mails/welcome.ts — 수신자 로케일로 렌더된다(결정 160)
+import { mail } from 'gaonjs/mail'
 import { t } from 'gaonjs/i18n'
-export const Welcome = mail({ subject: () => t('mail.welcome.subject', { name: '가온' }) })
+
+export const Welcome = mail<{ name: string; email: string }>((u) => ({
+  to: u.email,
+  subject: t('mail.welcome.subject', { name: u.name }),
+  html: `<h1>${t('mail.welcome.body')}</h1>`,
+}))
 ```
 
 ```ts
 // domain/jobs/sendDigest.ts — 잡은 요청 밖이라 로케일을 페이로드로 싣는다
+import { job } from 'gaonjs/async'
 import { runWithLanguage, t } from 'gaonjs/i18n'
+
 export const SendDigest = job(async ({ locale }: { locale: string }) => {
   const line = runWithLanguage(locale, () => t('mail.digest.body'))
 })
@@ -114,7 +130,7 @@ export const SendDigest = job(async ({ locale }: { locale: string }) => {
 `gaon gen`/`dev`/`check` 가 카탈로그를 읽어 **두 유니온**을 생성한다:
 서버(`gaonjs/i18n`) = backend ∪ frontend / 클라(`gaonjs/vue`) = frontend 만.
 
-```ts
+```ts fragment expect-error
 t('posts.heading')                    // ✅
 t('mail.welcome.subject', { name })   // ❌ 클라에서 backend 키 — 컴파일 에러
 t('greeting')                         // ❌ {{name}} 보간 파라미터 누락 — 컴파일 에러
@@ -152,7 +168,7 @@ t('cart.items', { count: 'many' })    // ❌ count 는 number — 컴파일 에
 `gaon.config.ts` 에 `i18n` 이 있으면 매 요청 **세션 > 쿠키 > Accept-Language** 로 협상된다.
 전환은 서버가 권위를 갖는다 — 클라에 `setLocale` 은 **없다**.
 
-```ts
+```ts controller-action
 // 컨트롤러 — 언어 전환 라우트
 async switchLocale() {
   const { lng } = this.params({ _row: {} as { lng: string } })
@@ -177,7 +193,7 @@ async switchLocale() {
 런타임까지 오는 것은 **동적 키**(`t(변수)`)와 진짜 카탈로그 누락뿐이라, 그 둘만 우아하게
 degrade 한다. 즉 **빌드 = 차단 / 런타임 = 키 렌더 + 경고**의 2단이다.
 
-```ts
+```ts fragment
 const key = `posts.${kind}`            // 동적 키 — 컴파일 게이트가 못 본다
 t(key as never)                        // 없으면 'posts.abc' 가 화면에 뜨고 경고 1줄
 ```
@@ -209,7 +225,7 @@ t(key as never)                        // 없으면 'posts.abc' 가 화면에
 // apps/web/locales/en.json  ← 같은 키를 나란히(locale-parity)
 { "posts": { "heading": "Posts", "empty": "No posts yet." } }
 ```
-```vue
+```vue fragment
 <script setup lang="ts">
 import { t } from 'gaonjs/vue'
 </script>
@@ -244,7 +260,7 @@ import { t, Link } from 'gaonjs/vue'
 // locales/ko/backend.json
 { "mail": { "welcome": { "subject": "{{name}}님, 환영합니다" } } }
 ```
-```ts
+```ts fragment
 import { t } from 'gaonjs/i18n'
 const subject = t('mail.welcome.subject', { name: user.name })
 ```

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

@@ -39,7 +39,7 @@ export const WelcomeMail = mail<{ name: string; email: string }>((u) => ({
 로케일은 앱이 `recipient.locale` 로 넘긴다(프레임웍이 모델 구조를 알지 않는다).
 `locale` 생략 시 현재 요청 로케일(없으면 fallback).
 
-```ts
+```ts fragment
 await WelcomeMail.deliver({ name: user.name, email: user.email }, { locale: user.locale })
 // to 옵션으로 수신자를 데이터 밖에서 덮어쓸 수도 있다:
 await WelcomeMail.deliver(data, { locale: 'ja', to: 'ops@example.com' })
@@ -71,6 +71,8 @@ await WelcomeMail.deliver(data, { locale: 'ja', to: 'ops@example.com' })
 
 ```ts
 // gaon.config.ts
+import { defineConfig } from 'gaonjs/config'
+
 export default defineConfig({
   mail: process.env.SMTP_HOST
     ? {

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

@@ -132,6 +132,7 @@ export default channel({
 // apps/web/controllers/posts.ts — service·job·listener 어디서든 동일하게 호출
 import { controller } from 'gaonjs/web'
 import { broadcast } from 'gaonjs/async'
+import { Post } from '../../../domain/models/Post.js'
 
 export default controller({
   async create() {
@@ -244,16 +245,16 @@ export default channel({
 })
 ```
 
-```ts
+```ts fragment
 // 클라이언트 — 인스턴스 키를 지정해 구독한다(경로: /gaon/ws/match/42)
 const game = useChannel('match', { instance: matchId })       // 숫자는 자동 문자열화
-const comments = useChannel('thread', { instance: postId })
+const comments = useChannel('thread', { instance: String(postId) })  // bigint PK 는 String() (결정 37)
 ```
 
-```ts
+```ts fragment
 // 서버 발화·조회 — { instance } 옵션으로 특정 인스턴스에만 스코프한다
 broadcast('match', { round: 2 }, { instance: '42' })                  // match:42 전원
-await sendToUsers('match', userId, { note: '…' }, { instance: '42' }) // match:42 의 그 유저만
+await sendToUsers('match', String(userId), { note: '…' }, { instance: '42' }) // match:42 의 그 유저만
 const players = await presenceList('match', { instance: '42' })       // match:42 로스터
 const rooms = await presenceOf(`user:${userId}`)                      // 역방향: 이 유저가 지금 있는 곳
 // rooms = [{ channel: 'match', instance: '42' }, { channel: 'lobby' }, …]
@@ -406,10 +407,16 @@ export default channel({})
 동적 정원이 된다:
 
 ```ts
-// 채팅방 — 고정 인원 제한
+// domain/channels/chat.ts — 채팅방: 고정 인원 제한
+import { channel } from 'gaonjs/async'
+
 export default channel({ instance: true, maxMembers: 100 })
+```
+
+```ts
+// domain/channels/match.ts — 게임 매치: 방별 정원(메타·DB 조회)
+import { channel, instanceMeta } from 'gaonjs/async'
 
-// 게임 매치 — 방별 정원(메타·DB 조회)
 export default channel({
   instance: true,
   async maxMembers(ctx) {
@@ -426,9 +433,9 @@ export default channel({
 present 대상 수(0 = 부재 = no-op 멱등). **누가 kick 할 수 있는가는 호출
 지점(컨트롤러·서비스)의 앱 인가가 정한다.**
 
-```ts
+```ts fragment
 // 채팅 모더레이터 강퇴 / 게임 안티치트 축출 — 같은 한 줄
-await kick('room', `user:${targetId}`, { instance: roomId, reason: '규정 위반' })
+await kick('room', `user:${targetId}`, { instance: String(roomId), reason: '규정 위반' })
 ```
 
 **버튼 → 컨트롤러 → `api()` 완결 경로(결정 452).** kick 은 서버 전용
@@ -437,10 +444,10 @@ await kick('room', `user:${targetId}`, { instance: roomId, reason: '규정 위
 (`agents/frontend.md` §2). 위임(delegate)·방 설정 변경류 **방장 커맨드도
 전부 같은 경로**다:
 
-```ts
-// apps/web/routes.ts
-r.post('/rooms/:key/kick', 'rooms#kick')
+라우트는 한 줄이다 — `apps/web/routes.ts` 의 `routes((r) => { … })` 안에
+`r.post('/rooms/:key/kick', 'rooms#kick')` 을 더한다.
 
+```ts controller-action
 // apps/web/controllers/rooms.ts — 인가(방장 검사) → kick → this.json
 async kick() {
   this.requireAuth()
@@ -454,8 +461,8 @@ async kick() {
 }
 ```
 
-```ts
-// apps/web/pages/Rooms/Show.vue — CSRF 는 api() 가 자동 부착(결정 166·341)
+```ts fragment
+// apps/web/pages/Rooms/Show.vue 의 <script setup> — CSRF 는 api() 가 자동 부착(결정 166·341)
 import { api, isApiError } from 'gaonjs/vue'
 await api('web:rooms#kick', { key: room.key, targetUserId })   // :key 는 자리표시자, 나머지는 JSON 바디
 ```
@@ -470,23 +477,34 @@ await api('web:rooms#kick', { key: room.key, targetUserId })   // :key 는 자
 도메인마다 달라 프레임웍이 정하지 않는다 — DB(정본) + authorize(보증) +
 kick(즉시성):
 
-```ts
-// ① 도메인 기록(정본 = DB)           ② 즉시 축출              ③ 재입장 차단(4401)
+```ts fragment
+// ① 도메인 기록(정본 = DB)           ② 즉시 축출
 await RoomBan.create({ roomId, userId, reason })
-await kick('room', `user:${userId}`, { instance: roomId, reason })
-// channels/room.ts — authorize 가 보증 층이다(kick 유실·재접속을 막는 백스톱)
-async authorize(ctx) {
-  const u = ctx.user as { id: bigint } | null
-  if (!u) return false
-  let roomId: bigint
-  try {
-    roomId = BigInt(ctx.instance)
-  } catch {
-    return false
-  }
-  if (String(roomId) !== ctx.instance) return false // 정규형만(§2.7 유령 인스턴스 · 결정 447)
-  return !(await RoomBan.where('roomId', '=', roomId).where('userId', '=', u.id).exists())
-}
+await kick('room', `user:${userId}`, { instance: String(roomId), reason })
+```
+
+③ 재입장 차단(4401)은 `authorize` 가 보증 층이다 — kick 유실·재접속을 막는 백스톱:
+
+```ts
+// domain/channels/room.ts — 공유 채널 정의는 domain/channels/ 가 정본(결정 456)
+import { channel } from 'gaonjs/async'
+import { RoomBan } from '../models/Room.js'
+
+export default channel({
+  instance: true,
+  async authorize(ctx) {
+    const u = ctx.user as { id: bigint } | null
+    if (!u) return false
+    let roomId: bigint
+    try {
+      roomId = BigInt(ctx.instance)
+    } catch {
+      return false
+    }
+    if (String(roomId) !== ctx.instance) return false // 정규형만(§2.7 유령 인스턴스 · 결정 447)
+    return !(await RoomBan.where('roomId', '=', roomId).where('userId', '=', u.id).exists())
+  },
+})
 ```
 
 익명 멤버(`conn:<uuid>`)는 신원 영속이 없어 ban 이 불가능하다(kick 만
@@ -499,13 +517,18 @@ DB + authorize** 고, 메타의 존재 이유는 닫힘 시 자동 소멸이다(
 소멸 앵커가 없어 메타 미지원 · 4400):
 
 ```ts
+// domain/channels/match.ts — 열림 시 1회 기록되는 인스턴스 메타
+import { channel } from 'gaonjs/async'
+
 export default channel({
   instance: true,
   instanceMeta(ctx) {              // 열림(첫 점유) 시 1회 기록 — 허브가 open 앵커에서만
     return { mode: ctx.query.mode ?? 'ranked', capacity: 4 }
   },
 })
+```
 
+```ts fragment
 await setInstanceMeta('match', { mode: 'casual' }, { instance: '42' })  // 인가된 액션 갱신(LWW)
 const meta = await instanceMeta('match', { instance: '42' })            // 읽기(미설정·닫힘 = null)
 const rooms = await instancesOf('match', { meta: true })                // 로비: [{ instance, meta }]
@@ -523,7 +546,7 @@ const rooms = await instancesOf('match', { meta: true })                // 로
 로스터로 한 곳에서 결정" 하는 로직의 정본 앵커다. `InstanceOpened/Closed` 와
 같은 전달(워커 하나만 처리 · at-least-once — 핸들러 멱등):
 
-```ts
+```ts fragment
 export default on(MemberLeft, async ({ channel, instance, member, roster }) => {
   // roster = 제거 반영 후 잔존 멤버 [{ id, joinSeq? }] · joinSeq 오름차순.
   // 빈 배열 = 마지막 이탈(InstanceClosed 도 발행되지만 컨슈머 축이 달라
@@ -575,7 +598,7 @@ export default on(MemberLeft, async ({ channel, instance, member, roster }) => {
 `ctx.presence()` 는 **전 서버의** 현재 접속자를 돌려준다. 목록의 권위는
 허브(KV) 이므로, 웹서버가 여러 대여도 같은 목록을 본다.
 
-```ts
+```ts fragment
 const members = await ctx.presence()
 // [{ id: 'user:1', info: { name: '가온' } }, …]
 ```

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

@@ -74,7 +74,9 @@ npm i @gaonjs/seal        # pnpm add @gaonjs/seal · yarn add @gaonjs/seal 동
 2) 앱 설정에서 켠다:
 
 ```ts
-// apps/<앱>/app.config.ts — 앱 wire 전체 봉인(요청/응답 JSON + 최초 문서 data-page).
+// apps/web/app.config.ts — 앱 wire 전체 봉인(요청/응답 JSON + 최초 문서 data-page).
+import { defineAppConfig } from 'gaonjs/config'
+
 export default defineAppConfig({
   seal: true, // 또는 { except: ['/webhooks/*'], strictQuery: true } — except = 외부가 seal 을 모르는 경로만 평문 통과 · strictQuery = 평문 쿼리도 거부(결정 354)
 })
@@ -82,10 +84,15 @@ export default defineAppConfig({
 3) 클라이언트를 배선한다:
 
 ```ts
-// apps/<앱>/main.ts — seal 클라이언트를 정적 import 해 createGaonApp 에 넘긴다.
+// apps/web/main.ts — seal 클라이언트를 정적 import 해 createGaonApp 에 넘긴다.
 import { createGaonApp } from 'gaonjs/vue'
 import * as sealClient from '@gaonjs/seal/client'   // 정적 import (사용자 vite 가 wasm 포함 번들)
-void createGaonApp({ pages, layouts, /* ... */ sealClient })
+import { routes } from './.gaon/routes.manifest.js'
+
+const pages = import.meta.glob('./pages/**/*.vue')
+const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
+
+void createGaonApp({ pages, layouts, routes, sealClient })
 ```
 
 - **왜 main.ts 배선이 필요한가 (결정 124 · §3.1)**: `@gaonjs/vue` 는 선택 플러그인 seal 을 **몰라야** 한다
@@ -194,16 +201,27 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 
 ```ts
 // apps/web/app.config.ts — 앱 wire 전체 봉인.
+import { defineAppConfig } from 'gaonjs/config'
+
 export default defineAppConfig({ seal: true })
 ```
 ```ts
 // apps/web/main.ts — seal 클라이언트 정적 import 를 createGaonApp 에 주입(결정 124 · doctor 가 강제·fixer 자동 배선).
 import { createGaonApp } from 'gaonjs/vue'
 import * as sealClient from '@gaonjs/seal/client'
-void createGaonApp({ pages, layouts, /* ... */ sealClient })
+import { routes } from './.gaon/routes.manifest.js'
+
+const pages = import.meta.glob('./pages/**/*.vue')
+const layouts = import.meta.glob('./layouts/*.vue', { eager: true })
+
+void createGaonApp({ pages, layouts, routes, sealClient })
 ```
 ```ts
+// apps/web/controllers/posts.ts
 // 컨트롤러는 그대로 — seal 을 전혀 모른다(요청/응답 JSON·최초 문서 data-page·WS 프레임이 자동 봉인).
+import { controller } from 'gaonjs/web'
+import { Post } from '../../../domain/models/Post.js'
+
 export default controller({
   async index() {
     return this.render('Posts/Index', { posts: await Post.latest().all() })

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

@@ -249,7 +249,7 @@
 
 ## 정본 예시
 
-```ts
+```ts fragment
 // 시크릿 — env 로만 (gaonjs/env)
 import { env } from 'gaonjs/env'
 const apiKey = env('PAYMENT_API_KEY')   // .env / 배포 환경변수

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

@@ -52,21 +52,26 @@
 ### 2. 설정 (`gaon.config.ts`)
 
 ```ts
-storage: process.env.STORAGE_ENDPOINT
-  ? {
-      default: 'main',
-      disks: {
-        main: {
-          driver: 's3',                              // 's3' | 'local'
-          bucket: process.env.STORAGE_BUCKET ?? 'myapp',
-          endpoint: process.env.STORAGE_ENDPOINT,    // MinIO/R2 = 필수 · AWS S3 = 생략
-          accessKeyId: process.env.STORAGE_ACCESS_KEY,
-          secretAccessKey: process.env.STORAGE_SECRET_KEY,
-          // publicUrl: 'https://cdn.example.com',    // 있으면 url()이 공개 URL
+// gaon.config.ts
+import { defineConfig } from 'gaonjs/config'
+
+export default defineConfig({
+  storage: process.env.STORAGE_ENDPOINT
+    ? {
+        default: 'main',
+        disks: {
+          main: {
+            driver: 's3',                            // 's3' | 'local'
+            bucket: process.env.STORAGE_BUCKET ?? 'myapp',
+            endpoint: process.env.STORAGE_ENDPOINT,  // MinIO/R2 = 필수 · AWS S3 = 생략
+            accessKeyId: process.env.STORAGE_ACCESS_KEY,
+            secretAccessKey: process.env.STORAGE_SECRET_KEY,
+            // publicUrl: 'https://cdn.example.com', // 있으면 url()이 공개 URL
+          },
         },
-      },
-    }
-  : undefined,
+      }
+    : undefined,
+})
 ```
 
 - dev 는 compose 의 `createbuckets` 가 버킷을 만들어 **첫 업로드부터 동작**한다
@@ -86,6 +91,9 @@ storage: process.env.STORAGE_ENDPOINT
 
 ```ts
 // apps/web/controllers/profile.ts
+import { controller } from 'gaonjs/web'
+import { Storage } from 'gaonjs/storage'
+
 export default controller({
   async updateAvatar() {
     const f = this.file('avatar')                     // UploadedFile | undefined
@@ -139,7 +147,7 @@ export default controller({
 
 ## 정본 예시
 
-```ts
+```ts fragment
 // 저장 → 공개/서명 URL 얻기(드라이버 무관 · 같은 코드). url() 은 async.
 // 화면에 표시할 파일이면 키를 public/ 아래에 둔다 — 로컬 디스크의 서빙 범위가
 // publicPrefix(기본 'public/')로 한정되기 때문이다(결정 401 · 밖이면 404).

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

@@ -56,7 +56,7 @@
 
 ### 3. 실 NATS 접속 관례
 
-```ts
+```ts test
 import { connectNats } from 'gaonjs/async'
 
 // 인자 없이 부르면 env NATS_URL(없으면 nats://127.0.0.1:4222)에 붙는다.
@@ -147,7 +147,7 @@ describe('PostPublished (실 NATS JetStream)', () => {
   표준 하네스(`connectTestDatabase` · `config.nats` + `main` 커넥션)가 배선하므로, `gaon test`
   로 도는 통합 테스트에서 그냥 성립한다.
 
-```ts
+```ts test
 // service() 가 emit 하는 흐름도 같은 한 줄로 확증된다(트리거만 서비스 호출로 바꾸면 됨).
 await expectEventProcessed(PostPublished, () => PublishPost.call({ postId: 1n }), { nats })
 ```
@@ -190,7 +190,7 @@ DB 테스트는 손으로 커넥션을 배선하지 않는다 — `gaon test`
 
 스캐폴드가 심어 주는 `test/setup.ts`(수정 불필요):
 
-```ts
+```ts test
 import { afterAll, afterEach, beforeAll } from 'vitest'
 import { connectTestDatabase, truncateAllConnections, type TestDbHandle } from 'gaonjs/testing'
 
@@ -273,7 +273,7 @@ describe('AuditLog(실 mongod)', () => {
   서비스가 반환하기 **전에** 실행되므로, 테스트는 서비스 호출을 `await` 한 직후 몽고
   문서를 단언하면 된다(별도 대기·폴링 불필요).
 
-```ts
+```ts test
 // SQL 커밋 → 몽고 감사 로그 순서를 한 흐름으로 확증한다.
 const user = await SignUp.call({ email: 'a@b.c', password: 'x' })   // main(SQL) 커밋 + afterCommit
 expect(await AuditLog.countDocuments({ actorId: String(user.id) })).toBe(1)
@@ -298,7 +298,7 @@ expect(await AuditLog.countDocuments({ actorId: 'dup' })).toBe(0)
 정본 = "직렬화 결과 어디에도 hidden 컬럼명이 없다" 를 **재귀로** 단언한다
 (배열·중첩 관계 전부 훑는 헬퍼). 관계를 포함한 픽스처에 적용한다:
 
-```ts
+```ts test
 // 직렬화 결과(JSON-safe)에 hidden 컬럼명이 어느 깊이에도 없음을 확인.
 function assertNoHiddenLeak(value: unknown, hidden: readonly string[]): void {
   const walk = (v: unknown): void => {

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

@@ -231,7 +231,7 @@ handler 안에서 파싱). **결정 342 이후 헤더 부착은 프레임웍 자
 (참고: 지원 Content-Type 은 `application/json` · `multipart/form-data` 뿐이라
 `x-www-form-urlencoded` 로 폼을 보내면 415 로 거부된다 · `inertia.ts` · §아래 415.)
 
-```vue
+```vue fragment
 <script setup lang="ts">
 import { useForm } from 'gaonjs/vue'
 const form = useForm({ avatar: null as File | null })
@@ -259,8 +259,10 @@ redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드
 폼 API 는 **`gaonjs/vue` 의 `useForm`·`router`** 뿐이다(결정 64) —
 `@inertiajs/vue3` 를 직접 import 하지 않는다(파사드가 The One Way).
 
-```ts
+```ts fragment
 // 로그인 폼 — 제출은 Inertia SPA 방식, 서버는 redirect 로 답한다.
+import { pageProps, router, useForm } from 'gaonjs/vue'
+
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
 // CSRF 토큰은 프레임웍이 자동 부착한다(결정 342) — _csrf 바디도, 수동 헤더도 없다.
 const props = pageProps<'web:session#new'>()
@@ -282,7 +284,7 @@ Inertia 폼(`useForm(...).post()`)의 검증 실패는 컨트롤러가 손으로
 방문의 `errors` 로 `form.errors.<필드>` 를 **자동으로 채운다**. 입력값은
 `useForm` 이 그대로 보존한다(재제출 방지). 컨트롤러는 성공 경로만 쓴다:
 
-```ts
+```ts controller-action
 // 컨트롤러 — 검증 실패 분기를 손으로 쓰지 않는다(결정 109).
 async create() {
   const data = this.params(Post.form.pick('title', 'body'))  // 실패 시 프레임웍이 303 back
@@ -291,10 +293,18 @@ async create() {
 }
 ```
 
-```vue
+```vue fragment
 <!-- 페이지 — form.errors.<필드> 는 서버 검증 실패 시 자동으로 채워진다. -->
-<input v-model="form.title" />
-<p v-if="form.errors.title">{{ form.errors.title }}</p>
+<script setup lang="ts">
+import { useForm } from 'gaonjs/vue'
+
+const form = useForm({ title: '', body: '' })
+</script>
+
+<template>
+  <input v-model="form.title" />
+  <p v-if="form.errors.title">{{ form.errors.title }}</p>
+</template>
 ```
 
 순수 JSON/API 앱(X-Inertia 아님·세션 없음)은 기존대로 **422 JSON** 을 받는다.
@@ -381,6 +391,8 @@ async create() {
 
 ```ts
 // apps/web/app.config.ts
+import { defineAppConfig } from 'gaonjs/config'
+
 export default defineAppConfig({
   sharedProps: (ctx) => ({ locale: ctx.session?.locale ?? 'en', theme: 'dark' }),
 })
@@ -414,7 +426,7 @@ shared.locale                            // 로그인/로그아웃·플래시로
 메서드(스코프)**, 대등한 조합이면 `domain/services/`(`agents/data.md` §8). 컨트롤러가
 `pluck`·교집합·사이드바 질의를 인라인 조립하기 시작하면 서비스/스코프로 옮긴다.
 
-```ts
+```ts fragment
 // ❌ 컨트롤러가 검색 교집합·태그 필터를 인라인 조립
 // ✅ const rows = await Post.searchPublished(term).latest().offset(o).limit(n).all()
 // ✅ 페이지네이션은 스코프 체인 종단 paginate — 컨트롤러는 여전히 한 줄(결정 119)
@@ -450,7 +462,7 @@ shared.locale                            // 로그인/로그아웃·플래시로
 base64·해시를 손으로 짜지 말고** `gaonjs/web` 의 헬퍼를 쓴다(The One Way · §7 인증).
 bcrypt(cost 10)로 해싱하며 상수시간 비교를 제공한다.
 
-```ts
+```ts fragment
 import { hashPassword, verifyPassword } from 'gaonjs/web'
 
 // 가입 — 서비스에서 평문을 해싱해 hidden 컬럼(passwordDigest)에 저장.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.63.1",
+  "version": "0.64.0",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -32,13 +32,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.22.0",
-    "@gaonjs/config": "0.25.11",
-    "@gaonjs/core": "0.3.0",
-    "@gaonjs/data": "0.26.1",
+    "@gaonjs/data": "0.26.2",
     "@gaonjs/i18n": "0.4.1",
+    "@gaonjs/config": "0.25.12",
+    "@gaonjs/async": "0.22.0",
     "@gaonjs/mail": "0.5.3",
-    "@gaonjs/web": "0.32.0"
+    "@gaonjs/core": "0.3.0",
+    "@gaonjs/web": "0.32.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"const fs=require('fs');fs.cpSync('src/templates','dist/templates',{recursive:true,filter:(s)=>!s.endsWith('.ts')});fs.rmSync('dist/templates/index.ts',{force:true})\""