@gaonjs/cli 0.40.0 → 0.41.0

package/dist/commands/new.js

@@ -40,7 +40,13 @@ function validateProjectName(name) {
             `  → 예: gaon new my-app · gaon new demo`);
     }
 }
-/** 파사드(gaonjs) 패키지의 실 버전을 찾는다 — package.json 을 위로 훑는다. */
+/**
+ * 파사드(gaonjs) 패키지의 실 버전을 찾는다 — package.json 을 위로 훑는다.
+ * 정상 설치(node_modules/gaonjs)·개발 트리(packages/gaonjs) 모두에서 인접
+ * package.json 을 상향 탐색하면 반드시 잡힌다. 못 찾으면 **fail-loud**(결정 242):
+ * 옛 폴백 `^0.5.0` 은 2년 전 스텁 라인을 조용히 핀해 첫 화면부터 API 불일치로
+ * 깨지는 스캐폴드를 낳았다 — 조용한 스테일 핀보다 명확한 실패가 낫다.
+ */
 function detectGaonjsVersion() {
     // 가장 안전한 방법: 이 파일 위치를 기준으로 packages/gaonjs/package.json 을
     // 상향 탐색. 개발 트리(src)와 배포 트리(dist) 모두에서 동작한다.
@@ -63,8 +69,10 @@ function detectGaonjsVersion() {
             break;
         dir = parent;
     }
-    // 발견 못 하면 최근 스텁 배포 라인의 안전 하한.
-    return '^0.5.0';
+    // 결정 242: 스테일 폴백 제거 — 감지 실패는 즉시 알린다(§7.5.3 · 조용한 실패 금지).
+    throw new Error('gaonjs 파사드 버전을 자동 감지하지 못했습니다.\n' +
+        '  → gaon 을 gaonjs 설치본(node_modules/gaonjs)을 통해 실행했는지 확인하세요.\n' +
+        '  → 정상 설치라면 이 오류는 나지 않습니다(스캐폴드가 인접 package.json 에서 버전을 읽습니다).');
 }
 /** 대상 폴더가 비어 있는지(생성 대상으로 안전한지) 확인. */
 function isEmptyOrMissing(dir) {
@@ -171,7 +179,14 @@ export async function runNewCommand(name, opts = {}) {
     }
     // 파일 생성 — 실패 시 부분 생성물이 남지 않도록 폴더를 정리하지는 않는다
     // (사용자가 원인 파악 후 rm -rf 로 지우도록). 정상 흐름에서는 문제 없음.
-    const gaonjsVersion = opts.gaonjsVersion ?? detectGaonjsVersion();
+    // 결정 242: 버전 감지 실패는 fail-loud — --json 계약을 지키려 emitError 로 라우팅한다.
+    let gaonjsVersion;
+    try {
+        gaonjsVersion = opts.gaonjsVersion ?? detectGaonjsVersion();
+    }
+    catch (err) {
+        return emitError(err instanceof Error ? err.message : String(err), Date.now() - t0);
+    }
     // 결정 169: packageManager 필드 = 선택한 pm 의 corepack 핀. 항상 pnpm 을
     // 적던 옛 관례는 --pm yarn 시 yarn 1.22 corepack 이 install 을 거부시켰다.
     const files = renderProjectFiles({
@@ -298,7 +313,8 @@ export async function runNewCommand(name, opts = {}) {
     lines.push('');
     lines.push('  다음 단계:');
     lines.push(`   1) cd ${name}`);
-    lines.push('   2) cp .env.example .env       # 환경 변수 편집');
+    // 결정 198: .env 는 스캐폴드가 이미 생성한다(.env.example 사본) — cp 재안내는 모순.
+    lines.push('   2) .env 편집                   # 이미 생성됨(.env.example 사본) · 필요한 값만 수정');
     lines.push('   3) gaon dev                    # Docker + 타입 브리지 + serve 통합');
     lines.push('   4) http://localhost:3000       # 홈 페이지 확인 (60초 실측 · v0.15 §13.5 M9)');
     lines.push('');

package/dist/db/diff.js

@@ -2,21 +2,9 @@
 //
 // 순수 diff — 아무것도 실행하지 않는다(SQL 만 출력). computeMigration 이
 // 방언별 up/down 을 이미 만든다(@gaonjs/data). 이 함수는 배선·표현 담당.
-import { computeMigration } from '@gaonjs/data';
+import { computeMigration, summarizeOp } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
 import { listMigrationFiles } from './replay.js';
-function opSummary(op) {
-    switch (op.kind) {
-        case 'createTable':
-            return { kind: op.kind, table: op.table.name };
-        case 'dropTable':
-            return { kind: op.kind, table: op.name };
-        case 'addColumn':
-        case 'dropColumn':
-        case 'alterColumn':
-            return { kind: op.kind, table: op.table, column: op.column };
-    }
-}
 /**
  * `gaon db diff` — 커넥션 대비 스키마 diff 를 계산해 텍스트·JSON 을 낳는다.
  * 아무것도 적용하지 않는다. exitCode 는 항상 0(변경 없음도 성공 · CI 에서
@@ -30,7 +18,7 @@ export async function runDbDiff(opts) {
     });
     try {
         const plan = await computeMigration(target.db, target.tables, target.dialect);
-        const ops = plan.ops.map(opSummary);
+        const ops = plan.ops.map(summarizeOp);
         // diff 는 스키마↔DB 차이만 미리 보여준다(적용 X). db/migrations/*.ts 는
         // migrate 의 replay 단계가 실제로 실행한다(§4.8) — 여기선 목록만 참고로 싣는다.
         const migrationFiles = listMigrationFiles(opts.cwd).map((f) => `db/migrations/${f}`);

package/dist/db/migrate.js

@@ -13,20 +13,23 @@
 // 트랜잭션: postgres 는 트랜잭셔널 DDL 이라 각 단계가 원자적. mysql/mariadb 는
 // DDL 이 autocommit 이라 순차 실행하고 이력만 남긴다(§4.5 방언 차이).
 import { sql } from 'kysely';
-import { computeMigration, renderUp, renderDown } from '@gaonjs/data';
+import { computeMigration, renderUp, renderDown, summarizeOp, DEFERRED_DROP_KINDS } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
 import { ensureJournal, journalExists, recordEntry } from './journal.js';
 import { listMigrationFiles, replayPending, rollbackLast } from './replay.js';
-function opSummary(op) {
+/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용. */
+function describeDeferred(op) {
     switch (op.kind) {
-        case 'createTable':
-            return { kind: op.kind, table: op.table.name };
-        case 'dropTable':
-            return { kind: op.kind, table: op.name };
-        case 'addColumn':
-        case 'dropColumn':
-        case 'alterColumn':
-            return { kind: op.kind, table: op.table, column: op.column };
+        case 'dropUnique':
+            return `unique(${op.name}: ${op.columns.join(', ')})`;
+        case 'dropIndex':
+            return `index(${op.name})`;
+        case 'dropCheck':
+            return `check(${op.name})`;
+        case 'dropDefault':
+            return `default(${op.table}.${op.column})`;
+        default:
+            return op.kind;
     }
 }
 /** 배치 식별자 — 초 단위 epoch + 적용 문수. 사람도 읽고 정렬도 된다. */
@@ -55,24 +58,31 @@ export async function runDbMigrate(opts) {
             dryRun: opts.dryRun,
         });
         // 2) schema-diff — replay 이후 상태를 다시 읽어 나머지를 계산.
-        // 합성형(결정 39): migrate 는 스키마에 없는 테이블을 **자동 DROP 하지 않는다**
-        // — replay(파일 마이그)가 만든 테이블·외부 테이블을 보호한다. 테이블 제거는
-        // 손작성 마이그(down 포함)로 한다. dropTable 은 'gaon db diff' 가 계속 보여준다.
+        // 합성형(결정 39·220): migrate 는 **drop 계열(테이블·unique·index·check·default 제거)을
+        // 자동 적용하지 않는다** — replay 가 만든/외부 객체·수동 추가한 제약을 보호한다. 제거는
+        // 손작성 마이그로 하고, 'gaon db diff' 가 계속 보여준다(조용히 넘어가지 않는다). ADD·SET
+        // (unique·index·check·default 추가)은 자동 적용해 "조용한 no-op"(결정 220 배경)을 없앤다.
         const full = await computeMigration(target.db, target.tables, target.dialect);
         const droppedTables = full.ops
             .filter((o) => o.kind === 'dropTable')
             .map((o) => o.name);
-        const schemaOps = full.ops.filter((o) => o.kind !== 'dropTable');
+        const deferredDrops = full.ops.filter((o) => o.kind !== 'dropTable' && DEFERRED_DROP_KINDS.has(o.kind));
+        const schemaOps = full.ops.filter((o) => !DEFERRED_DROP_KINDS.has(o.kind));
         const plan = {
             ops: schemaOps,
             up: renderUp(schemaOps, target.dialect),
             down: renderDown(schemaOps, target.dialect),
         };
-        const ops = plan.ops.map(opSummary);
-        const dropNote = droppedTables.length > 0
+        const ops = plan.ops.map(summarizeOp);
+        const tableDropNote = droppedTables.length > 0
             ? `  ℹ 스키마에 없는 테이블 ${droppedTables.length}개는 자동 DROP 하지 않았습니다: ${droppedTables.join(', ')}\n` +
                 `    → 제거하려면 손작성 마이그(down 포함)를 쓰거나, 'gaon db diff' 로 계획을 확인하세요.`
             : '';
+        const auxDropNote = deferredDrops.length > 0
+            ? `  ℹ 스키마에서 사라진 제약·인덱스·기본값 ${deferredDrops.length}개는 자동 제거하지 않았습니다: ${deferredDrops.map(describeDeferred).join(', ')}\n` +
+                `    → 제거하려면 'gaon db diff' 로 down SQL 을 확인해 손작성 마이그로 적용하세요.`
+            : '';
+        const dropNote = [tableDropNote, auxDropNote].filter(Boolean).join('\n');
         const replayLine = replay.applied.length > 0
             ? `  [${opts.dbKey}] 마이그레이션 파일 ${replay.applied.length}개 실행: ${replay.applied.join(', ')}`
             : replay.pending.length > 0 && opts.dryRun
@@ -85,6 +95,7 @@ export async function runDbMigrate(opts) {
             pendingMigrations: replay.pending,
             migrationFiles: replay.all,
             skippedDropTables: droppedTables,
+            skippedDrops: deferredDrops.map(summarizeOp),
         };
         const prefixLines = (body) => (replayLine ? replayLine + '\n' : '') + (dropNote ? dropNote + '\n' : '') + body;
         // schema 변경이 없다 — replay 만 있었을 수 있다. 성공으로 취급.

package/dist/doctor/dependency-direction.d.ts

@@ -4,7 +4,7 @@ interface ImportUse {
     readonly typeOnly: boolean;
     readonly resolvedAbs: string;
 }
-/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점). */
+/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점 · .ts·.vue 공통). */
 export declare function extractRelativeImports(file: string, source: string): ImportUse[];
 /** 프로젝트 전체 의존 방향 검사. */
 export declare function checkDependencyDirection(cwd: string): Promise<RuleReport>;

package/dist/doctor/dependency-direction.js

@@ -13,9 +13,37 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative, resolve, dirname } from 'node:path';
 import ts from 'typescript';
