@flextudio/scenario 0.1.0

package/skill/docs/index.json

@@ -0,0 +1,125 @@
+{
+  "count": 40,
+  "docs": [
+    {
+      "path": "SKELETON-SHELL.md"
+    },
+    {
+      "path": "bottom-buttons.md"
+    },
+    {
+      "path": "control/button.md"
+    },
+    {
+      "path": "control/calendar-navigator.md"
+    },
+    {
+      "path": "control/calendar.md"
+    },
+    {
+      "path": "control/check-box.md"
+    },
+    {
+      "path": "control/combo.md"
+    },
+    {
+      "path": "control/embed.md"
+    },
+    {
+      "path": "control/image-box.md"
+    },
+    {
+      "path": "control/input-date.md"
+    },
+    {
+      "path": "control/input-file.md"
+    },
+    {
+      "path": "control/input-mask.md"
+    },
+    {
+      "path": "control/input-number.md"
+    },
+    {
+      "path": "control/input-text.md"
+    },
+    {
+      "path": "control/label.md"
+    },
+    {
+      "path": "control/multi-input-box.md"
+    },
+    {
+      "path": "control/radio-box.md"
+    },
+    {
+      "path": "control/search.md"
+    },
+    {
+      "path": "control/tab.md"
+    },
+    {
+      "path": "control/tree.md"
+    },
+    {
+      "path": "control.md"
+    },
+    {
+      "path": "data-objects.md"
+    },
+    {
+      "path": "data-sources.md"
+    },
+    {
+      "path": "events.md"
+    },
+    {
+      "path": "group.md"
+    },
+    {
+      "path": "mockup-data.md"
+    },
+    {
+      "path": "node.md"
+    },
+    {
+      "path": "scenario.md"
+    },
+    {
+      "path": "service/CustomSystem.md"
+    },
+    {
+      "path": "service/Firestore.md"
+    },
+    {
+      "path": "service/FlexAutoQuery.md"
+    },
+    {
+      "path": "service/FlexSQL.md"
+    },
+    {
+      "path": "service/Flextudio API.md"
+    },
+    {
+      "path": "service/Flextudio.md"
+    },
+    {
+      "path": "service/GoogleSheet.md"
+    },
+    {
+      "path": "service/README.md"
+    },
+    {
+      "path": "service/ksystem.md"
+    },
+    {
+      "path": "service-binding.md"
+    },
+    {
+      "path": "step.md"
+    },
+    {
+      "path": "style-objects.md"
+    }
+  ]
+}

package/skill/docs/mockup-data.md

