@gaonjs/cli 0.4.0 → 0.10.0

package/dist/scaffold/index.d.ts

@@ -2,7 +2,8 @@ export type { ScaffoldFile } from './controller.js';
 export { controllerScaffold } from './controller.js';
 export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
 export { pageScaffold } from './page.js';
-export { jobScaffold } from './job.js';
+export { jobScaffold, jobTestScaffold } from './job.js';
+export { appScaffoldFiles, validateAppName } from './app.js';
 export { inflectModel, toCamel, toPascal, singularize, pluralize, type ModelNames, } from './inflect.js';
 import type { ScaffoldFile } from './controller.js';
 export interface WriteResult {

package/dist/scaffold/index.js

@@ -8,7 +8,8 @@ import { dirname, join, resolve } from 'node:path';
 export { controllerScaffold } from './controller.js';
 export { modelScaffold, modelScaffoldFiles, schemaScaffold } from './model.js';
 export { pageScaffold } from './page.js';
-export { jobScaffold } from './job.js';
+export { jobScaffold, jobTestScaffold } from './job.js';
+export { appScaffoldFiles, validateAppName } from './app.js';
 export { inflectModel, toCamel, toPascal, singularize, pluralize, } from './inflect.js';
 /**
  * 파일 계획을 실제로 쓴다. 기본은 기존 파일 skip(멱등 · 사고 방지).

package/dist/scaffold/job.d.ts

@@ -1,3 +1,8 @@
 import type { ScaffoldFile } from './controller.js';
 /** 잡 이름(파스칼) → 파일·잡명 파생. */
 export declare function jobScaffold(pascalName: string): ScaffoldFile;
+/**
+ * 잡 통합 테스트 골격 (결정 42) — 발행→실 처리 검증을 `expectJobProcessed`
+ * 한 호출로. 실 NATS 필수(§9 · 목업 금지) — `docker compose up -d nats`.
+ */
+export declare function jobTestScaffold(pascalName: string): ScaffoldFile;

package/dist/scaffold/job.js

@@ -44,3 +44,38 @@ export function jobScaffold(pascalName) {
     ];
     return { path: `domain/jobs/${camel}.ts`, contents: lines.join('\n') };
 }
+/**
+ * 잡 통합 테스트 골격 (결정 42) — 발행→실 처리 검증을 `expectJobProcessed`
+ * 한 호출로. 실 NATS 필수(§9 · 목업 금지) — `docker compose up -d nats`.
+ */
+export function jobTestScaffold(pascalName) {
+    const trimmed = pascalName.trim();
+    if (!trimmed) {
+        throw new Error(`[gaon g job] 잡 이름이 비어 있습니다. 예: gaon g job SendEmail`);
+    }
+    const pascal = trimmed
+        .split(/[_\-\s]+/)
+        .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : ''))
+        .join('');
+    const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+    const lines = [
+        `// ${pascal} 잡 통합 테스트 — gaon g job (결정 42).`,
+        `// 실 NATS JetStream 필수(§9 · 목업 금지): docker compose up -d nats`,
+        `import { describe, it } from 'vitest'`,
+        `import { connectNats, expectJobProcessed } from 'gaonjs/testing'`,
+        `import ${camel} from '../../domain/jobs/${camel}.js'`,
+        ``,
+        `describe('${pascal} (실 NATS JetStream)', () => {`,
+        `  it('발행한 잡이 워커에서 처리된다', async () => {`,
+        `    const nats = await connectNats(process.env.NATS_URL ?? 'nats://localhost:4222')`,
+        `    try {`,
+        `      await expectJobProcessed(${camel}, () => ${camel}.later({ id: 'test' }), { nats })`,
+        `    } finally {`,
+        `      await nats.close()`,
+        `    }`,
+        `  })`,
+        `})`,
+        ``,
+    ];
+    return { path: `test/integration/${camel}.integration.test.ts`, contents: lines.join('\n') };
+}

package/dist/scaffold/model.js

@@ -4,13 +4,13 @@
 // 스키마는 errata E-4 신규 컬럼 타입(decimal · enum · uuid)과 수식어(unique ·
 // nullable · default) 예시를 담아 새 개발자가 바로 참고할 수 있게 한다.
 //
