@gaonjs/cli 0.24.0 → 0.25.0

package/dist/doctor/page-layout-breakpoint.d.ts

@@ -0,0 +1,8 @@
+import type { RuleReport } from './types.js';
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export declare function usesLayoutBreakpoint(source: string): {
+    token: string;
+    line: number;
+}[];
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export declare function checkPageLayoutBreakpoint(cwd: string): Promise<RuleReport>;

package/dist/doctor/page-layout-breakpoint.js

@@ -0,0 +1,94 @@
+// @gaonjs/cli · doctor · 페이지 레이아웃 브레이크포인트 안내 (결정 107)
+//
+// 폭·여백·열 수 같은 레이아웃 반응형은 UI 킷 블록(PageShell·PageHeader …)이
+// 소유한다(결정 105·106·107). 페이지 파일이 레이아웃 브레이크포인트를 루트에서
+// 직접 쓰면 반응형 규칙이 여러 곳에 흩어져, "정답이 하나" 가 무너진다. 이 검사는
+// 그 사용을 **안내 경고(warning)** 로만 낸다 — 강제(error)가 아니다. 킷에 없는
+// 표현이면 Tailwind 유틸을 직접 써도 되므로(탈출구), 오탐을 줄이려 신호가 확실한
+// 레이아웃 유틸(반응형 flex-direction·grid 열 수)만 좁게 잡는다.
+//
+// 대상: apps/<앱>/pages/**/*.vue (페이지 파일만). shared/components/ui 의 킷 블록은
+// 반응형을 소유하므로 검사하지 않는다(그게 이 규칙의 목적).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/**
+ * 좁게 잡는 레이아웃 반응형 패턴: 반응형 접두사 + (flex-row/col · grid-cols-N/[).
+ * `sm:hidden`·`sm:text-lg`·`sm:px-6` 같은 흔한 반응형(표시·타이포·여백)은 잡지
+ * 않는다 — 오탐을 줄이려 페이지 레이아웃을 뒤집는 확실한 신호만 본다.
+ */
+const LAYOUT_BREAKPOINT = /\b(sm|md|lg|xl|2xl):(flex-(?:row|col)(?:-reverse)?|grid-cols-(?:\d+|\[))/;
+/** 소스에서 레이아웃 브레이크포인트 사용 위치(토큰·줄)를 모은다(단위 테스트 진입점). */
+export function usesLayoutBreakpoint(source) {
+    const out = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const m = LAYOUT_BREAKPOINT.exec(lines[i]);
+        if (m)
+            out.push({ token: m[0], line: i + 1 });
+    }
+    return out;
+}
+/** apps/<앱>/pages 를 훑어 페이지 레이아웃 브레이크포인트 사용을 경고로 낸다. */
+export async function checkPageLayoutBreakpoint(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const pagesDir = join(appsDir, app, 'pages');
+        for (const abs of await walkVueFiles(pagesDir)) {
+            const source = await readFile(abs, 'utf8').catch(() => '');
+            const hits = usesLayoutBreakpoint(source);
+            if (hits.length === 0)
+                continue;
+            const rel = relative(cwd, abs);
+            const first = hits[0];
+            issues.push({
+                rule: 'page-layout-breakpoint',
+                level: 'warning',
+                file: rel,
+                line: first.line,
+                message: `${rel} (line ${first.line})\n` +
+                    `  페이지가 레이아웃 브레이크포인트('${first.token}'${hits.length > 1 ? ` 외 ${hits.length - 1}건` : ''})를 직접 씁니다.\n` +
+                    `  반응형(폭·여백·열 수)은 UI 킷 블록이 책임집니다(결정 107).\n` +
+                    `→ shared/components/ui 의 블록(PageShell·PageHeader 등)으로 감싸 반응형을 킷에 두거나,\n` +
+                    `  킷에 없는 표현이면 그대로 둬도 됩니다 — 이 경고는 강제가 아닙니다(탈출구 유지).`,
+                detail: { token: first.token, count: hits.length },
+            });
+        }
+    }
+    return { rule: 'page-layout-breakpoint', issues };
+}
+/** 디렉터리 트리에서 .vue 파일 절대경로를 모은다(테스트·선언 제외 불필요 — .vue 만). */
+async function walkVueFiles(dir) {
+    const out = [];
+    const walk = async (d) => {
+        let entries;
+        try {
+            entries = (await readdir(d, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const abs = join(d, e.name);
+            if (e.isDirectory()) {
+                if (e.name === 'node_modules' || e.name === '.gaon' || e.name === 'dist')
+                    continue;
+                await walk(abs);
+            }
+            else if (e.isFile() && e.name.endsWith('.vue')) {
+                out.push(abs);
+            }
+        }
+    };
+    await walk(dir);
+    return out.sort();
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = (await readdir(dir, { withFileTypes: true }));
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | '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';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | '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';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/ui-kit-wiring.js

@@ -1,10 +1,12 @@
-// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76)
+// @gaonjs/cli · doctor · UI 킷 배선 검사 (결정 76 · 결정 105)
 //
-// 앱이 UI 킷 컴포넌트(apps/<앱>/components/ui/*)를 import 하는데 그 앱에
-// Tailwind 배선(apps/<앱>/style.css 의 @tailwind + main.ts 의 style.css import)이
-// 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·rounded-lg …)가 펼쳐지지 않아
-// 컴포넌트가 스타일 없이 렌더된다 — 컴파일은 통과하므로 check 로는 안 잡히는
-// 조용한 런타임 파손이다(결정 74·75·76). 이 검사가 그 상태를 경고로 낸다.
+// 앱이 UI 킷 컴포넌트(@shared/components/ui/* — 결정 105 로 shared 이전)를
+// import 하는데 그 앱에 Tailwind 배선(apps/<앱>/style.css 의 @tailwind +
+// main.ts 의 style.css import)이 없으면, UI 킷이 쓰는 유틸 클래스(bg-primary·
+// rounded-lg …)가 펼쳐지지 않아 컴포넌트가 스타일 없이 렌더된다 — 컴파일은
+// 통과하므로 check 로는 안 잡히는 조용한 런타임 파손이다(결정 74·75·76·105).
+// 이 검사가 그 상태를 경고로 낸다. 킷 위치와 무관하게 import 경로에 남는
+// 'components/ui/' 로 사용처를 잡으므로 @shared alias 도 그대로 감지된다.
 //
 // `gaon new`(web)·`gaon g app` 은 이제 배선을 함께 심으므로 정상 경로에서는
 // 걸리지 않는다. 이 규칙은 배선을 지웠거나 구버전 스캐폴드에서 만든 앱을 잡는
@@ -44,7 +46,9 @@ export async function checkUiKitWiring(cwd) {
 /** 앱 디렉터리를 재귀 스캔해 UI 킷을 import 하는 첫 .vue/.ts 파일(cwd 상대)을 찾는다. */
 async function findUiKitImporter(appDir, cwd) {
     for (const abs of await walkSources(appDir)) {
-        // components/ui 안의 컴포넌트 자체는 서로를 import 하므로 제외한다.
+        // 킷은 이제 shared/ 라 apps/ 스캔엔 안 들어오지만, 결정 105 이전의 앱별
+        // 사본(apps/<앱>/components/ui)이 남아 있으면 그 컴포넌트끼리의 상호 import 를
+        // 사용처로 오인하지 않도록 제외한다(마이그레이션 과도기 방어).
         if (abs.includes(`${join(appDir, 'components', 'ui')}`))
             continue;
         const source = await readFile(abs, 'utf8').catch(() => '');

package/dist/doctor.d.ts

@@ -19,6 +19,7 @@ export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js
 export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
+export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {

package/dist/doctor.js

@@ -1,7 +1,7 @@
 /**
  * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성 · E-5 확장)
  *
- * 21 검사를 조립한다:
+ * 22 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -23,6 +23,7 @@
  * 19) internal-anchor (결정 96 · 앱 내부 이동 일반 <a> = 풀 리로드 경고)
  * 20) pageprops-destructure (결정 99 · pageProps() 구조분해 = 반응성 끊김 경고)
  * 21) async-offload (결정 102·103 · 컨트롤러 인라인 메일·이미지·외부 HTTP = 응답 지연 경고)
+ * 22) page-layout-breakpoint (결정 107 · 페이지 레이아웃 브레이크포인트 직접 사용 = 안내 경고)
  *
  * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
  * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
@@ -56,6 +57,7 @@ import { checkCsrfWiring } from './doctor/csrf-wiring.js';
 import { checkInternalAnchor } from './doctor/internal-anchor.js';
 import { checkPagePropsDestructure } from './doctor/pageprops-destructure.js';
 import { checkAsyncOffload } from './doctor/async-offload.js';
+import { checkPageLayoutBreakpoint } from './doctor/page-layout-breakpoint.js';
 import { renderHuman, renderJson } from './doctor/reporter.js';
 import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 import { makeResult, } from './doctor/types.js';
@@ -78,6 +80,7 @@ export { hasStateChangingRoutes, checkCsrfWiring } from './doctor/csrf-wiring.js
 export { internalAnchorHref, usesInternalAnchor, checkInternalAnchor, } from './doctor/internal-anchor.js';
 export { usesPagePropsDestructure, checkPagePropsDestructure, } from './doctor/pageprops-destructure.js';
 export { isApiApp, importsMailSdk, importsImageLib, callsExternalHttp, pageActions, checkAsyncOffload, } from './doctor/async-offload.js';
+export { usesLayoutBreakpoint, checkPageLayoutBreakpoint, } from './doctor/page-layout-breakpoint.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
@@ -105,6 +108,7 @@ const ALL_RULES = [
     'internal-anchor',
     'pageprops-destructure',
     'async-offload',
+    'page-layout-breakpoint',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -128,6 +132,7 @@ const CHECKERS = {
     'internal-anchor': checkInternalAnchor,
     'pageprops-destructure': checkPagePropsDestructure,
     'async-offload': checkAsyncOffload,
+    'page-layout-breakpoint': checkPageLayoutBreakpoint,
 };
 /**
  * 규칙을 순서대로 실행해 RuleReport[] 를 낸다. 규칙 하나가 크래시해도 나머지는

package/dist/index.js

@@ -101,7 +101,7 @@ function renderHelp(version = VERSION) {
         "    gaon check         typecheck · vue-tsc · build 통합 검사 (--only <step> · --include-doctor)",
         "    gaon console       프로젝트 컨텍스트 REPL (--no-config)",
         "    gaon test          테스트 러너 (--scope unit|integration|all · -- vitest 인자)",
-        "    gaon doctor        정적 검사 (21 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드)",
+        "    gaon doctor        정적 검사 (22 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커·pageProps 구조분해·비동기 오프로드·페이지 레이아웃 브레이크포인트)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",

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

@@ -1,12 +1,12 @@
 <script setup lang="ts">
 import { pageProps, router } from 'gaonjs/vue'
-import Card from '../components/ui/Card.vue'
-import CardHeader from '../components/ui/CardHeader.vue'
-import CardTitle from '../components/ui/CardTitle.vue'
-import CardDescription from '../components/ui/CardDescription.vue'
-import CardContent from '../components/ui/CardContent.vue'
-import CardFooter from '../components/ui/CardFooter.vue'
-import Button from '../components/ui/Button.vue'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import CardFooter from '@shared/components/ui/CardFooter.vue'
+import Button from '@shared/components/ui/Button.vue'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).

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

@@ -1,16 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm, Link } from 'gaonjs/vue'
-import Card from '../../components/ui/Card.vue'
-import CardHeader from '../../components/ui/CardHeader.vue'
-import CardTitle from '../../components/ui/CardTitle.vue'
-import CardDescription from '../../components/ui/CardDescription.vue'
-import CardContent from '../../components/ui/CardContent.vue'
-import Form from '../../components/ui/Form.vue'
-import FormField from '../../components/ui/FormField.vue'
-import Input from '../../components/ui/Input.vue'
-import Button from '../../components/ui/Button.vue'
-import Alert from '../../components/ui/Alert.vue'
-import AlertDescription from '../../components/ui/AlertDescription.vue'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import Form from '@shared/components/ui/Form.vue'
+import FormField from '@shared/components/ui/FormField.vue'
+import Input from '@shared/components/ui/Input.vue'
+import Button from '@shared/components/ui/Button.vue'
+import Alert from '@shared/components/ui/Alert.vue'
+import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2). pageProps 는
 // 반응형이라 변수로 받아 props.x 로 접근한다 — 구조분해 금지(결정 99). 로그인

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

@@ -1,16 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm, Link } from 'gaonjs/vue'
-import Card from '../../components/ui/Card.vue'
-import CardHeader from '../../components/ui/CardHeader.vue'
-import CardTitle from '../../components/ui/CardTitle.vue'
-import CardDescription from '../../components/ui/CardDescription.vue'
-import CardContent from '../../components/ui/CardContent.vue'
-import Form from '../../components/ui/Form.vue'
-import FormField from '../../components/ui/FormField.vue'
-import Input from '../../components/ui/Input.vue'
-import Button from '../../components/ui/Button.vue'
-import Alert from '../../components/ui/Alert.vue'
-import AlertDescription from '../../components/ui/AlertDescription.vue'
+import Card from '@shared/components/ui/Card.vue'
+import CardHeader from '@shared/components/ui/CardHeader.vue'
+import CardTitle from '@shared/components/ui/CardTitle.vue'
+import CardDescription from '@shared/components/ui/CardDescription.vue'
+import CardContent from '@shared/components/ui/CardContent.vue'
+import Form from '@shared/components/ui/Form.vue'
+import FormField from '@shared/components/ui/FormField.vue'
+import Input from '@shared/components/ui/Input.vue'
+import Button from '@shared/components/ui/Button.vue'
+import Alert from '@shared/components/ui/Alert.vue'
+import AlertDescription from '@shared/components/ui/AlertDescription.vue'
 
 // pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
 const props = pageProps<'{{APP_NAME}}:registration#new'>()

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

@@ -104,7 +104,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
   컬럼명 · 스키마 파일 ↔ 테이블 ↔ `tables.d.ts` 키 변환 규칙)은
   `agents/data.md` "DB 네이밍" 표가 정본이다 — 먼저 읽는다.
 
-### 2.2 `gaon doctor` 검사 21종
+### 2.2 `gaon doctor` 검사 22종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -127,6 +127,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 19. `internal-anchor` — 앱 내부 경로 일반 `<a href="/...">`(풀 리로드로 SPA 파손 · `Link`/`router.visit` 를 쓰라 · 외부 URL·`target="_blank"` 는 제외) (결정 96 · 경고)
 20. `pageprops-destructure` — `const { x } = pageProps(…)` 구조분해(반응성 끊김 · 리다이렉트/리로드 후 갱신 안 됨 · `const props = pageProps(…)` 후 `props.x` 로 접근하라) (결정 99 · 경고)
 21. `async-offload` — 컨트롤러 액션 인라인의 무거운/외부 작업(메일 SDK·이미지 처리 sharp/jimp·외부 HTTP)이 응답을 지연 (`domain/jobs/` 잡 + `.later()` 로 빼라 · JSON/API 앱 외부 호출·빠른 내부 호출은 오탐 방지로 제외) (결정 102·103 · 경고)
+22. `page-layout-breakpoint` — 페이지 파일이 레이아웃 브레이크포인트(`sm:flex-row`·`md:grid-cols-2` 등)를 직접 사용(반응형은 UI 킷 블록이 책임 · `PageShell` 등으로 감싸라 · 킷에 없는 표현이면 그대로 둬도 됨 · 표시/타이포/여백 반응형은 오탐 방지로 제외) (결정 107 · 안내 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -187,7 +188,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 21종 (§2.2)
+gaon doctor       # 정적 검사 22종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -395,6 +395,33 @@ export const Post = model(posts, {
 })
 ```
 
+### 8.1 스키마 파생 폼 — `Model.form` · `Model.form.pick()` (결정 104)
+
+모든 모델은 `Model.form` 으로 **스키마 파생 폼**을 노출한다 — 컨트롤러의
+`this.params(Model.form)` 에 넘기면 컬럼 타입으로 런타임 강제 변환·검증
+(필수 강제 · 스키마 밖 키 제거 = 대량 할당 차단)까지 한다. 컨트롤러 쪽
+사용법(폼 모양 판단·라우트 파라미터 병합)은 `agents/web.md` §3 이 정본이다.
+
+**일부 컬럼만 검증해서 받으려면 `pick()`** — 지정한 컬럼만 담은 **새 폼**을
+돌려준다(원 폼 불변). 컬럼 타입·검증·기본값 정보가 그대로 따라오므로,
+"검증되는 부분 폼"이 필요할 때 애드혹 `{ _row: {} as T }`(검증 없음) 대신 쓴다.
+
+```ts
+// routes: r.post('/posts/:postId/comments', 'comments#create')
+// comments 스키마에서 postId·author·body 만 — :postId 는 라우트에서 자동 병합(결정 95).
+async create() {
+  const data = this.params(Comment.form.pick('postId', 'author', 'body'))
+  // data: { postId: bigint; author: string; body: string } — 안 고른 컬럼은 요구하지 않는다.
+  const comment = await Comment.create(data)
+  return this.redirect(`/posts/${String(data.postId)}`)
+}
+```
+
+- `pick()` 결과도 폼이다 — 부분집합으로 다시 `pick()` 할 수 있다.
+- 스키마에 없는 컬럼을 지정하면 즉시 throw(수리 안내 포함) · 빈
+  `pick()` 도 throw · 중복 지정은 조용히 하나로 합친다.
+- `omit`·`extend`·`merge` 는 **없다** — 폼 변형은 `pick()` 하나가 The One Way.
+
 ### 9. 서비스 (`service()`) — 트랜잭션 작업 흐름 (정본 §5.3 · `packages/data/src/service.ts`)
 
 로직 배치의 One Way 규칙은 루트 `AGENTS.md` 판단표가 정본이다 (정본 §5.3):
@@ -601,6 +628,9 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
   doctor **model-filename** 이 잡는다(`--fix` 지원 · 결정 32·46).
 - **잡·이벤트 발행을 트랜잭션과 정합시키려면** `afterCommit()`(service 안)
   또는 아웃박스(`agents/async.md`) — 커밋 전 발행은 롤백 시 유령 부수효과.
+- **폼 변형은 `pick()` 뿐** (결정 104) — `Model.form.omit/extend/merge` 는
+  없다. 검증되는 부분 폼 = `pick()`, 스키마와 무관한 입력만 애드혹
+  `{ _row: {} as T }`(검증 없음 · `agents/web.md` §3).
 
 ## 관련 결정 번호
 
@@ -615,4 +645,5 @@ await Post.upsert({ id, title, body })                // onConflict 생략 = 기
 | 결정 43 | 네이밍 정본화 · DB 네이밍 SSOT(§1.2 · 테이블 snake · 컬럼 camel) |
 | 결정 46 | doctor 컬럼(column-casing)·모델/페이지 파일명 검사 3종 |
 | 결정 47 | `gaon g model` 다단어 테이블명 snake_case(마지막 단어 복수) |
+| 결정 104 | 스키마 파생 폼에 name·defs 탑재(실검증) · `Model.form.pick()` 검증되는 부분 폼(§8.1) |
 | E-4 | 컬럼 타입·수식어·체이닝 확장 · `Post.query()` 정정 · Serialized 명명 |

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

@@ -149,6 +149,11 @@ shared/composables/useDebounce.ts      # 앱 간 공용 컴포저블 (순수 로
 `gaon doctor` 의 **shared-composable-purity** 검사가 shared 안에서
 `gaonjs/vue` 의 `api`/`pageProps` import 를 잡는다.
 
+**shared 컴포넌트(UI 킷 §8)의 허용/금지도 같은 기준(결정 25·105):** 허용 = 라우트 키와
+무관한 범용 API(`useForm`·`Link`·`router`) · 금지 = 앱 라우트 지식(`api()`·`pageProps`).
+그래서 킷의 `Form` 은 `useForm` 을 써도 되고, `Pagination` 은 라우트를 모른 채
+`v-model:page` 로 현재 페이지만 올려보낸다.
+
 ### 5. 레이아웃 관례 (errata E-5 §2.3)
 
 ```
@@ -195,37 +200,55 @@ import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
   ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
   소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
 
-### 8. UI 킷 (결정 74·75 · shadcn 참조 · 복사-소유)
+### 8. UI 킷 (결정 74·75 · 결정 105 shared 이전 · shadcn 참조 · 복사-소유)
 
-`gaon new` 는 기본 앱에 UI 킷을 심고(배터리 포함), `gaon g ui-kit [--app <앱>]`
-로 다른 앱에도 추가한다. 컴포넌트는 **프로젝트에 복사된 여러분 코드**다 — npm
-의존이 아니라 파일이므로 자유롭게 고친다(shadcn 방식). 외부 런타임 의존이 없다
-(clsx·tailwind-merge·cva·reka-ui 미도입 · `cn` 은 자작 · Dialog/Sheet 는 Teleport+
-Transition 자작).
+UI 킷은 프로젝트당 **한 벌**만 `shared/components/ui/` 에 둔다(결정 105 — 결정 75 의
+"앱마다 복사" 개정). `gaon new` 가 심고 `gaon g ui-kit` 로 재보장한다(멱등). 컴포넌트는
+**프로젝트에 복사된 여러분 코드**다 — npm 의존이 아니라 파일이므로 자유롭게 고친다
+(shadcn 방식). 외부 런타임 의존이 없다(clsx·tailwind-merge·cva·reka-ui 미도입 · `cn` 은
+자작 · Dialog/Sheet 는 Teleport+Transition 자작).
 
-배치·import:
+배치·import — 앱 페이지는 `@shared` alias 로 참조한다:
 
 ```
-apps/<앱>/lib/utils.ts            # cn() — 조건부 클래스 병합
-apps/<앱>/components/ui/*.vue      # Button·Input·Label·Badge·Card…·Alert…·Form…·Dialog·Sheet
+shared/lib/utils.ts                # cn() — 조건부 클래스 병합
+shared/components/ui/*.vue          # 원자 + 블록 (전 앱 공용 순수 UI)
 ```
 
 ```vue
 <script setup lang="ts">
-import Button from '../../components/ui/Button.vue'   // 앱 로컬 · 상대 경로
-import Card from '../../components/ui/Card.vue'
-import CardContent from '../../components/ui/CardContent.vue'
+import Button from '@shared/components/ui/Button.vue'   // @shared = 프로젝트 shared/
+import Card from '@shared/components/ui/Card.vue'
+import PageShell from '@shared/components/ui/PageShell.vue'
 </script>
 
 <template>
-  <Card>
-    <CardContent>
-      <Button variant="default">저장</Button>       <!-- variant·size 로 모양 선택 -->
-    </CardContent>
-  </Card>
+  <PageShell>
+    <Card><Button variant="default">저장</Button></Card>   <!-- variant·size 로 모양 선택 -->
+  </PageShell>
 </template>
 ```
 
+`@shared` 는 `vite.config.ts`(resolve.alias)·`tsconfig.json`(paths)에 배선돼 있다 —
+`../../../shared/...` 같은 깊은 상대경로 대신 alias 하나로 통일한다(결정 105). 앱 전용
+컴포넌트(예 `apps/<앱>/components/PostCard.vue`)는 이 킷을 **조합·확장**해 만든다.
+
+**킷 카탈로그 (원자 18 + 블록 4):**
+
+| 구분 | 컴포넌트 |
+|---|---|
+| 원자 (18) | Button · Input · Label · Badge · Card · CardHeader · CardTitle · CardDescription · CardContent · CardFooter · Alert · AlertTitle · AlertDescription · Form · FormField · FormMessage · Dialog · Sheet |
+| 블록 (4 · 결정 106) | PageShell · PageHeader · EmptyState · Pagination |
+
+- **블록은 성격 중립(결정 106)** — 관리자/프론트를 나누지 않고 전 앱에서 쓴다.
+  `PageShell`(최대폭·여백·세로 리듬) · `PageHeader`(제목+설명+액션) · `EmptyState`
+  (빈 목록) · `Pagination`(페이지 이동 · `v-model:page`). 이외 블록(DataTable·StatCard·
+  Tabs 등)은 아직 만들지 않는다(예약 · 실물 도그푸딩 후).
+- **반응형은 킷 책임(결정 107)** — 폭·여백·열 수 같은 레이아웃 반응형은 `PageShell`
+  등 킷 블록이 소유한다. **페이지 코드에 레이아웃 브레이크포인트(`sm:flex-row`·
+  `md:grid-cols-2` 등)를 직접 쓰지 않는다** — 킷에 그 표현이 있으면 킷을 쓴다.
+  (탈출구: 킷에 없는 표현이면 Tailwind 유틸을 직접 써도 된다 — doctor
+  **page-layout-breakpoint** 는 강제가 아닌 **안내 경고**다.)
 - **폼은 UI 킷 Form + gaonjs `useForm`(결정 64)** — `Form` 은 얇은 `<form>` 래퍼로
   `@submit` 을 `useForm` 의 `post/put/delete` 로 넘긴다. vee-validate 를 끌어오지
   않는다(검증·상태는 `useForm`). `FormField label error` + `FormMessage` 로 라벨·
@@ -236,13 +259,23 @@ import CardContent from '../../components/ui/CardContent.vue'
 - **디자인 토큰은 `style.css` 한 곳(결정 74)** — 컴포넌트는 `bg-primary`·
   `text-muted-foreground` 같은 의미 토큰만 쓰고, 실색은 `apps/<앱>/style.css` 의
   `:root`/`.dark` CSS 변수에서 바꾼다(다크 모드 = `<html class="dark">`).
-- **멀티앱은 앱마다 배선이 따로다(결정 76)** — `gaon g app admin` 은 새 앱에
-  프론트 배선(`apps/admin/{style.css,main.ts,index.html}`)을 web 앱과 동등하게
-  함께 심는다. 그래서 `gaon g ui-kit --app admin` 으로 심은 UI 킷이 Tailwind
-  유틸을 그대로 받는다(`g ui-kit --app` 은 배선이 없으면 멱등으로 보정한다).
-  `tailwind.config.ts`·`postcss.config.js` 는 프로젝트 루트 공유(앱마다 두지
-  않는다). 앱이 UI 킷을 import 하는데 그 앱에 `style.css` 배선이 없으면 doctor
-  **ui-kit-wiring** 이 경고한다.
+- **shared 킷의 허용/금지 API(결정 25·105)** — 킷은 `shared/` 라 라우트를 몰라야
+  한다: 허용 = 라우트 키와 무관한 범용 API(`useForm`·`Link`·`router`) · 금지 =
+  앱 라우트 지식(`api()`·`pageProps`). 데이터는 props 로 받는다(예 `Pagination` 은
+  `v-model:page` 로 현재 페이지만 올려보내고 실제 이동은 페이지가 정한다).
+- **멀티앱은 앱마다 Tailwind 배선이 따로다(결정 76)** — 킷은 shared 한 벌이지만,
+  각 앱이 Tailwind 유틸을 받으려면 그 앱에 `style.css` 배선이 있어야 한다.
+  `gaon g app admin` 이 배선을 동봉하고, `gaon g ui-kit --app admin` 은 배선이
+  없으면 멱등 보정한다(`--app` 은 이제 킷 위치가 아니라 배선만 정한다).
+  `tailwind.config.ts`·`postcss.config.js` 는 프로젝트 루트 공유이고 `content` 는
+  `apps/**` 와 `shared/**` 를 함께 훑는다. 앱이 킷을 import 하는데 배선이 없으면
+  doctor **ui-kit-wiring** 이 경고한다.
+
+**기존 프로젝트 마이그레이션(결정 105 이전 → 이후):** 앱별 사본(`apps/<앱>/components/ui`
+·`apps/<앱>/lib/utils.ts`)이 있으면 `gaon g ui-kit` 를 다시 실행해 `shared/` 에 킷을
+만든 뒤, 앱 사본을 지우고 import 를 `@shared/components/ui/…` 로 바꾼다.
+`tailwind.config.ts` 의 `content` 에 `./shared/**/*.{vue,ts}` 가 있는지도 확인한다
+(스캐폴드 기본값엔 이미 포함).
 
 ## 정본 예시
 
@@ -297,7 +330,15 @@ async function runSearch(q: string) {
   `useChannel(name, opts)` 가 정본(결정 87). `new WebSocket` 을 손으로 짜면
   URL(`/gaon/ws/<채널>`)·봉투(`{ t:'msg', data }`)·라이프사이클을 재구현하다
   틀린다(`agents/realtime.md` §4). 구독 래핑은 컴포저블에.
-- **레이아웃을 shared 에 두지 않는다** — 앱별이 정상.
+- **레이아웃을 shared 에 두지 않는다** — 앱별이 정상(UI 킷 §8 은 예외 — 성격
+  중립 순수 UI 라 `shared/components/ui` 프로젝트당 한 벌 · 결정 105).
+- **UI 킷은 `@shared/components/ui/…` 로 import** — `../../../shared/...` 같은 깊은
+  상대경로 대신 `@shared` alias 로 통일한다(결정 105 · `vite.config.ts`·`tsconfig.json`
+  배선). 킷을 `apps/<앱>/components/ui` 에 복제하지 않는다.
+- **페이지에 레이아웃 브레이크포인트 직접 사용 지양** — 폭·여백·열 수 반응형은
+  킷 블록(`PageShell` 등)이 책임진다(결정 107). `sm:flex-row`·`md:grid-cols-2` 를
+  페이지 루트에 직접 쓰면 doctor **page-layout-breakpoint** 가 **안내 경고**를 낸다
+  (강제 아님 · 킷에 없는 표현이면 그대로 둬도 된다 — 탈출구 유지).
 - **페이지 파일명은 PascalCase** — `pages/Posts/Index.vue`(폴더 세그먼트도
   Route 이름). 소문자(`posts/index.vue`)는 doctor **page-filename** 이 잡는다
   (결정 32·46). rename 후 컨트롤러 `this.render('...')` 키도 맞춘다.
@@ -320,4 +361,7 @@ async function runSearch(q: string) {
 | 결정 75 | shadcn 식 UI 킷(`gaon g ui-kit` · 복사-소유 · Vue 3 신작 · 외부 런타임 의존 0) |
 | 결정 76 | 멀티앱 UI 킷 배선 자동화(`g app`·`g ui-kit --app` 이 앱별 Tailwind 배선 동봉·멱등 보정 · doctor ui-kit-wiring) |
 | 결정 96 | 앱 내부 이동 = `Link`(선언적)/`router.visit`(프로그램적) · 내부 경로 일반 `<a>` 금지(풀 리로드) · `Link` 재수출 · doctor internal-anchor |
+| 결정 105 | UI 킷 shared 이전(`shared/components/ui` 프로젝트당 한 벌 · `@shared` alias · 결정 75 개정) |
+| 결정 106 | 최소 4블록(PageShell·PageHeader·EmptyState·Pagination · 성격 중립) |
+| 결정 107 | 반응형은 킷 책임(페이지 레이아웃 브레이크포인트 지양 · doctor page-layout-breakpoint 안내 경고 · 터치 44px·폰트 최소 크기 토큰) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |

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

@@ -122,10 +122,21 @@ export default controller({
   }
   ```
 
-- **② 애드혹 폼 `this.params({ _row: {} as { ... } })`** — 전용 모델이 없거나
-  받을 필드를 **정확히** 고를 때. 라우트 파라미터·폼 필드를 자유롭게 섞어 타입을
+  스키마 컬럼 중 **일부만** 받으면서 검증을 유지하려면
+  `Model.form.pick('a', 'b')` — 지정 컬럼만 검증·통과하는 새 폼을
+  돌려준다(안 고른 필수 컬럼은 요구하지 않음 · 원 폼 불변 · 결정 104 ·
+  정본 `agents/data.md` §8.1). 폼 변형은 `pick()` 하나뿐이다
+  (omit/extend/merge 없음):
+
+  ```ts
+  const data = this.params(Comment.form.pick('postId', 'author', 'body'))
+  ```
+
+- **② 애드혹 폼 `this.params({ _row: {} as { ... } })`** — 전용 모델(스키마)이
+  없는 입력일 때. 라우트 파라미터·폼 필드를 자유롭게 섞어 타입을
   못박는다. 단 **런타임 스키마 검증은 없다**(타입만 · 컬럼 정의가 없어 coerce
-  스킵) — 필요하면 값 검사를 직접 하거나 ①로 간다:
+  스킵) — 필요하면 값 검사를 직접 하거나 ①로 간다. 스키마가 있는데 필드만
+  좁히고 싶은 거라면 ②가 아니라 ①의 `pick()` 이다:
 
   ```ts
   // routes: r.post('/posts/:id/comments', 'comments#create')
@@ -333,4 +344,5 @@ export default controller({
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 (`agents/frontend.md`) |
 | 결정 59 | 인증 배선 = `app.config.ts` 의 `session`+`auth(loadUser)` — 없으면 currentUser 영구 null |
 | 결정 95 (W4) | 폼 모양 2종 — 스키마 파생 `Model.form`(검증) vs 애드혹 `{ _row }`(타입만) · 라우트 파라미터는 둘 다 자동 병합 |
+| 결정 104 | `Model.form.pick('a','b')` = 검증되는 부분 폼(결정 95 회부 종결) · 폼 변형은 pick 하나(omit/extend/merge 없음) |
 | E-1 | 파사드 = `gaonjs` · CLI = `gaon` |

package/dist/templates/project/apps/web/pages/Home/Index.vue.tpl

@@ -2,8 +2,8 @@
 import { computed } from 'vue'
 import { pageProps } from 'gaonjs/vue'
 import { useGaonHealth, type HealthDoctor } from '../../composables/useGaonHealth.js'
-import Card from '../../components/ui/Card.vue'
-import Badge from '../../components/ui/Badge.vue'
+import Card from '@shared/components/ui/Card.vue'
+import Badge from '@shared/components/ui/Badge.vue'
 
 // home#index 의 render props — Serialized<> 로 넘어온다(§6.2).
 // 라우트 키는 .gaon/routes.d.ts 가 유효한 값을 알려준다.
@@ -230,7 +230,7 @@ const routeLines = computed<CodeLine[]>(() => {
 
     <p class="mt-8 text-center text-xs text-muted-foreground">
       <Badge variant="secondary">UI 킷</Badge>
-      이 화면·카드·다음 단계는 gaon g ui-kit 로 심은 컴포넌트로 그렸습니다 — apps/web/components/ui/ 에서 소유·수정하세요.
+      이 화면·카드·다음 단계는 gaon g ui-kit 로 심은 컴포넌트로 그렸습니다 — shared/components/ui/ 에서 소유·수정하세요.
     </p>
   </div>
 </template>

package/dist/templates/project/apps/web/style.css.tpl

@@ -6,53 +6,63 @@
  * :root/.dark 의 CSS 변수 = 디자인 토큰(shadcn 관례). UI 킷 컴포넌트는 이
  * 토큰(bg-primary·text-muted-foreground …)만 참조하므로, 브랜드 색을 바꾸려면
  * 여기 한 곳만 고친다. hsl 채널 값으로 두는 이유는 tailwind.config.ts 가
- * hsl(var(--token)) 로 감싸 투명도 유틸(bg-primary/50)까지 동작하게 하기 위함이다. */
+ * hsl(var(--token)) 로 감싸 투명도 유틸(bg-primary/50)까지 동작하게 하기 위함이다.
+ *
+ * 결정 107: 토큰(:root·.dark)은 @layer base **밖**에 둔다 — @layer 안의 클래스
+ * 선택자 규칙(.dark)은 content 에 'dark' 문자열이 없으면 Tailwind 가 purge 해
+ * 다크 모드가 조용히 안 됐다(:root 등 요소 선택자는 남지만 .dark 는 사라짐).
+ * 토큰은 CSS 변수만 정의하므로 layer 밖이어도 유틸 속성과 충돌하지 않는다. */
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 240 10% 3.9%;
-    --card: 0 0% 100%;
-    --card-foreground: 240 10% 3.9%;
-    --primary: 240 5.9% 10%;
-    --primary-foreground: 0 0% 98%;
-    --secondary: 240 4.8% 95.9%;
-    --secondary-foreground: 240 5.9% 10%;
-    --muted: 240 4.8% 95.9%;
-    --muted-foreground: 240 3.8% 46.1%;
-    --accent: 240 4.8% 95.9%;
-    --accent-foreground: 240 5.9% 10%;
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 0 0% 98%;
-    --border: 240 5.9% 90%;
-    --input: 240 5.9% 90%;
-    --ring: 240 5.9% 10%;
-    --radius: 0.5rem;
-  }
+:root {
+  --background: 0 0% 100%;
+  --foreground: 240 10% 3.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 240 10% 3.9%;
+  --primary: 240 5.9% 10%;
+  --primary-foreground: 0 0% 98%;
+  --secondary: 240 4.8% 95.9%;
+  --secondary-foreground: 240 5.9% 10%;
+  --muted: 240 4.8% 95.9%;
+  --muted-foreground: 240 3.8% 46.1%;
+  --accent: 240 4.8% 95.9%;
+  --accent-foreground: 240 5.9% 10%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 240 5.9% 90%;
+  --input: 240 5.9% 90%;
+  --ring: 240 5.9% 10%;
+  --radius: 0.5rem;
+  /* 모바일·반응형 토큰(결정 107). tap-target-min = 터치 최소 타깃(권장 44px) ·
+     font-size-min = 입력·본문 최소 글꼴(iOS 가 16px 미만 입력에 포커스하면
+     화면을 자동 확대하는 것을 막는 값). 라이트/다크 공통이라 :root 한 곳에 둔다. */
+  --tap-target-min: 44px;
+  --font-size-min: 16px;
+}
 
-  .dark {
-    --background: 240 10% 3.9%;
-    --foreground: 0 0% 98%;
-    --card: 240 10% 3.9%;
-    --card-foreground: 0 0% 98%;
-    --primary: 0 0% 98%;
-    --primary-foreground: 240 5.9% 10%;
-    --secondary: 240 3.7% 15.9%;
-    --secondary-foreground: 0 0% 98%;
-    --muted: 240 3.7% 15.9%;
-    --muted-foreground: 240 5% 64.9%;
-    --accent: 240 3.7% 15.9%;
-    --accent-foreground: 0 0% 98%;
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 0 0% 98%;
-    --border: 240 3.7% 15.9%;
-    --input: 240 3.7% 15.9%;
-    --ring: 240 4.9% 83.9%;
-  }
+.dark {
+  --background: 240 10% 3.9%;
+  --foreground: 0 0% 98%;
+  --card: 240 10% 3.9%;
+  --card-foreground: 0 0% 98%;
+  --primary: 0 0% 98%;
+  --primary-foreground: 240 5.9% 10%;
+  --secondary: 240 3.7% 15.9%;
+  --secondary-foreground: 0 0% 98%;
+  --muted: 240 3.7% 15.9%;
+  --muted-foreground: 240 5% 64.9%;
+  --accent: 240 3.7% 15.9%;
+  --accent-foreground: 0 0% 98%;
+  --destructive: 0 62.8% 30.6%;
+  --destructive-foreground: 0 0% 98%;
+  --border: 240 3.7% 15.9%;
+  --input: 240 3.7% 15.9%;
+  --ring: 240 4.9% 83.9%;
+}
 
+@layer base {
   * {
     border-color: hsl(var(--border));
   }
@@ -63,4 +73,15 @@
     font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
     -webkit-font-smoothing: antialiased;
   }
+
+  /* 모바일(≤640px): 입력 글꼴이 16px 미만이면 iOS 가 포커스 시 화면을 확대한다.
+     UI 킷 Input 은 text-sm(14px)이라 좁은 화면에서만 최소 글꼴을 보장한다(결정 107).
+     데스크톱은 원래 text-sm 을 그대로 둔다. */
+  @media (max-width: 640px) {
+    input,
+    textarea,
+    select {
+      font-size: var(--font-size-min);
+    }
+  }
 }

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

@@ -11,7 +11,11 @@
     "resolveJsonModule": true,
     "noEmit": true,
     "jsx": "preserve",
-    "types": ["node", "vite/client"]
+    "types": ["node", "vite/client"],
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["./shared/*"]
+    }
   },
   "include": [
     "apps/**/*.ts",

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

@@ -7,13 +7,29 @@
 // 앱이 하나 이상이면 각 앱마다 vite.config.ts 를 두는 것이 아니라, 이 루트
 // 파일 하나가 root 를 apps/<앱> 으로 잡고 여러 번 실행된다(gaon dev 가 앱별
 // Vite 서버를 띄운다). 관례가 곧 배치.
+import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 
+// @shared → 프로젝트 루트의 shared/ (결정 105). UI 킷은 shared/components/ui 에
+// 프로젝트당 한 벌만 있고, 앱 페이지는 @shared 로 참조한다. root 가 apps/web 이라
+// shared 는 root 밖이므로, dev 서버가 읽을 수 있게 fs.allow 에 프로젝트 루트를 넣는다.
+const projectRoot = fileURLToPath(new URL('.', import.meta.url))
+const sharedDir = fileURLToPath(new URL('./shared', import.meta.url))
+
 export default defineConfig({
   // 기본 앱은 apps/web · gaon dev 가 다른 앱에 대해 root 를 재정의한다.
   root: 'apps/web',
   plugins: [vue()],
+  resolve: {
+    // 앱 페이지에서 shared UI 킷을 @shared 로 참조한다(결정 105).
+    // 예) import Button from '@shared/components/ui/Button.vue'
+    alias: { '@shared': sharedDir },
+  },
+  server: {
+    // root(apps/web) 밖의 shared 를 dev 서버가 읽도록 허용한다.
+    fs: { allow: [projectRoot] },
+  },
   build: {
     outDir: '../../dist/web',
     emptyOutDir: true,

package/dist/templates/ui-kit/EmptyState.vue.tpl

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// UI 킷 블록 · EmptyState (결정 106). 빈 목록·무결과 안내. 아이콘(슬롯)·제목·
+// 설명·액션(슬롯)으로 조합한다. 성격 중립 — 관리자/프론트 구분 없이 전 앱에서 쓴다.
+import { useSlots } from 'vue'
+
+defineProps<{ title?: string; description?: string }>()
+const slots = useSlots()
+</script>
+
+<template>
+  <div
+    class="flex flex-col items-center justify-center gap-3 rounded-lg border border-dashed px-6 py-12 text-center"
+  >
+    <div v-if="slots.icon" class="text-muted-foreground"><slot name="icon" /></div>
+    <div class="space-y-1">
+      <p class="text-sm font-medium"><slot name="title">{{ title }}</slot></p>
+      <p v-if="description || slots.description" class="text-sm text-muted-foreground">
+        <slot name="description">{{ description }}</slot>
+      </p>
+    </div>
+    <div v-if="slots.action" class="mt-1"><slot name="action" /></div>
+  </div>
+</template>

package/dist/templates/ui-kit/PageHeader.vue.tpl

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+// UI 킷 블록 · PageHeader (결정 106). 페이지 상단 — 제목 + 설명 + 액션(슬롯).
+// 모바일에선 액션이 제목 아래로 줄바꿈되고 넓은 화면에선 오른쪽에 붙는다
+// (반응형은 블록 책임 · 결정 107). 액션 슬롯이 없으면 액션 영역은 렌더되지 않는다.
+import { useSlots } from 'vue'
+
+defineProps<{ title?: string; description?: string }>()
+const slots = useSlots()
+</script>
+
+<template>
+  <div class="mb-6 flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+    <div class="min-w-0 space-y-1">
+      <h1 class="truncate text-2xl font-bold tracking-tight">
+        <slot name="title">{{ title }}</slot>
+      </h1>
+      <p v-if="description || slots.description" class="text-sm text-muted-foreground">
+        <slot name="description">{{ description }}</slot>
+      </p>
+    </div>
+    <div v-if="slots.actions" class="flex shrink-0 flex-wrap items-center gap-2">
+      <slot name="actions" />
+    </div>
+  </div>
+</template>

package/dist/templates/ui-kit/PageShell.vue.tpl

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// UI 킷 블록 · PageShell (결정 106). 페이지 바깥 골격 — 최대폭·좌우 여백·세로
+// 리듬을 한 곳에서 소유한다. 반응형(폭·여백)은 이 블록이 책임지므로(결정 107)
+// 페이지 코드는 레이아웃 브레이크포인트를 직접 쓰지 않는다. size 로 최대폭을 고른다.
+import { computed } from 'vue'
+import { cn } from '../../lib/utils.js'
+
+type Size = 'default' | 'narrow' | 'wide' | 'full'
+
+const props = withDefaults(defineProps<{ size?: Size }>(), { size: 'default' })
+
+const MAX: Record<Size, string> = {
+  narrow: 'max-w-2xl',
+  default: 'max-w-4xl',
+  wide: 'max-w-6xl',
+  full: 'max-w-none',
+}
+
+// 좌우 여백·세로 리듬을 브레이크포인트로 한 곳에서 정한다 — 페이지는 이 값을 모른다.
+const classes = computed(() =>
+  cn('mx-auto w-full px-4 py-6 sm:px-6 sm:py-8 lg:px-8 lg:py-10', MAX[props.size]),
+)
+</script>
+
+<template>
+  <div :class="classes"><slot /></div>
+</template>

package/dist/templates/ui-kit/Pagination.vue.tpl

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+// UI 킷 블록 · Pagination (결정 106). 페이지 이동 컨트롤. 라우트를 모르는 순수 UI —
+// 현재 페이지를 v-model(update:page)로 올려보내고, 실제 이동(Link·router)은 페이지가
+// 정한다(shared 순수성 · 결정 25). 모바일은 압축형(이전/다음 + "n / m"), sm 이상에선
+// 현재 주변 번호를 함께 보인다(반응형은 블록 책임 · 결정 107). 버튼은 모바일 44px·
+// 데스크톱 40px 로 터치 타깃을 확보한다(결정 107).
+import { computed } from 'vue'
+import { cn } from '../../lib/utils.js'
+
+const props = withDefaults(
+  defineProps<{ page: number; pageCount: number; siblings?: number }>(),
+  { siblings: 1 },
+)
+const emit = defineEmits<{ (e: 'update:page', page: number): void }>()
+
+const total = computed(() => Math.max(1, props.pageCount))
+const clamped = computed(() => Math.min(Math.max(1, props.page), total.value))
+const canPrev = computed(() => clamped.value > 1)
+const canNext = computed(() => clamped.value < total.value)
+
+// 현재 주변 번호 창(sm 이상): [현재-siblings, 현재+siblings]를 1..total 로 자른다.
+const windowPages = computed<number[]>(() => {
+  const from = Math.max(1, clamped.value - props.siblings)
+  const to = Math.min(total.value, clamped.value + props.siblings)
+  const out: number[] = []
+  for (let p = from; p <= to; p++) out.push(p)
+  return out
+})
+
+function go(p: number): void {
+  const next = Math.min(Math.max(1, p), total.value)
+  if (next !== clamped.value) emit('update:page', next)
+}
+
+const BTN =
+  'inline-flex h-11 min-w-11 sm:h-10 sm:min-w-10 items-center justify-center rounded-md border ' +
+  'px-3 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground ' +
+  'disabled:pointer-events-none disabled:opacity-50'
+</script>
+
+<template>
+  <nav class="flex items-center justify-between gap-2 sm:justify-center" aria-label="페이지 이동">
+    <button type="button" :class="BTN" :disabled="!canPrev" @click="go(clamped - 1)">이전</button>
+
+    <span class="text-sm text-muted-foreground sm:hidden">{{ clamped }} / {{ total }}</span>
+
+    <span class="hidden items-center gap-1 sm:inline-flex">
+      <button
+        v-for="p in windowPages"
+        :key="p"
+        type="button"
+        :class="cn(BTN, p === clamped && 'bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground')"
+        :aria-current="p === clamped ? 'page' : undefined"
+        @click="go(p)"
+      >{{ p }}</button>
+    </span>
+
+    <button type="button" :class="BTN" :disabled="!canNext" @click="go(clamped + 1)">다음</button>
+  </nav>
+</template>

package/dist/templates/ui-kit/utils.ts.tpl

@@ -1,4 +1,4 @@
-// apps/<app>/lib/utils.ts — UI 킷 공용 헬퍼 (결정 75 · shadcn 참조 · 복사-소유).
+// shared/lib/utils.ts — UI 킷 공용 헬퍼 (결정 75 · 결정 105 · shadcn 참조 · 복사-소유).
 //
 // UI 킷은 외부 런타임 의존 없이 자기완결이다(gaon g ui-kit 로 프로젝트에
 // 복사된 뒤엔 이 파일도 여러분 코드다 — 자유롭게 고친다).

package/dist/uikit.d.ts

@@ -11,10 +11,10 @@ export interface UiKitScaffoldResult {
     readonly created: string[];
     readonly skipped: string[];
 }
-/** UI 킷 전체가 생성하는 파일 목록. */
-export declare function uiKitScaffoldFiles(opts?: UiKitScaffoldOptions): UiKitScaffoldFile[];
-/** `gaon g auth` 가 필요로 하는 UI 킷 최소 세트 파일 목록. */
-export declare function authUiKitFiles(app?: string): UiKitScaffoldFile[];
+/** UI 킷 전체가 생성하는 파일 목록(shared/ · 프로젝트당 한 벌). */
+export declare function uiKitScaffoldFiles(_opts?: UiKitScaffoldOptions): UiKitScaffoldFile[];
+/** `gaon g auth` 가 필요로 하는 UI 킷 최소 세트 파일 목록(shared/). */
+export declare function authUiKitFiles(_app?: string): UiKitScaffoldFile[];
 /** 파일 목록을 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip(멱등 · 복사-소유). */
 export declare function writeUiKitFiles(cwd: string, files: readonly UiKitScaffoldFile[]): UiKitScaffoldResult;
 /** `gaon g ui-kit` — UI 킷 전체를 쓴다. */

package/dist/uikit.js

@@ -1,20 +1,25 @@
 /**
- * @gaonjs/cli · `gaon g ui-kit` — shadcn 식 UI 킷 제너레이터 (결정 75)
+ * @gaonjs/cli · `gaon g ui-kit` — shadcn 식 UI 킷 제너레이터 (결정 75 · 결정 105 개정)
  *
  * shadcn 을 참조해 Vue 3 로 새로 쓴 UI 컴포넌트를 프로젝트에 **복사**한다
  * (복사-소유 — 생성된 뒤엔 사용자 코드다). npm 의존이 아니라 파일로 심으므로
  * 자유롭게 고칠 수 있고, 외부 런타임 의존이 전혀 없다(cn 은 자작 · reka-ui·
  * clsx·cva 미도입 · 결정 75). Tailwind(결정 74)를 전제로 한다.
  *
- * 배치:
- *   apps/<app>/lib/utils.ts        — cn() 헬퍼
- *   apps/<app>/components/ui/*.vue  — Button·Input·Card·Form·Dialog … (앱 전용 순수 UI)
+ * 배치(결정 105 — 결정 75 의 "앱마다 복사" 개정):
+ *   shared/lib/utils.ts            — cn() 헬퍼 (프로젝트당 한 벌)
+ *   shared/components/ui/*.vue      — Button·Input·Card·Form·Dialog … (전 앱 공용 순수 UI)
  *
- * 앱 전용에 두는 이유: 컴포넌트에서 lib/utils 로 가는 import 를 얕게 유지해
- * (`../../lib/utils.js`) AI·사람 모두 실수 없이 참조하게 하고, `gaon g auth`
- * 처럼 앱 단위(--app)로 생성한다. 여러 앱이 각자 소유한다(복사-소유 관례).
+ * shared 에 두는 이유(결정 105): UI 킷은 성격 중립 순수 UI 라 앱마다 복제하지
+ * 않고 프로젝트당 한 벌만 둔다 — 앱 컴포넌트는 이 킷을 조합·확장한다. 앱 페이지는
+ * `@shared/components/ui/…` alias 로 참조한다(vite.config.ts·tsconfig.json 에 배선).
+ * 킷 내부 import(cn·하위 컴포넌트)는 상대 경로(`../../lib/utils.js`·`./Label.vue`)라
+ * 위치가 apps/<app> 에서 shared 로 옮겨져도 그대로 유효하다.
+ *
+ * --app 은 이제 킷 위치가 아니라 대상 앱의 Tailwind 배선(style.css·main.ts)을
+ * 멱등 보정하는 데만 쓰인다 — 킷은 앱과 무관하게 shared 로 간다.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { appWiringFiles, readProjectName } from './scaffold/app-wiring.js';
@@ -39,6 +44,11 @@ const COMPONENTS = [
     'FormMessage',
     'Dialog',
     'Sheet',
+    // 블록(결정 106) — 성격 중립 페이지 조각. 원자를 조합해 페이지 골격을 만든다.
+    'PageShell',
+    'PageHeader',
+    'EmptyState',
+    'Pagination',
 ];
 /** `gaon g auth` 가 스캐폴드하는 로그인·가입·대시보드 페이지가 쓰는 최소 세트.
  *  auth 생성 시 이 컴포넌트가 없으면 페이지가 컴파일되지 않으므로 함께 보장한다. */
@@ -62,26 +72,26 @@ const AUTH_SUBSET = [
 function read(name) {
     return readFileSync(join(TEMPLATE_DIR, name), 'utf8');
 }
-/** 컴포넌트명 목록 → 생성 파일 목록(utils 포함). */
-function filesFor(components, app) {
+/** 컴포넌트명 목록 → 생성 파일 목록(utils 포함). 위치는 shared/ 고정(결정 105). */
+function filesFor(components) {
     const files = [
-        { path: `apps/${app}/lib/utils.ts`, contents: read('utils.ts.tpl') },
+        { path: `shared/lib/utils.ts`, contents: read('utils.ts.tpl') },
     ];
     for (const name of components) {
         files.push({
-            path: `apps/${app}/components/ui/${name}.vue`,
+            path: `shared/components/ui/${name}.vue`,
             contents: read(`${name}.vue.tpl`),
         });
     }
     return files;
 }
-/** UI 킷 전체가 생성하는 파일 목록. */
-export function uiKitScaffoldFiles(opts = {}) {
-    return filesFor(COMPONENTS, opts.app ?? 'web');
+/** UI 킷 전체가 생성하는 파일 목록(shared/ · 프로젝트당 한 벌). */
+export function uiKitScaffoldFiles(_opts = {}) {
+    return filesFor(COMPONENTS);
 }
-/** `gaon g auth` 가 필요로 하는 UI 킷 최소 세트 파일 목록. */
-export function authUiKitFiles(app = 'web') {
-    return filesFor(AUTH_SUBSET, app);
+/** `gaon g auth` 가 필요로 하는 UI 킷 최소 세트 파일 목록(shared/). */
+export function authUiKitFiles(_app = 'web') {
+    return filesFor(AUTH_SUBSET);
 }
 /** 파일 목록을 디스크에 쓴다. 기존 파일은 덮어쓰지 않고 skip(멱등 · 복사-소유). */
 export function writeUiKitFiles(cwd, files) {
@@ -118,11 +128,12 @@ export function runGenerateUiKitCommand(opts = {}) {
         skipped: [...wiring.skipped, ...kit.skipped].sort(),
     };
     if (opts.json) {
-        process.stdout.write(JSON.stringify({ command: 'g ui-kit', app, ...result }, null, 2) + '\n');
+        const legacy = legacyUiKitApps(cwd);
+        process.stdout.write(JSON.stringify({ command: 'g ui-kit', app, ...result, legacyUiKitApps: legacy }, null, 2) + '\n');
         return 0;
     }
     const lines = [''];
-    lines.push(`  gaon g ui-kit — UI 킷 (${app} 앱 · shadcn 참조 · 복사-소유)`);
+    lines.push(`  gaon g ui-kit — UI 킷 (shared/ · shadcn 참조 · 복사-소유)`);
     lines.push('');
     for (const f of result.created)
         lines.push(`   + ${f}`);
@@ -130,9 +141,32 @@ export function runGenerateUiKitCommand(opts = {}) {
         lines.push(`   · ${f} (이미 있음 — 건너뜀)`);
     lines.push('');
     lines.push('  Tailwind 배선(tailwind.config.ts·postcss.config.js·apps/' + app + '/style.css)이 함께 보정됩니다.');
-    lines.push('  컴포넌트는 이제 여러분 코드입니다 — apps/' + app + '/components/ui/ 에서 자유롭게 고치세요.');
-    lines.push('  예) import Button from \'../../components/ui/Button.vue\'');
+    lines.push('  컴포넌트는 이제 여러분 코드입니다 — shared/components/ui/ 에서 자유롭게 고치세요.');
+    lines.push('  예) import Button from \'@shared/components/ui/Button.vue\'');
+    const legacy = legacyUiKitApps(cwd);
+    if (legacy.length > 0) {
+        lines.push('');
+        lines.push('  ⚠ 구버전 UI 킷 사본이 남아 있습니다(결정 105 이전 · 앱별 배치):');
+        for (const app of legacy)
+            lines.push(`     apps/${app}/components/ui/  ·  apps/${app}/lib/utils.ts`);
+        lines.push('  → shared/ 로 옮겼으니 앱 사본을 지우고 import 를 @shared 로 바꾸세요:');
+        lines.push("     import X from '../../components/ui/X.vue'  →  import X from '@shared/components/ui/X.vue'");
+    }
     lines.push('');
     process.stdout.write(lines.join('\n') + '\n');
     return 0;
 }
+/** 결정 105 이전 배치(apps/<app>/components/ui)를 아직 가진 앱 목록 — 마이그레이션 안내용. */
+function legacyUiKitApps(cwd) {
+    const appsDir = join(cwd, 'apps');
+    let apps;
+    try {
+        apps = readdirSync(appsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+    return apps.filter((app) => existsSync(join(appsDir, app, 'components', 'ui'))).sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Gaon CLI 구현: 제너레이터·스캐폴딩·로드맵 출력 (M1 스텁)",
   "type": "module",
   "license": "MIT",
@@ -27,12 +27,12 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.6.1",
-    "@gaonjs/web": "0.7.2",
-    "@gaonjs/config": "0.5.3",
+    "@gaonjs/data": "0.10.0",
+    "@gaonjs/config": "0.5.4",
     "@gaonjs/core": "0.2.1",
     "@gaonjs/mail": "0.1.3",
-    "@gaonjs/data": "0.9.2"
+    "@gaonjs/web": "0.7.2",
+    "@gaonjs/async": "0.6.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""