@@ -0,0 +1,186 @@
+# 목업 데이터 (Mockup Data)
+
+스킬 생성 모드(외부 Service/API 차단)에서 화면이 그릴 **유일한 데이터 출처**. 시작 Step (`StartSteps[0]`) 의 `Events.Init` 핸들러가 `f.Collection.addSector({...}, '<카테고리>')` 로 카테고리 섹터 데이터를 박는 방식이다.
+
+> **이 데이터는 `DataSource` 가 아니다.** 시나리오 `DataSources` 와 무관하게, 카테고리(`scenario.Panel.Category` 정의 또는 `DataConnection.CategoryName` 명시) 의 **섹터 누적**으로 표현된다. 단순 선택지 목록(Combo/Radio 옵션 등)이 필요하면 [Data Sources](data-sources.md) 의 `Fixed`/`Grid` 를 사용한다.
+
+## 큰 그림
+
+```
+[1] 그룹/컨트롤이 카테고리 사용
+    UseDataConnection: true + DataConnection.CategoryName='CtgX'
+       ↓
+[2] 시작 Step.Events.Init 가 카테고리에 mock 섹터 N건 박음
+    f.Collection.addSector({...키:값...}, 'CtgX')
+       ↓
+[3] DataConnection 으로 자동 반복 렌더링 — 같은 컨트롤이 섹터 수만큼 반복
+```
+
+`[mock-init]` cross-check 가 이 정합을 강제 — 시나리오에서 사용되는 카테고리(`DataConnection.CategoryName`) 에 대해 시작 Step 의 Init 핸들러가 `addSector` 호출을 1회 이상 포함해야 통과. `LinkedEvent` 로 위임된 보조 핸들러도 함께 추적된다.
+
+> **예외 — `DataUsage:"new"` (신규입력) 는 Init mock 불필요.** 신규입력 그룹은 **진입 시 빈 섹터가 자동 생성**되어 그 섹터에 입력값이 바인딩되므로(data-objects.md §1.2), 시작 Step Init 에서 따로 `addSector` 를 박지 않아도 된다. `[mock-init]` 도 `new` 로만 쓰인 카테고리는 요구 대상에서 제외한다. 단, **같은 카테고리가 어딘가에서 `query`/`update`/`detail`/`default` 등 읽기 용도로도 쓰이면** 그 읽기 화면이 그릴 데이터가 필요하므로 Init mock 이 여전히 필요하다.
+
+## ★ 짝 규칙 — DC 그룹 하위 데이터 항목은 콜렉션키 바인딩 필수
+
+`[mock-init]` 이 강제하는 건 **정방향**(카테고리 → Init 에서 mock 섹터 박기)뿐이다. 그 짝이 되는 **역방향** 도 반드시 지켜야 한다:
+
+> **mock 을 박은 DataConnection 그룹 하위에서, 데이터가 연결되어야 하는 항목들은 콜렉션키(Ckey)가 지정되어 있어야 한다.**
+
+addSector 로 섹터에 넣은 필드(`fName`, `fPrice` 등)는 그룹 하위 컨트롤이 **콜렉션키로 바인딩**해야 화면에 그려진다. 바인딩 키 없이 정적 텍스트(`Label.labeltext`, 정적 `Caption`)만 두면 **mock 데이터는 들어가지만 화면에는 고정 텍스트만 나오고 데이터는 죽는다** (DC 그룹이 섹터 수만큼 복제되어도 모든 카드가 똑같은 정적 문구를 반복).
+
+| 항목 유형 | 데이터 표시/입력 시 채워야 할 콜렉션키 |
+|---|---|
+| `Label` (값 표시) | `LabelType: "LabelCKey"` + `LabelCKey: "<섹터 필드명>"` (정적 라벨은 `labeltext` 그대로 OK) |
+| `InputText` / `InputNumber` / `InputMask` / `InputDate` / `MultiInputBox` | `Ckeys: ["<섹터 필드명>"]` (update/new 그룹에서 입력값 ↔ 섹터 매핑) |
+| `Combo` / `Search` | `Ckeys` + `SaveValueKey` / `CtrlDisplayCkey` (rules.md §5.5) |
+| `CheckBox` / `RadioBox` | `Ckeys` |
+| `Button` (값 표시) | `ButtonValueCKey` |
+
+- 바인딩 대상은 **그 섹터에서 실제로 보여줄/입력받을 필드들** — 카드 안의 장식용 정적 라벨까지 전부 바꾸라는 뜻은 아니다. 데이터가 흘러야 하는 항목만 콜렉션키를 채운다.
+- 콜렉션키를 가진 컨트롤은 조상 어딘가에 `UseDataConnection:true` 그룹이 있어야 한다 (`[bind]` / rules.md §5.1).
+- 어떤 콜렉션키도 안 쓰는 순수 정적 UI 라면 애초에 DataConnection / mock 을 두지 말 것 → `[proto]` 모드(`Ckeys`/`DataConnection`/`LabelCKey` 금지).
+
+## 기본 예시
+
+```jsonc
+// 시작 Step
+"Step1": {
+  "Events": {
+    "UseEvents": true,
+    "StepEventOrder": ["Init"],
+    "Init": "InitMockData"
+  },
+  "Contents": [
+    {
+      "ContentsType": "Group",
+      "UseDataConnection": true,
+      "DataConnection": { "TargetType": "category", "DataUsage": "query", "CategoryName": "CtgItemList" },
+      "Contents": [
+        // 카드 안 데이터 항목은 addSector 가 박은 필드(fName/fPrice)를 콜렉션키로 바인딩.
+        { "ControlType": "Label", "LabelType": "LabelCKey", "LabelCKey": "fName",  /* ... */ },
+        { "ControlType": "Label", "LabelType": "LabelCKey", "LabelCKey": "fPrice", /* ... */ }
+        // ✗ LabelType:"labeltext" + labeltext:"사과" 로 두면 모든 카드가 '사과' 만 반복 — mock 이 죽음.
+      ]
+    }
+  ]
+}
+
+// scenario.Events — 한 카테고리의 모든 섹터는 Script 액션 하나에 모은다.
+//   addSector 호출마다 \n 으로 줄바꿈하고, 객체 필드도 \n 들여쓰기로 (Ctrl+K+F 수준 가독성).
+//   섹터 1건당 {Action:Script} 를 따로 만들지 말 것.
+"Events": {
+  "InitMockData": [
+    {
+      "Action": "Script",
+      "Script": "f.Collection.addSector({\n  fId: 'i1',\n  fName: '사과',\n  fPrice: 1000\n}, 'CtgItemList');\nf.Collection.addSector({\n  fId: 'i2',\n  fName: '바나나',\n  fPrice: 1500\n}, 'CtgItemList');"
+    }
+  ]
+}
+```
+
+> 카테고리 자체는 `Panel.Category` 정의 또는 `DataConnection.CategoryName` 명시로 자유롭게 만들 수 있다 — 카테고리 생성에는 제한 없음.
+
+## 카테고리 리셋 패턴 (재진입 안전)
+
+`Init` 이 여러 번 도는 경우(`moveToFirst` 등) 섹터가 중복으로 박힐 수 있으므로 리셋 + 재생성 순서를 권장한다.
+
+```jsonc
+"STEP1_Init_E": [
+  { "Action": "Script", "Script": "f.Collection.removeCategory('CtgItemList');\nf.Collection.createCategory('CtgItemList');\n_c.CtgItemList.addSector({ Title:'A' });\n_c.CtgItemList.addSector({ Title:'B' });" }
+]
+```
+
+> **CRITICAL** — `_c.CtgX[0].set(...)` 호출 전에 반드시 `removeCategory + createCategory` 선행. 없으면 TypeError. (system-prompt-v2.md §4644)
+
+## `[script-allow]` — Init 핸들러 제한
+
+Init 은 mock 섹터를 박는 단계이므로 화면 갱신/푸시/외부 스크립트 로드 호출이 차단된다.
+
+| 차단되는 호출 | 사유 |
+|---|---|
+| `Current.step.reload(WithAnimation)` | DOM 아직 안 그려졌음 — Loaded 이후에서 호출 |
+| `f.Content(fid).reload(WithAnimation)` | 동일 |
+| `f.Event(...).runNext()` / `.break()` | Init 은 단순 mock 생성만 |
+| `f.MessageBox(...)` | 모달 다이얼로그 표시는 Loaded 이후에서 |
+| `f.Script.load(...)` | 외부 라이브러리 로드는 Loaded 또는 별도 이벤트 |
+
+허용 호출: `f.Collection.addSector` / `_c.<Cat>.addSector` / `_c.<Cat>[*].set(...)` / `f.Date()` 등.
+
+## Tab + LinkedStep 패턴
+
+탭이 있는 부모 Step 의 Init 에서 모든 샘플 데이터를 한 번에 로딩. LinkedStep 의 Init 에 두면 탭 전환마다 `removeCategory + createCategory` 가 다시 돌아 데이터가 초기화된다 (LinkedStep 의 Step 이벤트는 미실행이므로 부모 Step 에 박는 것이 표준).
+
+```jsonc
+// 부모 Step (탭이 있는 Step) — 모든 카테고리 한 번에 로딩
+"Step1": {
+  "Events": { "UseEvents": true, "StepEventOrder": ["Init"], "Init": "InitAllMock" }
+}
+// LinkedStep 들은 Events: [] (탭이 자체적으로 그릴 데이터는 부모 Step 의 Init 결과를 공유)
+```
+
+## `[proto]` 모드와의 관계
+
+DataSources 도 비어있고 Init 에도 `f.Collection.addSector` 가 전혀 없다면 진짜 정적 UI 목업 — `[proto]` 모드가 발동해 `Ckeys` / `DataConnection` / `LabelCKey` 사용을 금지한다. 표준 흐름은 [mock-init] + DC 반복 렌더링이므로 보통은 Init 에서 mock 섹터를 박는 쪽으로 작성한다.
+
+## Script 본문 표기 규칙
+
+`Action: "Script"` 의 `Script` 값은 **한 줄 JSON 문자열로 박고 줄바꿈은 `\n` 이스케이프**로 표현한다. JS 문자열 `+` 연결로 여러 줄에 걸쳐 두지 말 것.
+
+```jsonc
+// ✓ 정상 — 한 줄 + \n
+{ "Action": "Script", "Script": "f.Collection.removeCategory('CtgX');\nf.Collection.createCategory('CtgX');\n_c.CtgX.addSector({ Title:'A' });" }
+
+// ✗ 잘못 — JS + 연결 (JSON 파서가 받을 수 없음)
+{ "Action": "Script", "Script":
+  "f.Collection.removeCategory('CtgX');" +
+  "f.Collection.createCategory('CtgX');"
+}
+```
+
+### addSector 작성 규칙 (★ 필수)
+
+**1. 인자 순서 — `addSector(객체, '카테고리')`**
+첫 인자는 섹터 데이터 **객체**, 둘째 인자는 **카테고리명 문자열**이다. 순서를 뒤집은 `addSector('카테고리', {...})` 는 틀린 호출 — `[mock-init]` 이 카테고리를 인식하지 못해 "addSector 된 카테고리: (없음)" 으로 판정되고, 실제로도 섹터가 안 박혀 화면에 데이터가 안 나온다.
+
+```js
+// ✓ f.Collection.addSector({ orderNo: 'ORD-001' }, 'CtgOrderList')
+// ✗ f.Collection.addSector('CtgOrderList', { orderNo: 'ORD-001' })   ← 인자 역전, 동작 안 함
+```
+
+**2. 카테고리 단위로 묶기 — 섹터마다 액션을 쪼개지 말 것**
+한 카테고리에 박을 섹터가 여러 건이어도 **Script 액션 하나** 안에 `addSector` 호출들을 `\n` 으로 이어 담는다. 섹터 1건당 `{ "Action": "Script" }` 를 따로 만들면 안 된다. **카테고리가 2개면 Script 액션 2개** — 카테고리당 하나씩.
+
+**3. 줄바꿈/들여쓰기 가독성 (Ctrl+K+F 수준)**
+`addSector` 호출 사이는 `\n`, 객체 필드는 `\n  ` 들여쓰기로 한 필드씩 — 사람이 보기 쉽게 포맷한다. 여러 `addSector` 를 한 줄에 `;` 로 다닥다닥 붙이지 말 것.
+
+```jsonc
+// ✓ 정상 — 카테고리 2개 → Script 액션 2개, 각 액션 안에서 줄바꿈/들여쓰기
+"Init": [
+  {
+    "Action": "Script",
+    "Script": "f.Collection.addSector({\n  fOrderNo: 'ORD-001',\n  fOrderDate: '2024-01-15',\n  fTotalAmt: '150000'\n}, 'CtgOrder');\nf.Collection.addSector({\n  fOrderNo: 'ORD-002',\n  fOrderDate: '2024-01-16',\n  fTotalAmt: '85000'\n}, 'CtgOrder');"
+  },
+  {
+    "Action": "Script",
+    "Script": "f.Collection.addSector({\n  fOrderNo: 'ORD-001',\n  fItemName: '노트북',\n  fQty: '1'\n}, 'CtgOrderItem');\nf.Collection.addSector({\n  fOrderNo: 'ORD-002',\n  fItemName: '키보드',\n  fQty: '1'\n}, 'CtgOrderItem');"
+  }
+]
+
+// ✗ 잘못 — 섹터마다 Script 액션을 쪼갬 (한 줄에 ; 로 붙이거나 액션 7개로 분산)
+"Init": [
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-001',...}, 'CtgOrder');" },
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-002',...}, 'CtgOrder');" },
+  { "Action": "Script", "Script": "f.Collection.addSector({fOrderNo:'ORD-001',...}, 'CtgOrderItem');" }
+]
+```
+
+## 함정
+
+- **`DataSourceType: "Script"` 는 존재하지 않음** — 동적으로 만드는 화면 데이터는 카테고리 섹터로 표현한다.
+- 카테고리에 mock 섹터를 박지 않으면 컨트롤이 DC 로 반복되어도 화면에 아무것도 안 그려짐 → `[mock-init]` cross-check fail. **단 `DataUsage:"new"` 신규입력 그룹은 빈 섹터가 자동 생성되므로 Init mock 불필요** — 빈 입력 폼을 위해 `addSector({필드:''}, ...)` 로 빈 섹터를 억지로 박지 말 것.
+- **반대로** mock 은 박았는데 DC 그룹 하위 데이터 항목이 콜렉션키 없이 정적 텍스트(`labeltext` / 정적 `Caption`)뿐이면, 모든 카드가 같은 고정 문구를 반복하고 mock 데이터는 화면에 안 나옴 → 위 ★ 짝 규칙 위반. 데이터가 흘러야 하는 항목은 `LabelCKey` / `Ckeys` / `SaveValueKey` 등으로 바인딩.
+- `moveToFirst` 로 시작 Step 으로 돌아가면 Init 이 재실행되어 사용자 입력이 날아갈 수 있다 — 카테고리 리셋 패턴 필요. (system-prompt-v2.md §4730)
+- LinkedStep 의 Init 에 mock 을 박지 말 것 — Step 이벤트가 미실행이라 데이터가 안 들어감.
+- `Script` 값에 raw newline 박지 말 것 — JSON 파싱 실패. 줄바꿈은 항상 `\n` 이스케이프.
+- **`addSector` 인자 순서 역전** — `addSector('카테고리', {...})` 는 틀림. 항상 `addSector({...}, '카테고리')` (객체 먼저, 카테고리 마지막). 역전하면 `[mock-init]` 이 카테고리를 못 잡아 통과 실패 + 섹터도 안 박힘. (위 "addSector 작성 규칙 §1")
+- **섹터마다 Script 액션을 쪼개지 말 것** — 한 카테고리의 여러 섹터는 Script 액션 하나에 `\n` 으로 모은다. 카테고리 수만큼만 Script 액션을 둔다 (카테고리 2개 → 액션 2개). 섹터 N건을 액션 N개로 분산하면 가독성·구조 모두 나쁘다. (위 "addSector 작성 규칙 §2")