-// 파일 위치 (CLAUDE.md §2 · rule 5):
-//  · 스키마 → domain/schema/<name>.ts (테이블 정의 · tables.d.ts 원천)
-//  · 모델   → domain/models/<name>.ts (Active Record · scopes/methods)
+// 파일 위치 (CLAUDE.md §2 · rule 5 · 파일 네이밍 표 v0.16 §3.4):
+//  · 스키마 → domain/schema/<posts>.ts (파일명 = 테이블명 · camelCase 복수)
+//  · 모델   → domain/models/<Post>.ts  (파일명 = 모델명 · PascalCase 단수)
 // 앱→도메인 import 만 허용되므로 이 위치가 유일한 정답이다.
 /** 스키마 스캐폴드 — E-4 컬럼 타입 예시를 함께 담는다. */
 export function schemaScaffold(names) {
-    const { pascal, camel, plural } = names;
+    const { pascal, plural } = names;
     const lines = [
         `// ${pascal} 스키마 — gaon g model (M9-B).`,
         `// errata E-4 예시: unique · default · enum · nullable. 컬럼은 자유롭게 추가/삭제한다.`,
@@ -34,19 +34,19 @@ export function schemaScaffold(names) {
         ``,
     ];
     return {
-        path: `domain/schema/${camel}.ts`,
+        path: `domain/schema/${plural}.ts`,
         contents: lines.join('\n'),
     };
 }
 /** 모델 스캐폴드 — scopes 예시를 담는다(체이닝 진입점 도우미). */
 export function modelScaffold(names) {
-    const { pascal, camel, plural } = names;
+    const { pascal, plural } = names;
     const lines = [
         `// ${pascal} 모델 — gaon g model (M9-B).`,
         `// scopes 는 체인 어느 지점에서든 호출 가능하다(§4.4). E-4 체이닝 예시:`,
         `//   ${pascal}.published().orderBy('createdAt', 'desc').limit(20).all()`,
         `import { model } from 'gaonjs/data'`,
-        `import { ${plural} } from '../schema/${camel}.js'`,
+        `import { ${plural} } from '../schema/${plural}.js'`,
         ``,
         `export const ${pascal} = model(${plural}, {`,
         `  scopes: {`,
@@ -56,7 +56,7 @@ export function modelScaffold(names) {
         ``,
     ];
     return {
-        path: `domain/models/${camel}.ts`,
+        path: `domain/models/${pascal}.ts`,
         contents: lines.join('\n'),
     };
 }

package/dist/templates/auth/auth.wiring.ts.tpl

@@ -1,6 +1,6 @@
 // 인증 배선 — gaon g auth 스캐폴드.
 import type { AuthOptions } from 'gaonjs/web'
-import { User } from '../../domain/models/user.js'
+import { User } from '../../domain/models/User.js'
 
 // 세션에 심긴 userId 로 사용자를 로드한다(§7). web 은 도메인을 loadUser 로 받는다.
 export const loadUser: AuthOptions['loadUser'] = async (id) =>

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

@@ -1,6 +1,6 @@
 // 회원가입 컨트롤러 — gaon g auth 스캐폴드.
 import { controller, hashPassword } from 'gaonjs/web'
-import { User } from '../../../domain/models/user.js'
+import { User } from '../../../domain/models/User.js'
 
 export default controller({
   // GET /registration/new — 회원가입 폼

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

@@ -1,6 +1,6 @@
 // 세션 컨트롤러(로그인/로그아웃) — gaon g auth 스캐폴드.
 import { controller, verifyPassword } from 'gaonjs/web'
-import { User } from '../../../domain/models/user.js'
+import { User } from '../../../domain/models/User.js'
 
 export default controller({
   // GET /session/new — 로그인 폼

package/dist/templates/auth/user.model.ts.tpl

@@ -1,5 +1,5 @@
 // 사용자 모델 — gaon g auth 스캐폴드.
 import { model } from 'gaonjs/data'
-import { users } from '../schema/user.js'
+import { users } from '../schema/users.js'
 
 export const User = model(users, {})

package/dist/templates/index.d.ts

@@ -0,0 +1,23 @@
+/** 생성할 파일 하나 — path 는 프로젝트 루트 기준 상대 경로(POSIX). */
+export interface ProjectFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** 템플릿 렌더 시 치환되는 토큰 값. */
+export interface ProjectTemplateTokens {
+    readonly projectName: string;
+    readonly gaonjsVersion: string;
+}
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export declare function renderTemplate(raw: string, tokens: ProjectTemplateTokens): string;
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export declare function listTemplateFiles(root?: string): string[];
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export declare function renderProjectFiles(tokens: ProjectTemplateTokens): ProjectFile[];
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export declare function templateDir(): string;
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export declare function findUnresolvedTokens(contents: string): string[];

package/dist/templates/index.js

@@ -0,0 +1,66 @@
+// @gaonjs/cli · templates/index.ts — 프로젝트 스캐폴드 템플릿 로더 (M9-F).
+//
+// `gaon new <name>` 이 소비하는 파일 트리. 소스 트리(src/templates/project/*)
+// 를 재귀 스캔해 각 `.tpl` 파일의 최종 경로와 렌더된 내용을 반환한다.
+// 렌더는 `{{TOKEN}}` 리터럴 replaceAll — Vue 의 `{{ }}` 보간과 겹치지 않는
+// 고정 리터럴이라 정규식 없이 안전하다(generate.ts 와 동일 관례).
+//
+// 폴더는 관례상 유지되어야 하지만 git 이 빈 폴더를 추적하지 않으므로
+// `.gitkeep.tpl` 을 두어 실 파일 `.gitkeep` 으로 렌더한다. 최종 경로는
+// `.tpl` 접미사를 벗긴 값이다.
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, posix, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'project');
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export function renderTemplate(raw, tokens) {
+    return raw
+        .replaceAll('{{PROJECT_NAME}}', tokens.projectName)
+        .replaceAll('{{GAONJS_VERSION}}', tokens.gaonjsVersion);
+}
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export function listTemplateFiles(root = TEMPLATE_DIR) {
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            out.push(abs);
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export function renderProjectFiles(tokens) {
+    const paths = listTemplateFiles();
+    return paths.map((abs) => {
+        const rel = relative(TEMPLATE_DIR, abs).split(sep).join(posix.sep);
+        const outPath = rel.endsWith('.tpl') ? rel.slice(0, -'.tpl'.length) : rel;
+        const raw = readFileSync(abs, 'utf8');
+        return { path: outPath, contents: renderTemplate(raw, tokens) };
+    });
+}
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export function templateDir() {
+    return TEMPLATE_DIR;
+}
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export function findUnresolvedTokens(contents) {
+    const re = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g;
+    const found = new Set();
+    for (const m of contents.matchAll(re)) {
+        // Vue 템플릿의 {{ prop }} (소문자·공백 시작) 은 제외 — 위 정규식이 대문자만
+        // 잡으므로 자연스럽게 걸러진다. 남으면 진짜 미치환.
+        found.add(m[1]);
+    }
+    return [...found].sort();
+}

package/dist/templates/index.ts

@@ -0,0 +1,85 @@
+// @gaonjs/cli · templates/index.ts — 프로젝트 스캐폴드 템플릿 로더 (M9-F).
+//
+// `gaon new <name>` 이 소비하는 파일 트리. 소스 트리(src/templates/project/*)
+// 를 재귀 스캔해 각 `.tpl` 파일의 최종 경로와 렌더된 내용을 반환한다.
+// 렌더는 `{{TOKEN}}` 리터럴 replaceAll — Vue 의 `{{ }}` 보간과 겹치지 않는
+// 고정 리터럴이라 정규식 없이 안전하다(generate.ts 와 동일 관례).
+//
+// 폴더는 관례상 유지되어야 하지만 git 이 빈 폴더를 추적하지 않으므로
+// `.gitkeep.tpl` 을 두어 실 파일 `.gitkeep` 으로 렌더한다. 최종 경로는
+// `.tpl` 접미사를 벗긴 값이다.
+
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, posix, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 생성할 파일 하나 — path 는 프로젝트 루트 기준 상대 경로(POSIX). */
+export interface ProjectFile {
+  readonly path: string
+  readonly contents: string
+}
+
+/** 템플릿 렌더 시 치환되는 토큰 값. */
+export interface ProjectTemplateTokens {
+  readonly projectName: string
+  readonly gaonjsVersion: string
+}
+
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), 'project')
+
+/** 템플릿 문자열의 {{TOKEN}} 을 치환한다. 알 수 없는 토큰은 그대로 둔다. */
+export function renderTemplate(raw: string, tokens: ProjectTemplateTokens): string {
+  return raw
+    .replaceAll('{{PROJECT_NAME}}', tokens.projectName)
+    .replaceAll('{{GAONJS_VERSION}}', tokens.gaonjsVersion)
+}
+
+/** 템플릿 폴더를 재귀 스캔해 파일 목록을 만든다(POSIX 경로 · 정렬). */
+export function listTemplateFiles(root: string = TEMPLATE_DIR): string[] {
+  const out: string[] = []
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(abs)
+        continue
+      }
+      if (!entry.isFile()) continue
+      out.push(abs)
+    }
+  }
+  walk(root)
+  return out.sort()
+}
+
+/**
+ * 스캐폴드 파일 전체를 렌더링해 반환한다.
+ * `.tpl` 접미사는 벗기고, `{{PROJECT_NAME}}`·`{{GAONJS_VERSION}}` 을 치환한다.
+ */
+export function renderProjectFiles(tokens: ProjectTemplateTokens): ProjectFile[] {
+  const paths = listTemplateFiles()
+  return paths.map((abs) => {
+    const rel = relative(TEMPLATE_DIR, abs).split(sep).join(posix.sep)
+    const outPath = rel.endsWith('.tpl') ? rel.slice(0, -'.tpl'.length) : rel
+    const raw = readFileSync(abs, 'utf8')
+    return { path: outPath, contents: renderTemplate(raw, tokens) }
+  })
+}
+
+/** 테스트·검증용 — 템플릿 폴더의 절대 경로. */
+export function templateDir(): string {
+  return TEMPLATE_DIR
+}
+
+/** 렌더링된 내용에 미치환 토큰이 남아 있는지 검사(회귀 방지). */
+export function findUnresolvedTokens(contents: string): string[] {
+  const re = /\{\{([A-Z_][A-Z0-9_]*)\}\}/g
+  const found = new Set<string>()
+  for (const m of contents.matchAll(re)) {
+    // Vue 템플릿의 {{ prop }} (소문자·공백 시작) 은 제외 — 위 정규식이 대문자만
+    // 잡으므로 자연스럽게 걸러진다. 남으면 진짜 미치환.
+    found.add(m[1]!)
+  }
+  return [...found].sort()
+}
+

package/dist/templates/project/.env.example.tpl

@@ -0,0 +1,18 @@
+# {{PROJECT_NAME}} 환경 변수 — cp .env.example .env 후 편집.
+# gaon.config.ts 의 env('KEY') 로 참조된다. gaon dev · gaon serve 가 자동 로드.
+
+# DB — docker-compose.yaml 의 postgres 서비스와 정합.
+DATABASE_URL=postgres://{{PROJECT_NAME}}:{{PROJECT_NAME}}@127.0.0.1:5432/{{PROJECT_NAME}}_dev
+
+# Redis — 세션 스토어.
+REDIS_URL=redis://127.0.0.1:6379
+
+# NATS — 실시간·비동기 백본(§7).
+NATS_URL=nats://127.0.0.1:4222
+
+# 세션 · 쿠키 서명 비밀 (32자 이상, 운영은 반드시 교체).
+SESSION_SECRET=change-me-to-a-32-char-random-secret!!
+COOKIE_SECRET=change-me-too-32-char-random-secret!!
+
+# 리슨 포트 (gaon serve --port 로 덮음).
+PORT=3000

package/dist/templates/project/.gitignore.tpl

@@ -0,0 +1,24 @@
+# 의존성 · 빌드 산출물
+node_modules/
+dist/
+*.tsbuildinfo
+
+# 자동 생성 타입 브리지(§6.3) — gaon check / gaon dev 가 재생성한다.
+.gaon/
+
+# 환경 변수
+.env
+.env.local
+.env.*.local
+
+# 로그 · 캐시
+*.log
+.DS_Store
+.cache/
+coverage/
+
+# 에디터
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json

package/dist/templates/project/.npmrc.tpl

@@ -0,0 +1,4 @@
+# pnpm 로컬 설정(선택). 대부분의 pnpm 설정은 pnpm-workspace.yaml 로
+# 이동했다(구 package.json 의 pnpm 필드도 마찬가지). 여기는 로그·레지스트리
+# 처럼 파일 단위로 다르게 둘 수 있는 것만 남긴다.
+loglevel=info

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

@@ -0,0 +1,210 @@
+# AGENTS.md — Gaon 프로젝트 AI 개발자 지침 (코어)
+
+이 문서는 **AI 코딩 에이전트**(Claude · Codex · Cursor · Copilot 등)와
+사람 개발자가 Gaon 프로젝트에서 작업할 때 참조하는 관례의 진입점이다.
+정본은 설계 문서(v0.15 동결 + errata E-1~E-5, v0.16 편입)이며, 관례
+문서는 **2층 구조**다 (결정 40):
+
+- **이 파일 (코어)** — 절대 규칙 · 로직 배치 판단표 · 검증 루프 ·
+  카테고리 색인. 여기엔 요약만 있다.
+- **`agents/*.md` (카테고리)** — 시그니처·체이닝 표·정본 예시·함정의
+  정본. **해당 영역 파일을 만지기 전에 반드시 그 카테고리 문서를 읽는다.**
+
+**대상 프로젝트 = Gaon 프레임웍으로 만든 사용자 프로젝트**(`gaonjs`
+설치 후 `gaon new` 로 생성한 앱).
+
+## 0. 카테고리 색인 — 작업 전에 반드시 읽어라
+
+작업이 아래 영역에 걸치면, 코드를 만지기 **전에** 해당 파일을 읽는다.
+코어에는 요약만 있다 — 메서드 시그니처·표·정본 예시는 전부 카테고리
+파일에 있고, 표에 없는 API 를 추측하면 실패한다.
+
+| 작업 영역 | 먼저 읽을 파일 |
+|---|---|
+| 스키마 · 모델 · 관계 · 쿼리/체이닝 · 서비스 · 마이그레이션 | `agents/data.md` |
+| 라우트 · 컨트롤러 · params · JSON 액션 · 인증/비밀번호 | `agents/web.md` |
+| 페이지 · 컴포넌트 · 컴포저블 · 레이아웃 · `api()` · bigint key | `agents/frontend.md` |
+| 잡 · 이벤트 · 리스너 · 아웃박스 · 스케줄 | `agents/async.md` |
+| 채널 · 프레즌스 · 허브 | `agents/realtime.md` |
+| 테스트 작성·실행 (실 인프라 · `expectJobProcessed`) | `agents/testing.md` |
+| 보안 기본값 · 탈출구(v-html · raw SQL) 사용 | `agents/security.md` |
+
+예: 회원가입 세로 조각(스키마+서비스+잡+컨트롤러+테스트)이면
+`data · web · async · testing` 네 파일을 먼저 읽는다.
+
+## 1. The One Way 원칙
+
+Gaon 의 제1 설계 목표는 **"AI 가 개발을 가장 잘하는 프레임웍"** 이다
+(v0.15 §1.2). 우선순위는 **AI 첫 시도 성공률 > 개발자 편의 > 구현
+편의** — 선택지가 생기면 정답이 하나가 되는 쪽을 고른다.
+
+1. **The One Way** — 모든 문제에 공식 답이 하나. 선택지는 탈출구
+   (escape hatch)로만 남긴다.
+2. **관례가 곧 문서** — 파일 위치·이름이 곧 동작. 설정은 관례를
+   벗어날 때만 쓴다.
+3. **마법은 타입 추론으로** — 데코레이터·DI 컨테이너 없음. 스키마 →
+   모델 → 컨트롤러 → Vue 까지 **타입 추론만**으로 흐른다 (`.gaon/`
+   생성 파일만 예외 · 프레임웍이 관리).
+
+**파일 하나 = 한 개념 · 명시적 import**. Nuxt식 자동 import 는 넣지
+않는다 (errata E-5 §2.4).
+
+## 2. 절대 규칙
+
+1. **TypeScript 전용 · 함수/객체 스타일.** JS 파일 추가 금지, 클래스형·
+   데코레이터 금지 — `model()`·`controller()`·`job()`·`service()`·
+   `channel()` 함수형 API 만.
+2. **파사드 import 만.** 프레임웍 심볼은 `gaonjs/*` (`gaonjs/web`·
+   `gaonjs/data`·`gaonjs/vue`·`gaonjs/async`·`gaonjs/service`·
+   `gaonjs/testing`)에서 import 한다. `@gaonjs/*`(내부 스코프)·
+   `@inertiajs/vue3`(어댑터 내부 의존)는 앱 코드에서 직접 import 금지.
+   (설치명 `gaonjs` · CLI 명령 `gaon` — errata E-1.)
+3. **의존 방향 4규칙** (doctor 강제): ① 앱→`domain/` 허용 ②
+   `domain/`→앱 금지 ③ 앱→앱 금지 ④ 앱→`shared/` 허용 — `shared/` 는
+   앱 import 금지, `domain/` 은 **타입 import 만** (공용 컴포넌트는
+   props 로만 받는 순수 UI).
+4. **보안 기본값(CORS·rate limit·CSRF)은 기본 켬.** 끄는 것은 명시적
+   설정으로만 (`agents/security.md`).
+5. **테스트는 Docker 실인프라 필수** — DB·NATS 목업·인메모리 대체 절대
+   금지 (§9 · `agents/testing.md`).
+6. **인증·폼은 Inertia SPA 방식** (SSR 아님). 폼은 `Inertia.post()` →
+   서버 redirect. REST + `fetch()` 는 **API 앱(JWT) 전용**.
+7. **한 액션은 한 종류 응답만** (render 또는 JSON 또는 redirect —
+   혼용 금지 · doctor response-mixing).
+8. **`.gaon/` 자동 생성 파일 편집 금지** — `routes.d.ts`·`tables.d.ts`
+   는 `gaon check`/`gaon dev` 가 재생성한다.
+
+### 2.1 파일 네이밍 표 (2026-07-24 승인 · 벤치마크 R1 실측 고정)
+
+"Pascal 인가 camel 인가" 를 추측하지 않는다 — 아래 표가 전부다.
+
+| 대상 | 파일명 | 예시 |
+|---|---|---|
+| 모델 | **PascalCase** | `domain/models/Post.ts` |
+| 스키마 | **camelCase** (테이블명) | `domain/schema/posts.ts` · `posts_tags`→`postsTags.ts` |
+| 서비스 | **camelCase** | `domain/services/registerUser.ts` |
+| 잡 | **camelCase** | `domain/jobs/sendWelcomeMail.ts` |
+| 이벤트 | **camelCase** | `domain/events/orderPlaced.ts` |
+| 리스너 | **camelCase** | `domain/listeners/notifyAdmin.ts` |
+| 메일 | **camelCase** | `domain/mails/welcome.ts` |
+| 컨트롤러 | **camelCase** (액션 단위) | `apps/web/controllers/posts.ts` |
+| Vue 페이지 | **PascalCase** (Route 이름) | `apps/web/pages/Posts/Index.vue` |
+| Vue 컴포넌트 | **PascalCase** | `apps/web/components/PostCard.vue` |
+| 컴포저블 | **use** + PascalCase | `apps/web/composables/usePostSearch.ts` |
+| 레이아웃 | **PascalCase** | `apps/web/layouts/Default.vue` |
+| 채널 | **camelCase** | `apps/web/channels/chatMessages.ts` |
+| 마이그레이션 | **timestamp_action** | `db/migrations/20260724_add_posts.ts` |
+
+- 다단어 테이블의 스키마 **파일명**은 camelCase (`posts_tags` →
+  `postsTags.ts`) — 파일 **안**의 `table('posts_tags', …)` 문자열은
+  스네이크 그대로.
+
+### 2.2 `gaon doctor` 검사 9종
+
+1. `response-mixing` — 한 액션 안 render/JSON/redirect 혼용 (E-3)
+2. `n-plus-one` — include 미사용 · loop 안 관계 호출 (E-4)
+3. `dependency-direction` — 의존 방향 4규칙 위반
+4. `connections` — 커넥션 간 belongsTo · service 트랜잭션 (§4.5)
+5. `migration-diff` — 스키마 vs DB 상태 불일치
+6. `shared-composable-purity` — shared 안 `api`/`pageProps` import (결정 25)
+7. `no-auto-import` — 자동 import 설정 (E-5 §2.4)
+8. `schema-filename` — 스키마 파일명 camelCase 관례 (결정 38 · `--fix` 지원)
+9. `agents-doc-index` — 이 문서 색인(§0) ↔ `agents/` 실 파일 불일치 (결정 40)
+
+## 3. 로직 배치 One Way 판단표
+
+### 3.1 서버 로직 (정본 §5.3 원문)
+
+> 1. 한 모델 안에서 끝나는 로직 → **모델 메서드**
+> 2. 여러 모델·외부 API·트랜잭션이 얽히는 작업 흐름 → **`domain/services/`**
+> 3. 컨트롤러에는 비즈니스 로직을 두지 않는다 — HTTP와의 **번역만**
+
+### 3.2 프론트 로직 (errata E-5 §2.1 원문 · 결정 25)
+
+> 1. 컴포저블에는 **프론트 전용 로직만** — UI 상태, 브라우저 API,
+>    `api()` 호출 래핑, 채널 구독 래핑.
+> 2. 비즈니스 로직(도메인 규칙·계산·트랜잭션)은 컴포저블에 두지 않는다
+>    — 서버의 `domain/`(모델 메서드·서비스)에만.
+> 3. 한 컴포넌트 안에서만 쓰는 상태는 컴포저블로 뽑지 않는다 — 그냥
+>    `<script setup>` 에. 컴포저블은 **재사용될 때만**.
+
+### 3.3 데이터 경로 4종 (errata E-3 §2 원문)
+
+| 상황 | 경로 | 근거 |
+|---|---|---|
+| 지금 페이지의 데이터를 다시 받기 (필터 변경·새로고침·무한 스크롤) | **Inertia partial reload** — 같은 액션 재호출, 필요한 props만 | §6.1 |
+| 서버가 먼저 밀어주는 데이터 (알림·채팅·접속자) | **채널/프레즌스** (`agents/realtime.md`) | §7 |
+| 페이지와 무관한 데이터 요청 (자동완성·옵션 조회 등 앱 내부용) | **JSON 액션 + `api()` 클라이언트** (`agents/web.md`·`agents/frontend.md`) | E-3 |
+| 외부에 공개하는 API (모바일 앱·서드파티) | **별도 API 앱 + JWT 옵션** | §3, §7 |
+
+### 3.4 잡 발행 위치 (결정 32)
+
+잡 `.later(...)` 은 **컨트롤러 · 서비스 · 리스너 어디서든** 발행 가능 —
+위치를 강제하지 않는다 (`agents/async.md` §2). DB 커밋 정합이 필요하면
+서비스 `afterCommit()` 또는 아웃박스.
+
+## 4. 검증 루프
+
+작업마다 실행한다:
+
+```bash
+gaon check        # .gaon 재생성 → typecheck + vue-tsc + build (+doctor)
+gaon test         # vitest — DB·NATS 는 실 인프라 (agents/testing.md)
+gaon doctor       # 정적 검사 8종 (§2.2)
+```
+
+### 4.1 CLI 명령 (전 명령 `--json` 지원)
+
+| 명령 | 역할 |
+|---|---|
+| `gaon new <name>` | 프로젝트 스캐폴드 |
+| `gaon dev` | 통합 개발 오케스트레이션 (Docker·`.gaon` 재생성·워처) |
+| `gaon serve` / `work` / `hub` | 운영 프로세스 3종 (웹 · 워커 · 실시간 허브) |
+| `gaon g <type> <name>` | 스캐폴드: `auth`·`controller`·`model`·`page`·`job` |
+| `gaon db <sub>` | `diff`·`migrate`(`down`)·`status`·`reset`·`seed` (`agents/data.md` §10) |
+| `gaon check` / `test` / `doctor` | 검증 루프 |
+| `gaon console` | 프로젝트 컨텍스트 REPL |
+| `gaon jobs` | DLQ 조회·재적재 |
+| `gaon mcp` | 내장 MCP 서버 — 도구: `list_routes`·`get_schema`·`run_migration`·`run_tests`·`read_agent_doc` |
+
+`gaon mcp` 는 프레임웍이 자신을 AI 도구로 노출한다 (§7.5.3) — grep
+으로 더듬는 대신 프레임웍에게 직접 묻는다. `read_agent_doc` 은 §0
+카테고리 문서를 조회한다 (결정 40).
+
+## 5. npm 배포본 (2026-07-23 실측 · `npm view <pkg> version`)
+
+| 패키지 | 버전 | 역할 |
+|---|---|---|
+| `gaonjs` | 0.6.0 | 파사드(설치 단위) · CLI `gaon` |
+| `@gaonjs/cli` | 0.5.0 | 제너레이터·스캐폴딩·명령 라우팅 |
+| `@gaonjs/data` | 0.3.0 | 스키마 DSL · 모델 · 마이그레이션 |
+| `@gaonjs/config` | 0.1.0 | `gaon.config.ts`·`app.config.ts` |
+| `@gaonjs/web` | 0.3.0 | Fastify 웹 레이어 · 인증 · JSON 액션 |
+| `@gaonjs/vue` | 0.2.0 | Vue 어댑터 · pageProps · 타입드 `api()` |
+| `@gaonjs/async` | 0.2.2 | 채널 · 프레즌스 · 허브 · 잡 · 스케줄 |
+| `@gaonjs/core` | 0.1.4 | 메타데이터 · 직렬화 프리미티브(Hidden) |
+| `@gaonjs/mail` / `storage` / `i18n` | 0.1.0 | 메일 · 파일 스토리지 · 다국어 |
+
+## 6. 원칙 · 엄수
+
+- **추론 금지 · 사실에 입각.** 확인 안 된 것은 실행·측정으로 검증
+  하거나 사용자에게 묻는다. 표에 없는 API 를 추측해서 쓰지 않는다 —
+  카테고리 문서(§0)를 먼저 읽는다.
+- **무조건 긍정 금지.** 문제가 있으면 문제라고 말하고, 비용·제약이
+  있으면 반영 전에 명시한다.
+- **에러 메시지는 수리 안내서.** "무엇이 잘못됐다" 가 아니라 → "어느
+  파일에 무엇을 추가/수정하고 어떤 명령을 실행하라" 까지 (v0.15 §7.5.3).
+- **관례가 곧 문서** — 관례를 어길 때만 설정을 쓴다.
+- **정본·정오표 원문 우선.** 이 문서·카테고리 문서와 정본이 충돌하면
+  정본·최신 정오표를 따른다.
+
+## 7. 참고 문서
+
+- 설계 정본: `docs/gaondesignv0.15.md` (동결) + errata E-1~E-5
+  (E-1 파사드명 · E-2 실시간 TCP · E-3 JSON 액션/params · E-4 컬럼·
+  체이닝 · E-5 컴포저블·레이아웃).
+- 가이드: `docs/guides/*.md` (getting-started · data · data-flow ·
+  serialization · authentication · realtime · async · pipeline ·
+  operations · configuration).
+- 프레임웍 구현 저장소의 AI 지침은 `CLAUDE.md` — 이 문서와 대상이
+  다르다 (CLAUDE = 프레임웍 구현자용, AGENTS = 프레임웍 사용자용).