@gaonjs/cli 0.64.0 → 0.65.2

package/dist/messages-gen.js

@@ -1,19 +1,23 @@
-// @gaonjs/cli · .gaon 메시지 축 생성기 (결정 158 · 13차 W2 · 결정 454)
+// @gaonjs/cli · .gaon 메시지 축 생성기 (결정 158 · 13차 W2 · 결정 454 · 459)
 //
-// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 메시지 축. 결정 454 부터 두 산출을 낸다:
+// tables.d.ts·routes.d.ts 와 같은 .gaon 파이프라인의 메시지 축. 두 산출을 낸다:
 //
-//  1) `.gaon/messages.d.ts` — **두 갈래 타입 브리지**
-//     · `gaonjs/i18n`(서버) = backend ∪ frontend ∪ 앱 frontend
-//     · `gaonjs/vue`(클라)  = frontend 만(+ 키별 보간 파라미터) → 서버 전용 문구를
+//  1) `.gaon/messages.d.ts` — **두 갈래 타입 브리지**(루트 단일 · 결정 459 O7)
+//     · `gaonjs/i18n`(서버) = domain-backend ∪ 전 앱 backend ∪ 전 앱 frontend
+//     · `gaonjs/vue`(클라)  = 전 앱 frontend 만(+ 키별 보간 파라미터) → 서버 전용 문구를
 //       클라에서 참조하면 컴파일 에러.
+//     유니온이 **프로젝트 전역**인 것은 타협이 아니라 제약이다 — 앱마다 다른 유니온으로
+//     `GaonMessages.keys` 를 augment 하면 TS2717(결정 454 실측 · 결정 459 §5.1 로 유효).
+//     앱 경계는 ① 번들 물리 경계 ② doctor(i18n-app-scope·i18n-server-scope)가 강제한다.
 //  2) `apps/<앱>/.gaon/messages.catalog.ts` — **앱별 값 모듈**(routes.manifest.ts 선례).
 //     그 앱의 frontend 카탈로그만 동적 import 로 묶어 vite 가 로케일별 청크로 쪼갠다.
 //     backend.json 은 입력에 아예 없다(노출 차단은 번들 경계가 물리적으로 강제).
+//     결정 459: 공용 스코프가 사라져 **로케일당 소스가 정확히 하나**다.
 //
