@gaonjs/cli 0.14.0 → 0.18.0

package/dist/index.js

@@ -17,6 +17,7 @@ import { runNewCommand } from "./commands/new.js";
 import { runConsoleCommand } from "./commands/console.js";
 import { runTestCommand } from "./commands/test.js";
 import { runGenerateAuthCommand } from "./generate.js";
+import { runGenerateUiKitCommand } from "./uikit.js";
 import { runGenerateCommand } from "./commands/g.js";
 import { runHubCommand } from "./hub.js";
 import { runServeCommand } from "./serve.js";
@@ -25,7 +26,7 @@ import { runJobsCommand } from "./jobs.js";
 import { runDbCommand } from "./commands/db.js";
 import { runDoctorCommand } from "./doctor.js";
 import { runMcpCommand } from "./commands/mcp.js";
-export { startDev, resolveDevLayout, } from "./dev.js";
+export { startDev, resolveDevLayout, regenerateGaonOnce, } from "./dev.js";
 export { runDevCommand } from "./commands/dev.js";
 export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, } from "./dev/index.js";
 export { runCheckCommand, } from "./commands/check.js";
@@ -33,15 +34,19 @@ export { runNewCommand } from "./commands/new.js";
 export { runConsoleCommand } from "./commands/console.js";
 export { runTestCommand } from "./commands/test.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, } from "./generate.js";
+export { writeUiKitScaffold, writeUiKitFiles, uiKitScaffoldFiles, authUiKitFiles, runGenerateUiKitCommand, } from "./uikit.js";
 export { runGenerateCommand, planScaffold, parseGenerateArgs, } from "./commands/g.js";
 export { runHubCommand } from "./hub.js";
 export { runServeCommand } from "./serve.js";
+// dev 전용 라이브 헬스(결정 69). serve(--dev)가 등록하고, 브라우저 e2e 층이
+// serve --dev 를 재현하기 위해 재사용한다.
+export { computeHealth, DEV_HEALTH_PATH, } from "./dev/health.js";
 export { runWorkCommand } from "./work.js";
 export { runJobsCommand } from "./jobs.js";
 export { runDbSeedCommand, loadSeed } from "./db.js";
 export { runDbCommand, } from "./commands/db.js";
 export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, } from "./db/index.js";
