@gaonjs/cli 0.60.0 → 0.62.0

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'agents-docs-stale' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return' | 'channel-collision' | 'channel-instance-authorize' | 'dotenv-node-env' | 'page-fetch' | 'i18n-layout' | 'i18n-app-scope';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -25,6 +25,8 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkI18nLayout } from './doctor/i18n-layout.js';
+export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -33,7 +35,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 32종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 32 검사를 조립한다:
+ * 33 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -30,10 +30,13 @@
  * 25) schema-relations (§4.5 · 결정 134 · 커넥션 가로지르는 belongsTo·관계 · 대상 부재 error)
  * 26) no-import-meta-env (결정 198 · F-9 ② · `.vue` 의 import.meta.env = TS1470 → env 접근자 안내 error)
  * 27) locale-parity (결정 216 · 13차 W4 · 로케일 간 키 부분 누락 = fallback 조용 노출 경고)
+ * 34) i18n-layout (결정 454 · 레거시 단일 파일 = 클라 t() 불가 안내 · --fix 로 폴더 이관)
+ * 35) i18n-app-scope (결정 454 · 앱 카탈로그에 없는 클라 t() 키 = 런타임 키 노출)
  * 28) render-return (결정 340 · this.render/redirect/json 호출만 하고 return 누락 = 무신호 204 경고)
  * 29) channel-collision (§7 · 앱간 동명 채널 = 전역 subject·프레즌스 병합 error)
  * 30) channel-instance-authorize (결정 440 · authorize 없는 인스턴스 채널 = 임의 인스턴스 공개 입장 경고)
  * 31) dotenv-node-env (결정 430 · 공유 .env 의 NODE_ENV = 모드 누출 경고)