-// @gaonjs/i18n 의 공개 API(loadScopedLocales·loadAppLocales·renderMessagesDtsSplit 등)만 쓴다.
+// @gaonjs/i18n 의 공개 API(loadProjectLocales·renderMessagesDtsSplit 등)만 쓴다.
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
-import { extractParams, flattenKeys, loadAppLocales, loadScopedLocales, renderMessagesDtsSplit, withPluralBaseKeys, } from '@gaonjs/i18n';
+import { extractParams, flattenKeys, loadProjectLocales, projectLanguages, renderMessagesDtsSplit, withPluralBaseKeys, } from '@gaonjs/i18n';
 /** 번역 트리 두 개를 깊은 병합한다(리프 충돌은 로더가 이미 fail-loud). */
 function mergeTrees(a, b) {
     const out = { ...a };
@@ -36,42 +40,35 @@ function pickBaseLng(langs, baseLng) {
     return [...langs].sort()[0];
 }
 /**
- * locales/ 카탈로그에서 `.gaon/messages.d.ts`(두 갈래)와 앱별 카탈로그 값 모듈을 생성한다.
- * 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를 비운 채로 둬 키가 string 폴백 —
- * i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게). 생성 여부를 돌려준다.
+ * 프로젝트 카탈로그(domain/locales · apps/*&#47;locales)에서 `.gaon/messages.d.ts`(두 갈래)와
+ * 앱별 카탈로그 값 모듈을 생성한다. 카탈로그가 없거나 비면 생성하지 않는다(GaonMessages 를
+ * 비운 채로 둬 키가 string 폴백 — i18n 을 안 쓰는 프로젝트가 never 로 깨지지 않게).
+ * 생성 여부를 돌려준다.
  */
-export function generateMessagesDts(localesDir, out, baseLng, apps = []) {
+export function generateMessagesDts(root, out, baseLng, apps = []) {
+    const project = loadProjectLocales(root);
+    const langs = projectLanguages(project);
     // 결정 414: 카탈로그가 사라졌으면 **옛 생성물을 지운다** — 남겨두면 없어진 키의
     // 유니온이 그대로 살아 t('없어진키') 가 계속 컴파일된다(제거를 못 잡는 사각).
-    if (!existsSync(localesDir)) {
+    if (langs.length === 0) {
         if (existsSync(out))
             rmSync(out, { force: true });
         for (const app of apps)
             removeStale(app.catalogOut);
         return false;
     }
-    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);
+    // 결정 459: 클라 키 = **전 앱 frontend 합집합**(공용 스코프는 폐지됐다). 앱×앱 축을
+    // 타입으로 못 나누는 것은 TS2717 제약이라 그대로다 — 경계는 청크 분리와 doctor 가 강제한다.
+    let clientTree = {};
+    let appBackendTree = {};
+    for (const scoped of Object.values(project.apps)) {
+        clientTree = mergeTrees(clientTree, translationOf(scoped.frontend, base));
+        appBackendTree = mergeTrees(appBackendTree, translationOf(scoped.backend, base));
     }
-    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);
+    // 서버 키 = domain-backend ∪ 전 앱 backend ∪ 전 앱 frontend(결정 459 O5 — 서버는
+    // 화면 문구도 볼 수 있다: SSR·로그·관리 스크립트 경로를 좁히지 않는다).
+    const serverTree = mergeTrees(mergeTrees(translationOf(project.domain.backend, base), appBackendTree), clientTree);
     const clientKeys = withPluralBaseKeys(flattenKeys(clientTree));
     const serverKeys = withPluralBaseKeys(flattenKeys(serverTree));
     mkdirSync(dirname(out), { recursive: true });
@@ -81,14 +78,12 @@ export function generateMessagesDts(localesDir, out, baseLng, apps = []) {
         clientKeys,
         clientParams: extractParams(clientTree),
     }), 'utf8');
-    // 앱별 카탈로그 값 모듈 — frontend 소스가 하나도 없으면 만들지 않는다(레거시 레이아웃).
+    // 앱별 카탈로그 값 모듈 — 그 앱에 frontend 소스가 없으면 만들지 않는다.
     const fallback = base ?? 'en';
     for (const app of apps) {
         generateMessagesCatalog({
-            localesDir,
             app,
-            appLocales: appResources.get(app.name) ?? {},
-            frontendLangs: Object.keys(scoped.frontend),
+            appScoped: project.apps[app.name],
             fallbackLng: fallback,
         });
     }
@@ -104,40 +99,33 @@ function importPath(fromDir, target) {
     return rel.startsWith('.') ? rel : `./${rel}`;
 }
 /**
- * 결정 454: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **공용 frontend + 앱 카탈로그**를
+ * 결정 454·459: 앱별 카탈로그 값 모듈을 쓴다. 로케일별 로더가 **그 앱의 frontend.json 하나**를
  * 동적 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();
+    const frontend = input.appScoped?.frontend ?? {};
+    const langs = Object.keys(frontend).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('// `gaon check` / `gaon dev` / `gaon gen` 가 이 파일을 재생성한다(결정 454 · 459).');
+    lines.push('// 클라이언트 번역 카탈로그: 로케일 → 로더(이 앱의 frontend.json).');
+    lines.push('// 서버 전용 문구(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)
+        // 결정 459: 로케일당 소스가 정확히 하나다(공용 스코프 폐지) — 다중 import 분기가 없다.
+        const file = join(input.app.localesDir, lng, 'frontend.json');
+        if (!existsSync(file))
             continue;
-        const body = sources.length === 1
-            ? `import('${sources[0]}')`
-            : `Promise.all([${sources.map((s) => `import('${s}')`).join(', ')}])`;
-        lines.push(`  '${lng}': () => ${body},`);
+        lines.push(`  '${lng}': () => import('${importPath(outDir, file)}'),`);
     }
     lines.push('}');
     lines.push('');

package/dist/scaffold/app.d.ts

@@ -1,5 +1,14 @@
 import type { ScaffoldFile } from './controller.js';
 /** 이름 유효성 — apps/<name>/ 이 안전하고 URL 프리픽스로도 무리 없는 부분집합. */
 export declare function validateAppName(name: string): void;