-export { runDoctorCommand, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
+export { runDoctorCommand, computeDoctorResult, runDoctor, runDoctorFix, renderFixHuman, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, } from "./doctor.js";
 export { FIXERS, FIXER_CAPABILITIES, fixDependencyDirection, fixDomainToSharedTypeOnly, } from "./doctor/fixers/index.js";
 export { loadDomain } from "./domain.js";
 /** `--json` 출력용 구조화 리포트. */
@@ -98,7 +103,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        정적 검사 (13 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선)",
+        "    gaon doctor        정적 검사 (14 검사 · 응답 혼용·N+1·의존·커넥션·마이그·컴포저블 순수·자동 import·파일명/컬럼 관례·인증 배선·UI 킷 배선)",
         "    gaon doctor --json                        자동화용 JSON 출력",
         "    gaon doctor --check=n-plus-one,connections  선택 검사만 실행",
         "    gaon doctor --fix                         기계 정정 가능한 위반 계획(dry-run · v0.16 §7.5.3)",
@@ -191,7 +196,9 @@ export function runCli(argv, opts = {}) {
         const hostIdx = argv.indexOf("--host");
         const port = portIdx >= 0 ? Number(argv[portIdx + 1]) : undefined;
         const host = hostIdx >= 0 ? argv[hostIdx + 1] : undefined;
-        void runServeCommand({ json: argv.includes("--json"), port, host }).catch((err) => {
+        // --dev: dev 전용 진단 라우트(/_gaon/health) 등록. gaon dev 가 자식
+        // serve 에 넘긴다(결정 69 · dev-only by construction).
+        void runServeCommand({ json: argv.includes("--json"), port, host, dev: argv.includes("--dev") }).catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
             process.stderr.write(`  ✗ gaon serve 실패: ${msg}\n`);
             process.exitCode = 1;
@@ -223,7 +230,7 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
-    // `gaon doctor` — 정적 검사(M9-E · 13 검사). --check=<이름>[,<이름>...] 로
+    // `gaon doctor` — 정적 검사(M9-E · 14 검사). --check=<이름>[,<이름>...] 로
     // 선택 실행, --json 은 자동화 파싱용.
     // exit code (M9-E-Fix): fatal → 2(사용자 오류) / errors > 0 → 1 / 그 외 → 0.
     if (argv[0] === "doctor") {
@@ -346,6 +353,13 @@ export function runCli(argv, opts = {}) {
             process.exitCode = code;
             return;
         }
+        if (argv[1] === "ui-kit" || argv[1] === "ui") {
+            const appIdx = argv.indexOf("--app");
+            const app = appIdx >= 0 ? argv[appIdx + 1] : undefined;
+            const code = runGenerateUiKitCommand({ app, json: argv.includes("--json") });
+            process.exitCode = code;
+            return;
+        }
         const known = ["controller", "model", "page", "job", "app"];
         const type = argv[1];
         if (type && known.includes(type)) {
@@ -390,7 +404,7 @@ export function runCli(argv, opts = {}) {
             return;
         }
         process.stderr.write(`  ✗ 알 수 없는 제너레이터: ${argv[1] ?? "(없음)"}\n` +
-            `  → 현재 지원: gaon g auth | controller | model | page | job | app\n` +
+            `  → 현재 지원: gaon g auth | ui-kit | controller | model | page | job | app\n` +
             `  → 옵션: --app <이름> · --overwrite · --json\n`);
         process.exitCode = 1;
         return;

package/dist/scaffold/app-wiring.d.ts

@@ -0,0 +1,12 @@
+import type { ScaffoldFile } from './controller.js';
+/**
+ * 대상 앱의 프론트 배선 파일(main.ts·style.css·index.html)을 web 정본에서
+ * 파생해 반환한다. 실제 쓰기는 writeScaffold/writeUiKitFiles 가 담당(멱등).
+ */
+export declare function appWiringFiles(app: string, projectName: string): ScaffoldFile[];
+/** 배선 파일 3종의 대상 경로(존재 검사용). */
+export declare function appWiringPaths(app: string): string[];
+/** 대상 앱에 Tailwind 배선(style.css + main.ts 의 style.css import)이 있는지. */
+export declare function hasAppWiring(cwd: string, app: string): boolean;
+/** 프로젝트 package.json 의 name — 배선 title 치환용. 없으면 'app'. */
+export declare function readProjectName(cwd: string): string;

package/dist/scaffold/app-wiring.js

@@ -0,0 +1,68 @@
+// @gaonjs/cli · scaffold · app-wiring — 앱 프론트 배선 (결정 76)
+//
+// 새 앱(`gaon g app admin`)과 web 앱(`gaon new`)이 프론트 배선에서 동등해야
+// 한다: Tailwind CSS 파이프라인(style.css)·Vite 진입(main.ts·index.html).
+// 이 배선이 없으면 그 앱에서 `gaon g ui-kit --app admin` 으로 심은 UI 킷
+// 컴포넌트가 Tailwind 유틸을 못 받아 스타일 없이 렌더된다(결정 74·75).
+//
+// 단일 소스: web 앱의 정본 템플릿(templates/project/apps/web/{main.ts,style.css,
+// index.html}.tpl)을 그대로 읽어 `{{PROJECT_NAME}}` 만 치환하고 대상 앱으로
+// 재타겟한다. style.css 는 앱 무관(토큰만)이라 web 과 바이트 동일하고, main.ts·
+// index.html 은 프로젝트명 title 만 다르다 — 템플릿을 복제하지 않아 드리프트가
+// 없다(결정 76).
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderTemplate, templateDir } from '../templates/index.js';
+/** web 정본 템플릿을 대상 앱으로 재타겟하는 배선 파일 3종의 원본 경로. */
+const WIRING = [
+    { tpl: 'apps/web/main.ts.tpl', out: 'main.ts' },
+    { tpl: 'apps/web/style.css.tpl', out: 'style.css' },
+    { tpl: 'apps/web/index.html.tpl', out: 'index.html' },
+];
+/**
+ * 대상 앱의 프론트 배선 파일(main.ts·style.css·index.html)을 web 정본에서
+ * 파생해 반환한다. 실제 쓰기는 writeScaffold/writeUiKitFiles 가 담당(멱등).
+ */
+export function appWiringFiles(app, projectName) {
+    const base = templateDir();
+    const tokens = { projectName, gaonjsVersion: readGaonjsVersion() };
+    return WIRING.map(({ tpl, out }) => {
+        const raw = readFileSync(join(base, tpl), 'utf8');
+        // 주석 안 `apps/web/…` 경로 표기를 대상 앱으로 맞춘다(import 는 상대라 무관).
+        const retargeted = renderTemplate(raw, tokens).replaceAll('apps/web/', `apps/${app}/`);
+        return { path: `apps/${app}/${out}`, contents: retargeted };
+    });
+}
+/** 배선 파일 3종의 대상 경로(존재 검사용). */
+export function appWiringPaths(app) {
+    return WIRING.map(({ out }) => `apps/${app}/${out}`);
+}
+/** 대상 앱에 Tailwind 배선(style.css + main.ts 의 style.css import)이 있는지. */
+export function hasAppWiring(cwd, app) {
+    const styleCss = join(cwd, 'apps', app, 'style.css');
+    const mainTs = join(cwd, 'apps', app, 'main.ts');
+    if (!existsSync(styleCss) || !existsSync(mainTs))
+        return false;
+    const css = readFileSync(styleCss, 'utf8');
+    const main = readFileSync(mainTs, 'utf8');
+    return /@tailwind\b/.test(css) && /['"]\.\/style\.css['"]/.test(main);
+}
+/** 프로젝트 package.json 의 name — 배선 title 치환용. 없으면 'app'. */
+export function readProjectName(cwd) {
+    return readPackageField(cwd, (pkg) => (typeof pkg.name === 'string' ? pkg.name : undefined)) ?? 'app';
+}
+/** 설치된 gaonjs 버전(배선 템플릿엔 미사용이나 렌더 계약상 채운다). */
+function readGaonjsVersion() {
+    return '';
+}
+function readPackageField(cwd, pick) {
+    const pj = join(cwd, 'package.json');
+    if (!existsSync(pj))
+        return undefined;
+    try {
+        return pick(JSON.parse(readFileSync(pj, 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/serve.d.ts

@@ -5,6 +5,12 @@ export interface ServeCommandOptions {
     readonly port?: number;
     /** 리슨 호스트. 우선순위: 옵션 > config.web.host > '0.0.0.0'. */
     readonly host?: string;
+    /**
+     * dev 모드(gaon dev 자식). true 면 dev 전용 진단 라우트(/_gaon/health)를
+     * 등록한다. 운영 serve 는 이 플래그 없이 실행되어 진단 라우트가 노출되지
+     * 않는다(결정 69 · dev-only by construction).
+     */
+    readonly dev?: boolean;
     /** 프로세스 시그널(테스트 주입). 기본 process. */
     readonly signals?: {
         on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;

package/dist/serve.js

@@ -14,6 +14,7 @@
 import { loadDotEnv } from '@gaonjs/core';
 import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
+import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
 function humanEvent(e) {
     switch (e.kind) {
         case 'starting': {
@@ -54,6 +55,14 @@ export async function runServeCommand(opts = {}) {
     const port = opts.port ??
         config.web?.port ??
         (process.env.PORT ? Number(process.env.PORT) : 3000);
+    // dev 전용 진단 라우트(결정 69). listen 전에 등록한다 — 운영 serve 는
+    // opts.dev 가 없어 등록되지 않으므로 /_gaon/health 는 production 에 없다.
+    // wired.app 은 여기서 FastifyInstance 로 해상되므로(cli 는 fastify 타입을
+    // 직접 의존하지 않는다) 라우트 등록은 serve 층에서 인라인으로 한다.
+    if (opts.dev) {
+        const healthCtx = { cwd, config, apps: wired.apps, nats: wired.nats, port, host };
+        wired.app.get(DEV_HEALTH_PATH, async () => computeHealth(healthCtx));
+    }
     await wired.app.listen({ host, port });
     const displayHost = host === '0.0.0.0' ? 'localhost' : host;
     emit({ kind: 'listening', host, port, url: `http://${displayHost}:${port}` });

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

@@ -1,5 +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'
 
 // dashboard#show 의 render props — user 는 직렬화되며 passwordDigest 는 없다(§4.2).
 const { user, csrf } = pageProps<'{{APP_NAME}}:dashboard#show'>()
@@ -14,9 +21,18 @@ function logout(): void {
 </script>
 
 <template>
-  <main>
-    <h1>환영합니다, {{ user.name }}님</h1>
-    <p>{{ user.email }}</p>
-    <button type="button" @click="logout">로그아웃</button>
-  </main>
+  <div class="mx-auto max-w-2xl px-4 py-10">
+    <Card>
+      <CardHeader>
+        <CardTitle>환영합니다, {{ user.name }}님</CardTitle>
+        <CardDescription>{{ user.email }}</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p class="text-sm text-muted-foreground">보호된 페이지입니다 — this.requireAuth() 로 지킵니다.</p>
+      </CardContent>
+      <CardFooter>
+        <Button variant="outline" @click="logout">로그아웃</Button>
+      </CardFooter>
+    </Card>
+  </div>
 </template>

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

@@ -1,5 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm } 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'
 
 // 컨트롤러 session#new 의 render props 타입이 그대로 흐른다(§6.2).
 const { error, csrf } = pageProps<'{{APP_NAME}}:session#new'>()
@@ -10,12 +21,30 @@ const form = useForm({ email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form @submit.prevent="form.post('/session')">
-    <h1>로그인</h1>
-    <p v-if="error" class="error">{{ error }}</p>
-    <label>이메일 <input v-model="form.email" type="email" required /></label>
-    <label>비밀번호 <input v-model="form.password" type="password" required /></label>
-    <button type="submit" :disabled="form.processing">로그인</button>
-    <a href="/registration/new">회원가입</a>
-  </form>
+  <div class="mx-auto flex min-h-[70vh] max-w-sm items-center px-4">
+    <Card class="w-full">
+      <CardHeader>
+        <CardTitle>로그인</CardTitle>
+        <CardDescription>계정으로 로그인하세요.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Alert v-if="error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ error }}</AlertDescription>
+        </Alert>
+        <Form @submit="form.post('/session')">
+          <FormField label="이메일" :error="form.errors.email">
+            <Input v-model="form.email" type="email" required />
+          </FormField>
+          <FormField label="비밀번호" :error="form.errors.password">
+            <Input v-model="form.password" type="password" required />
+          </FormField>
+          <Button type="submit" class="w-full" :disabled="form.processing">로그인</Button>
+        </Form>
+        <p class="mt-4 text-center text-sm text-muted-foreground">
+          계정이 없으신가요?
+          <a href="/registration/new" class="font-medium text-primary underline-offset-4 hover:underline">회원가입</a>
+        </p>
+      </CardContent>
+    </Card>
+  </div>
 </template>

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

@@ -1,5 +1,16 @@
 <script setup lang="ts">
 import { pageProps, useForm } 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'
 
 const { error, csrf } = pageProps<'{{APP_NAME}}:registration#new'>()
 
@@ -8,13 +19,33 @@ const form = useForm({ name: '', email: '', password: '', _csrf: csrf })
 </script>
 
 <template>
-  <form @submit.prevent="form.post('/registration')">
-    <h1>회원가입</h1>
-    <p v-if="error" class="error">{{ error }}</p>
-    <label>이름 <input v-model="form.name" required /></label>
-    <label>이메일 <input v-model="form.email" type="email" required /></label>
-    <label>비밀번호 <input v-model="form.password" type="password" required /></label>
-    <button type="submit" :disabled="form.processing">회원가입</button>
-    <a href="/session/new">로그인</a>
-  </form>
+  <div class="mx-auto flex min-h-[70vh] max-w-sm items-center px-4">
+    <Card class="w-full">
+      <CardHeader>
+        <CardTitle>회원가입</CardTitle>
+        <CardDescription>새 계정을 만드세요.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Alert v-if="error" variant="destructive" class="mb-4">
+          <AlertDescription>{{ error }}</AlertDescription>
+        </Alert>
+        <Form @submit="form.post('/registration')">
+          <FormField label="이름" :error="form.errors.name">
+            <Input v-model="form.name" required />
+          </FormField>
+          <FormField label="이메일" :error="form.errors.email">
+            <Input v-model="form.email" type="email" required />
+          </FormField>
+          <FormField label="비밀번호" :error="form.errors.password">
+            <Input v-model="form.password" type="password" required />
+          </FormField>
+          <Button type="submit" class="w-full" :disabled="form.processing">회원가입</Button>
+        </Form>
+        <p class="mt-4 text-center text-sm text-muted-foreground">
+          이미 계정이 있으신가요?
+          <a href="/session/new" class="font-medium text-primary underline-offset-4 hover:underline">로그인</a>
+        </p>
+      </CardContent>
+    </Card>
+  </div>
 </template>

package/dist/templates/auth/registration.controller.ts.tpl

@@ -5,7 +5,7 @@ import { User } from '../../../domain/models/User.js'
 export default controller({
   // GET /registration/new — 회원가입 폼
   async new() {
-    return this.render('auth/Signup', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Signup', { error: null as string | null, csrf: this.csrfToken() })
   },
   // POST /registration — 회원가입
   async create() {

package/dist/templates/auth/session.controller.ts.tpl

@@ -5,7 +5,7 @@ import { User } from '../../../domain/models/User.js'
 export default controller({
   // GET /session/new — 로그인 폼
   async new() {
-    return this.render('auth/Login', { error: null as string | null, csrf: this.csrfToken() })
+    return this.render('Auth/Login', { error: null as string | null, csrf: this.csrfToken() })
   },
   // POST /session — 로그인
   async create() {
@@ -16,7 +16,7 @@ export default controller({
       this.auth.login(user)
       return this.redirect('/dashboard')
     }
-    return this.render('auth/Login', {
+    return this.render('Auth/Login', {
       error: '이메일 또는 비밀번호가 올바르지 않습니다.' as string | null,
       csrf: this.csrfToken(),
     })

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` 검사 13종
+### 2.2 `gaon doctor` 검사 14종
 
 1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
 2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
@@ -119,6 +119,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 11. `model-filename` — 모델 파일명 PascalCase 관례 (결정 32·46 · `--fix` 지원)
 12. `page-filename` — Vue 페이지 파일명 PascalCase 관례 (결정 32·46)
 13. `auth-wiring` — requireAuth/this.auth 사용 ↔ `app.config.ts` 인증 배선 (결정 59)
+14. `ui-kit-wiring` — UI 킷 컴포넌트 import ↔ `apps/<앱>/style.css` Tailwind 배선 (결정 76 · 경고)
 
 ## 3. 로직 배치 One Way 판단표
 
@@ -159,7 +160,7 @@ Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍
 ```bash
 gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
 gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
-gaon doctor       # 정적 검사 13종 (§2.2)
+gaon doctor       # 정적 검사 14종 (§2.2)
 ```
 
 ### 4.1 CLI 명령 (전 명령 `--json` 지원)

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

@@ -36,8 +36,9 @@ Gaon 프레임웍 문서: https://gaonjs.dev
 9. **실시간은 v1 포함**(§7): 웹서버 ↔ 허브는 TCP 지속 연결 · NATS 는
    broadcast 전용(errata E-2). 운영 프로세스는 serve·work·hub 3종.
 10. **인증·폼은 Inertia SPA**(§6 · SSR 아님). 로그인/회원가입은
-    `this.render('auth/Login')` + `Inertia.post()` → 서버 redirect.
-    REST + `fetch()` 는 API 앱(JWT) 전용.
+    `this.render('Auth/Login')` + `gaonjs/vue` 의 `useForm(...).post()`
+    (DELETE 등은 `router`) → 서버 redirect(결정 64). REST + `fetch()`
+    는 API 앱(JWT) 전용.
 11. **컴포저블·레이아웃**(errata E-5): 컴포저블은 컴포넌트와 대칭
     (`apps/<앱>/composables/` + `shared/composables/`, `use` 접두사).
     shared 컴포저블은 인자로만 받는 순수 로직(api·pageProps 금지).

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

@@ -115,21 +115,29 @@ await OrderPlaced.emit({ orderId: 1n })
 ### 4. 아웃박스 (트랜잭션 정합)
 
 이벤트를 DB 트랜잭션과 **원자적으로** 발행하려면 아웃박스를 쓴다.
-`runInTransaction` 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스
-테이블에 스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에
-발행한다. 트랜잭션이 롤백되면 이벤트도 사라진다.
+트랜잭션 안에서 발행한 이벤트는 같은 트랜잭션의 아웃박스 테이블에
+스테이징되고, 트랜잭션이 커밋돼야 릴레이가 실제로 NATS 에 발행한다.
+트랜잭션이 롤백되면 이벤트도 사라진다. `service()` 본문 전체가 한
+트랜잭션이므로(§서비스), 본문 안 `emit` 이 곧 아웃박스 스테이징이다.
 
 ```ts
-import { runInTransaction } from 'gaonjs/async'
+// domain/services/placeOrder.ts — service() 본문 = 한 트랜잭션.
+import { service } from 'gaonjs/service'
+import { Order } from '../models/Order.js'
+import { OrderPlaced } from '../events/orderPlaced.js'
 
-await runInTransaction(async () => {
-  await Order.create({ /* … */ })
-  await OrderPlaced.emit({ orderId })   // 커밋돼야 실제 발행됨
+export const PlaceOrder = service(async (input: { name: string }) => {
+  const order = await Order.create(input)
+  await OrderPlaced.emit({ orderId: order.id })   // 트랜잭션 안 → 아웃박스 스테이징 · 커밋돼야 발행
+  return order
 })
 ```
 
 - 트랜잭션 안의 `emit` 은 `AsyncLocalStorage` 로 투명하게 감지돼
   아웃박스에 스테이징된다(별도 API 호출 불필요).
+- 저수준 원시는 `runInTransaction(db, fn)`(커넥션을 넘긴다) — `service()`
+  가 내부에서 이를 쓴다. 대부분의 도메인 코드는 `service()` 본문에서
+  emit 하거나, "커밋 후 즉시 발행"이면 `afterCommit(fn)`(§서비스)을 쓴다.
 - 릴레이(`gaon work` 내장)가 `SKIP LOCKED` 로 아웃박스를 폴링해 발행
   한다 (기본 폴 1000ms · 배치 100).
 - at-least-once — 발행 후 표시하므로 중복 가능성이 있고, dedup(msgID)이

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

@@ -151,6 +151,78 @@ Nuxt 식 자동 import 는 넣지 않는다. 모든 컴포넌트·컴포저블
 import 한다. `gaon doctor` 의 **no-auto-import** 검사가 자동 import
 설정을 잡는다.
 
+### 7. 랜딩·라이브 헬스 (결정 69 · 70)
+
+`gaon new` 첫 화면(`apps/web/pages/Home/Index.vue`)은 라이브 상태 랜딩이다 — 다크
+헤더 레이아웃(`layouts/Default.vue`) + 실 상태 카드(WEB·DATABASE·HUB·DOCTOR) + 동적
+다음 단계 + 실 `routes.ts` 코드 블록. 상태는 **하드코딩하지 않는다** — dev 전용
+엔드포인트 `/_gaon/health` 를 컴포저블(`composables/useGaonHealth.ts`)로 읽어 바인딩한다.
+이 엔드포인트는 `gaon dev` 에서만 등록되고(운영 빌드엔 없음), 404 면 컴포저블이
+`available=false` 로 우아하게 degrade 한다.
+
+- **HUB 카드는 실 introspection(결정 71)** — jobs = JetStream 스트림 대기(pending)
+  수 · channels = 프레즌스 KV 권위의 채널별 실 접속자 수. 조회 실패·미접속을 0/true
+  로 가장하지 않는다(과대 약속 금지) — 버킷·스트림 미생성이면 각각 null 로 degrade.
+- **스타일은 Tailwind 유틸 + UI 킷(결정 74·75)** — 스캐폴드는 Tailwind
+  (`tailwind.config.ts`·`postcss.config.js`·`apps/<앱>/style.css`)를 편입한다.
+  랜딩·auth 페이지는 Tailwind 유틸과 UI 킷 컴포넌트(§8)로 그린다(결정 69 의
+  scoped-CSS 미편입 방침은 결정 74 로 뒤집혔다).
+- **auth 링크는 수동(결정 70)** — `gaon g auth` 는 auth 페이지·라우트만 신설하고
+  랜딩·레이아웃 nav 를 편집하지 않는다. 헤더에 로그인 링크를 두려면 `Default.vue`
+  의 nav 에 `<a href="/session/new">로그인</a>` 을 직접 추가한다(Rails 관례).
+- **auth 페이지 경로 = `pages/Auth/`(PascalCase)** — `gaon g auth` 는 `Auth/Login.vue`
+  ·`Auth/Signup.vue` 를 내고 컨트롤러는 `this.render('Auth/Login')` 로 부른다.
+  소문자 `auth/` 는 doctor page-filename 이 잡는다(결정 32·46).
+
+### 8. UI 킷 (결정 74·75 · shadcn 참조 · 복사-소유)
+
+`gaon new` 는 기본 앱에 UI 킷을 심고(배터리 포함), `gaon g ui-kit [--app <앱>]`
+로 다른 앱에도 추가한다. 컴포넌트는 **프로젝트에 복사된 여러분 코드**다 — npm
+의존이 아니라 파일이므로 자유롭게 고친다(shadcn 방식). 외부 런타임 의존이 없다
+(clsx·tailwind-merge·cva·reka-ui 미도입 · `cn` 은 자작 · Dialog/Sheet 는 Teleport+
+Transition 자작).
+
+배치·import:
+
+```
+apps/<앱>/lib/utils.ts            # cn() — 조건부 클래스 병합
+apps/<앱>/components/ui/*.vue      # Button·Input·Label·Badge·Card…·Alert…·Form…·Dialog·Sheet
+```
+
+```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'
+</script>
+
+<template>
+  <Card>
+    <CardContent>
+      <Button variant="default">저장</Button>       <!-- variant·size 로 모양 선택 -->
+    </CardContent>
+  </Card>
+</template>
+```
+
+- **폼은 UI 킷 Form + gaonjs `useForm`(결정 64)** — `Form` 은 얇은 `<form>` 래퍼로
+  `@submit` 을 `useForm` 의 `post/put/delete` 로 넘긴다. vee-validate 를 끌어오지
+  않는다(검증·상태는 `useForm`). `FormField label error` + `FormMessage` 로 라벨·
+  오류를 붙이고, `:error="form.errors.<field>"` 로 서버 검증을 표시한다.
+- **`class` 는 폴스루로 병합** — 단일 루트 컴포넌트는 `<Button class="w-full">` 처럼
+  넘긴 클래스가 루트로 흘러간다(별도 `class` prop 선언 없음). `cn` 은 충돌 클래스
+  자동 해소를 하지 않는다 — 오버라이드가 잦으면 tailwind-merge 를 설치해 `cn` 만 교체.
+- **디자인 토큰은 `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** 이 경고한다.
+
 ## 정본 예시
 
 ```vue
@@ -186,7 +258,7 @@ async function runSearch(q: string) {
 - **shared 컴포넌트/컴포저블에서 `pageProps`/`api` 호출 금지** — doctor
   shared-composable-purity 위반. 데이터는 props/인자로.
 - **Vue 페이지에서 `fetch()` 로 폼 구현 금지** — 세션 앱 폼은
-  `Inertia.post()` (`agents/web.md` §4).
+  `gaonjs/vue` 의 `useForm(...).post()` (`agents/web.md` §4 · 결정 64).
 - **레이아웃을 shared 에 두지 않는다** — 앱별이 정상.
 - **페이지 파일명은 PascalCase** — `pages/Posts/Index.vue`(폴더 세그먼트도
   Route 이름). 소문자(`posts/index.vue`)는 doctor **page-filename** 이 잡는다
@@ -203,4 +275,10 @@ async function runSearch(q: string) {
 | 결정 25 (E-5) | 컴포저블·레이아웃 관례 · 프론트 로직 배치 3규칙 · 자동 import 금지 |
 | 결정 37 | bigint PK 컨트롤러 `String()` 정규화 |
 | 결정 46 | doctor page-filename(페이지 PascalCase)·model/column 검사 3종 |
+| 결정 69 | 랜딩 정본(라이브 헬스 카드 · 다크 헤더 레이아웃 · 실 상태 · 코드 블록) |
+| 결정 70 | auth 통합 = 수동(`gaon g auth` 는 랜딩·nav 를 안 건드림 · Rails 관례) |
+| 결정 71 | HUB 카드 실 introspection(jobs=스트림 pending · channels=프레즌스 실 접속자 · 과대 약속 금지) |
+| 결정 74 | Tailwind 스캐폴드 편입(tailwind.config.ts·postcss.config.js·style.css · 결정 69 scoped-CSS 방침 뒤집기) |
+| 결정 75 | shadcn 식 UI 킷(`gaon g ui-kit` · 복사-소유 · Vue 3 신작 · 외부 런타임 의존 0) |
+| 결정 76 | 멀티앱 UI 킷 배선 자동화(`g app`·`g ui-kit --app` 이 앱별 Tailwind 배선 동봉·멱등 보정 · doctor ui-kit-wiring) |
 | E-3 §C | 타입드 `api()` 클라이언트 (routes.d.ts 브리지 재사용) |