+ * 32) page-fetch (결정 453 · 세션 앱 .vue 의 내부 경로 raw fetch = CSRF 미부착 403 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -75,9 +78,12 @@ import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { checkLinkButtonNesting } from './doctor/link-button-nesting.js';
 import { checkNoImportMetaEnv } from './doctor/no-import-meta-env.js';
 import { checkLocaleParity } from './doctor/locale-parity.js';
+import { checkI18nLayout } from './doctor/i18n-layout.js';
+import { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 import { checkChannelCollision } from './doctor/channel-collision.js';
 import { checkChannelInstanceAuthorize } from './doctor/channel-instance-authorize.js';
 import { checkDotenvNodeEnv } from './doctor/dotenv-node-env.js';
+import { checkPageFetch } from './doctor/page-fetch.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -106,6 +112,8 @@ export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActio
 export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { usesLinkButtonNesting, checkLinkButtonNesting, } from './doctor/link-button-nesting.js';
 export { checkLocaleParity } from './doctor/locale-parity.js';
+export { checkI18nLayout } from './doctor/i18n-layout.js';
+export { checkI18nAppScope } from './doctor/i18n-app-scope.js';
 export { checkChannelCollision, reexportSpecifier } from './doctor/channel-collision.js';
 export { checkChannelInstanceAuthorize, declaresInstance, hasAuthorize, } from './doctor/channel-instance-authorize.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
@@ -114,7 +122,7 @@ export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, }
  * 실행할 검사 이름. 지정 없음(undefined) = 31개 모두.
  */
 /**
- * doctor 정적 검사 32종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 35종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */
@@ -151,6 +159,9 @@ export const ALL_RULES = [
     'channel-collision',
     'channel-instance-authorize',
     'dotenv-node-env',
+    'page-fetch',
+    'i18n-layout',
+    'i18n-app-scope',
 ];
 /**
  * `gaon help` 이 doctor 한 줄에 요약할 규칙별 문구(§2.2 상세는 AGENTS). 타입이
@@ -187,10 +198,13 @@ export const RULE_SUMMARIES = {
     'schema-relations': '§4.5 관계',
     'no-import-meta-env': 'import.meta.env',
     'locale-parity': '로케일 커버리지',
+    'i18n-layout': 'i18n 카탈로그 레이아웃(단일 파일 → backend/frontend 분리 안내 · 결정 454)',
+    'i18n-app-scope': '앱 경계를 넘는 클라 번역 키(그 앱 카탈로그에 없는 t() 키 · 결정 454)',
     'render-return': 'render return 누락',
     'channel-collision': '앱간 동명 채널',
     'channel-instance-authorize': '인스턴스 채널 authorize',
     'dotenv-node-env': '.env NODE_ENV',
+    'page-fetch': '세션 앱 raw fetch',
 };
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -221,10 +235,13 @@ const CHECKERS = {
     'schema-relations': checkSchemaRelations,
     'no-import-meta-env': checkNoImportMetaEnv,
     'locale-parity': checkLocaleParity,
+    'i18n-layout': checkI18nLayout,
+    'i18n-app-scope': checkI18nAppScope,
     'render-return': checkRenderReturn,
     'channel-collision': checkChannelCollision,
     'channel-instance-authorize': checkChannelInstanceAuthorize,
     'dotenv-node-env': checkDotenvNodeEnv,
+    'page-fetch': checkPageFetch,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -156,7 +156,7 @@ function renderHelp(version = VERSION) {
  * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
  */
 export function parseDoctorChecks(argv) {
-    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 32종)를 단일 출처로 쓴다 — 과거
+    // 인정 집합은 doctor.ts 의 ALL_RULES(정본 35종)를 단일 출처로 쓴다 — 과거
     // 손유지 9종 리스트가 뒤처져 --check=seal-security 같은 16종이 조용히 무시되고
     // 전체 검사로 되돌아가던 표류를 근본 차단한다(결정 168).
     const isKnown = (s) => ALL_RULES.includes(s);
@@ -177,7 +177,7 @@ export function parseDoctorChecks(argv) {
     }
     // 결정 411: 모르는 이름은 여전히 무시하되(안전 방향 — 전체 검사로 넓어짐) **조용히**
     // 넘기지 않는다. 오타 하나가 "그 검사만 돌렸다" 는 착각으로 이어지고, 전부 오타면
-    // 32종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
+    // 35종 전체가 돌아가 선택 실행 의도가 통째로 사라진다.
     if (unknown.length > 0) {
         process.stderr.write(`  ! 알 수 없는 검사 이름 무시: ${unknown.join(", ")}\n` +
             `    → 지원 이름은 gaon doctor --json 의 rule 값 또는 gaon help 참고` +
@@ -497,7 +497,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 32 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 33 검사 · ALL_RULES 단일 출처). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {

package/dist/messages-gen.d.ts

@@ -1,6 +1,30 @@
+import { type LocaleResources } from '@gaonjs/i18n';
+/** 메시지 축이 카탈로그 모듈을 낼 앱(결정 454). dev 레이아웃이 만들어 넘긴다. */
+export interface MessagesApp {
+    readonly name: string;
+    /** apps/<앱>/locales (앱 전용 frontend 카탈로그 · 없어도 된다). */
+    readonly localesDir: string;
+    /** apps/<앱>/.gaon/messages.catalog.ts */
+    readonly catalogOut: string;
+}
 /**
- * locales/ 카탈로그에서 .gaon/messages.d.ts 를 생성한다. 카탈로그가 없거나 비어
- * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
- * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ * locales/ 카탈로그에서 `.gaon/messages.d.ts`(두 갈래)와 앱별 카탈로그 값 모듈을 생성한다.
+ * 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를 비운 채로 둬 키가 string 폴백 —
+ * i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
-export declare function generateMessagesDts(localesDir: string, out: string, baseLng?: string): boolean;
+export declare function generateMessagesDts(localesDir: string, out: string, baseLng?: string, apps?: readonly MessagesApp[]): boolean;
+interface CatalogInput {
+    readonly localesDir: string;
+    readonly app: MessagesApp;
+    readonly appLocales: LocaleResources;
+    readonly frontendLangs: readonly string[];
+    readonly fallbackLng: string;
+}
+/**
+ * 결정 454: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **공용 frontend + 앱 카탈로그**를
+ * 동적 import 해 vite 가 로케일별 해시 청크(.js)로 쪼갠다 — `/assets/*` immutable 캐시 대상이며
+ * `text/javascript` 라 seal 봉인 대상(application/json)에서 자연 면제된다.
+ * 생성 여부를 돌려준다(프론트 카탈로그가 없으면 false + 스테일 제거).
+ */
+export declare function generateMessagesCatalog(input: CatalogInput): boolean;
+export {};

package/dist/messages-gen.js

@@ -1,35 +1,155 @@
-// @gaonjs/cli · .gaon/messages.d.ts 생성기 (결정 158 · 13차 W2)
+// @gaonjs/cli · .gaon 메시지 축 생성기 (결정 158 · 13차 W2 · 결정 454)
 //
-// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 세 번째 축(메시지). locales/
-// 카탈로그의 키를 유니온 타입으로 물성화해, t('key') 의 존재하지 않는 키를 컴파일
-// 타임에 잡는다(현재는 GaonMessages 가 비어 있어 키가 string 으로 열림). 생성 파일은
-// 타입만 담는다(규칙 3). @gaonjs/i18n 의 공개 API(loadLocales·renderMessagesDts)만 쓴다.
+// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 메시지 축. 결정 454 부터 두 산출을 낸다:
+//
+//  1) `.gaon/messages.d.ts` — **두 갈래 타입 브리지**
+//     · `gaonjs/i18n`(서버) = backend ∪ frontend ∪ 앱 frontend
+//     · `gaonjs/vue`(클라)  = frontend 만(+ 키별 보간 파라미터) → 서버 전용 문구를
+//       클라에서 참조하면 컴파일 에러.
+//  2) `apps/<앱>/.gaon/messages.catalog.ts` — **앱별 값 모듈**(routes.manifest.ts 선례).
+//     그 앱의 frontend 카탈로그만 동적 import 로 묶어 vite 가 로케일별 청크로 쪼갠다.
+//     backend.json 은 입력에 아예 없다(노출 차단은 번들 경계가 물리적으로 강제).
+//
+// @gaonjs/i18n 의 공개 API(loadScopedLocales·loadAppLocales·renderMessagesDtsSplit 등)만 쓴다.
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { loadLocales, renderMessagesDts } from '@gaonjs/i18n';
+import { dirname, join, relative, sep } from 'node:path';
+import { extractParams, flattenKeys, loadAppLocales, loadScopedLocales, renderMessagesDtsSplit, withPluralBaseKeys, } from '@gaonjs/i18n';
+/** 번역 트리 두 개를 깊은 병합한다(리프 충돌은 로더가 이미 fail-loud). */
+function mergeTrees(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) {
+        const cur = out[k];
+        const isTree = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+        out[k] = isTree(cur) && isTree(v) ? mergeTrees(cur, v) : v;
+    }
+    return out;
+}
+function translationOf(res, lng) {
+    if (lng === undefined)
+        return {};
+    return res[lng]?.translation ?? {};
+}
+/** 기준 로케일 = config i18n.fallbackLng(결정 352). 없으면 정렬 첫 로케일. */
+function pickBaseLng(langs, baseLng) {
+    if (baseLng && langs.includes(baseLng))
+        return baseLng;
+    return [...langs].sort()[0];
+}
 /**
- * locales/ 카탈로그에서 .gaon/messages.d.ts 를 생성한다. 카탈로그가 없거나 비어
- * 있으면 생성하지 않는다(GaonMessages 를 비운 채로 둬 t() 키가 string 폴백 — i18n 을
- * 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ * locales/ 카탈로그에서 `.gaon/messages.d.ts`(두 갈래)와 앱별 카탈로그 값 모듈을 생성한다.
+ * 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를 비운 채로 둬 키가 string 폴백 —
+ * i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
  */
-export function generateMessagesDts(localesDir, out, baseLng) {
+export function generateMessagesDts(localesDir, out, baseLng, apps = []) {
     // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
     // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
     if (!existsSync(localesDir)) {
         if (existsSync(out))
             rmSync(out, { force: true });
+        for (const app of apps)
+            removeStale(app.catalogOut);
         return false;
     }
-    const resources = loadLocales(localesDir);
-    if (Object.keys(resources).length === 0) {
+    const scoped = loadScopedLocales(localesDir);
+    const appResources = new Map();
+    for (const app of apps)
+        appResources.set(app.name, loadAppLocales(app.localesDir));
+    const langs = new Set([...Object.keys(scoped.backend), ...Object.keys(scoped.frontend)]);
+    for (const res of appResources.values())
+        for (const lng of Object.keys(res))
+            langs.add(lng);
+    if (langs.size === 0) {
         if (existsSync(out))
             rmSync(out, { force: true });
+        for (const app of apps)
+            removeStale(app.catalogOut);
         return false;
     }
+    const base = pickBaseLng([...langs], baseLng);
+    // 클라 키 = 공용 frontend ∪ 모든 앱 frontend(결정 454 · 앱×앱 축은 타입으로 못 나눈다 —
+    // TS2717. 앱 경계는 청크 분리와 doctor `i18n-app-scope` 가 강제한다).
+    let clientTree = translationOf(scoped.frontend, base);
+    for (const res of appResources.values())
+        clientTree = mergeTrees(clientTree, translationOf(res, base));
+    const serverTree = mergeTrees(translationOf(scoped.backend, base), clientTree);
+    const clientKeys = withPluralBaseKeys(flattenKeys(clientTree));
+    const serverKeys = withPluralBaseKeys(flattenKeys(serverTree));
     mkdirSync(dirname(out), { recursive: true });
-    // 결정 352: 기준 로케일 = config i18n.fallbackLng(호출자가 정적 분석으로 전달).
-    // 이전엔 항상 알파벳순 첫 로케일이라 컴파일 보증이 fallback 체인과 다른 로케일에
-    // 정박했다(en/ko + fallbackLng:'ko' 프로젝트에서 기준이 en).
-    writeFileSync(out, renderMessagesDts(resources, baseLng), 'utf8');
+    writeFileSync(out, renderMessagesDtsSplit({
+        baseLng: base,
+        serverKeys,
+        clientKeys,
+        clientParams: extractParams(clientTree),
+    }), 'utf8');
+    // 앱별 카탈로그 값 모듈 — frontend 소스가 하나도 없으면 만들지 않는다(레거시 레이아웃).
+    const fallback = base ?? 'en';
+    for (const app of apps) {
+        generateMessagesCatalog({
+            localesDir,
+            app,
+            appLocales: appResources.get(app.name) ?? {},
+            frontendLangs: Object.keys(scoped.frontend),
+            fallbackLng: fallback,
+        });
+    }
+    return true;
+}
+function removeStale(path) {
+    if (existsSync(path))
+        rmSync(path, { force: true });
+}
+/** import 지정자로 쓸 상대 경로(항상 ./ 또는 ../ 로 시작 · POSIX 구분자). */
+function importPath(fromDir, target) {
+    const rel = relative(fromDir, target).split(sep).join('/');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+}
+/**
+ * 결정 454: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **공용 frontend + 앱 카탈로그**를
+ * 동적 import 해 vite 가 로케일별 해시 청크(.js)로 쪼갠다 — `/assets/*` immutable 캐시 대상이며
+ * `text/javascript` 라 seal 봉인 대상(application/json)에서 자연 면제된다.
+ * 생성 여부를 돌려준다(프론트 카탈로그가 없으면 false + 스테일 제거).
+ */
+export function generateMessagesCatalog(input) {
+    const outDir = dirname(input.app.catalogOut);
+    const langs = [...new Set([...input.frontendLangs, ...Object.keys(input.appLocales)])].sort();
+    if (langs.length === 0) {
+        removeStale(input.app.catalogOut);
+        return false;
+    }
+    const lines = [];
+    lines.push('// AUTO-GENERATED by @gaonjs/cli — 편집 금지.');
+    lines.push('// `gaon check` / `gaon dev` / `gaon gen` 가 이 파일을 재생성한다(결정 454).');
+    lines.push('// 클라이언트 번역 카탈로그: 로케일 → 로더(공용 frontend + 이 앱의 카탈로그).');
+    lines.push('// 서버 전용 문구(locales/<로케일>/backend.json)는 여기에 실리지 않는다 — 클라로 나가지 않는다.');
+    lines.push("import type { CatalogLoaders } from 'gaonjs/vue'");
+    lines.push('');
+    lines.push('export const catalogs: CatalogLoaders = {');
+    for (const lng of langs) {
+        const sources = [];
+        const shared = join(input.localesDir, lng, 'frontend.json');
+        if (existsSync(shared))
+            sources.push(importPath(outDir, shared));
+        const appFile = join(input.app.localesDir, `${lng}.json`);
+        if (input.appLocales[lng] !== undefined && existsSync(appFile))
+            sources.push(importPath(outDir, appFile));
+        if (sources.length === 0)
+            continue;
+        const body = sources.length === 1
+            ? `import('${sources[0]}')`
+            : `Promise.all([${sources.map((s) => `import('${s}')`).join(', ')}])`;
+        lines.push(`  '${lng}': () => ${body},`);
+    }
+    lines.push('}');
+    lines.push('');
+    lines.push(`export const fallbackLng = '${input.fallbackLng}'`);
+    lines.push('');
+    const text = lines.join('\n');
+    // 로더가 하나도 없으면(전부 backend 뿐) 모듈을 만들지 않는다 — 빈 카탈로그 배선은 오해를 만든다.
+    if (!text.includes('() =>')) {
+        removeStale(input.app.catalogOut);
+        return false;
+    }
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(input.app.catalogOut, text, 'utf8');
     return true;
 }

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

@@ -113,7 +113,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 32종
+### 2.2 `gaon doctor` 검사 35종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -147,6 +147,9 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 30. `channel-instance-authorize` — `instance: true` 채널(파라미터화 채널 · 결정 440)에 `authorize` 가 없음 = **경고**. 인스턴스 채널은 임의 문자열 키로 무한 실행 인스턴스(`/gaon/ws/<이름>/<인스턴스>`)가 열리므로, authorize 가 없으면 누구나 아무 인스턴스에나 입장한다. 매치·스레드처럼 참가자가 정해진 채널이면 `authorize(ctx)` 에서 `ctx.instance` 로 입장을 판정하라 — 공개 관전형(누구나 입장)이 의도면 무시해도 된다(재수출 정의는 대상 모듈을 따라가 판정 · `agents/realtime.md` §2.7)
 31. `agents-docs-stale` — 이 문서(`AGENTS.md`)·`agents/*.md` 사본이 **설치된 gaonjs 템플릿(정본)과 다름** = **경고**(byte 비교). gaonjs 업그레이드 후 관례 문서가 옛 채로 남으면 AI 가 낡은 관례·없는 표면으로 코드를 짠다 — `gaon g agents-docs` 로 재동기하라(미리보기 `--check` · 멱등 · 사본에 직접 적은 내용은 프로젝트 소유 문서(CLAUDE.md)로 옮긴 뒤 — 이 문서들은 프레임웍 정본 사본이다) (결정 449)
 32. `dotenv-node-env` — 공유 `.env`(·`.env.local`·`.env.example`)에 `NODE_ENV` 가 설정됨 = **경고**. **모드는 명령이 정한다** — `gaon dev` = development · `gaon serve` = production(결정 430). 이 파일들은 개발·운영이 함께 읽으므로 값을 박으면 모드가 양쪽으로 샌다: `production` 이면 `gaon dev` 가 쿠키 Secure·dev 플레이스홀더 secret 거부로 죽고, `development` 면 운영 `gaon serve` 에서 프로덕션 안전장치(플레이스홀더 secret 거부·쿠키 Secure·락 in-memory 폴백 차단)가 통째로 꺼진다(**부팅은 green, 보안만 꺼짐**). `.env` 에서 그 줄을 지우고, 모드별 값이 필요하면 `.env.development`/`.env.production` 오버레이에, 일회성이면 명령 앞에 붙인다(`NODE_ENV=production gaon serve`) — 모드별 오버레이 파일은 검사 대상이 아니다 (결정 430)
+33. `page-fetch` — 세션 앱 `.vue` 가 앱 내부 경로를 raw `fetch('/...')` 로 호출 = **경고**. CSRF 토큰 자동 부착(결정 166·341·342)은 `api()`·`useForm`·`router` 를 탈 때만 작동해, raw fetch 의 상태 변경 요청(POST/PUT/PATCH/DELETE)은 403 으로 죽는다(rooms 샘플 실사용에서 강퇴/위임이 이 경로로 죽었다). JSON 액션(강퇴·위임·좋아요 등 커맨드 포함)은 `api()`, 폼은 `useForm`, 부득이한 커스텀 전송은 `readCsrfToken()` 탈출구 — 첫 인자가 `/` 로 시작하는 문자열/템플릿 리터럴만 검출(외부 URL·변수 인자 오탐 제외), JWT/API 앱은 REST + fetch 가 정본이라 제외 (결정 453 · `agents/frontend.md` §2)
+34. `i18n-layout` — 카탈로그가 **레거시 단일 파일**(`locales/<로케일>.json`) = **경고**. 결정 454 의 정본 저작 레이아웃은 언어별 폴더 + 스코프 분리(`locales/<로케일>/{backend,frontend}.json`)다. 단일 파일은 계속 동작하지만 미분류라 **전량 서버 전용**으로 취급돼 클라 `t()`(`gaonjs/vue`)가 그 문구를 쓸 수 없다(클라 키 축 미생성). `gaon doctor --fix` 가 `locales/<로케일>/backend.json` 으로 옮겨 주고(내용·키 무변경), 그 뒤 화면 문구만 `frontend.json` 으로 나누면 된다 — 자동 분류는 하지 않는다(frontend 로 잘못 보내면 클라 번들·CDN 캐시에 노출돼 되돌리기 어렵다) (결정 454 · `agents/i18n.md`)
+35. `i18n-app-scope` — 앱 코드가 **그 앱 카탈로그에 없는** 클라 `t()` 키를 참조 = **오류**. 클라 키 유니온은 프로젝트 전체 frontend 합집합이라(두 앱이 같은 `GaonMessages.keys` 를 다른 유니온으로 augment 하면 TS2717 이고 `gaon check` 는 단일 tsc 프로그램이다 — 앱별 유니온이 구조적으로 불가) 타입만으로는 앱 경계를 못 지킨다. 앱 번들에는 그 앱 카탈로그만 실리므로 다른 앱 전용 키는 런타임에 번역 대신 **키 문자열이 그대로** 보인다. 공용으로 쓸 문구는 `locales/<로케일>/frontend.json`, 그 앱 전용이면 `apps/<앱>/locales/<로케일>.json` 에 두고 `gaon gen`. 서버 `t()`(`gaonjs/i18n`) 호출은 대상이 아니다 (결정 454)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -171,7 +174,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 |---|---|---|
 | 지금 페이지의 데이터를 다시 받기 (필터 변경·새로고침·무한 스크롤) | **Inertia partial reload** — 같은 액션 재호출, 필요한 props만 | §6.1 |
 | 서버가 먼저 밀어주는 데이터 (알림·채팅·접속자) | **채널/프레즌스** (`agents/realtime.md`) — 서버 개시는 `broadcast(name,data)`, 클라 메시지 응답은 `ctx.broadcast` | §7 |
-| 페이지와 무관한 데이터 요청 (자동완성·옵션 조회 등 앱 내부용) | **JSON 액션 + `api()` 클라이언트** (`agents/web.md`·`agents/frontend.md`) | E-3 |
+| 페이지 리로드가 필요 없는 앱 내부 요청 — 조회(자동완성·옵션)든 **상태 변경 커맨드(강퇴·위임·좋아요·토글)**든 | **JSON 액션 + `api()` 클라이언트** (`agents/web.md`·`agents/frontend.md` · CSRF 자동 부착) | E-3 · 결정 452 |
 | 외부에 공개하는 API (모바일 앱·서드파티) | **별도 API 앱 + JWT 옵션** | §3, §7 |
 
 ### 3.4 잡 발행 위치 (결정 32)
@@ -207,7 +210,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build + doctor (기본 포함 · --no-doctor 로 뺌 · 결정 157)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 32종 (§2.2)
+gaon doctor       # 정적 검사 35종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -86,7 +86,7 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 
 ```bash
 gaon check                        # .gaon 재생성 → 타입검사+build+doctor (CI 한 번에 · --no-doctor 로 doctor 뺌)
-gaon doctor                       # 정적 검사 32종 (상세 AGENTS §2.2)
+gaon doctor                       # 정적 검사 33종 (상세 AGENTS §2.2)
 npm test                          # Vitest · DB 테스트는 실 Docker 필수 (§9)
 ```
 

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

@@ -50,9 +50,12 @@ const props = pageProps<'web:posts#index'>()
   // <template> 에서 shared.currentUser?.name · shared.csrf · shared.flash.success
   // 앱이 app.config sharedProps 로 등록한 키(locale·theme 등)도 같은 자리에서 읽힌다(결정 150).
   ```
-  **i18n 문구도 이 경로로 온다** — Vue 는 `t()` 를 직접 부르지 않는다(서버 ALS 전용).
-  페이지 문구는 컨트롤러 render props, nav·레이아웃 같은 앱 chrome 문구는 `sharedProps`
-  로 서버가 번역해 흘려보낸다(`agents/i18n.md` §5 · 결정 213).
+  **i18n 문구는 여기가 아니라 클라 `t()` 로 온다**(결정 454) — `import { t } from 'gaonjs/vue'`
+  로 `.vue` 에서 직접 부른다. 카탈로그는 `locales/<로케일>/frontend.json`(앱 공용)과
+  `apps/<앱>/locales/<로케일>.json`(앱 전용)이고, 서버 전용 문구(`backend.json`)를 클라에서
+  참조하면 컴파일 에러다(`agents/i18n.md`). 컨트롤러 render props·`sharedProps` 로 번역을
+  흘려보내던 옛 경로(결정 213)는 탈출구로만 남는다 — `sharedProps` 는 번역과 무관한 앱 공유
+  값(테마·플래그)에 쓴다.
   `pageProps<K>()` 반환에도 교차되어 `props.csrf` 로도 읽히지만, 라우트 키가 필요 없는
   `useShared()` 가 정본 표면이다(임의 라우트 키를 빌려 currentUser 를 읽던 우회 트릭을 없앤다).
   - **구조분해 금지 — `pageProps` 와 같은 함정** (`packages/vue/src/shared.ts`). `useShared()`
@@ -114,6 +117,30 @@ async function search(q: string) {
 </script>
 ```
 
+**상태 변경 커맨드도 같은 경로다(결정 452)** — 강퇴·위임·좋아요·토글처럼
+페이지의 버튼이 서버 상태를 바꾸는 JSON 액션 호출도 `api()` 가 정본이다
+(폼이 아니므로 `useForm` 이 아니고, `fetch()` 는 CSRF 미부착으로 403 — 아래
+함정). POST 라우트 `r.post('/posts/:id/like', 'posts#like')` 기준:
+
+```vue
+<script setup lang="ts">
+import { api, isApiError } from 'gaonjs/vue'
+
+async function like(postId: string) {
+  try {
+    // :id 자리표시자는 params 에서 채워지고, 남는 값은 JSON 본문으로 실린다.
+    // CSRF 토큰은 프레임웍이 X-CSRF-Token 헤더로 자동 부착한다(결정 166·341).
+    const { likes } = await api('web:posts#like', { id: postId })
+    return likes
+  } catch (e) {
+    // 4xx/5xx 는 ApiError throw — res.ok 검사가 아니라 catch 로 받는다(결정 304).
+    if (isApiError(e) && e.status === 403) return alert('권한이 없습니다.')
+    throw e
+  }
+}
+</script>
+```
+
 - **시그니처** — `api(key, params?, opts?)`. 제네릭 타입 인자를 직접
   붙이지 않는다 — `key` 값 자체가 `keyof GaonRouteMap` 으로 좁혀져
   반환 타입을 결정한다 (`packages/vue/src/api.ts`).
@@ -459,8 +486,12 @@ async function runSearch(q: string) {
   결정한다.
 - **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출·domain 값 import 금지** —
   doctor **shared-purity** 위반(`.ts`·`.vue` 공통 · 결정 217). 데이터는 props/인자로.
-- **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
-  `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
+- **세션 앱 페이지에서 `fetch()` 금지 — 폼이든 버튼 액션이든**(결정 452) —
+  폼은 `useForm(...).post()` (`agents/web.md` §4 · 결정 64), 강퇴·위임·좋아요
+  같은 상태 변경 커맨드는 `api()` (§2). raw `fetch()` 는 CSRF 토큰이 안 실려
+  상태 변경 요청(POST/PUT/PATCH/DELETE)이 **403 으로 죽는다** — 자동 부착
+  (결정 166·341·342)은 `api()`·`useForm`·`router` 를 탈 때만 작동한다.
+  REST + `fetch()` 는 API 앱(JWT) 전용이다.
 - **내부 경로 일반 `<a href="/...">` 금지** — 클릭마다 전체 문서를 다시
   로드해 SPA 상태가 초기화된다. 앱 내부 이동은 `gaonjs/vue` 의 `Link`
   (`<Link href="/...">`) 또는 `router.visit(...)`, 외부 URL·`target="_blank"`
@@ -532,7 +563,8 @@ async function runSearch(q: string) {
 | 결정 128 | `useChannel` 자동 재연결(지수 백오프 1s·2s·5s·10s·지터 · `onReconnect` 로 놓친 데이터 따라잡기 · 미인가 4401 은 재연결 안 함 · `agents/realtime.md` §4) |
 | 결정 198 | 클라 환경변수 접근자 `env`(gaonjs/vue · `.vue` 의 import.meta.env TS1470 회피) · VITE_* 접두만 노출·접두 제거 · `.gaon/env.d.ts`(.env 스캔) 타입 브리지 · doctor no-import-meta-env(§9) |
 | 결정 206 | UI 킷 §8 슬롯·props 요약표(카탈로그가 이름만이라 소스 열람 유발 · O-2 해소) · named slot 비대칭 명시(PageHeader `#actions` 복수 vs EmptyState `#action` 단수) |
-| 결정 213 | i18n Vue 소비 = 서버 주도 render props/sharedProps 만 · `t()`·`useT()` 클라 미노출(`agents/i18n.md` §5) |
+| 결정 213 | (구) i18n Vue 소비 = 서버 주도 render props/sharedProps 만 — **결정 454 로 부분 번복**(탈출구로 존속) |
+| 결정 454 | 클라 `t()` 신설(`gaonjs/vue`) · 카탈로그 backend/frontend 분리 · 두 갈래 키 타입 · 앱별 카탈로그 청크(`agents/i18n.md`) |
 | 결정 217 | doctor `shared-purity`(구 shared-composable-purity 개명) — `shared/` 의 .ts 컴포저블 + .vue 컴포넌트 순수성(pageProps/api 호출·domain 값 import 금지 · §4) |
 | 결정 271 | W4 표면 정합 — `Head` 재수출(`gaonjs/vue` · `<Head title>` 제목 조합자 발화) 외 표면/최적화 4건(§12 결정 271) |
 | 결정 299 | 타입 브리지 PropsOf 정정 — 유니온 분배(조건부 redirect 혼합 액션의 never 붕괴 봉합) + `this.json(data)` 언랩(`{json,status}` 래퍼 타입 거짓 봉합 · `JsonResult<T>` 제네릭) (§2) |