+/** 앱 스캐폴드 옵션. */
+export interface AppScaffoldOptions {
+    /**
+     * 결정 459: i18n 을 쓰는 프로젝트의 기준 로케일. 주면 그 앱의 **필수** frontend
+     * 카탈로그(`apps/<앱>/locales/<로케일>/frontend.json`)를 함께 만든다. 생략 =
+     * i18n 미사용 프로젝트라 카탈로그를 만들지 않는다.
+     */
+    readonly fallbackLng?: string;
+}
 /** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
-export declare function appScaffoldFiles(name: string): ScaffoldFile[];
+export declare function appScaffoldFiles(name: string, options?: AppScaffoldOptions): ScaffoldFile[];

package/dist/scaffold/app.js

@@ -47,7 +47,7 @@ export function validateAppName(name) {
     }
 }
 /** 앱 스캐폴드 파일 계획. 순수 함수 — 실제 쓰기는 writeScaffold 가 담당. */
-export function appScaffoldFiles(name) {
+export function appScaffoldFiles(name, options = {}) {
     validateAppName(name);
     const files = [];
     // 1) routes.ts — 관례상 GET / + /health 두 라우트로 시작한다.
@@ -160,7 +160,17 @@ export function appScaffoldFiles(name) {
             ``,
         ].join('\n'),
     });
-    // 6-8) 관례 폴더 유지 — git 이 빈 폴더를 추적하지 않아 .gitkeep 을 둔다.
+    // 6) locales/<로케일>/frontend.json — 결정 459: **화면 문구의 소유자는 그 앱**이다.
+    //    frontend 카탈로그는 앱마다 필수라 스캐폴드가 자리를 만들어 둔다(빈 파일이 아니라
+    //    실제로 쓰이는 키 하나를 둬야 "여기에 넣으면 되는구나" 가 보인다). 서버 문구가
+    //    필요해지면 같은 폴더에 backend.json 을 추가한다(선택).
+    if (options.fallbackLng) {
+        files.push({
+            path: `apps/${name}/locales/${options.fallbackLng}/frontend.json`,
+            contents: `${JSON.stringify({ nav: { home: name } }, null, 2)}\n`,
+        });
+    }
+    // 7-9) 관례 폴더 유지 — git 이 빈 폴더를 추적하지 않아 .gitkeep 을 둔다.
     //     components · composables · channels 는 앱이 클수록 자주 채워지는
     //     세 자리다(E-5 §2.2 · M6 실시간).
     for (const sub of ['components', 'composables', 'channels']) {

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

@@ -80,7 +80,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
    혼용 금지 · doctor response-mixing).
 8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`routes.manifest.ts`
    (routes 축 = 타입 브리지 + api() 런타임 매니페스트 2파일 · 결정 127)·
-   `tables.d.ts`·`messages.d.ts`(3축 · `locales/` 있을 때 · 결정 158)·`env.d.ts`
+   `tables.d.ts`·`messages.d.ts`(3축 · 카탈로그 있을 때 · 결정 158)·`env.d.ts`
    (`.env` 스캔 · 프론트 앱 · 결정 198) 는 `gaon check`/`gaon dev`/`gaon gen` 이
    재생성한다.
 
