@flextudio/scenario 0.1.0

package/skill/schemas/service/GoogleSheet.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/GoogleSheet.schema.json",
+  "title": "GoogleSheet ServiceBinding",
+  "description": "Google Sheet 직접 연동. SystemID='GoogleSheet'. spreadsheetId + Sheet 명 + 기준 컬럼명 (보통 _SUID) 으로 동작. ModuleID 4종 (Query / Append / Update / Clear).",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "GoogleSheet" },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["Query", "Append", "Update", "Clear"],
+          "description": "GoogleSheet 작업 종류. Firestore 와 다름 — Save→Append, Delete→Clear (행 삭제 X, 값만 비움)."
+        },
+        "SpreadsheetId": {
+          "type": "string",
+          "description": "Google Spreadsheet ID — URL `/spreadsheets/d/{spreadsheetId}/edit` 의 부분."
+        },
+        "SheetName":     { "type": "string", "description": "시트 명 (탭 이름)." },
+        "BaseColumn":    { "type": "string", "description": "기준 컬럼명. 보통 `_SUID` — 빈 컬럼이면 자동 생성. Update/Clear 시 _rowIndex 와 함께 행 식별 키." },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" }
+      }
+    }
+  ]
+}

package/skill/schemas/service/_base.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/_base.schema.json",
+  "title": "Service Base",
+  "description": "서비스 종류별 ServiceBinding 분기에서 공통으로 쓰는 $defs. 각 service/<type>.schema.json 은 commonBase 위에 분기별 키를 얹는다 (allOf).",
+
+  "$defs": {
+    "commonBase": {
+      "type": "object",
+      "description": "모든 ServiceBinding 항목에 공통으로 등장하는 필드. 실 샘플 99 항목 통계 기반.",
+      "properties": {
+        "SystemID":             { "type": "string", "description": "시스템 식별자. FlexSQL / Firestore / Custom / ksystem / New_<NN> 등." },
+        "SystemType":           { "type": "string", "description": "시스템 종류 (CustomSystem / 비어있음 / FlexAutoQuery 등)." },
+        "ModuleID":             { "type": "string", "description": "모듈 식별자. FlexSQL='Default' / Firestore='Query' / FlexAPI / GUID(CustomSystem) 등." },
+        "ServiceName":          { "type": "string" },
+        "SetCategory":          { "type": "boolean", "description": "결과 반영 대상 카테고리 토글. 프로퍼티 SWITCH 가 boolean 저장." },
+        "UsePKey":              { "type": "boolean" },
+        "UseParamBlock":        { "type": "boolean" },
+        "UseResultBlock":       { "type": "boolean" },
+        "UseInnerBlock":        { "type": "boolean" },
+        "NotSeperateInnerBlock":{ "type": "boolean", "description": "InnerBlock 분리 안 함. 서버 내부 동작에 영향." }
+      }
+    },
+
+    "systemIDPattern": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
+      "description": "SystemID 패턴. 영문 시작, 영문/숫자/언더스코어. 실 샘플: FlexSQL / Firestore / Custom / ksystem / New_01 / New_05."
+    }
+  }
+}

package/skill/schemas/service/ksystem.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service/ksystem.schema.json",
+  "title": "ksystem ServiceBinding",
+  "description": "ksystem 서비스 호출 정의. const.js 의 SYSTEM_ID.KSYSTEM='ksystem' 에 매핑. 영림원소프트랩 ksystem 사내 모듈 (FlexAPI / OpenAPI / Codehelp / Ksystem / Filehelp). 자동생성 BIZ 테이블에 대한 SP 호출 형태가 가장 흔함.",
+  "type": "object",
+  "required": ["SystemID", "ModuleID"],
+  "additionalProperties": true,
+  "allOf": [
+    { "$ref": "_base.schema.json#/$defs/commonBase" },
+    {
+      "properties": {
+        "SystemID": { "const": "ksystem", "description": "ksystem 호출 시 'ksystem' 고정 (소문자)." },
+        "ModuleID": {
+          "type": "string",
+          "enum": ["FlexAPI", "OpenAPI", "Codehelp", "Ksystem", "Filehelp"],
+          "description": "ksystem 모듈. FlexAPI=BIZ 테이블 SP 호출 / OpenAPI=공개 API / Codehelp=코드 매핑 / Ksystem=ksystem 본체 / Filehelp=파일 헬퍼."
+        },
+        "UseTable":      { "type": "string", "examples": ["BIZ", "FLEX"], "description": "테이블 유형 코드. 보통 'BIZ' (비즈니스 테이블) / 'FLEX'." },
+        "SelectTable":   { "type": "string", "description": "대상 테이블 이름." },
+        "SPList":        {
+          "type": "array",
+          "description": "스토어드 프로시저 목록. 자동생성된 SP 이름 (예: '_SWFlexARUsualCostAppListQuery'). FlexAPI 모듈에서 흔히 사용.",
+          "items": { "type": "string" }
+        },
+        "UseBundle":     { "type": "boolean", "description": "번들 호출 — 여러 SP 묶음 실행." },
+        "UseSearch":     { "type": "boolean" },
+        "UsePKey":       { "type": "boolean" },
+        "UseParamBlock": { "type": "boolean" },
+        "UseResultBlock":{ "type": "boolean" },
+        "UseInnerBlock": { "type": "boolean" },
+        "BeforeScript":  { "type": "string" }
+      }
+    }
+  ]
+}