-/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점). */
+/**
+ * .vue SFC 를 파싱용 TS 소스로 바꾼다. `<script>`·`<script setup>` 블록 안
+ * 텍스트만 남기고, 나머지(`<template>`·`<style>`·태그 자체)는 공백/개행으로
+ * 치환해 **원본과 동일한 줄·칸 위치를 보존**한다 — 위반 line 번호가 .vue 파일
+ * 기준으로 정확히 찍히게(§7.5.3). script 밖에는 import 가 없으므로 파싱에서
+ * 자연히 사라진다. 두 블록(일반+setup)이 다 있어도 각자 제자리에 남는다.
+ */
+function vueToTsPreservingLines(source) {
+    const chars = source.split('');
+    const keep = new Uint8Array(source.length);
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script>/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const content = m[1] ?? '';
+        // 여는 태그 길이 = 전체 매치 − content − 닫는 태그. content 가 비거나 반복돼도 정확.
+        const start = m.index + (m[0].length - content.length - '</script>'.length);
+        for (let i = start; i < start + content.length; i++)
+            keep[i] = 1;
+    }
+    for (let i = 0; i < chars.length; i++) {
+        if (!keep[i] && chars[i] !== '\n' && chars[i] !== '\r')
+            chars[i] = ' ';
+    }
+    return chars.join('');
+}
+/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점 · .ts·.vue 공통). */
 export function extractRelativeImports(file, source) {
-    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const isVue = file.endsWith('.vue');
+    const text = isVue ? vueToTsPreservingLines(source) : source;
+    // .vue 는 TS 가 확장자로 스크립트 종류를 못 잡으므로 TS 로 명시한다.
+    const sf = ts.createSourceFile(file, text, ts.ScriptTarget.ES2022, true, isVue ? ts.ScriptKind.TS : undefined);
     const uses = [];
     const baseDir = dirname(file);
     const record = (specifierText, node, typeOnly) => {
@@ -180,7 +208,10 @@ async function collectSourceFiles(root, out) {
         else if (e.isFile()) {
             if (name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts'))
                 out.push(full);
-            // .vue 는 SFC — 이번 M9-E 는 .ts 만 (Vue 컴파일러 도입은 후속).
+            // .vue SFC 도 검사한다(결정 226) — <script> 블록 안 import 로 apps/shared 의
+            // app→app·shared→app 값 참조를 잡는다. 헤더 주석(.ts/.vue)과 정합.
+            else if (name.endsWith('.vue'))
+                out.push(full);
         }
     }
 }

package/dist/doctor/fixers/index.d.ts

@@ -13,5 +13,11 @@ export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
 /**
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
+ *
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
+ * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
+ * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
+ * (`fixers/capabilities.test.ts` · ALL_RULES ↔ 카탈로그 대칭).
  */
 export declare const FIXER_CAPABILITIES: readonly FixerCapability[];

package/dist/doctor/fixers/index.js

@@ -27,6 +27,12 @@ export const FIXERS = {
 /**
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
+ *
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
+ * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
+ * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
+ * (`fixers/capabilities.test.ts` · ALL_RULES ↔ 카탈로그 대칭).
  */
 export const FIXER_CAPABILITIES = [
     {
@@ -89,9 +95,79 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: "수동 · 페이지는 this.render('...') 문자열·Inertia glob 로 해석돼 import 참조 갱신만으론 부족합니다(결정 32·46 · PascalCase 로 rename 후 render 키 확인).",
     },
+    {
+        rule: 'auth-wiring',
+        hasFixer: false,
+        note: '수동 · requireAuth 를 쓰는데 app.config.ts 에 auth 미배선 — auth 블록·세션 설정은 앱 정책이라 자동 주입이 안전하지 않습니다(결정 59 · `gaon g auth` 로 스캐폴드).',
+    },
+    {
+        rule: 'ui-kit-wiring',
+        hasFixer: false,
+        note: '수동 · UI 킷 import 가 있는데 style.css 에 Tailwind 미배선 — `gaon g ui-kit` 로 킷과 style.css 를 함께 심으세요(결정 76).',
+    },
+    {
+        rule: 'route-registration',
+        hasFixer: false,
+        note: '수동 · 고아 컨트롤러의 URL·HTTP 메서드·액션은 추론할 수 없습니다 — routes.ts 에 라우트를 추가하거나 쓰지 않는 파일을 지우세요(결정 79).',
+    },
+    {
+        rule: 'static-collision',
+        hasFixer: false,
+        note: '수동 · 정적 파일이 라우트/에셋에 가려집니다 — 파일명을 바꾸거나 충돌 라우트를 조정하세요(결정 85).',
+    },
+    {
+        rule: 'method-override',
+        hasFixer: false,
+        note: '수동 · _method HTTP 스푸핑은 설계 기피 대상 — router.delete()/put() 등 실 HTTP 메서드로 전환하세요(결정 89).',
+    },
+    {
+        rule: 'csrf-wiring',
+        hasFixer: false,
+        note: '수동 · 비-GET 라우트 + session 미배선 — 세션·CSRF 배선은 앱 보안 정책이라 자동 주입이 안전하지 않습니다(결정 93).',
+    },
+    {
+        rule: 'internal-anchor',
+        hasFixer: false,
+        note: '수동 · 앱 내부 이동 <a> → <Link> 전환은 템플릿·import 편집이 필요합니다(결정 96 · 풀 리로드 방지).',
+    },
+    {
+        rule: 'pageprops-destructure',
+        hasFixer: false,
+        note: '수동 · pageProps() 구조분해는 반응성을 끊습니다 — pageProps().x 접근이나 computed 로 재작성하세요(결정 99).',
+    },
+    {
+        rule: 'async-offload',
+        hasFixer: false,
+        note: '수동 · 컨트롤러 인라인 메일·이미지·외부 HTTP 는 응답을 지연시킵니다 — 잡으로 오프로드하세요(결정 102·103 · 재설계).',
+    },
+    {
+        rule: 'page-layout-breakpoint',
+        hasFixer: false,
+        note: '수동 · 페이지가 레이아웃 브레이크포인트를 직접 다룹니다 — 레이아웃(Default.vue)으로 옮기세요(결정 107).',
+    },
+    {
+        rule: 'link-button-nesting',
+        hasFixer: false,
+        note: '수동 · <Link><Button> 중첩은 <a><button> 을 낳습니다 — Link(as) 또는 Button 하나로 재구성하세요(결정 113).',
+    },
     {
         rule: 'seal-security',
         hasFixer: true,
         note: 'seal:true 앱의 main.ts 에 @gaonjs/seal/client 정적 import + createGaonApp sealClient 전달을 자동 배선(결정 124). 방어 역전 warning 은 설계 결정이라 수동.',
     },
+    {
+        rule: 'schema-relations',
+        hasFixer: false,
+        note: '수동 · 커넥션을 가로지르는 belongsTo·관계는 도메인 재설계가 필요합니다(§4.5 · 결정 134).',
+    },
+    {
+        rule: 'no-import-meta-env',
+        hasFixer: false,
+        note: '수동 · .vue 의 import.meta.env(TS1470)는 env 접근자로 전환하세요 — 접근자 도입은 코드 편집이 필요합니다(결정 198).',
+    },
+    {
+        rule: 'locale-parity',
+        hasFixer: false,
+        note: '수동 · 로케일 간 누락 키는 각 카탈로그(locales/*.json)에 채우세요 — 번역문은 사람이 작성합니다(결정 216).',
+    },
 ];

package/dist/doctor/route-registration.d.ts

@@ -1,5 +1,13 @@
 import type { RuleReport } from './types.js';
-/** routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점). */
+/**
+ * routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점).
+ *
+ * 정규식 스캔이 아니라 TS AST 를 파싱한다(doctor 의 지배 관례 · 결정 243). 이유:
+ * 주석 안의 `'ctrl#action'` 을 참조로 오인해 진짜 고아를 놓치던(false-negative)
+ * 정규식 취약점을 제거하고, 실행 레이어 `routes()`(@gaonjs/web)의 `parseTarget`
+ * 의미(‘#’ 앞 부분·trim)를 그대로 따른다. 소스를 **실행하지 않고** 파싱만 하므로
+ * (createSourceFile) doctor 의 "routes.ts 를 실행하지 않는다" 계약은 유지된다.
+ */
 export declare function referencedControllers(routesSource: string): Set<string>;
 /** apps/ 를 훑어 라우트에 등록되지 않은(고아) 컨트롤러를 경고로 낸다. */
 export declare function checkRouteRegistration(cwd: string): Promise<RuleReport>;

package/dist/doctor/route-registration.js

@@ -7,19 +7,53 @@
 // 컨트롤러 파일은 배선을 깜빡한 흔한 실수 · §7.5.3 수리 안내).
 //
 // routes.ts 가 참조하는데 파일이 없는 반대 경우는 이미 generator 가 하드 에러로
-// 잡으므로(gaon check 중 throw) 여기서는 고아 컨트롤러만 본다. 판정은 소스 텍스트
-// 기반(가벼운 정적 검사) — routes.ts 를 실행하지 않는다.
+// 잡으므로(gaon check 중 throw) 여기서는 고아 컨트롤러만 본다. 판정은 TS AST 파싱
+// (가벼운 정적 검사 · 결정 243) — routes.ts 를 실행하지 않는다(파싱만).
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-/** routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점). */
+import ts from 'typescript';
+/** DSL 메서드 대상: r.get/post/put/patch/delete(path, 'ctrl#action'). */
+const METHOD_CALLS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+/** 문자열 리터럴(따옴표·백틱 무치환)이면 그 텍스트를, 아니면 undefined. */
+function literalText(node) {
+    if (node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)))
+        return node.text;
+    return undefined;
+}
+/**
+ * routes.ts 소스에서 참조된 컨트롤러 이름 집합을 뽑는다(단위 테스트 진입점).
+ *
+ * 정규식 스캔이 아니라 TS AST 를 파싱한다(doctor 의 지배 관례 · 결정 243). 이유:
+ * 주석 안의 `'ctrl#action'` 을 참조로 오인해 진짜 고아를 놓치던(false-negative)
+ * 정규식 취약점을 제거하고, 실행 레이어 `routes()`(@gaonjs/web)의 `parseTarget`
+ * 의미(‘#’ 앞 부분·trim)를 그대로 따른다. 소스를 **실행하지 않고** 파싱만 하므로
+ * (createSourceFile) doctor 의 "routes.ts 를 실행하지 않는다" 계약은 유지된다.
+ */
 export function referencedControllers(routesSource) {
     const names = new Set();
-    // 메서드 대상: r.get('/', 'posts#index') → 'posts'
-    for (const m of routesSource.matchAll(/['"]([A-Za-z_]\w*)#\w+['"]/g))
-        names.add(m[1]);
-    // 리소스: r.resource('posts') · r.resources('posts')
-    for (const m of routesSource.matchAll(/\bresources?\s*\(\s*['"]([A-Za-z_]\w*)['"]/g))
-        names.add(m[1]);
+    const sf = ts.createSourceFile('routes.ts', routesSource, ts.ScriptTarget.Latest, true);
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            if (method === 'resources' || method === 'resource') {
+                // r.resource('posts') · r.resources('posts') → 컨트롤러 = 첫 인자.
+                const name = literalText(node.arguments[0])?.trim();
+                if (name)
+                    names.add(name);
+            }
+            else if (METHOD_CALLS.has(method)) {
+                // r.get(path, 'ctrl#action') → 컨트롤러 = 둘째 인자의 '#' 앞부분(trim).
+                const target = literalText(node.arguments[1]);
+                if (target !== undefined) {
+                    const controller = (target.split('#')[0] ?? '').trim();
+                    if (controller)
+                        names.add(controller);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
     return names;
 }
 /** apps/ 를 훑어 라우트에 등록되지 않은(고아) 컨트롤러를 경고로 낸다. */

package/dist/doctor/types.js

@@ -1,6 +1,6 @@
 // @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 25 검사(전체 목록은 AGENTS §2.2 · doctor.ts `ALL_RULES`)가 모두 이 DoctorCheck
+// 모든 doctor 검사(정본 목록·개수는 doctor.ts `ALL_RULES` · AGENTS §2.2)가 이 DoctorCheck
 // 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
 // warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
 // errors.length > 0 이면 fail 로 판단한다.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { type DevCommandOptions } from "./commands/dev.js";
+import { type ServeCommandOptions } from "./serve.js";
 import { type DoctorRule } from "./doctor.js";
 export { startDev, resolveDevLayout, regenerateGaonOnce, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type RegenDeps, type RegenResult, } from "./dev.js";
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
@@ -70,5 +72,16 @@ export interface ParsedNewArgs {
  * npm 이 프로젝트 이름으로 오인되지 않도록(결정 167 · O-1 근본 fix).
  */
 export declare function parseNewArgs(rest: readonly string[]): ParsedNewArgs;
+/**
+ * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
+ * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른
+ * 플래그면 fail-loud, 값이 있으면 parsePort 로 1~65535 정수를 강제한다 —
+ * `Number('abc')=NaN` 이 listen 까지 조용히 흐르던 것을 파싱 경계에서 막는다(결정 240).
+ */
+export declare function readPortFlag(argv: readonly string[]): number | undefined;
+/** `gaon serve` argv → ServeCommandOptions. 포트 검증은 fail-loud(결정 240). */
+export declare function parseServeArgs(argv: readonly string[]): ServeCommandOptions;
+/** `gaon dev` argv → DevCommandOptions. 포트 검증은 fail-loud(결정 240). */
+export declare function parseDevArgs(argv: readonly string[]): DevCommandOptions;
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export declare function runCli(argv: readonly string[], opts?: RunOptions): void;

package/dist/index.js

@@ -12,6 +12,8 @@
  */
 import { MILESTONES, VERSION, HOMEPAGE, loadDotEnv } from "@gaonjs/core";
 import { runDevCommand } from "./commands/dev.js";
+import { runServeCommand } from "./serve.js";
+import { parsePort } from "./port.js";
 import { runCheckCommand } from "./commands/check.js";
 import { runGenCommand } from "./commands/gen.js";
 import { runBuildCommand } from "./commands/build.js";
@@ -22,7 +24,6 @@ import { runGenerateAuthCommand } from "./generate.js";
 import { runGenerateUiKitCommand } from "./uikit.js";
 import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
-import { runServeCommand } from "./serve.js";
 import { runWorkCommand } from "./work.js";
 import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
@@ -98,7 +99,7 @@ function renderHelp(version = VERSION) {
         "    gaon new <name>    새 프로젝트 스캐폴드 (파일 → 설치 → git · --skip-install · --skip-git · --package-manager <pnpm|npm|yarn>)",
         "    gaon dev           개발 스택 통합 (Docker · .gaon · serve · work · hub · tsc/vue-tsc · 재시작 워처)",
         "    gaon dev --stop-docker  Ctrl+C 시 Docker Compose 도 down",
-        "    gaon dev --no-watch|--no-tsc|--no-vue-tsc|--no-docker|--no-work|--no-hub  개별 debug 옵션",
+        "    gaon dev --no-watch|--no-tsc|--no-vue-tsc|--no-docker|--no-vite|--no-work|--no-hub  개별 debug 옵션",
         "    gaon dev --port <n> --host <h>  serve 리슨 지정",
         "    gaon dev --json    통합 콘솔을 JSON 라인으로 출력(자동화)",
         "    gaon serve         웹 서버 부팅 (gaon.config.ts 자동 배선 · Fastify listen)",
@@ -109,7 +110,7 @@ function renderHelp(version = VERSION) {
         "    gaon build         멀티 앱 프론트 프로덕션 빌드 (gaon gen + apps/* 순회 · 앱별 dist/<앱>·base=/<앱>/ · --json)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (테스트 DB <db>_test 자동 생성·마이그레이션 후 vitest · --scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (27 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지)",
+        `    gaon doctor        정적 검사 (${ALL_RULES.length} 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트·Link>Button 중첩·seal 클라 배선·보안 역전·§4.5 관계·import.meta.env·로케일 커버리지)`,
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -196,6 +197,61 @@ export function parseNewArgs(rest) {
     }
     return { name, unknownPm: pmRaw === undefined || pmRaw === "" ? undefined : pmRaw };
 }
+/**
+ * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
+ * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른
+ * 플래그면 fail-loud, 값이 있으면 parsePort 로 1~65535 정수를 강제한다 —
+ * `Number('abc')=NaN` 이 listen 까지 조용히 흐르던 것을 파싱 경계에서 막는다(결정 240).
+ */
+export function readPortFlag(argv) {
+    const idx = argv.indexOf("--port");
+    if (idx < 0)
+        return undefined;
+    const raw = argv[idx + 1];
+    if (raw === undefined || raw.startsWith("-")) {
+        throw new Error("--port 값이 없습니다.\n" +
+            "  → 예: gaon serve --port 3000 (1~65535 정수). 지정하지 않으면 기본 포트를 씁니다.");
+    }
+    return parsePort(raw, "--port");
+}
+/** `gaon serve` argv → ServeCommandOptions. 포트 검증은 fail-loud(결정 240). */
+export function parseServeArgs(argv) {
+    const hostIdx = argv.indexOf("--host");
+    const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+    const workersIdx = argv.indexOf("--workers");
+    // --workers <n|auto>: node:cluster 다중화(결정 84). env WEB_CONCURRENCY 도 가능.
+    const workersRaw = workersIdx >= 0 ? argv[workersIdx + 1] : undefined;
+    const workers = workersRaw === "auto" ? "auto" : workersRaw !== undefined ? Number(workersRaw) : undefined;
+    return {
+        json: argv.includes("--json"),
+        port: readPortFlag(argv),
+        host,
+        workers,
+        // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식 serve 에 넘긴다(결정 69).
+        dev: argv.includes("--dev"),
+    };
+}
+/** `gaon dev` argv → DevCommandOptions. 포트 검증은 fail-loud(결정 240). */
+export function parseDevArgs(argv) {
+    const hostIdx = argv.indexOf("--host");
+    const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
+    return {
+        json: argv.includes("--json"),
+        stopDocker: argv.includes("--stop-docker"),
+        noWatch: argv.includes("--no-watch"),
+        noTsc: argv.includes("--no-tsc"),
+        noVueTsc: argv.includes("--no-vue-tsc"),
+        noDocker: argv.includes("--no-docker"),
+        // --no-vite: 프론트 watch 빌드(vite build --watch) 끄기(결정 239). vite.ts 안내가
+        // 이 플래그를 광고했으나 파싱이 없어 조용히 무시되던 드리프트를 닫는다.
+        noVite: argv.includes("--no-vite"),
+        noWork: argv.includes("--no-work"),
+        noHub: argv.includes("--no-hub"),
+        timestamp: argv.includes("--timestamp"),
+        port: readPortFlag(argv),
+        host,
+    };
+}
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export function runCli(argv, opts = {}) {
     const version = opts.version ?? VERSION;
@@ -212,23 +268,17 @@ export function runCli(argv, opts = {}) {
     // (serve·work·hub → tsc → 워처 → Docker[--stop-docker 시]).
     // 개별 debug 옵션은 --no-watch / --no-tsc / --no-vue-tsc / --no-docker / --no-work / --no-hub.
     if (argv[0] === "dev") {
-        const portIdx = argv.indexOf("--port");
-        const hostIdx = argv.indexOf("--host");
-        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
-        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
-        void runDevCommand({
-            json: argv.includes("--json"),
-            stopDocker: argv.includes("--stop-docker"),
-            noWatch: argv.includes("--no-watch"),
-            noTsc: argv.includes("--no-tsc"),
-            noVueTsc: argv.includes("--no-vue-tsc"),
-            noDocker: argv.includes("--no-docker"),
-            noWork: argv.includes("--no-work"),
-            noHub: argv.includes("--no-hub"),
-            timestamp: argv.includes("--timestamp"),
-            port,
-            host,
-        }).catch((err) => {
+        let devOpts;
+        try {
+            devOpts = parseDevArgs(argv);
+        }
+        catch (err) {
+            // 포트 등 인자 파싱 오류는 부팅 전에 즉시 알린다(결정 240 · fail-loud).
+            process.stderr.write(`  ✗ gaon dev: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        void runDevCommand(devOpts).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon dev 실패: ${msg}\n`);
             process.exitCode = 1;
@@ -237,17 +287,17 @@ export function runCli(argv, opts = {}) {
     }
     // `gaon serve` — 웹 서버 부팅(§7 · M9-A). gaon.config.ts 자동 배선 후 listen.
     if (argv[0] === "serve") {
-        const portIdx = argv.indexOf("--port");
-        const hostIdx = argv.indexOf("--host");
-        const workersIdx = argv.indexOf("--workers");
-        const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
-        const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
-        // --workers <n|auto>: node:cluster 다중화(결정 84). env WEB_CONCURRENCY 도 가능.
-        const workersRaw = workersIdx >= 0 ? argv[workersIdx + 1] : undefined;
-        const workers = workersRaw === "auto" ? "auto" : workersRaw !== undefined ? Number(workersRaw) : undefined;
-        // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식
-        // serve 에 넘긴다(결정 69 · dev-only by construction).
-        void runServeCommand({ json: argv.includes("--json"), port, host, workers, dev: argv.includes("--dev") }).catch((err) => {
+        let serveOpts;
+        try {
+            serveOpts = parseServeArgs(argv);
+        }
+        catch (err) {
+            // 포트 등 인자 파싱 오류는 부팅 전에 즉시 알린다(결정 240 · fail-loud).
+            process.stderr.write(`  ✗ gaon serve: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        void runServeCommand(serveOpts).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
             process.exitCode = 1;

package/dist/port.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 포트 문자열을 1~65535 정수로 검증한다. 유효하지 않으면 throw.
+ * @param raw 검증할 값(플래그/ env 에서 온 문자열). 반드시 존재하는 값이어야 한다.
+ * @param source 에러 문맥 라벨(예 `--port` · `env PORT`).
+ */
+export declare function parsePort(raw: string, source: string): number;

package/dist/port.js

@@ -0,0 +1,21 @@
+// @gaonjs/cli · 포트 파싱/검증 (감사 P2 D3 · 결정 240)
+//
+// `--port <n>` (serve·dev)·env PORT 를 1~65535 정수로만 받는다. 비숫자·
+// 범위 밖은 조용한 NaN 전파(Fastify listen 이 알 수 없는 포트로 뜨거나
+// 실패) 대신 즉시 throw 한다 — fail-loud(§7.5.3 · 에러 = 수리 안내서).
+//
+// 미지정(플래그·env 부재)은 검증 대상이 아니다 — 호출부가 기본 포트로
+// 폴백한다. 검증은 "값이 주어졌는데 유효하지 않을 때" 만 개입한다.
+/**
+ * 포트 문자열을 1~65535 정수로 검증한다. 유효하지 않으면 throw.
+ * @param raw 검증할 값(플래그/ env 에서 온 문자열). 반드시 존재하는 값이어야 한다.
+ * @param source 에러 문맥 라벨(예 `--port` · `env PORT`).
+ */
+export function parsePort(raw, source) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new Error(`유효하지 않은 포트(${source}): '${raw}'.\n` +
+            `  → 포트는 1~65535 사이의 정수여야 합니다(예: 3000). 지정하지 않으면 기본 포트를 씁니다.`);
+    }
+    return n;
+}

package/dist/serve.js

@@ -18,6 +18,7 @@ import { availableParallelism } from 'node:os';
 import { loadDotEnv } from '@gaonjs/core';
 import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
+import { parsePort } from './port.js';
 import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
 /**
  * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
@@ -135,9 +136,10 @@ export async function runServeCommand(opts = {}) {
     const wired = await wireGaon(config, cwd);
     emit({ kind: 'starting', configPath, apps: wired.apps.map((a) => a.name) });
     const host = opts.host ?? config.web?.host ?? '0.0.0.0';
-    const port = opts.port ??
-        config.web?.port ??
-        (process.env.PORT ? Number(process.env.PORT) : 3000);
+    // opts.port(프로그램적)는 검증하지 않는다 — port:0(임의 포트) 같은 정당한 값이 있다.
+    // env PORT 는 사용자 입력이라 비숫자면 NaN 대신 fail-loud(결정 240 · §7.5.3).
+    const envPort = process.env.PORT != null && process.env.PORT !== '' ? parsePort(process.env.PORT, 'env PORT') : undefined;
+    const port = opts.port ?? config.web?.port ?? envPort ?? 3000;
     // dev 전용 진단 라우트(결정 69). listen 전에 등록한다 — 운영 serve 는
     // opts.dev 가 없어 등록되지 않으므로 /_gaon/health 는 production 에 없다.
     // wired.app 은 여기서 FastifyInstance 로 해상되므로(cli 는 fastify 타입을

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

@@ -1,4 +1,4 @@
-# {{PROJECT_NAME}} 환경 변수 — cp .env.example .env 후 편집.
+# {{PROJECT_NAME}} 환경 변수 — gaon new 가 .env 로 자동 복제(결정 198). 값만 채워 쓰세요.
 # gaon.config.ts 의 env('KEY') 로 참조된다. gaon dev · gaon serve 가 자동 로드.
 
 # DB — docker-compose.yaml 의 postgres 서비스와 정합.

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

@@ -76,8 +76,9 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
    `router.delete(...)` 등). REST + `fetch()` 는 **API 앱(JWT) 전용**.
 7. **한 액션은 한 종류 응답만** (render 또는 JSON 또는 redirect —
    혼용 금지 · doctor response-mixing).
-8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`
-   는 `gaon check`/`gaon dev` 가 재생성한다.
+8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`·
+   `messages.d.ts`(3축 · `locales/` 있을 때 · 결정 158) 는 `gaon check`/
+   `gaon dev` 가 재생성한다.
 
 ### 2.1 파일 네이밍 표 (2026-07-24 승인 · 벤치마크 R1 실측 고정)
 

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

@@ -77,7 +77,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 │  └─ composables/                shared 컴포저블 (인자로만 · E-5)
 ├─ gaon.config.ts                 루트 설정 (DB · Redis · NATS · ...)
 ├─ docker-compose.yaml            개발 인프라 (gaon dev 자동 기동)
-├─ .env.example                   env 템플릿 (cp .env.example .env)
+├─ .env.example                   env 템플릿 (gaon new 가 .env 로 자동 복제 · 결정 198)
 └─ package.json                   개발자는 gaonjs 하나만 설치
 ```
 
@@ -85,7 +85,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
-gaon doctor                       # 정적 검사 25종 (상세 AGENTS §2.2)
+gaon doctor                       # 정적 검사 27종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

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

@@ -256,6 +256,11 @@ wall-clock 으로 매치한다(`new Date()` 로컬 시·분·요일). v1 은 **
 타임존으로 띄운다(예: `TZ=Asia/Seoul gaon work`). 여러 인스턴스는 같은 TZ 로
 맞춘다(리더가 어느 인스턴스든 같은 wall-clock 을 봐야 한다).
 
+`gaon.config.ts` 의 `timezone` 을 두면 `gaon work`(부팅 시 wireDomain)가 그
+값을 `process.env.TZ` 로 세팅한다 — 이 경우 **config.timezone 이 런치 `TZ`
+환경변수보다 우선**한다(결정 230). 앱 전역에 한 타임존을 못박는 One Way 로,
+serve·work 가 같은 wall-clock 을 보게 하려면 런치별 `TZ` 대신 config 를 쓴다.
+
 #### 중첩 방지 (결정 202)
 
 스케줄러는 매 주기 **발행만** 한다(§7 리더). 한 주기보다 오래 걸리는 잡이

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

@@ -348,7 +348,14 @@ const rows = await Post.query()
   대상을 **에러**로 잡는다(배포 후 raw postgres 에러 대신 `gaon doctor` 에서).
   커넥션 키 등록 정합은 **connections** 검사가 본다.
 - **`service()` 트랜잭션은 단일 커넥션에서만 원자적** — Gaon 은 분산
-  트랜잭션을 흉내 내지 않는다(§9 정본).
+  트랜잭션을 흉내 내지 않는다(§9 정본). 열린 트랜잭션 안에서 다른
+  커넥션에 **쓰기**(create·update·delete)를 하면 **런타임에 throw**된다
+  (조용한 부분 커밋 방지 · fail-closed · 결정 221). **읽기는 예외**(다른
+  커넥션 조회는 자유). 커넥션 간 쓰기는 아래처럼 커밋 뒤 `afterCommit`
+  으로 잇는다. 중첩 `service({ db })`·`transaction:false`·`afterCommit`
+  은 자기 경계라 정상이다. (한계: model·`Post.query()`·`getConnection()`
+  쓰기는 가드가 잡지만, `kysely` 에서 직접 import 한 `sql``` raw SQL 쓰기는
+  못 잡는다 — 크로스커넥션 raw 쓰기는 직접 피한다.)
 - **마이그레이션은 전 커넥션에 걸린다** — `gaon db migrate`(인자 없음)는 등록된
   **모든** 커넥션을 순회 적용한다(결정 139 · One Way — 커넥션 하나를 잊어 빈 채
   배포하는 사고 방지). 한 커넥션만 좁히려면 `gaon db migrate --db legacy`.
@@ -465,11 +472,14 @@ export const Post = model(posts, {
 })
 ```
 
-- **여러 모델을 조합하는 읽기 질의도 이름을 붙인다 (§5.3 읽기 규칙 · 결정 114).**
+- **여러 모델을 조합하는 읽기 질의도 이름을 붙인다 (§5.3 읽기 규칙 · 결정 114·228).**
   검색·태그 필터처럼 여러 모델/서브쿼리를 엮는 읽기는 컨트롤러에 인라인 조립하지
-  않는다 — 주 모델이 분명하면 **모델 정적 메서드(스코프)**, 대등한 조합이면
-  `domain/services/` 로 이름을 붙인다. 컨트롤러에 허용되는 쿼리는 **스코프 체인
-  한 줄**까지다(`await Post.published().latest().limit(20).all()`).
+  않는다. **다중 컬럼 검색(whereAny)만이면 스코프**로 이름 붙인다(아래 ✅). 그러나
+  **`join()` 이 끼는 조합(관계·태그를 조인으로 좁히는 읽기)은 스코프에 못 담는다** —
+  `join()` 은 `JoinChain` 을 반환하는데 스코프 함수(ScopeFn)는 `Chain` 반환을 요구해
+  타입이 안 맞는다(`Chain` 에 `JoinChain` 대입 = TS2322). 이때 정본은 **`domain/services/`
+  에 이름 붙인 서비스**다(결정 228). 컨트롤러에 허용되는 쿼리는 **스코프/서비스 호출
+  한 줄**까지다(`await Post.searchPublished(term).latest().all()` · `await searchPostsByTag(..)`).
   ```ts
   // ❌ 컨트롤러 인라인 조립 (검색 교집합을 컨트롤러가 조립)
   //   const ids = await Post.where('title','ilike',p).orWhere('body','ilike',p).pluck('id')
@@ -484,6 +494,20 @@ export const Post = model(posts, {
   }
   // 컨트롤러: const rows = await Post.searchPublished(term).latest().all()
   ```
+  **조인이 끼는 조합(태그 필터 + 검색)은 서비스로** — 스코프는 타입 불가(결정 228):
+  ```ts
+  // domain/services/searchPostsByTag.ts — join 은 스코프에 못 담아 서비스가 정본.
+  export async function searchPostsByTag(input: { q?: string; tagId: string; page?: number }) {
+    const term = String(input.q ?? '').trim()
+    return await Post
+      .join('posts_tags', 'posts_tags.postId', 'posts.id') // 태그 필터
+      .where('posts_tags.tagId', '=', BigInt(input.tagId))
+      .where('published', '=', true)
+      .whereAny(['title', 'body'], 'ilike', `%${term}%`)    // 검색(괄호로 묶임)
+      .paginate(input.page ?? 1, 20)
+  }
+  // 컨트롤러 index 는 위임만: const result = await searchPostsByTag({ q, tagId, page })
+  ```
 
 ### 8.1 스키마 파생 폼 — `Model.form` · `Model.form.pick()` (결정 104)
 
@@ -662,6 +686,24 @@ diff/migrate/status/seed 는 `--db` 를 생략하면 **등록된 전 커넥션
   테이블 보호 · 자동 apply 의 데이터 손실 배제). 테이블 제거는 손작성 마이그의
   `down`(또는 명시적 마이그)으로 한다. `gaon db diff` 는 dropTable 을 계속
   미리 보여주고, migrate 는 건너뛴 테이블을 크게 알린다(조용한 무시 방지).
+- **스키마 diff 는 컬럼 타입·널뿐 아니라 제약·인덱스·기본값 변경도 잡는다**
+  (결정 220). 기존 테이블 컬럼에 `.unique()`·`.index()`·`.default()`·`.check()`
+  추가나 `t.enum([...])` 값 목록 변경을 하면 diff 가 감지해 **추가(ADD·SET)는
+  migrate 가 자동 적용**한다(예: `email` 에 `.unique()` 추가 → `ADD CONSTRAINT
+  … UNIQUE` 생성). **제거(제약·인덱스·기본값을 스키마에서 뗌)는 자동 적용하지
+  않고** dropTable 처럼 크게 알린다 — 제거는 `gaon db diff` 의 down SQL 을 보고
+  손작성 마이그로 적용한다(수동/외부 제약 보호 · 결정 39 정합). **한계**: 임의
+  `.check(expr)` 의 **표현식만** 바꾸는 변경(같은 컬럼·같은 제약, 식만 수정)은
+  Postgres 가 표현식을 정규화해 신뢰 비교가 불가능하므로 **감지하지 못한다** —
+  이 경우 컬럼을 갈거나 손작성 마이그로 CHECK 를 drop→add 한다. (enum 값 변경과
+  제약 **추가/제거** 는 정상 감지된다.) 마찬가지로 **기본값의 값 변경** 중 일부는
+  미검출된다 — **시간 타입**(`t.datetime()`·`t.date()`·`t.time()`)의 기본값 값 변경과
+  선행 0 문자열(`'007'` 류)의 값 변경은, Postgres 가 리터럴을 재포맷·정규화해 신뢰
+  비교가 안 되므로 **존재만 비교**한다(값이 바뀌어도 no-op). 허위 diff(멱등 붕괴)보다
+  미검출(undershoot)이 안전하다는 원칙 — 값 변경이 필요하면 손작성 마이그로 `ALTER
+  COLUMN … SET DEFAULT` 를 쓴다. (기본값 **추가/제거**·스칼라(bool·정수·문자열·enum)
+  값 변경은 정상 감지된다.) 이 제약·기본값 diff 는 postgres 커넥션 기준이다
+  (mysql=legacy §4.5 는 aux introspect 미지원 → 이 diff 생략).
 - 마이그레이션은 커넥션별로 돈다(§7 · `--db <키>`).
 
 ### 10.1 시드 — `domain/seed.ts` · `seed()` (§7)

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

@@ -103,8 +103,11 @@ async function search(q: string) {
   반환하면 그 타입 그대로, render 액션이면 render props 타입이 온다.
 - **실패** — 4xx/5xx 는 예외로 던진다. 422(`ValidationError`)는
   `err.body` 에 검증 이슈가 실려 있다.
-- **CSRF** — 세션 앱은 `<meta name="csrf-token">` 값을 자동으로
-  `X-CSRF-Token` 헤더에 붙인다 (`agents/security.md`).
+- **CSRF** — 세션 앱은 상태 변경 요청(POST/PUT/PATCH/DELETE)에 CSRF 토큰을
+  자동으로 `X-CSRF-Token` 헤더에 붙인다(손수 넘길 필요 없음 · 결정 166). 정본
+  출처는 data-page 의 `props.csrf` 공유 prop(결정 116 · `useForm({ _csrf: shared.csrf })`
+  와 **같은 단일 출처**)이고, `<meta name="csrf-token">` 은 레거시 폴백이다(표준 셸은
+  안 내지만 앱이 손수 넣었으면 존중 · `packages/vue/src/api.ts` · `agents/security.md`).
 
 ### 3. bigint PK 식별자 — 컨트롤러에서 `String()` 정규화 (결정 37)
 
@@ -458,6 +461,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`) |
+| 결정 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`) |
 | 결정 198 | 클라 환경변수 접근자 `env`(gaonjs/vue · `.vue` 의 import.meta.env TS1470 회피) · VITE_* 접두만 노출·접두 제거 · `.gaon/env.d.ts`(.env 스캔) 타입 브리지 · doctor no-import-meta-env(§9) |

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

@@ -28,7 +28,7 @@ export const WelcomeMail = mail<{ name: string; email: string }>((u) => ({
 |---|---|---|
 | 정의 | `mail<T>((data) => MailMessage)` | 파일명 = 이름 |
 | 발송 | `def.deliver(data, { locale?, to? })` | 설정된 SMTP 로 보냄 |
-| 미리보기 | `def.render(data, { locale? })` | 발송 없이 메시지만(테스트·미리보기) |
+| 미리보기 | `def.render(data, { locale?, to? })` | 발송 없이 메시지만(테스트·미리보기) · `to` 는 `deliver` 와 대칭 |
 
 ### 2. 로케일 메일 — `deliver(data, { locale })` (결정 160)
 
@@ -57,6 +57,8 @@ await WelcomeMail.deliver(data, { locale: 'ja', to: 'ops@example.com' })
 ·`.env.example` 에 mail 블록이 이미 있어(결정 160) `cp .env.example .env` 후 바로 돈다.
 운영은 `SMTP_HOST`·자격증명·`SMTP_SECURE=true` 로 교체(같은 코드).
 
+- **미리보기 정본 = MailPit** 이다 — 조용히 메모리로 삼키는 `captureTransport`(in-memory 싱크)는 **프레임웍 내부 테스트 전용**이라 파사드(`gaonjs/mail`)에 노출하지 않는다(결정 238 · 프로덕션 오배선 시 무신호 유실 방지).
+
 ### 5. `gaon.config.ts` 의 `mail` 블록 (env-gated)
 
 메일러는 루트 `gaon.config.ts` 의 `mail` 블록으로 배선된다 — `db`·`redis`·`nats`

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

@@ -111,6 +111,39 @@ export default controller({
 - **realtime(NATS) 미설정 앱**에서 호출하면 수리 안내와 함께 throw · **구독자 없음**이면 조용히
   아무 데도 안 간다(fire-and-forget · 예외 아님).
 
+### 2.6 특정/다중 유저 타겟 발송 (결정 227)
+
+채널 전체가 아니라 **특정 유저(들)에게만** 밀 때는 `gaonjs/async` 의
+`sendToUsers(name, userIds, data)` 를 쓴다 — `broadcast(name, data)` 와 **대칭**이되
+대상 userId 를 지정한다(`broadcast` = 전체 · `sendToUsers` = 지정 유저). `userIds` 는 한
+명(문자열)이나 여러 명(배열)이고, 대상은 세션 로그인 유저(멤버 `user:<id>`)다.
+
+```ts
+// apps/web/controllers/notifications.ts — service·job·listener 어디서든 동일
+import { controller } from 'gaonjs/web'
+import { sendToUsers } from 'gaonjs/async'
+
+export default controller({
+  async ping() {
+    // 한 명: 'notifications' 채널의 유저 42 에게만.
+    const reached = await sendToUsers('notifications', String(42), { type: 'ping' })
+    // 여러 명:
+    // await sendToUsers('notifications', ['1', '2', '3'], { type: 'announce' })
+    return { reached }               // reached = 그 채널에 접속한 대상 유저 수
+  },
+})
+```
+
+- **전달 대상** — 대상 유저의 **살아있는 연결에만** 간다. 멀티탭이면 그 유저의 **모든 연결**이
+  받고(연결별 전달), 멀티서버여도 대상이 어느 서버에 붙어 있든 받는다(각 서버가 자기 로컬
+  연결을 필터). 비대상 유저는 안 받는다.
+- **반환 = 도달한 대상 유저 수**(`Promise<number>`). 그 채널에 접속(present)한 대상 수를
+  프레즌스 권위(허브 KV)에서 센다. **대상이 전원 오프라인이면 `0` 을 정상 반환**한다 — throw
+  가 아니라 반환값으로 미도달을 알린다(조용히 삼키지 않음). 멀티탭 유저는 연결이 여럿이어도
+  present **유저** 기준이라 `1` 로 센다.
+- **아키텍처(errata E-2)** — `broadcast` 와 같은 NATS 채널 subject 를 타므로 새 연결·프로토콜이
+  없다. seal 재봉인·authorize 규칙(§2.5)도 그대로다(authorize 는 구독 시점 게이트 · 재실행 없음).
+
 ### 3. 프레즌스
 
 `ctx.presence()` 는 **전 서버의** 현재 접속자를 돌려준다. 목록의 권위는
@@ -125,6 +158,11 @@ const members = await ctx.presence()
 - **read**(`presence()`)는 KV(권위)를 직접 조회한다.
 - leave 는 best-effort 이고, 서버가 죽으면 허브가 그 서버의 멤버 전원을
   **즉시** 정리한다 (TCP `close`).
+- **멤버는 연결 단위로 refcount 된다(결정 225).** 같은 유저(`user:<id>`)가
+  멀티탭·멀티서버로 여러 연결을 열면, **살아 있는 연결이 하나라도 있는 동안
+  로스터에 유지**된다 — 탭 하나를 닫아도 이탈이 아니고, 마지막 연결이 끊길
+  때만 leave 델타가 나간다. 한 서버가 죽어도(cleanupServer) 같은 유저가 다른
+  서버에 붙어 있으면 그 유저는 남는다.
 
 ### 4. 클라이언트 (`useChannel` · 결정 87)
 
@@ -205,7 +243,8 @@ export function useRoom(roomId: number) {
 | 발화 주체 | 표면 | 쓰는 곳 |
 | --- | --- | --- |
 | 클라 메시지에 응답 | `ctx.broadcast(data)` | 채널 훅 `onMessage`(클라 메시지 필요) |
-| 서버가 단독으로 밀기 | `broadcast(name, data)` (`gaonjs/async`) | 컨트롤러·서비스·잡·리스너 (클라 메시지 없이 · 결정 126) |
+| 서버가 채널 전체로 밀기 | `broadcast(name, data)` (`gaonjs/async`) | 컨트롤러·서비스·잡·리스너 (클라 메시지 없이 · 결정 126) |
+| 서버가 특정 유저(들)에게 밀기 | `sendToUsers(name, userIds, data)` (`gaonjs/async`) | 컨트롤러·서비스·잡·리스너 (지정 유저만 · 도달 수 반환 · 결정 227) |
 
 ```ts
 // apps/web/channels/chatMessages.ts — 파일명 camelCase · 클라 메시지 응답형
@@ -251,6 +290,11 @@ export default channel({
   (E-2). NATS 는 broadcast 팬아웃 전용.
 - **서버 푸시 데이터를 `api()` 폴링으로 대체 금지** — 데이터 경로
   판단표 위반.
+- **특정 유저 발송을 `broadcast` + 클라 필터로 흉내내지 말 것** — 전체
+  broadcast 로 밀고 클라가 `if (내 id)` 로 거르면 **민감 페이로드가 전원에게
+  샌다**(클라가 버려도 이미 도달). 지정 유저는 `sendToUsers`(서버가 대상
+  연결에만 전달 · 결정 227). `sendToUsers` 는 그 **채널에 접속한** 유저만
+  대상이다 — 접속 안 한(오프라인) 유저는 `0` 도달로 반환된다.
 - **자기 자신의 join 델타** — 클라이언트는 자기 `presence:join` 델타도
   스냅샷과 별개로 받는다(멱등이라 무해). 필요하면 자기 `id` 로 필터.
 - **테스트에서 NATS·허브 목업 금지** (§9) — 실 인프라
@@ -265,6 +309,8 @@ export default channel({
 | 결정 126 | 서버 개시 `broadcast(name, data)`(`gaonjs/async`) — 컨트롤러·서비스·잡에서 클라 메시지 없이 채널 발화 · authorize 재실행 없음 · seal 재봉인 자동 |
 | 결정 154 | `useChannel` 앱 프리픽스 자동 주입 — `import.meta.env.BASE_URL`(vite base·에셋 base 단일 소스) 로 `<프리픽스>/gaon/ws/<name>` · `opts.path` 는 탈출구 · 프리픽스 앱 실시간 무한 재연결 제거(§4) |
 | 결정 207 | 허브 fail-fast(§5) — 리스는 얻고 TCP 포트 bind 실패 시 좀비 리더 대신 리스 사임 + `process.exit(1)`(F-13 fix · `onFatal` 훅으로 주입 가능) |
+| 결정 225 | 프레즌스 연결 축 refcount(§3) — 같은 멤버의 멀티탭·멀티서버 연결을 refcount 해 마지막 연결에서만 이탈 · cleanupServer 는 그 서버 연결만 회수(타서버 불간섭) |
+| 결정 227 | 특정/다중 유저 타겟 발송(§2.6) — `sendToUsers(name, userIds, data)` · `broadcast` 와 대칭 · 대상 연결에만 전달(멀티서버·멀티탭) · 도달 유저 수 반환(오프라인=0) · 수정 1 연결 추적 위에 얹음 |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

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

@@ -99,13 +99,22 @@ void createGaonApp({ pages, layouts, /* ... */ sealClient })
   네이티브 브라우저 form·정적 자산·HTML 직접 로드는 셋 다 없어 자동 면제된다.
 - **최초 문서 data-page**: 서버가 `<script data-page="app" data-gaon-sealed="1">` 로 봉인 + `<meta gaon-seal-ts>`.
   클라 `createGaonApp` 이 Inertia 마운트 **전**에 wasm 으로 개봉 → 소스 보기·개발자도구에 평문 props 미노출.
+  **봉인 대상은 sentinel 로 특정 (결정 224)**: 서버가 주입한 **진짜** data-page 만 `data-gaon-seal-target` sentinel
+  로 표시되고 봉인 정규식이 그것만 잡는다 — 스캐폴드 주석·유저 index.html 의 예시 data-page 리터럴(decoy)을 봉인하고
+  멈추던 first-match P0(진짜 data-page·props·CSRF 평문 유출)를 근본 차단한다. 봉인 후에도 평문 data-page 가 남으면
+  **렌더가 throw**(fail-closed 가드 · 조용한 유출 금지). 커스텀 rootTemplate 을 쓰더라도 data-page script 를 직접
+  만들지 말고 서버가 주입하게 둔다.
 - **WS 프레임 (결정 124 · §3.4)**: `useChannel` 이 `setWsFrameCodec`(seal 클라 `wsEncode`/`wsDecode`)로
   채널 송수신을 봉인한다. 송신 `E:<ts>:<base64>` · seal namespace 는 평문 `P:` 프레임 **거부**(requireDecrypt · 결정 121).
+  **수신은 서버·클라가 대칭 (결정 222)**: 서버 `SealWsTerminator` 도, 클라 `wsDecode` 도 `E:` 만 개봉하고 `P:`
+  평문·무prefix 프레임을 거부한다 — 클라 수신이 평문을 통과시키면(fail-open) 봉인 앱 클라가 주입된 평문을 그대로
+  소비해 봉인이 깨진다. 클라 개봉 실패는 조용히 무시하지 않고 소켓을 **4500 종료**(`useChannel` · 아래 fail-closed).
 - **자동 제외 / 옵트아웃**: 정적 자산·헬스체크·multipart 업로드 body·비대상(JSON 도 Inertia 도 아닌 HTML
   직접 로드·네이티브 form)은 **자동 제외**(사람 판단 없이 헤더 기계 판별 · 결정 125). 외부(웹훅 등)가 봉인을
   모르는 경로는 `seal: { except: ['/webhooks/*'] }`.
 - **fail-closed (403 · 결정 121)**: 봉인 강제 경로에 시그널 헤더 없이 온 요청, drift/replay/키 실패는
-  **403 SealError** — 평문 통과 절대 없음. WS 개봉 실패는 소켓 4500 종료(silent fallback 없음).
+  **403 SealError** — 평문 통과 절대 없음. WS 개봉 실패는 **서버·클라 모두 소켓 4500 종료**(결정 222 · silent
+  fallback 없음). 클라(`useChannel`)는 4500 이후 재연결하지 않는다(개봉 실패 = transient 아님 · 종단).
 
 ## 3. CSP (결정 124)
 
@@ -135,7 +144,11 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 - **알고리즘**: AES-256-GCM(12-byte nonce · 16-byte tag) + nibble-swap XOR(0x5A) + base64 · 키 유도 =
   `SHA256(hex(HMAC-SHA256(masterSecret, "domain:path:uaSlice:timestamp")))` · per-frame keying(userId 미포함).
 - **replay 방어**: AES-GCM 12-byte nonce 를 `setIfNotExists`(Redis SETNX 대응) 캐시 + timestamp drift(±60s)로
-  차단. WS 기본은 drift 윈도우(고빈도라 프레임마다 SETNX 는 비용 과다 · 엄격 nonce 는 옵션 주입).
+  차단. **HTTP 경로는 nonce 검사가 항상 배선된다 (결정 223)** — 앱이 세션 Redis 를 가지면 그걸 재사용(멀티
+  인스턴스 안전), 없으면 **in-memory 폴백(단일 인스턴스 전용)**을 쓰고 부팅 시 경고한다(nonce 검사가 조용히
+  사라지지 않는다). **in-memory 는 프로세스별 격리라 멀티 워커(`--workers`·`WEB_CONCURRENCY>1`)·멀티 서버에서
+  replay 를 완전히 막지 못하므로, 프로덕션 멀티 인스턴스는 세션 Redis 를 구성한다.** WS 기본은 drift 윈도우
+  (고빈도라 프레임마다 SETNX 는 비용 과다 · 엄격 nonce 는 옵션 주입).
 - **허브(`gaon hub`)는 손대지 않는다** — 봉인/개봉은 각 웹서버의 소켓 경계에서만. 타 서버 접속자의
   UA·ts 컨텍스트가 없어 허브가 프레임을 복호할 수 없는 것은 구조적 필연(설계상) · 허브·NATS 내부는 평문.
 
@@ -145,6 +158,8 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
   `test/integration/seal-browser-e2e.integration.test.ts`(마운트·data-page 개봉·useForm POST·api()·WS `E:` 왕복·
   평문 `P:` 거부·hidden 누출 0·**비-seal 앱 번들 무-wasm 단언**) + `seal-fullstack-e2e`(실 `gaon serve`+`gaon hub`+NATS
   경유 봉인 broadcast).
+- **배포 게이트 편입 (결정 224)**: 이 두 e2e 는 `pnpm test:runtime-e2e` 에 들어 있다 — 이전엔 어느 스크립트에도 없어
+  **red 인데도 배포를 통과**해 seal 최초 문서 data-page 평문 유출 P0 를 못 잡았다(결정 224 근본). 배포 전 반드시 green.
 - **목업 e2e 로 대체 금지.** 서버 inject·단위·wasm-parity 는 byte 호환을 잠글 뿐 "실 브라우저에서 마운트되나"를
   못 본다 — 원 wave 가 실-브라우저 e2e 를 미뤄 P0 3건(번들 불가·CSP 차단·Inertia 인터셉터 파손)을 놓친 교훈(결정 124).
 - **봉인 검증은 네트워크 날 바디로만 봐야 한다 (검증법 함정).** seal 앱에서 `page.evaluate(fetch(...))` 나 렌더된
@@ -162,8 +177,10 @@ seal 앱 응답에만 `script-src` 에 `'wasm-unsafe-eval'` 을 **자동 주입*
 5. **반쪽 봉인 금지** — "wire 전체 봉인" 기대. HTTP 만 봉인하고 WS 를 빼먹지 말 것(seal 앱 namespace 는 requireDecrypt).
 6. **비-seal 앱 번들에 wasm 유입 금지** — `@gaonjs/vue` 가 seal 을 직접 참조하면 회귀. 게이트가 무-wasm 번들을 단언한다.
 
-## 관련 결정
+## 관련 결정 번호
 
 - **결정 121** — `@gaonjs/seal` 신설(GSP 이식 · 인터셉터 설계 · 앱 토글 · WS requireDecrypt · 기각 대안 4건).
 - **결정 124** — §3.1 개정: **app-side 정적 주입**(변수 동적 import 폐기) · **wasm 표면 은닉**(불투명 함수 · domain/ua/path 를 wasm 이 확보 · 미끼 시크릿 내장) · **WS 클라 봉인**(`setWsFrameCodec`) · **seal 앱 한정 CSP** · doctor `seal-security` main.ts 배선 검사 + `seal-client-wiring` fixer · 실 브라우저 e2e 게이트 · 부수 정정(`.wasm` MIME · `session.csrf` forwarding).
 - **결정 125** — **Inertia 네비게이션 평문 P0** 수정: 봉인 대상 판별기(`isSealTarget`)에 `X-Inertia: true` 를 편입. Inertia GET 방문은 `Accept: text/html` 로 와 application/json 이 없어 자동 면제되던 탓에 응답 props 가 평문으로 새어나갔다(클라 인터셉터는 시그널을 붙였으나 서버가 봉인 안 함). 네비게이션 봉인 e2e 를 seal blocking 게이트에 편입(실 vite+chromium · wire 봉인/`?q=` 왕복 단언).
+- **결정 222** — **클라 WS 수신 fail-open P1** 수정: 클라 `wsDecode`(client.ts)가 `P:` 평문·무prefix 프레임을 throw 없이 원문 통과시켜, 서버는 requireDecrypt 로 거부하는데 클라만 주입된 평문을 소비하던 봉인 파괴. `wsDecode` 를 서버 `SealWsTerminator` 와 대칭으로 만들어 `E:` 만 개봉·`P:`/무prefix 거부. `useChannel` 은 개봉 실패를 조용히 드롭하지 않고 소켓을 **4500 종료**(서버 대칭) + 콘솔 명시 + 재연결 안 함.
+- **결정 223** — **HTTP replay Redis 없으면 조용히 off + 허위 주석 P1** 수정: `normalizeSealConfig` 이 nonceStore 없으면 `replay=null` 로 두어 nonce 검사가 사라지고 drift(±60s)만 남아 60초 내 재전송이 통과했다(`sealBridge` 주석은 "in-memory 폴백" 이라 거짓 단언 — `MemoryNonceStore` 는 export 만·미배선). HTTP replay 를 **항상 배선**한다 — Redis 있으면 재사용(멀티 인스턴스 안전), 없으면 in-memory 폴백(단일 인스턴스 전용) + 부팅 경고. **기각: 부팅 throw(옵션 A)** — 기본 배포가 워커 1(CLAUDE 규칙 6)이라 단일 인스턴스 in-memory 가 정상 경로인데 throw 는 dev·단일 인스턴스 seal 앱을 깨고 문서(§4 "in-memory 는 dev/단일/테스트")와 상충. 폴백+경고가 비파괴적·정본 정합.

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

@@ -27,6 +27,11 @@
   `expiresIn`(초)로 만료를 조절한다. 존재하지 않는 `Attachment.urlFor` 같은
   헬퍼를 만들지 말 것 — 표면은 `Storage.url()` 뿐이다.
 - **키는 경로**다(`avatars/${user.id}.png`). 앞 슬래시는 정규화된다.
+- **`contentType` 은 어댑터별로 다르게 반영된다**(결정 236): `s3` 는 객체
+  메타데이터로 저장해 다운로드·presign 시 그대로 나가고, **로컬**은 저장하지
+  않고 **서빙 시 key 확장자로 Content-Type 이 결정**된다(로컬엔 메타데이터
+  채널이 없음). 로컬에서 타입을 보장하려면 **key 에 올바른 확장자**를 쓰거나
+  s3 를 쓴다 — 조용한 무시가 아니라 명시된 관례다.
 
 ### 2. 설정 (`gaon.config.ts`)
 
@@ -63,7 +68,10 @@ storage: process.env.STORAGE_ENDPOINT
 export default controller({
   async updateAvatar() {
     const f = this.file('avatar')                     // UploadedFile | undefined
-    if (!f) return this.back().withErrors({ avatar: '파일이 필요합니다.' })
+    if (!f) {
+      this.flash('error', '파일이 필요합니다.')          // useShared().flash.error 로 표시(결정 116)
+      return this.redirect('/profile')
+    }
     const key = `avatars/${this.auth.user!.id}.png`
     await Storage.put(key, f.buffer, { contentType: f.mimetype })
     return this.redirect('/profile')

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

@@ -414,7 +414,7 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
   ```ts
   async new() {
     this.requireAuth()                          // 미인증이면 로그인으로 리다이렉트
-    return this.render('Posts/New', { csrf: this.csrfToken() })
+    return this.render('Posts/New', {})         // csrf 는 자동 주입 공유 prop — 넘기지 않는다(결정 116·117)
   }
   async create() {
     const user = this.requireAuth()             // 반환값을 바로 쓴다
@@ -438,7 +438,8 @@ const ok = await verifyPassword(plain, user.passwordDigest) // Promise<boolean>
     const { email, password } = this.params({ _row: {} as { email: string; password: string } })
     const user = await User.where('email', '=', email).first()
     if (!user || !(await verifyPassword(password, user.passwordDigest))) {
-      return this.render('Auth/Login', { error: '이메일 또는 비밀번호가 올바르지 않습니다.', csrf: this.csrfToken() })
+      // csrf 는 자동 주입 공유 prop 이므로 컨트롤러가 넘기지 않는다(결정 116·117)
+      return this.render('Auth/Login', { error: '이메일 또는 비밀번호가 올바르지 않습니다.' })
     }
     this.auth.login(user)                       // 세션 확정
     return this.redirect('/dashboard')

package/dist/templates/project/apps/web/index.html.tpl

@@ -9,9 +9,9 @@
     <!--
       Vite 개발 서버가 이 index.html 을 서빙한다(dev). 운영 빌드는
       vite build 가 이 파일을 진입점 삼아 프로덕션 번들을 만든다.
-      Fastify(gaonjs/web) 는 초기 SPA 응답 셸에서 빈 <div id="app"></div> 와
-      함께 초기 페이지 객체를 <script type="application/json" data-page="app">…</script>
-      엘리먼트로 내려보낸다(data-page 는 div 속성이 아니라 이 script 태그에 실린다) —
+      Fastify(gaonjs/web) 는 초기 SPA 응답 셸에서 빈 div#app 뒤에 초기 페이지 객체를
+      script[type=application/json][data-page=app] 엘리먼트로 자동 주입한다(data-page 는
+      div 속성이 아니라 이 script 태그에 실린다 · 여기에 직접 쓰지 말 것 — 서버가 넣는다).
       개발과 운영이 같은 셸이다.
     -->
     <div id="app"></div>

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

@@ -19,7 +19,6 @@
   },
   "dependencies": {
     "gaonjs": "{{GAONJS_VERSION}}",
-    "@inertiajs/vue3": "^3.6.0",
     "vue": "^3.5.0"
   },
   "devDependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "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/config": "0.16.0",
-    "@gaonjs/async": "0.13.0",
-    "@gaonjs/mail": "0.2.1",
-    "@gaonjs/core": "0.2.2",
-    "@gaonjs/i18n": "0.2.1",
-    "@gaonjs/data": "0.16.1",
-    "@gaonjs/web": "0.19.0"
+    "@gaonjs/async": "0.15.0",
+    "@gaonjs/config": "0.17.0",
+    "@gaonjs/core": "0.2.3",
+    "@gaonjs/data": "0.17.0",
+    "@gaonjs/mail": "0.3.0",
+    "@gaonjs/i18n": "0.2.2",
+    "@gaonjs/web": "0.19.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""