@@ -113,7 +113,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 35종
+### 2.2 `gaon doctor` 검사 37종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -141,15 +141,17 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 24. `seal-security` — `@gaonjs/seal` 을 켠 앱에서 (a) `gaon.config.ts` 가 진짜 방어층(rate limit·보안 헤더·CORS)을 **명시적으로 껐을** 때 = 봉인을 켜고 방어를 끄는 역전 **경고**, (b) `main.ts` 가 seal 클라이언트를 배선(`@gaonjs/seal/client` 정적 import + `createGaonApp` sealClient)하지 않았을 때 = 봉인 문서를 브라우저가 못 열어 blank 가 되는 **에러**(`gaon doctor --fix --yes` 의 `seal-client-wiring` fixer 가 자동 배선). seal 은 서버 검증을 대체하지 않는다 (결정 121·124 · `agents/seal.md`)
 25. `schema-relations` — 커넥션을 가로지르는 belongsTo·역방향 관계(SQL 조인이 커넥션을 못 넘음)와 존재하지 않는 관계 대상 = **에러**(§4.5). **파티션 키 컬럼이 실제 컬럼인지도 검사**(결정 277 · `checkPartitions` — 오타·유령 컬럼). data 패키지 검사(`checkCrossConnectionRelations`·`checkRelationTargets`·`checkPartitions`)를 CLI 러너가 배선 — 배포 후 raw postgres 에러 대신 doctor 가 잡는다 (결정 134·277 · `agents/data.md`)
 26. `no-import-meta-env` — `.vue`(SFC) `<script>` 에서 `import.meta.env` 직접 사용 = **에러**. SFC 는 nodenext 아래 CommonJS 출력으로 분류돼 vue-tsc 가 TS1470 로 거부한다(`gaon check` red). 클라 공개 환경변수는 `import { env } from 'gaonjs/vue'` 로 읽으라(VITE_* 접두 제거·타입드 · `.gaon/env.d.ts` 는 `.env` 스캔 생성) — 템플릿 프로즈·주석의 언급은 오탐 제외 (결정 198 · `agents/frontend.md` §9)
-27. `locale-parity` — 루트 `locales/` **와 앱 스코프 `apps/<앱>/locales/`** 의 로케일 간 키 부분 누락 = **경고**. 어떤 키가 특정 로케일에만 빠지면 `messages.d.ts`(기준 로케일 기준)는 컴파일을 통과하고, 런타임에 그 로케일 사용자는 fallback(루트) 또는 키 문자열(앱 · 결정 455)을 본다. 검사가 로케일 간 키 diff 를 계산해 빠진 파일·키를 짚는다(`--json` 은 `detail.missing`·`detail.scope` 로 구조화 · 스코프는 `backend`·`frontend`·`app:<앱>`). **앱 카탈로그는 앱 내부에서만 비교**한다 — 앱 전용 키는 루트에 없는 것이 정상이라 교차 비교는 전량 오탐이다. 로케일이 0·1개면 무소음 (결정 216·456 · `agents/i18n.md` §9)
+27. `locale-parity` — **같은 스코프 안에서 로케일 간** 키 부분 누락 = **경고**. 어떤 키가 특정 로케일에만 빠지면 `messages.d.ts`(기준 로케일 기준)는 컴파일을 통과하고, 런타임에 그 로케일 사용자는 fallback(서버) 또는 키 문자열(클라 · 결정 455)을 본다. 비교 단위 3종 — ① `domain/locales` backend ② 앱별 frontend ③ 앱별 backend. **스코프·소유자를 가로지르는 비교는 하지 않는다**(앱 전용 키가 전량 오탐). 복수형 접미사는 base 로 정규화해 비교한다. 로케일이 0·1개면 무소음 (`--json` 은 `detail.missing`·`detail.scope`·`detail.owner` · 결정 216·456·459 · `agents/i18n.md` §9.1)
 28. `render-return` — 액션이 `this.render`/`this.redirect`/`this.json` 을 호출만 하고 `return` 하지 않음 = 응답이 버려져 조용히 204(백지) — `return this.render(...)` 로 고치라 (결정 340 · 경고)
 29. `channel-collision` — 두 앱이 **같은 이름의 채널**을 각각 정의 = **에러**. 채널 이름은 전역이다(브로드캐스트 subject `gaon.chan.<이름>`·프레즌스 키에 앱 프리픽스 없음) — 한 앱의 broadcast 가 다른 앱 연결로 팬아웃되고 접속자 목록이 병합되며, 두 정의의 `authorize` 가 갈리면 공개 쪽 규칙으로 메시지가 샌다. 앱마다 이름을 분리하거나(클라이언트 `useChannel` 인자도 함께), **여러 앱이 한 방을 공유**하는 것이 의도면 정의를 `domain/channels/<이름>.ts` 하나에 두고 각 앱 채널 파일에서 재수출하라(재수출은 통과 · 정의 하나 = 인가 규칙 하나 · **등록 파일은 `apps/<앱>/channels/` 에 그대로**). `shared/channels/` 는 정본이 아니다 — authorize 가 DB 를 보면 domain 값 import 가 필요해 `shared-purity`(#6)와 성립 불가이고, `shared/` 는 props 로만 받는 순수 UI 영역이다(§1-3). 옛 배치가 남아 있으면 같은 규칙이 **경고**로 회수한다 — 잡·리스너의 동명 등록 throw(결정 271)와 같은 계열의 정적 검사 (결정 456 · `agents/realtime.md` §2.10)
 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)