package/skill/schemas/service-binding.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/service-binding.schema.json",
+  "title": "ServiceBinding",
+  "description": "scenarioMeta.ServiceBinding — 서비스 호출 정의 맵. 키는 서비스 식별자 (영문/숫자/언더스코어), 값은 호출 정의(SystemID + ModuleID 등). 스킬 생성 시에는 비어있는 객체 `{}` 만 허용 — `[no-service]` 후검증이 strict (`strict_no_service:true`). 운영 메타 호환을 위해 형식만 정의.",
+
+  "$comment": "서비스 종류별 분기 스키마는 service/<type>.schema.json 분리 (FlexSQL / FlexAutoQuery / Firestore / Custom REST / CustomSystem). 본 파일의 serviceBindingEntry 는 모든 분기를 흡수하는 관용 형태 — 운영 메타 검증 시 SystemID / SystemType 으로 구체 분기 선택은 service/README.md 의 분기 결정 규칙 참조.",
+
+  "type": "object",
+  "patternProperties": {
+    "^[A-Za-z_][A-Za-z0-9_]*$": { "$ref": "#/$defs/serviceBindingEntry" }
+  },
+  "additionalProperties": false,
+
+  "$defs": {
+    "serviceBindingEntry": {
+      "title": "ServiceBinding Entry",
+      "description": "단일 서비스 정의. 지원 시스템: FlexSQL / Firestore / FlexAutoQuery / GoogleSheet (flextudio-guide §6.6). 스킬 생성에서는 사용 금지.",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "SystemID":              { "type": "string", "enum": ["Flextudio API", "FlexSQL", "FlexAutoQuery", "Firestore", "GoogleSheet", "ServerKit", "Other"], "description": "시스템 식별자 (예: 'Flextudio', 'Other', 'FlexSQL')." },
+        "SystemType":            { "type": "string" },
+        "ModuleID":              { "type": "string", "description": "모듈 식별자." },
+        "ServiceName":           { "type": "string", "description": "FlexSQL / 외부 시스템에서 정의한 서비스 이름." },
+        "SQLServiceName":        { "type": "string", "description": "FlexSQL 사용 시 등록된 SQL 서비스 이름." },
+        "MajorVersion":          { "type": "integer", "minimum": 1, "description": "서비스 버전 (FlexSQL 등). 정수만 허용 (보통 1 또는 2)." },
+        "ExternalDB":            { "type": "string", "description": "외부 DB 식별자." },
+        "UseTable":              { "type": "boolean", "description": "테이블 직접 사용 토글 (FlexAutoQuery)." },
+        "SelectTable":           { "type": ["string", "object"], "description": "FlexAutoQuery 대상 테이블." },
+        "SPList":                { "type": "array",  "items": { "type": "string" }, "description": "스토어드 프로시저 목록 (FlexAutoQuery)." },
+        "UsePKey":               { "type": "boolean" },
+        "UseParamBlock":         { "type": "boolean" },
+        "UseResultBlock":        { "type": "boolean" },
+        "UseInnerBlock":         { "type": "boolean" },
+        "UseSearch":             { "type": "boolean" },
+        "UseBundle":             { "type": "boolean" },
+        "NotSeperateInnerBlock": { "type": "boolean" },
+        "SetCategory":           { "type": "string", "description": "결과 반영 대상 카테고리 이름." },
+        "fEvent":                { "type": "object", "additionalProperties": { "type": "string" }, "description": "API 연동 Event Config Key 키-값 맵." },
+        "fEventKey":             { "type": "array",  "items": { "type": "string" }, "description": "API 연동 Event Config Key 키 값 배열"},
+        "Method":                { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"], "description": "외부 REST API 사용 시 HTTP 메서드." },
+        "Url":                   { "type": "string" },
+        "RequestHeader":         { "type": "object" },
+        "BeforeScript":          { "type": "string", "description": "FlexSQL Before Script — 호출 전 전처리." },
+        "ParamScript":           { "type": "string" },
+        "ResultScript":          { "type": "string", "description": "FlexSQL After Script — 결과 후처리." }
+      }
+    }
+  }
+}