package/skill/docs/node.md

@@ -0,0 +1,32 @@
+# Node
+
+`Group | Control` 의 discriminated union. `Group.Contents[]` 의 자식으로 사용.
+
+## 식별
+
+| 노드 | 분기 필드 | 값 |
+|---|---|---|
+| Group | `ContentsType` | `"Group"` |
+| Control | `ControlType` | catalog.json `controlTypes[].value` 또는 v1 외 |
+
+Step은 Scenario 의 `Steps` 객체 직속이므로 이 union에 포함되지 않는다.
+
+## 트리 위치
+
+| 위치 | 자식 |
+|---|---|
+| `Step.Contents[]` | Group (Control 직접 자식 불가) |
+| `Step.FixedContentsTop[]` | Group |
+| `Step.FixedContentsBottom[]` | Group |
+| `Group.Contents[]` | Group \| Control (=`node.schema.json`) |
+| `Control(InputDate, Combo).Dialog.Layouts[0].Controls[]` | Control |
+
+## oneOf 동작
+
+- Group 분기: `ContentsType` 가 있으면 매치 → `group.schema.json` 검증
+- Control 분기: `ControlType` 가 있으면 매치 → `control.schema.json` 검증
+- 한 노드에 두 필드 동시 존재 시 oneOf 실패 (정확히 1개만 매치)
+
+## 검증 시 주의
+
+JSON Schema의 `discriminator` 키워드는 OpenAPI 확장이므로, 표준 호환 ajv 등에서는 `oneOf` + `required` + `const` 패턴만 사용한다.