+34. `i18n-layout` — **옛 카탈로그 배치**가 남아 있음 = **경고**(폐지된 루트 `locales/`·앱 평면 `<로케일>.json`) · **오류**(`domain/locales/<로케일>/frontend.json`·제거된 `i18n.dir` 설정). 결정 459 의 정본 배치는 소유자 2개다 — `domain/locales/<로케일>/backend.json`(도메인 공통 서버 문구) · `apps/<앱>/locales/<로케일>/{frontend,backend}.json`(그 앱 화면·서버 문구). 옛 배치를 그냥 두면 **아무도 읽지 않는 폴더**가 되어 전 화면·전 메일이 키 문자열로 degrade 하므로 조용히 두지 않는다. `gaon doctor --fix` 가 이관한다(루트 backend·레거시 단일 파일 → `domain/locales`, 앱 평면 파일 → 그 앱 `frontend.json`, 루트 공용 frontend → **전 앱 복제 후 원본 제거**). 전 앱 복제는 되돌리기 쉬운 방향이라 자동화하고, 잉여 키 정리·도메인 frontend 재배치는 사람이 판단한다 (결정 454·459 · `agents/i18n.md`)
+35. `i18n-app-scope` — 앱 코드가 **그 앱 카탈로그에 없는** 클라 `t()` 키를 참조, 또는 `shared/` 컴포넌트가 쓰는 키가 **일부 앱에만** 존재 = **오류**. 클라 키 유니온은 프로젝트 전체 frontend 합집합이라(두 앱이 같은 `GaonMessages.keys` 를 다른 유니온으로 augment 하면 TS2717 이고 `gaon check` 는 단일 tsc 프로그램이다 — 앱별 유니온이 구조적으로 불가) 타입만으로는 앱 경계를 못 지킨다. 앱 번들에는 그 앱 카탈로그만 실리므로 다른 앱 전용 키는 런타임에 번역 대신 **키 문자열이 그대로** 보인다. `shared/` 는 어느 앱 번들에도 실릴 수 있어 그 키는 **모든 앱**에 있어야 한다(공용 카탈로그는 폐지됐다 — 결정 459 O1 · 복제 + 이 검사로 강제). 문구는 `apps/<앱>/locales/<로케일>/frontend.json` 에 두고 `gaon gen`. 서버 `t()`(`gaonjs/i18n`) 호출은 `i18n-server-scope` 담당이다 (결정 454·459)
+36. `i18n-server-scope` — 서버 `t()`(`gaonjs/i18n`)가 **소유자 경계**를 넘는 키를 참조 = **오류**. `domain/**` 은 `domain/locales` backend 만, `apps/<앱>/**` 은 그 앱 backend ∪ frontend ∪ domain backend 만 볼 수 있다. 이 유형은 두 층이 모두 놓친다 — 서버 키 유니온은 domain ∪ 전 앱이라 **컴파일을 통과**하고(결정 459 O5), 요청 컨텍스트에서는 앱 네임스페이스가 상속돼 **우연히 해석된다**. 같은 코드가 워커(`gaon work`)·크론에서 불리면 앱 스코프가 없어 키가 비므로 "개발 중엔 되는데 잡에서만 키 문자열이 뜬다" 로 샌다. 결정 455 의 2단 계약(빌드=차단 / 런타임=키 렌더+경고)에서 **빌드=차단의 절반이 무너지는** 지점이라 정적으로 못박는다. 수리: 문구를 `domain/locales/<로케일>/backend.json` 으로 올리거나 그 호출을 도메인 밖으로 옮긴다 (결정 459 · `agents/i18n.md` §3)
+37. `redundant-index` — **unique·PK 컬럼에 붙은 `.index()`** = **경고**. UNIQUE 제약과 PK 는 그 자체가 인덱스라 컬럼 레벨 `.index()` 는 중복이고, DDL 생성기가 정확히 그래서 **건너뛴다**(스키마·DDL 결과는 옳다). 문제는 그 skip 이 조용해 개발자가 no-op 인 줄 모르는 것 — 특히 `.index({ where: ... })`(부분 인덱스)·`.index({ using: 'brin' })`(인덱스 메서드)까지 함께 증발하는데 아무 신호가 없다. 수리: 그 `.index()` 를 지우거나(지워도 결과 동일), 원래 의도가 **그 컬럼을 선두로 하는 복합·부분 인덱스**였다면 테이블 레벨 `table('t', {...}, { index: [['email','teamId']] })` 로 옮긴다. 빌더·타입은 막지 않는다 — 수식어는 어떤 조합·순서든 컴파일되는 것이 의도된 성질이라(`.unique().index()` 포함) 신호는 이 정적 검사로만 준다. `--fix` 없음(지울지 옮길지는 의도 판단 · 결정 460 · `agents/data.md` §3)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -210,7 +212,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       # 정적 검사 35종 (§2.2)
+gaon doctor       # 정적 검사 37종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -164,6 +164,11 @@ import 하면 순환 참조가 생기므로, 실제 연결은 부팅 시 프레
   - `.index({ where: "status = 'active'" })` — partial(부분) 인덱스.
   - method 집합 = `btree | gin | brin | gist`. **jsonb→gin 자동은 컬럼 `.index()` 한 곳뿐** —
     brin/gist 는 명시(과유도가 perpetual-diff 를 늘림). **`t.jsonb()` 도 `.index()` 를 가진다**(결정 273 신설).