package/skill/schemas/step.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/step.schema.json",
+  "title": "Step",
+  "description": "Steps[StepId] 의 값. StepType 누락 시 런타임은 StepView 로 처리.",
+  "type": "object",
+  "additionalProperties": true,
+
+  "properties": {
+    "StepType": {
+      "type": "string",
+      "enum": ["StepView", "StepDialog", "StepSub"],
+      "description": "누락 시 런타임은 StepView 로 처리. AI 생성 시 StepView 명시 권장."
+    },
+    "StepDialogType": {
+      "type": "string",
+      "enum": ["", "SlideUp", "PopUp"],
+      "description": "StepView 의 다이얼로그 변종. '' = 일반 화면, SlideUp = 바텀시트, PopUp = 중앙 팝업."
+    },
+    "StepName":  { "type": "string", "description": "내부 표시명 (디자인 탭 '스텝명')." },
+    "StepTitle": { "type": "string", "description": "상단 헤더 타이틀. UseStepHeader=true 일 때 표시." },
+    "StepRow":   { "type": "number", "description": "그리드 좌표." },
+    "StepCol":   { "type": "number", "description": "그리드 좌표." },
+
+    "Contents":            { "type": "array", "items": { "$ref": "group.schema.json" } },
+    "FixedContentsTop":    { "type": "array", "items": { "$ref": "group.schema.json" } },
+    "FixedContentsBottom": { "type": "array", "items": { "$ref": "group.schema.json" } },
+
+    "Padding": {
+      "$ref": "style-objects.schema.json#/$defs/spacing",
+      "$comment": "디자인 탭 '패딩(T,R,B,L)' 토글 ON 시 등장. OFF 시 키 자체 누락 — 런타임 기본값 padding: .5rem 1.25rem 0 1.25rem 적용."
+    },
+    "Margin":  { "$ref": "style-objects.schema.json#/$defs/spacing" },
+    "BgStyle": {
+      "$ref": "style-objects.schema.json#/$defs/bgStyle",
+      "$comment": "디자인 탭 '배경' 토글 ON 시 등장. OFF 시 키 자체 누락."
+    },
+
+    "UseStepHeader": { "type": "boolean", "description": "상단 헤더 사용. 디자인 탭 토글." },
+
+    "Next": {
+      "type": "array",
+      "description": "다음 Step 후보의 StepId 배열. forward-only. StepSub Step 에서는 사용 X.",
+      "items": { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+    },
+
+    "UseBackButton": {
+      "type": "boolean",
+      "description": "뒤로가기 토글. 디자인 ↔ 데이터 탭 공통. **StepSub 에서는 false 자동 강제**."
+    },
+    "BackButton": {
+      "type": "object",
+      "description": "뒤로가기 버튼. UseBackButton=true 일 때 동반 등장. 데이터 탭에서 세부 설정.",
+      "additionalProperties": true,
+      "properties": {
+        "Next": {
+          "description": "Step 모드의 이동 대상. \"None\" = 직전 스텝(PrevStack), 또는 본인 외 StepId 지정 가능. 자기 자신 StepId 참조 금지 (validate.mjs 후검증).",
+          "anyOf": [
+            { "type": "string", "const": "None" },
+            { "type": "string", "pattern": "^Step[1-9][0-9]*$" }
+          ]
+        },
+        "IsRestored": {
+          "type": "boolean",
+          "description": "콜렉션 이전 상태로 복원하기 토글. true=복원(취소 흐름), false=변경 유지(상세 화면 등)."
+        },
+        "BackButtonMode": {
+          "type": "string",
+          "enum": ["Step", "event"],
+          "description": "Step=이전 스텝 이동 (Next/IsRestored 적용). event=이벤트 실행 (BackButtonEvent 의 이벤트가 동작 제어 — 별도 추가 뒤로가기 동작 없음)."
+        },
+        "BackButtonEvent": {
+          "type": "string",
+          "description": "BackButtonMode='event' 일 때 실행할 이벤트 이름. 사용 안 할 때는 문자열 \"undefined\"."
+        }
+      }
+    },
+
+    "UseBottomButton": {
+      "type": "boolean",
+      "description": "하단 버튼 사용. **StepSub 에서는 false 자동 강제**."
+    },
+    "StepButton":      { "type": "object" },
+    "BottomButtons":   { "type": "array", "items": { "$ref": "bottom-buttons.schema.json" } },
+
+    "UseEvents": {
+      "type": "boolean",
+      "description": "Step 이벤트 사용. **StepSub 에서는 false 자동 강제**."
+    },
+    "Events": {
+      "description": "Step 이벤트 핸들러 맵. const.js STEP_EVENT 6종 + ScrollEnd. 자세한 명세는 step.md §Step Events 상세 명세. UseEvents=true 면 객체, false 면 빈 배열.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "UseEvents=true. StepEventOrder enum 으로 활성화 + 이벤트별 핸들러명 (scenario.Events 키 참조).",
+          "additionalProperties": false,
+          "properties": {
+            "StepEventOrder": {
+              "type": "array",
+              "uniqueItems": true,
+              "description": "활성화할 이벤트 enum. 여기 든 이벤트만 호출됨. const.js STEP_EVENT + ScrollEnd.",
+              "items": {
+                "type": "string",
+                "enum": ["Init", "Loaded", "OnBackLoaded", "OnLeave", "OnForeground", "ScrollEnd"]
+              }
+            },
+            "Init":         { "type": "string", "description": "Step 로드 직전 (DOM 그려지기 전). 샘플 데이터 / 카테고리 초기화 (`removeCategory + createCategory + addSector`)." },
+            "Loaded":       { "type": "string", "description": "Step UI 모두 그려진 후. DOM 의존 셋업 (Chart.js / Map / Canvas / Timer / CDN 라이브러리 로드)." },
+            "OnBackLoaded": { "type": "string", "description": "뒤로가기로 이 Step 복원 직후. 데이터 갱신 / 지도 재렌더링 — Init/Loaded 와 별개로 매 복귀 시 호출." },
+            "OnLeave":      { "type": "string", "description": "이 Step 이탈 직전 (Next/Back). Cleanup (`clearInterval` / 외부 SDK destroy)." },
+            "OnForeground": { "type": "string", "description": "**모바일 한정** — 앱이 백그라운드 → 포그라운드 복귀 시. 푸시 후 데이터 동기화 등." },
+            "ScrollEnd":    { "type": "string", "description": "Step 영역 스크롤이 끝까지 닿았을 때. 무한 스크롤 / 페이지네이션." }
+          },
+          "allOf": [
+            { "$comment": "EventOrder 의 각 이벤트는 동명 핸들러 키 필수.",
+              "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "Init"         } } }, "required": ["StepEventOrder"] }, "then": { "required": ["Init"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "Loaded"       } } }, "required": ["StepEventOrder"] }, "then": { "required": ["Loaded"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnBackLoaded" } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnBackLoaded"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnLeave"      } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnLeave"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "OnForeground" } } }, "required": ["StepEventOrder"] }, "then": { "required": ["OnForeground"] } },
+            { "if": { "properties": { "StepEventOrder": { "type":"array", "contains": { "const": "ScrollEnd"    } } }, "required": ["StepEventOrder"] }, "then": { "required": ["ScrollEnd"] } }
+          ]
+        },
+        {
+          "type": "array",
+          "description": "UseEvents=false. 빈 배열로 둠. (`Events` 키 자체 누락 시 런타임 에러.)",
+          "maxItems": 0
+        }
+      ]
+    },
+
+    "Height": {
+      "$ref": "style-objects.schema.json#/$defs/sizeObject",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 디자인 탭에서 SlideUp/PopUp 선택 시만 노출. (Width 는 Step 차원에서 작성 금지 — SlideUp/PopUp 모두 항상 전체 너비 사용.)"
+    },
+    "PopupPosition": {
+      "type": "string",
+      "enum": ["Centered", "Top Left", "Top Center", "Top Right", "Bottom Left", "Bottom Center", "Bottom Right"],
+      "$comment": "PopUp 전용. 위치 지정."
+    },
+    "hideDlgHeader": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 헤더 숨김 토글."
+    },
+    "useDim": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 어두운 배경 dim 사용."
+    },
+    "dimTransp": {
+      "type": "number",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. dim 투명도 (0 ~ 1)."
+    },
+    "bgTransparent": {
+      "type": "boolean",
+      "$comment": "다이얼로그 SlideUp/PopUp 전용. 배경 투명 토글."
+    },
+
+    "ScenarioId": {
+      "type": "string",
+      "description": "StepSub 의 호출 대상 시나리오 ID. 형식: 'flex||<숫자_숫자>' 또는 직접입력 문자열."
+    },
+    "ScenarioIdText": {
+      "type": "string",
+      "description": "StepSub 의 시나리오 ID 직접입력 모드 텍스트."
+    },
+    "Protocol": {
+      "type": "object",
+      "description": "StepSub 전용. 호출 시나리오 프로토콜. 참조.",
+      "additionalProperties": true,
+      "properties": {
+        "Protocol":     { "type": "string", "$comment": "레거시 호환. 보통 'Original' 고정." },
+        "StartStep":    { "type": "string", "description": "호출할 서브 시나리오의 시작 StepId." },
+        "StartStepText":{ "type": "string", "description": "StartStep 직접입력 모드 텍스트." },
+        "InitType": {
+          "type": "string",
+          "enum": ["Original", "Parent", "Current"],
+          "description": "Init(처음)으로 돌아갈 시나리오. Original=최상위, Parent=현재, Current=서브."
+        },
+        "UseBackButton": {
+          "type": "boolean",
+          "description": "호출한 시나리오로 돌아가기 허용 (UI 토글)."
+        },
+        "UseCopyCollectionToSub": {
+          "type": "boolean",
+          "description": "서브시나리오로 현재 콜렉션 전달."
+        },
+        "TargetStatusToSub": {
+          "type": "string",
+          "enum": ["all", "active", "selected", "last", "added", "updated", "deleted"],
+          "description": "콜렉션 전달 Status 필터. 기본 All."
+        },
+        "UseCopyCollectionToOrigin": {
+          "type": "boolean",
+          "description": "서브시나리오의 콜렉션으로 대체하기."
+        },
+        "TargetStatusToOrigin": {
+          "type": "string",
+          "enum": ["all", "active", "selected", "last", "added", "updated", "deleted"],
+          "description": "콜렉션 대체 Status 필터. 기본 All."
+        },
+        "beforeLoadSubScenario": {
+          "type": "string",
+          "description": "서브시나리오 로드 전 실행 스크립트. (afterLoadSubScenario 는 메타에 존재하지 않음.)"
+        }
+      }
+    },
+    "SubBackup": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "StepView ↔ StepSub 전환 시 이전 상태 복원용 백업 객체. 예: { UseBackButton: true, Contents: [] }. 직접 편집 금지 — 스튜디오가 자동 관리."
+    }
+  },
+
+  "allOf": [
+    {
+      "$comment": "StepSub 일 때 Protocol 필수.",
+      "if": {
+        "properties": { "StepType": { "const": "StepSub" } },
+        "required": ["StepType"]
+      },
+      "then": { "required": ["Protocol"] }
+    },
+    {
+      "$comment": "다이얼로그(SlideUp/PopUp) 가 아니면 다이얼로그 전용 키들 등장 금지. (Width 는 모든 Step 에서 작성 금지 — properties 에서 제거되어 strict-fields 단계에서 차단.)",
+      "if": {
+        "not": {
+          "properties": { "StepDialogType": { "enum": ["SlideUp", "PopUp"] } },
+          "required": ["StepDialogType"]
+        }
+      },
+      "then": {
+        "allOf": [
+          { "not": { "required": ["hideDlgHeader"] } },
+          { "not": { "required": ["useDim"] } },
+          { "not": { "required": ["dimTransp"] } },
+          { "not": { "required": ["bgTransparent"] } },
+          { "not": { "required": ["Height"] } }
+        ]
+      }
+    },
+    {
+      "$comment": "PopUp 이 아니면 PopupPosition 등장 금지 (PopUp 전용).",
+      "if": {
+        "not": {
+          "properties": { "StepDialogType": { "const": "PopUp" } },
+          "required": ["StepDialogType"]
+        }
+      },
+      "then": {
+        "allOf": [
+          { "not": { "required": ["PopupPosition"] } }
+        ]
+      }
+    }
+  ],
+
+  "$comment": "BottomButton 단일 항목 스키마는 bottom-buttons.schema.json 으로 분리."
+}