package/skill/docs/scenario.md

@@ -0,0 +1,112 @@
+# Scenario
+
+`scenarioMeta` JSON 의 루트.
+
+> **호환 엔진:** flextudio 6.4.x (verified 2026-05-04, 45 시나리오 샘플 + public/engine 소스 검증). 엔진 메이저 변경(6→7) 시 v2 컨트랙트로 분리.
+>
+> **schema ↔ md 동기화:** 본 md 의 필드 표는 `scenario.schema.json` 과 1:1 일치해야 한다. schema 갱신 시 반드시 이 표도 같이 수정. ajv 가 검증하는 사실 출처는 `.schema.json` 이고, 본 md 는 사람/AI 가 읽는 가이드다.
+
+## 최상위 구조
+
+```jsonc
+{
+  "modules": {},                          // const {} 고정
+  "htmlkey": "stephtml",                  // const "stephtml" 고정
+  "ScenarioTitle": "",                    // const "" 고정 (가비지 슬롯)
+  "fScenarioName": "시나리오 이름",
+  "fConverterVersion": 1,                 // const 1 고정
+  "StartSteps": ["Step1"],                // Steps 있으면 minItems: 1
+  "Steps": {                              // ← 객체 (Map). 키가 StepId.
+    "Step1": { /* Step */ },
+    "Step2": { /* Step */ }
+  },
+  "Language": {},
+  "Events": {},
+  "ServiceBinding": {},
+  "Collections": {},                      // const {} 고정 (Ksystem 호출 시 타입 결정용 — 런타임이 채움)
+  "DataSources": {},
+  "Scenario": { "StyleURLs": [] },        // 외부 라이브러리 JS 경로 배열
+  "Panel": {                              // 6키 고정, additionalProperties: false
+    "Collection": { "Ckeys": [] },
+    "Category": {},
+    "CategoryOrder": [],
+    "Table": [],
+    "ExternalTable": [],
+    "AuthKey": []
+  },
+  "LastSavedTime": 1766022252184,         // 옵션 (스튜디오 자동 기록)
+  "FlexSQLService": {}                    // const {} 고정 (AI 생성 시)
+  // EmbedScenarioPrefix: 절대 추가 금지 (schema에서 false 로 거부)
+}
+```
+
+## 필드
+
+| 키 | 타입 / 강제 | 비고 |
+|---|---|---|
+| `modules` | **const `{}`** | 런타임 모듈 슬롯. 항상 빈 객체. |
+| `htmlkey` | **const `"stephtml"`** | 고정값. |
+| `ScenarioTitle` | **const `""`** | 가비지 슬롯. 표시명은 `fScenarioName` 사용. |
+| `fScenarioName` | string | 시나리오 표시명. |
+| `fConverterVersion` | **const `1`** | 메타 컨버터 버전. |
+| `StartSteps` | string[] | 진입 StepId 배열. **Steps가 1개 이상이면 minItems: 1 강제**. |
+| `Steps` | object (Map) | 키 = StepId (`Step[A-Za-z0-9_]+`), 값 = Step. patternProperties + additionalProperties: false. |
+| `Language` | object | 다국어 매핑 (`{{key}}` 치환 대상). |
+| `Events` | object | 이벤트 핸들러 정의. |
+| `ServiceBinding` | object | 서비스 바인딩. |
+| `Collections` | **const `{}`** | Ksystem 호출 시 타입 결정용 슬롯. 운영 메타에서는 시스템이 type 정의를 채우는 영역이라 일부 운영 메타에는 데이터 존재. **AI 생성 시 빈 객체**. 추후 AI가 직접 type 정의를 추가하는 요건이 생기면 const 해제. |
+| `DataSources` | object | Combo/RadioBox/Search용 명명 데이터소스. |
+| `Scenario` | object | `additionalProperties: false`. 현재 `StyleURLs` (string[]) 만 허용. **외부 JS 라이브러리(Chart.js, 지도 SDK 등) URL 추가 위치 — 라이브러리 로드는 `f.Script.load()` 보다 여기 등록을 우선**(정적 URL, 진입 시 자동 로드). |
+| `Panel` | object (6키 고정) | `additionalProperties: false`. 키 6개: `Collection`, `Category`, `CategoryOrder`, `Table`, `ExternalTable`, `AuthKey`. AI 생성 시 별도 키 추가 금지. 내부 값(Ckeys 배열, Category 객체 등)은 운영 메타에서 채워질 수 있으나 AI 생성 시 빈 형태. |
+| `LastSavedTime` | number | 마지막 저장 시각 (Unix timestamp ms). 스튜디오 저장 시 자동 기록 — 실 시나리오 42/45 에 존재. AI 생성 시 누락/0 허용. |
+| `FlexSQLService` | **const `{}`** | FlexSQL 서비스 이름/버전 매핑 슬롯. 코드: scenario-studio/studio-util.js:2957. 운영 메타에서는 `{NameArray, VersionMap}` 으로 채워질 수 있으나 AI 생성 시 빈 객체 고정. |
+| `EmbedScenarioPrefix` | **`false` (금지)** | 임베디드 시나리오 ID 접두사. 코드: engine/common/fquery.js:54. **AI 생성에 절대 등장 금지** (schema에서 properties: false 로 거부). |
+
+### Panel 세부 필드
+
+| 키 | 타입 | AI 생성 권장 |
+|---|---|---|
+| `Collection` | `{ Ckeys: array }` | `{ "Ckeys": [] }` |
+| `Category` | object | `{}` |
+| `CategoryOrder` | array | `[]` |
+| `Table` | array | `[]` |
+| `ExternalTable` | array | `[]` |
+| `AuthKey` | array | `[]` |
+
+## StepType / Step 식별 규칙
+
+- StepId 형식: `Step[A-Za-z0-9_]+` (예: `Step1`, `StepMain`).
+- Steps 객체의 키 자체가 StepId (별도 `StepId` 필드 없음).
+- 자세한 Step 분기는 `step.md` 참조.
+
+## 검증 요점 (Schema + Reachability 후검증)
+
+### Schema 차원
+- `Steps` 키 패턴: `^Step[1-9][0-9]*$` (예: `Step1`, `Step2`, `Step10`. **0 시작 불가, 영문/언더스코어 불가, `Step0` 도 불가**.)
+- `StartSteps` 는 **반드시 배열** (단수 `StartStep` 아님 — 단수 `StartStep` 은 StepSub의 `Protocol.StartStep` 키이며 의미가 다름).
+- Steps가 1개 이상이면 `StartSteps` 도 minItems: 1 강제.
+- `htmlkey` 누락 시 런타임 인식 실패.
+- 위 const 들 위반 시 ajv 가 잡아냄.
+
+### Reachability 후검증 (`validate.mjs`)
+- `StartSteps[*]` 는 반드시 `Steps` 의 키 중 하나.
+- `Step.Next[*]` 도 반드시 `Steps` 의 키 중 하나.
+- **모든 Step은 (StartSteps + 모든 Step.Next 합집합) 에서 정확히 1번 등장**해야 한다.
+  - 0회 = 고아 Step (진입 불가).
+  - 2회 이상 = 순환구조 또는 다중 진입 (트리 위반).
+
+이 cross-reference 규칙들은 표준 JSON Schema 로 표현 불가하므로 `validate.mjs` 의 `checkStepReachability()` 후검증 로직으로 처리한다.
+
+## 루트에 없는 필드 (혼동 방지)
+
+다음 키는 **scenarioMeta 루트에 존재하지 않으므로** 컨트랙트나 AI 생성에서 절대 추가하지 말 것:
+
+- `MetaContractVersion` — 컨트랙트 자체의 버전이지 메타 안에 들어가는 값이 아님.
+- `ScenarioId` (루트) — 루트 식별자는 따로 없음. 단, **StepSub의 자식 필드로서의 `ScenarioId`** (호출 대상 시나리오 ID) 는 `StepType: "StepSub"` 와 함께 쓰이는 정상 키.
+- `StartStep` (단수) — 루트에는 항상 **`StartSteps`(복수, 배열)**. 단수 `StartStep` 은 StepSub의 `Protocol.StartStep` 안에서만 등장 (의미: 호출할 서브 시나리오의 시작 Step).
+- `fAppJson` — 일부 운영 메타에 존재하지만 AI 생성 schema에서는 정의하지 않음 (필요시 운영 도구가 처리). `additionalProperties: true` 라 운영 메타도 통과.
+- `EmbedScenarioPrefix` — schema 에서 `false` 로 명시적 거부.
+
+## 예시
+
+`examples/simple-form.json`, `examples/nested-groups.json`, `examples/combo-with-dialog.json`.