+  - **unique·PK 컬럼에는 `.index()` 를 붙이지 않는다**(결정 460). UNIQUE 제약·PK 가 이미
+    인덱스라 DDL 이 그 `.index()` 를 **생성하지 않는다** — 옵션(`where`·`using`)까지 함께
+    증발한다. 체이닝은 컴파일되므로(수식어는 어떤 조합·순서든 통과) `gaon doctor` 의
+    `redundant-index` 가 경고로 알린다. 그 컬럼을 **선두로 하는 복합·부분 인덱스**가
+    필요했다면 테이블 레벨 `{ index: [[...]] }` 로 옮긴다.
 - `.check(expr)` — 컬럼 레벨 CHECK 제약 (E-4 · `enum`·`uuid`·`belongsTo`·`bytea`
   제외 — §3.1).
 
@@ -1340,3 +1345,4 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 336 | 중첩 hidden dot-path 실지원(290 대체) — 중첩 객체·type:{} 서브도큐먼트·서브도큐먼트 배열 · 직렬화 경계 상속 스레딩 · 지원 밖 위치는 fail-loud(§7.1) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |
 | **결정 456** | **수식어 × 빌더 매트릭스(§3.1) + `t.belongsTo(...).unique()` 신설** — "모든 타입에 적용" 이라 적고 조합표가 없어 `t.belongsTo('x').unique()` 가 migrate 를 죽였다(auction 실측). 1:1 FK 는 정당한 도메인 요구라 `unique` 는 **열고**, `default`·`check` 는 참조 무결성과 어긋나 **닫는다**(표에 이유까지 명기 · `type-tests/columnModifiers.test-d.ts` 가 매트릭스를 타입으로 고정) |
+| 결정 460 | unique·PK 컬럼의 `.index()` 는 DDL 이 건너뛴다(중복) — 조용한 no-op 을 `gaon doctor` `redundant-index` **경고**로 표면화(§3 `.index()`) · 빌더·타입은 무변경(체이닝 자유는 의도된 성질) |