package/skill/schemas/style-objects.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flextudio.local/meta-contract/v1/style-objects.schema.json",
+  "title": "Style Objects",
+  "description": "Group/Control/BottomButton 등에서 공통 사용되는 스타일/레이아웃 객체 카탈로그. 모든 객체는 additionalProperties: true (런타임에서 추가 키를 무시하지 않으므로 유연성 유지).",
+
+  "$defs": {
+    "colorToken": {
+      "type": "string",
+      "description": "권장 컬러 토큰. AI 생성 시 이 enum 값들 중에서 선택 권장. 단 BgColor/FontColor/BorderColor 등 색상 필드는 type:string 으로 두며 다음 형태 모두 허용: ① 토큰(`var(--colorMain)`), ② hex(`#333333`, `#000`, `#abc`), ③ rgb/rgba(`rgb(255,0,0)`, `rgba(33,21,7,0.654)`), ④ hsl/hsla, ⑤ legacy(`@colorBlack`), ⑥ CSS color keyword(`red`, `transparent`).",
+      "enum": [
+        "var(--colorMain)",       "var(--colorMainLight)",
+        "var(--colorWhite)",      "var(--colorBlack)",
+        "var(--colorGray1)",      "var(--colorGray2)",      "var(--colorGray3)",
+        "var(--colorGray4)",      "var(--colorGray5)",
+        "var(--colorGray9)",      "var(--colorGray10)",
+        "var(--colorRed)",        "var(--colorRedLight)",
+        "var(--colorBlue)",       "var(--colorBlueLight)",
+        "var(--colorGreen)",      "var(--colorGreenLight)",
+        "var(--colorOrange)",
+        "var(--colorPurple)",     "var(--colorPurpleLight)",
+        "var(--colorYellow)",     "var(--colorYellowLight)",
+        "var(--colorMint)",       "var(--colorMintLight)",
+        "var(--colorSub0)",       "var(--colorSub0Light)",
+        "var(--colorSub1)",       "var(--colorSub3)"
+      ]
+    },
+
+    "sizeObject": {
+      "type": "object",
+      "description": "Width/Height 등 크기 표현. MatchText=true 면 컨텐츠에 맞춤 (SizeValue 무시).",
+      "additionalProperties": false,
+      "properties": {
+        "MatchText": { "type": "boolean" },
+        "SizeValue": { "type": ["number", "string"] },
+        "SizeUnit":  { "type": "string", "examples": ["%", "px", "text"] }
+      }
+    },
+
+    "spacing": {
+      "type": "object",
+      "description": "Padding / Margin / AbsolutePosition 공통 형태. 사용하는 방향만 키 포함. 빈 문자열은 미설정. 하단은 'Btm' 사용 (BorderStyle만 'Bottom').",
+      "additionalProperties": true,
+      "properties": {
+        "UseAuto":  { "type": "boolean" },
+        "UseEach":  { "type": "boolean" },
+        "All":      { "type": "string" },
+        "Top":      { "type": "string" },
+        "Right":    { "type": "string" },
+        "Btm":      { "type": "string" },
+        "Left":     { "type": "string" },
+        "SizeUnit": { "type": "string" }
+      }
+    },
+
+    "absolutePosition": {
+      "allOf": [{ "$ref": "#/$defs/spacing" }],
+      "description": "절대 위치 오버레이. 사용 방향만 키 포함. 값은 '0' 이상의 숫자 문자열."
+    },
+
+    "displayStyle": {
+      "type": "object",
+      "description": "Flex/Display 레이아웃 제어.",
+      "additionalProperties": true,
+      "properties": {
+        "UseDisplay":           { "type": "boolean" },
+        "DisplayType":          { "type": "string", "examples": ["Flex", "None"] },
+        "FlexDirection":        { "type": "string", "examples": ["row", "column", "wrap"] },
+        "FlexWrap":             { "type": "boolean" },
+        "DisplayAlign":         { "type": "string", "examples": ["Left", "Center", "Right", "Between"] },
+        "DisplayVerticalAlign": { "type": "string", "examples": ["Top", "Center", "Bottom"] },
+        "flexBoxType":          { "type": "string", "examples": ["align", "space"] },
+        "columnGapValue":       { "type": "string" },
+        "columnGapUnit":        { "type": "string", "examples": ["px"] },
+        "rowGapValue":          { "type": "string" },
+        "rowGapUnit":           { "type": "string", "examples": ["px"] }
+      }
+    },
+
+    "fontStyle": {
+      "type": "object",
+      "description": "폰트 표현. 색상은 $defs/colorToken 의 var(--colorXxx) 사용 권장 (legacy `@colorXxx` 도 통용).",
+      "additionalProperties": true,
+      "properties": {
+        "UseFont":       { "type": "boolean" },
+        "FontColor":     { "type": "string", "$comment": "권장: $defs/colorToken enum. 실 메타는 hex/legacy 도 통용." },
+        "FontSize":      { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장." },
+        "FontWeight":    { "type": "string", "examples": ["Regular", "Medium", "SemiBold", "Bold"] },
+        "FontAlign":     { "type": "string", "examples": ["flex-start", "center", "flex-end"] },
+        "UseBold":       { "type": "boolean" },
+        "LetterSpacing": { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장.", "description": "자간. ★ AI 생성 시 미포함 (사용자 수동 설정 전용)." }
+      }
+    },
+
+    "borderStyle": {
+      "type": "object",
+      "description": "테두리. 하단은 'Bottom' 사용 (Padding/Margin은 'Btm'). SizeSet/RadiusSet 이 'Each' 면 per-side / per-corner 키 (Top/Right/Bottom/Left, RadiusTopLeft/RadiusTopRight/RadiusBottomLeft/RadiusBottomRight) 가 활성화되고 균일 키 (BorderSize / BorderRadius) 는 '' 로 비움 — 균일 vs 개별은 상호배타.",
+      "additionalProperties": true,
+      "properties": {
+        "Useborder":           { "type": "boolean" },
+        "BorderColor":         { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex(#333333) / rgb·rgba / hsl·hsla / legacy(@colorXxx) / CSS keyword 모두 허용."},
+        "BorderSize":          { "type": ["number", "string"], "description": "균일 두께. SizeSet:'Each' 면 '' 로 비우고 Top/Right/Bottom/Left 사용." },
+        "BorderType":          { "type": "string", "examples": ["solid", "dashed", "dotted"] },
+        "SizeSet":              { "type": "string", "examples": ["All", "Each", "Top", "Right", "Bottom", "Left"], "description": "균일 두께 = 'All', 사이드별 두께 = 'Each' (Top/Right/Bottom/Left 활성)." },
+        "Top":                 { "type": "string", "description": "SizeSet:'Each' 일 때 상단 두께. 미지정은 ''." },
+        "Right":               { "type": "string", "description": "SizeSet:'Each' 일 때 우측 두께. 미지정은 ''." },
+        "Bottom":              { "type": "string", "description": "SizeSet:'Each' 일 때 하단 두께. 미지정은 ''. (★ Padding/Margin 은 'Btm' 사용)" },
+        "Left":                { "type": "string", "description": "SizeSet:'Each' 일 때 좌측 두께. 미지정은 ''." },
+        "BorderRadius":        { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장.", "description": "균일 반경. RadiusSet:'Each' 면 '' 로 비우고 RadiusTopLeft/TopRight/BottomLeft/BottomRight 사용. '9999' 는 자동 RadiusSet:'None' (pill)." },
+        "RadiusSet":           { "type": "string", "examples": ["All", "Each", "None", "Top", "Right", "Bottom", "Left"], "description": "균일 반경 = 'All', 코너별 반경 = 'Each' (RadiusTopLeft 등 활성), pill = 'None'." },
+        "RadiusTopLeft":       { "type": "string", "description": "RadiusSet:'Each' 일 때 좌상단 반경. 미지정은 ''." },
+        "RadiusTopRight":      { "type": "string", "description": "RadiusSet:'Each' 일 때 우상단 반경. 미지정은 ''." },
+        "RadiusBottomLeft":    { "type": "string", "description": "RadiusSet:'Each' 일 때 좌하단 반경. 미지정은 ''." },
+        "RadiusBottomRight":   { "type": "string", "description": "RadiusSet:'Each' 일 때 우하단 반경. 미지정은 ''." }
+      }
+    },
+
+    "bgStyle": {
+      "type": "object",
+      "description": "배경 색/이미지. UseBackground=true 일 때 BgColor 필요.",
+      "additionalProperties": true,
+      "properties": {
+        "UseBackground": { "type": "boolean" },
+        "BgColor":       { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex(#333333) / rgb·rgba / hsl·hsla / legacy(@colorXxx) / CSS keyword 모두 허용."},
+        "UseImage":      { "type": "boolean" },
+        "Image":         { "type": "object" }
+      }
+    },
+
+    "captionStyle": {
+      "type": "object",
+      "description": "Control의 Caption 영역 스타일.",
+      "additionalProperties": true,
+      "properties": {
+        "UseDesign":       { "type": "boolean" },
+        "FontColor":       { "type": "string", "$comment": "권장: $defs/colorToken enum. 토큰 외 hex / rgb / legacy / CSS keyword 도 통용." },
+        "FontWeight":      { "type": "string", "examples": ["Regular", "Medium", "SemiBold", "Bold"] },
+        "CaptionPosition": { "type": "string", "examples": ["", "Left", "Top"] },
+        "FontSize":        { "type": "string", "$comment": "프로퍼티 SIZE_INPUT 컨트롤이 항상 string 으로 저장." },
+        "FontAlign":       { "type": "string", "examples": ["flex-start", "center", "flex-end"] }
+      }
+    },
+
+    "arrangeItemsStyle": {
+      "type": "object",
+      "description": "탭/리스트 헤더 아이템 정렬·배치. ArrangeItemsType 으로 너비 정책, ArrangeItemsAlign 으로 정렬을 지정.",
+      "additionalProperties": true,
+      "properties": {
+        "UseArrangeItems":   { "type": "boolean" },
+        "ArrangeItemsType":  { "type": "string", "examples": ["MatchText", "EqualDistribution", "Fixed"], "description": "MatchText=텍스트 크기에 맞춤 / EqualDistribution=균등분배 / Fixed=고정 너비." },
+        "ArrangeItemsAlign": { "type": "string", "examples": ["Left", "Center", "Right", "Between"], "description": "헤더 영역 안에서의 정렬." }
+      }
+    }
+  }
+}

package/skill/skill-guides/README.md

@@ -0,0 +1,50 @@
+# skill-guides — 화면 생성 보편 가이드
+
+> scenario 생성(scenario-gen) 시 참고하는 **주제별 보편 가이드** 모음(진실원본).
+> 각 주제의 개념·권장 방식·"더 좋게 만드는 법"을 한곳에서 본다.
+> 스킬에 주입되어 생성 품질을 끌어올리는 보조 자료다 — 실수 목록이 아니라
+> "이렇게 하면 잘 되고, 한 단계 더 좋게 하려면 이렇게" 를 담는다.
+
+## 위치와 흐름
+
+```
+[진실원본]                          [빌드]                                  [미러]
+meta-contract/skill-guides/    ──build-skill-payload.mjs──▶  skill/skill-guides/   ──cp -R──▶  .claude/skills/scenario-gen/skill-guides/
+  events.md                        (walk + index.json 생성)     events.md                       (setup-bench.sh 5단계에서 자동)
+  ...                                                           index.json
+```
+
+- **이 디렉토리가 유일한 진실원본.** `skill/skill-guides/`, `.claude/skills/.../skill-guides/` 는 전부
+  빌드 산출물 — 직접 고치면 다음 빌드에 덮어쓰인다. ([SOURCE-MAP.md](../SOURCE-MAP.md) 참고)
+- `*.md` 와 이 `README.md` 만 빌드 대상. `index.json` 은 빌드가 생성한다(수기 작성 불필요).
+
+## 작성 규약
+
+1. **주제 1개 = 파일 1개.** 파일명은 주제(kebab-case): `events.md`, `data-connection.md`,
+   `layout.md` … 한 주제 한 파일.
+2. 각 파일은 아래 골격을 따른다 — **개념 → 권장 → 더 좋게** 순서:
+
+   ```markdown
+   # <주제> 가이드
+
+   > 한 줄 요약 + 관련 진실원본 링크.
+
+   ## 개념 — 무엇이고 어떻게 동작하나
+   ## 권장 방식 — 기본적으로 이렇게
+   ## 더 좋게 — 한 단계 끌어올리는 법
+   ## (선택) 자주 틀리는 점 — 짧은 체크리스트
+   ```
+3. **진실원본 위임** — 상세 규칙·제약은 `schema/v1/*.md` / `core/validators.mjs` 가 권위.
+   skill-guides 는 그 규칙을 "어떻게 잘 쓰나" 관점으로 풀어줄 뿐, 규칙 자체를 새로
+   만들지 않는다. 근거 위치를 링크한다.
+
+## 항목 추가·승격
+
+새 주제는 이 디렉토리에 `.md` 1개 추가하면 다음 setup에 자동 반영된다.
+`feedback/` 에서 **반복적으로 도움이 된 권장 패턴**을 사람이 검토해 해당 주제 파일로
+승격할 수도 있다(수동 게이트). 승격된 내용만 빌드/생성에 반영된다.
+
+## SKILL.md 와의 관계
+
+SKILL.md 의 "절대 금지" 섹션은 **별개로 관리**한다(통합하지 않음). skill-guides 는
+생성 시 품질을 끌어올리는 참고 가이드다.