@gaonjs/cli 0.23.0 → 0.25.0

package/dist/doctor.d.ts

@@ -17,6 +17,9 @@ export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } fr
 export { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
 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 확장)
  *
- * 19 검사를 조립한다:
+ * 22 검사를 조립한다:
  *  1) response-mixing (errata E-3 §C · 라이브)
  *  2) n-plus-one (errata E-4 (e))
  *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
@@ -21,6 +21,9 @@
  * 17) method-override (결정 89 · _method HTTP 스푸핑 hack 경고)
  * 18) csrf-wiring (결정 93 · 비-GET 라우트 + session 미배선 = CSRF 무방비 경고)
  * 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)를 위해 반드시 파싱 가능한
@@ -52,6 +55,9 @@ import { checkStaticCollision } from './doctor/static-collision.js';
 import { checkMethodOverride } from './doctor/method-override.js';
 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';
@@ -72,10 +78,13 @@ export { usesAuthSurface, hasAuthWiring, hasSessionWiring, checkAuthWiring, } fr
 export { importsUiKit, checkUiKitWiring } from './doctor/ui-kit-wiring.js';
 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';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 19개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 21개 모두.
  */
 const ALL_RULES = [
     'response-mixing',
@@ -97,6 +106,9 @@ const ALL_RULES = [
     'method-override',
     'csrf-wiring',
     'internal-anchor',
+    'pageprops-destructure',
+    'async-offload',
+    'page-layout-breakpoint',
 ];
 const CHECKERS = {
     'response-mixing': checkResponseMixing,
@@ -118,6 +130,9 @@ const CHECKERS = {
     'method-override': checkMethodOverride,
     'csrf-wiring': checkCsrfWiring,
     '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        정적 검사 (19 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선·라우트 등록·정적 충돌·_method·CSRF 배선·내부 앵커)",
+        "    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)",
@@ -147,6 +147,7 @@ export function parseDoctorChecks(argv) {
         "shared-composable-purity",
         "no-auto-import",
         "csrf-wiring",
+        "async-offload",
     ];
     const isKnown = (s) => known.includes(s);
     const out = [];

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

@@ -1,22 +1,23 @@
 <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).
-const { user, csrf } = pageProps<'{{APP_NAME}}:dashboard#show'>()
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'{{APP_NAME}}:dashboard#show'>()
 
 // 로그아웃 = DELETE /session (r.resource('session') 의 destroy).
 // HTML <form> 은 DELETE 를 보낼 수 없으므로 Inertia 라우터로 실제 메서드를
 // 보낸다(결정 64) — `?_method=DELETE` 우회는 서버가 해석하지 않아 POST /session
 // (= 로그인 create) 으로 잘못 라우팅됐다.
 function logout(): void {
-  router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+  router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
 }
 </script>
 
@@ -24,8 +25,8 @@ function logout(): void {
   <div class="mx-auto max-w-2xl px-4 py-10">
     <Card>
       <CardHeader>
-        <CardTitle>환영합니다, {{ user.name }}님</CardTitle>
-        <CardDescription>{{ user.email }}</CardDescription>
+        <CardTitle>환영합니다, {{ props.user.name }}님</CardTitle>
+        <CardDescription>{{ props.user.email }}</CardDescription>
       </CardHeader>
       <CardContent>
         <p class="text-sm text-muted-foreground">보호된 페이지입니다 — this.requireAuth() 로 지킵니다.</p>

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

@@ -1,23 +1,25 @@
 <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).
-const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
+// 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2). pageProps 는
+// 반응형이라 변수로 받아 props.x 로 접근한다 — 구조분해 금지(결정 99). 로그인
+// 실패로 서버가 같은 페이지를 다시 render 하면 props.error 가 즉시 갱신된다.
+const props = pageProps<'{{APP_NAME}}:session#new'>()
 
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
 // 서버는 redirect(Inertia 응답)로 답하고, 실패 시 같은 페이지를 다시 render 한다.
-const form = useForm({ email: '', password: '', _csrf: csrf })
+const form = useForm({ email: '', password: '', _csrf: props.csrf })
 </script>
 
 <template>
@@ -28,8 +30,8 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
         <CardDescription>계정으로 로그인하세요.</CardDescription>
       </CardHeader>
       <CardContent>
-        <Alert v-if="error" variant="destructive" class="mb-4">
-          <AlertDescription>{{ error }}</AlertDescription>
+        <Alert v-if="props.error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
         <Form @submit="form.post('/session')">
           <FormField label="이메일" :error="form.errors.email">

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

@@ -1,21 +1,22 @@
 <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'
 
-const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'{{APP_NAME}}:registration#new'>()
 
 // 세션 앱 폼 = Inertia SPA 제출(결정 64) — fetch() 로 만들지 않는다.
-const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
+const form = useForm({ name: '', email: '', password: '', _csrf: props.csrf })
 </script>
 
 <template>
@@ -26,8 +27,8 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
         <CardDescription>새 계정을 만드세요.</CardDescription>
       </CardHeader>
       <CardContent>
-        <Alert v-if="error" variant="destructive" class="mb-4">
-          <AlertDescription>{{ error }}</AlertDescription>
+        <Alert v-if="props.error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ props.error }}</AlertDescription>
         </Alert>
         <Form @submit="form.post('/registration')">
           <FormField label="이름" :error="form.errors.name">

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` 검사 19종
+### 2.2 `gaon doctor` 검사 22종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -125,6 +125,9 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 17. `method-override` — `_method` HTTP 메서드 스푸핑 hack(Gaon 미지원 · router.delete 를 쓰라) (결정 89 · 경고)
 18. `csrf-wiring` — 비-GET 라우트(POST/PUT/PATCH/DELETE)가 있는데 `app.config.ts` 에 session 미배선 = CSRF 무방비 (결정 93 · 경고)
 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 판단표
 
@@ -158,6 +161,26 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 위치를 강제하지 않는다 (`agents/async.md` §2). DB 커밋 정합이 필요하면
 서비스 `afterCommit()` 또는 아웃박스.
 
+### 3.5 비동기 배치 (동기 인라인 vs 잡/이벤트/스케줄 · 결정 102)
+
+§3.1~§3.4 가 "로직을 **어느 층**에 둘까"라면, 이 표는 "그 로직을 **동기로 둘까
+비동기로 뺄까**"의 One Way 다. 상세·예시는 `agents/async.md` 서두 판단표.
+
+| 상황 | 배치 | 이유 |
+|---|---|---|
+| 응답에 결과가 **필요** | 요청 인라인 | 사용자가 그 값을 기다린다 |
+| 응답 불필요 · 실패 시 재시도 (메일·알림·웹훅) | **잡** (`domain/jobs/`) | 응답 지연 제거 + 재시도(백오프·DLQ) |
+| 느리거나 불안정한 **외부 API** | **잡** | 이벤트 루프·응답 시간 보호 |
+| **CPU 무거운** 작업 (이미지 리사이즈·리포트·대량 연산) | **잡** | 루프 블로킹 = 이웃 요청 전부 정지 |
+| 트랜잭션 커밋 **파생 효과** | **이벤트 + 아웃박스** (`afterCommit`) | DB 확정과 정합 (롤백 시 발행 취소) |
+| **주기** 작업 (정리·집계·랭킹) | **`domain/schedule.ts`** | 요청과 무관한 시간축 · 리더 1인만 |
+
+**실무 신호**: 요청 중 수백 ms 이상 걸리는 일은 잡 후보. Node 는 싱글 스레드라
+무거운 작업 하나가 이웃 요청을 세운다. **"잡으로 뺀다 = `work` 프로세스로
+옮긴다"** — 인라인은 `serve`(웹)가, 잡·`afterCommit`·`schedule` 은 `work` 가
+처리하므로 웹 응답이 그 무게를 지지 않는다. `gaon doctor` 의 `async-offload`
+가 컨트롤러 인라인 메일·이미지 처리·외부 HTTP 를 경고로 잡는다(결정 103).
+
 ## 4. 검증 루프
 
 작업마다 실행한다:
@@ -165,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       # 정적 검사 19종 (§2.2)
+gaon doctor       # 정적 검사 22종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -5,6 +5,54 @@
 > 대상 패키지: `@gaonjs/async` (파사드 import 는 `gaonjs/async`). 백본 = NATS JetStream ·
 > 실행은 워커 프로세스(`gaon work`).
 
+## 비동기 배치의 One Way 판단표 (결정 102)
+
+`agents/data.md` §5.3 / `AGENTS.md` §3.1 이 **서버 로직을 어느 층**(모델·서비스·
+컨트롤러)에 둘지 정한다면, 이 표는 그 로직을 **동기(요청 인라인)로 둘지 비동기
+(잡·이벤트·스케줄)로 뺄지**를 정한다 — 같은 "정답이 하나" 원칙의 비동기 축이다.
+
+| 상황 | 배치 | 이유 |
+|---|---|---|
+| 응답에 결과가 **필요** | 요청 인라인 | 사용자가 그 값을 기다린다 (조회·검증·생성 결과) |
+| 응답 불필요 · 실패 시 재시도 (메일·알림·웹훅) | **잡** (`domain/jobs/`) | 응답 지연 제거 + 재시도 배터리(백오프·DLQ) |
+| 느리거나 불안정한 **외부 API** 호출 | **잡** | 이벤트 루프·응답 시간 보호 (외부 지연이 응답에 새지 않음) |
+| **CPU 무거운** 작업 (이미지 리사이즈·리포트·대량 연산) | **잡** | 루프 블로킹 = 그 사이 이웃 요청 전부 정지 |
+| 트랜잭션 커밋에 딸린 **파생 효과** | **이벤트 + 아웃박스** (`afterCommit`) | DB 확정과 정합 (롤백 시 발행도 취소 · §4) |
+| **주기** 작업 (정리·집계·랭킹) | **`domain/schedule.ts`** | 요청과 무관한 시간축 · 리더 1인만 실행 |
+
+**실무 신호**: 요청 처리 중 **수백 ms 이상** 걸리는 일은 잡 후보다. Node 는 싱글
+스레드라 무거운 작업 하나가 워커 앞에 이웃 요청을 전부 세운다(head-of-line
+blocking). 확신이 안 서면 "응답에 이 결과가 필요한가?" 만 묻는다 — 아니면 잡이다.
+
+**"잡으로 뺀다 = work 프로세스로 옮긴다".** 운영 프로세스는 3종(§6): `gaon serve`
+(웹 요청) · `gaon work`(잡·리스너·스케줄·아웃박스 릴레이) · `gaon hub`(실시간).
+인라인 코드는 `serve` 안에서 요청 스레드로 돈다. `.later()`·`afterCommit`·
+`schedule.ts` 로 뺀 일은 **`work` 프로세스**가 별도로 처리하므로 웹 응답이 그
+무게를 지지 않는다. 그래서 "느리다/무겁다/실패해도 재시도" 는 전부 `work` 행(行)이다.
+
+각 배치의 정본 예시 (전체 시그니처·옵션은 아래 §1·§4·§5):
+
+```ts
+// 잡 — 응답과 분리해 발행 (메일·알림·이미지 처리 등). 컨트롤러/서비스에서:
+await SendWelcomeMail.later(user.id)   // domain/jobs/sendWelcomeMail.ts (§1)
+```
+
+```ts
+// 파생 효과 — 커밋 뒤에만 나가야 하는 발행은 서비스 afterCommit (§4 아웃박스).
+export const RegisterUser = service(async (input: RegisterInput) => {
+  const user = await User.create(input)
+  afterCommit(() => ResizeAvatar.later(user.id))  // 커밋 성공 후에만 발행
+  return user
+})
+```
+
+```ts
+// 주기 작업 — domain/schedule.ts · 대상은 항상 잡 (§5 · 인라인 함수 금지).
+export default schedule((s) => {
+  s.cron('0 9 * * 1', SendWeeklyReport)  // 매주 월 09:00 · 리더 1인만
+})
+```
+
 ## 정본 규칙
 
 ### 1. 잡 (`job()`) (`packages/async/src/jobs.ts:146-185`)
@@ -209,6 +257,11 @@ async create() {
 
 - **컨트롤러에서 메일·외부 발송 직접 호출 = 함정** — 컨트롤러는 잡
   발행만. nodemailer·resend·@sendgrid/mail 직접 import 금지.
+- **무거운/느린 작업을 요청 인라인에 두면 함정** (판단표 · 결정 102) —
+  이미지 리사이즈(sharp·jimp)·외부 API 호출을 컨트롤러 액션 안에서 동기로
+  하면 응답이 그 무게를 진다. `domain/jobs/` 잡으로 빼고 `.later()` 로 발행한다.
+  `gaon doctor` 의 `async-offload` 가 이 인라인 패턴을 경고로 잡는다(결정 103 ·
+  JSON/API 앱의 정당한 외부 호출은 오탐 방지로 제외).
 - **클래스형 잡·데코레이터(`@Job`·`@Processor`) 금지** — `job()` 함수형만.
 - **잡 파일 위치는 `domain/jobs/`** — 앱 폴더가 아니다 (잡은 도메인
   소속 · 어느 앱에서든 큐잉).
@@ -225,6 +278,8 @@ async create() {
 
 | 결정 | 내용 |
 |---|---|
+| 결정 102 | 비동기 배치 One Way 판단표 (동기 인라인 vs 잡/이벤트/스케줄 · 서두 표) |
+| 결정 103 | doctor `async-offload` 검사 (컨트롤러 인라인 메일·이미지·외부 HTTP 경고) |
 | 결정 32 | 잡 발행 위치 자유 (컨트롤러·서비스·리스너 모두 정합) |
 | 결정 42 | 비동기 테스트 헬퍼 `expectJobProcessed` (`agents/testing.md`) |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |

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

@@ -31,6 +31,13 @@ const props = pageProps<'web:posts#index'>()
 </template>
 ```
 
+- **변수로 받아 `props.x` 로 접근 — 구조분해 금지** (결정 99). `pageProps()` 는
+  반응형 프록시라, 같은 페이지로의 리다이렉트/리로드로 서버가 새 props 를 주면
+  (댓글 작성·삭제 등) 재마운트 없이 화면이 즉시 갱신된다. 하지만
+  `const { posts } = pageProps<...>()` 처럼 구조분해하면 그 순간 값을 한 번
+  읽어 **반응성이 끊긴다**(Vue `defineProps` 를 구조분해하면 안 되는 것과 같은
+  함정). 항상 `const props = pageProps<...>()` 로 받아 `props.posts` 로 쓴다.
+  구조분해는 doctor **pageprops-destructure** 가 잡는다(경고).
 - **라우트 키** = `<app>:<controller>#<action>` (앱 폴더명 · 컨트롤러 파일명
   stem · 소문자 복수 · 결정 55). `apps/web/controllers/posts.ts` 의 `index`
   액션 → `'web:posts#index'`.
@@ -142,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)
 
 ```
@@ -188,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` 로 라벨·
@@ -229,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}` 가 있는지도 확인한다
+(스캐폴드 기본값엔 이미 포함).
 
 ## 정본 예시
 
@@ -290,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('...')` 키도 맞춘다.
@@ -313,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')
@@ -155,12 +166,13 @@ redirect 로 처리한다 — 전체 페이지 리로드도, 별도 REST 엔드
 
 ```ts
 // 로그인 폼 — 제출은 Inertia SPA 방식, 서버는 redirect 로 답한다.
-const { error, csrf } = pageProps<'web:session#new'>()
-const form = useForm({ email: '', password: '', _csrf: csrf })
-// <form @submit.prevent="form.post('/session')">
+// pageProps 는 반응형 — 변수로 받아 props.x 로 접근한다(구조분해 금지 · 결정 99).
+const props = pageProps<'web:session#new'>()
+const form = useForm({ email: '', password: '', _csrf: props.csrf })
+// <form @submit.prevent="form.post('/session')">  ·  실패 시 {{ props.error }} 가 반응형으로 갱신
 
 // HTML <form> 이 못 보내는 메서드(DELETE 등)는 router 로 보낸다.
-router.delete('/session', { headers: { 'x-csrf-token': csrf } })
+router.delete('/session', { headers: { 'x-csrf-token': props.csrf } })
 ```
 
 `?_method=DELETE` 같은 우회는 **서버가 해석하지 않는다** — POST 로 나가
@@ -332,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` |