package/skill/docs/service/CustomSystem.md

@@ -0,0 +1,139 @@
+# CustomSystem Service (CustomSystem.schema.json) — Action='API' 와 짝
+
+사용자 정의 시스템 (외부 마이크로서비스 / 인증 시스템 / 별도 도메인 백엔드 등) 호출. 워크스페이스 콘솔에서 등록한 [API 연동 템플릿](https://docs.flextudio.com/flextudio/workspace/interface/data/api) 을 이벤트로 등록한 결과 메타.
+
+스튜디오 UI 의 **이벤트 → API 추가** 가 메타에서는 `Action: 'API'` + `SystemType: 'CustomSystem'` 으로 박힘. **`fEventKey` + `fEvent` (= docs.flextudio.com 의 "Event Config Key") 로 외부 라우팅** 정의.
+
+> **참고**: [docs.flextudio.com — API 호출](https://docs.flextudio.com/flextudio/scenario/dev-mode/event/api), [API 연동 템플릿](https://docs.flextudio.com/flextudio/workspace/interface/data/api).
+> **스킬 생성에서는 사용 금지** — `[no-service]` 가 차단.
+
+각 fEvent 값은 [대체 스크립트 `{% %}`](https://docs.flextudio.com/flextudio/concept/alternative) 로 동적 치환. docs.flextudio.com 의 "Event Config Key" 항목이 본 schema 의 `fEventKey` 배열에 해당.
+
+## 1. 사용 시점
+
+- 워크스페이스 콘솔에서 등록한 CustomSystem (이름: `New_01`, `New_02`, `New_05`, ...) 으로의 라우팅.
+- Custom REST 와 차이: URL/Method 직접 노출 X. 시스템 식별자(`New_NN`) + 모듈 GUID + fEvent 매핑으로 추상화.
+- 회사 내부 마이크로서비스, 다른 시나리오 / 도메인 호출.
+
+## 2. 식별 필드
+
+| 필드 | 값 / 패턴 | 비고 |
+|---|---|---|
+| `SystemID` | `^New_[0-9]+$` | 실 샘플: `New_01`, `New_02`, `New_05` |
+| `SystemType` | `"CustomSystem"` (고정) | const |
+| `ModuleID` | GUID v4 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | 워크스페이스가 발급 |
+| `fEventKey` | string[] | 사용할 키 이름 배열 |
+| `fEvent` | { [key]: string } | 키 → 값 매핑 |
+
+## 3. fEventKey + fEvent 페어링
+
+`fEventKey` 에 나열한 키들이 `fEvent` 객체의 키와 일치해야 한다 (워크스페이스 라우팅이 fEventKey 기준으로 fEvent 값을 추출).
+
+```jsonc
+"fEventKey": ["companySeq", "memSeq", "groupSeq", "url", "mapping"],
+"fEvent": {
+  "companySeq": "{%_c.userInfo[0].companySeq%}",
+  "memSeq":     "{%_c.userInfo[0].memSeq%}",
+  "groupSeq":   "{%_c.activeGroup[0].groupSeq%}",
+  "url":        "{%_base.flextudio.serviceUrl%}",
+  "mapping":    "ideation/getmanualmembers"
+}
+```
+
+### fEvent 값 종류
+
+| 형태 | 의미 |
+|---|---|
+| 정적 문자열 (`"ideation/newideation"`) | 외부 시스템의 endpoint path 또는 라우팅 코드 |
+| `{%_base.X.Y%}` | 시스템 컨텍스트 — `_base.User`, `_base.Company`, `_base.flextudio.serviceUrl` 등 |
+| `{%_c.<Cat>[0].<field>%}` | 컬렉션 첫 섹터의 필드 |
+| `{%_c.<Cat>.activeSector.<field>%}` | 활성 섹터의 필드 |
+
+### 표준 fEventKey 항목
+
+실 샘플에서 자주 등장하는 키:
+
+| 키 | 용도 |
+|---|---|
+| `url` | 외부 시스템 base URL (`{%_base.flextudio.serviceUrl%}`) |
+| `mapping` | 라우팅 path (정적 문자열, 예: `"ideation/clickend"`) |
+| `companySeq` / `fBaseCompanyID` | 회사 식별자 |
+| `memSeq` / `fBaseUserNo` | 사용자 식별자 |
+| `groupSeq` | 그룹/조직 식별자 |
+| `ideationSeq` | 기능별 도메인 키 |
+
+## 4. 형태
+
+```jsonc
+"ServiceBinding": {
+  "newIdeation": {
+    "SystemID":       "New_05",
+    "SystemType":     "CustomSystem",
+    "ModuleID":       "59f96601-69c3-411f-93b7-b0b230523fa2",
+    "SetCategory":    true,
+    "UsePKey":        true,
+    "UseParamBlock":  true,
+    "UseResultBlock": true,
+    "NotSeperateInnerBlock": true,
+    "fEventKey":      ["url", "mapping"],
+    "fEvent": {
+      "url":     "{%_base.flextudio.serviceUrl%}",
+      "mapping": "ideation/newideation"
+    }
+  }
+}
+```
+
+## 5. Action 인라인 형태
+
+ServiceBinding 을 별도 등록하지 않고 Action 안에 인라인 박는 패턴:
+
+```jsonc
+"Events": {
+  "doStuff": [{
+    "Action": "API",
+    "ModuleID":      "13be8848-501d-4fa4-a0c7-e5a5b0bcb5e6",
+    "SystemID":      "New_05",
+    "SystemType":    "CustomSystem",
+    "UseCategory":   true,
+    "UseParamBlock": true,
+    "UseResultBlock":true,
+    "UsePKey":       true,
+    "SetCategory":   true,
+    "NotSeperateInnerBlock": true,
+    "fEventKey":     ["fBaseCompanyID", "fBaseUserNo", "url", "mapping"],
+    "fEvent": {
+      "fBaseCompanyID": "{%_base.Company.fBaseCompanyID%}",
+      "fBaseUserNo":    "{%_base.User.fBaseUserNo%}",
+      "url":            "{%_base.flextudio.serviceUrl%}",
+      "mapping":        "member/userinfo"
+    },
+    "ParamBlocks":  [],
+    "ResultBlocks": [{ "TargetType":"replace", "CategoryName":"userInfo" }]
+  }]
+}
+```
+
+`Action: 'API'` 로 적는 게 실 샘플 패턴 (CustomSystem 은 API 호출 형태로 표기).
+
+## 6. API 연동 흐름
+
+```
+[1] Action='API' SystemType='CustomSystem' → 워크스페이스 라우팅
+[2] fEventKey 의 각 키에 대해 fEvent[key] 템플릿 평가
+    (예: {%_base.flextudio.serviceUrl%} → 실제 URL 치환)
+[3] {url}/{mapping} 으로 HTTP 요청 (백엔드 자동 정의된 Method)
+[4] ParamBlocks → 요청 본문
+[5] 응답 → ResultBlocks 카테고리 반영
+```
+
+## 7. 검증 규칙 (스키마 강제)
+
+| 규칙 | 동작 |
+|---|---|
+| `SystemID` 패턴 `^New_[0-9]+$` | `New_NN` 외 거부 |
+| `SystemType === 'CustomSystem'` const | |
+| `ModuleID` GUID v4 패턴 | 잘못된 형식 거부 |
+| `fEventKey` 항목 패턴 `^[A-Za-z_][A-Za-z0-9_]*$` | 식별자 형태 |
+| `fEvent` 모든 값 string | 객체/숫자/null 금지 |
+| `fEventKey` ↔ `fEvent.keys()` 일치 | $comment — 후검증 후크 (TODO) |