@flextudio/scenario 0.1.0

package/skill/skill-guides/control-options.md

@@ -0,0 +1,126 @@
+# Control Options — 컨트롤별 옵션 매트릭스
+
+> 어떤 컨트롤에 어떤 옵션 키가 허용되는가.
+>
+> 진실원본: [schema/v1/control/*.schema.json](../schema/v1/control/), [_base.schema.json](../schema/v1/control/_base.schema.json), [design.schema.json](../schema/v1/design-system/design.schema.json).
+
+## ★ 데이터 바인딩 3종 세트 (생성 전 필수 — 가장 자주 빠뜨림)
+
+> 입력/선택 컨트롤이 **값을 저장하거나(`Ckeys`/`SaveValueKey`) 외부 선택지를 쓰면(`DataSourceName`)**, 아래 셋이 **항상 함께** 있어야 한다. 하나라도 빠지면 cross-check 가 막고, 값이 데이터 의존이라 **자동 보정되지 않는다** — 생성 시 직접 채운다. (자가 검증에서 가장 흔히 깨지는 지점. 단순 프로토타입이면 [데이터연결 없이 화면만](#데이터연결-없이-화면만-프로토타입) 참조.)
+
+1. **조상 Group 의 데이터연결** — 컨트롤을 감싸는 Group(또는 상위 Group) 에 `"UseDataConnection": true` + `DataConnection` 객체.
+   - 없으면 → `[bind]` "uses SaveValueKey but no ancestor Group has UseDataConnection:true + DataConnection".
+2. **`scenario.DataSources` 에 sample 정의** — `DataSourceName` 으로 참조한 **그 이름의 키를 `scenario.DataSources` 에 `Fixed` 또는 `Grid` 로 반드시 생성**. 참조만 하고 정의를 빠뜨리지 않는다.
+   - 미정의 참조 → `[dsref]` "DataSourceName='X' is not defined in scenario.DataSources".
+   - `SaveValueKey` 를 쓰는데 `scenario.DataSources` 가 통째로 비어있음 → `[proto]` "scenario.DataSources is empty".
+   - 운영 타입(`Collection`/`Service`/`API`) 금지 — AI 샘플은 `Fixed`/`Grid` 만 ([data-sources.md](../schema/v1/data-sources.md)).
+3. **컨트롤 측 키** — 저장/표시/매핑 키를 컨트롤에 채운다.
+   - 입력(InputText/Number/…): `Ckeys` / `SaveValueKey`.
+   - 선택(Combo/Search/RadioBox/Tree): `DataSourceName` + 자식의 `DataSourceName` + `CollectionMapper` (UseDataSource:true 면 필수).
+   - 날짜(Calendar): `SelectType` 별 페어객체(`SingleDate` / `StartDate`+`EndDate`) 의 **`Ckeys` 를 1개 이상** 채움 — 데이터연결 컨텍스트에서 빈 배열 `[]` 은 `[date]` "must NOT have fewer than 1 items". (비연결이면 `[]` 허용, 단 페어객체 자체는 항상 둘 것.)
+
+**증상 → 빠뜨린 것 빠른 표**
+
+| validate cross-check | 빠뜨린 것 | 고치기 |
+|---|---|---|
+| `[bind]` | 조상 Group `UseDataConnection`/`DataConnection` | Group 에 데이터연결 부여 (1번) |
+| `[dsref]` `is not defined` | `DataSources` 에 그 이름 정의 | 동일 이름 `Fixed`/`Grid` 추가 (2번) |
+| `[proto]` `DataSources is empty` | `DataSources` 자체 | 최소 1개 `Fixed`/`Grid` 추가 (2번) |
+| `[date]` `fewer than 1 items` | 페어객체 `.Ckeys` 비어있음 | `Ckeys: ["..."]` 채움 (3번) |
+| `must have required property 'DataSourceName'` | 자식 ComboList/List 의 `DataSourceName` | 자식에 추가 ([combo](../schema/v1/control/combo.md)/[search](../schema/v1/control/search.md)) |
+
+> ★ **빈 껍데기 컨트롤 금지 (조회 화면).** 조회 화면은 검색조건 Search/Combo 를 여럿 둔다. 각 컨트롤을 `ControlType` 만 있는 골격으로 두면 위 누락들이 **컨트롤 수만큼 곱으로 폭증**한다(Search N개 → ≈4N 에러). **하나를 끝까지 완결한 뒤 복제**하라. materialize 자동 보정은 *본체에 일부 정보가 있을 때만* 작동하고, 정보가 통째로 빈 컨트롤은 손대지 못한다.
+
+> **materialize 가 자동 정규화하는 항목 (직접 신경 안 써도 흡수됨)** — Calendar `SelectType` 어휘(`One`→`SingleDate`), `ScenarioTitle`→`""`, BottomButton 잉여 토글(`UseEvents`/`UseClickEvent`)·`MoveTo='Prev'`→빈 `Prev`·`Next` 슬롯 객체→`""`·`design` expand, Combo 본체→자식 `DataSourceName` 동기화(★ `Ckeys` 는 자식 ComboList/List 에만 두고 본체엔 두지 않음 — `[combo-body-ckeys]`), `DataConnection` shape, `AllowExtensions` 문자열, boolean 문자열. **단 위는 "정보가 있을 때 형태만" 교정** — 없는 데이터(`DataSources` 정의, `CollectionMapper` 매핑값, Search 자식 `DataSourceName`)는 직접 채워야 한다.
+
+### 데이터연결 없이 화면만 (프로토타입)
+
+저장 의도가 없는 순수 표시/레이아웃이면 데이터연결을 만들지 않는다 — 단 **그 Group 에 `"UseDataConnection": false` 를 명시**하고, 컨트롤에서 `SaveValueKey`/`Ckeys`/`DataSourceName` 을 두지 않는다. (Calendar 등 페어객체는 두되 `Ckeys: []`.)
+
+## 모든 컨트롤이 공유 — `controlBase`
+
+`Id` / `ControlType` / `Caption` / `Width` / `Height` / `Padding` / `Margin` / `Ckeys` / `Events` / `DataConnection` / `Maxlength` / `Placeholder` / `DefaultValue` / `design`
+
+## Input 계열이 추가로 공유 — `inputBase`
+
+`InputText` / `InputNumber` / `InputMask` / `InputDate` / `MultiInputBox` / `Combo` / `Search` / `RadioBox` / `CheckBox`:
+
+`CtrlDisplayCkey` / `DisplayValue` / `DisplayType` / `UseValidate` / `UseCondition` / `UseEvents`
+
+## 컨트롤별 고유 옵션
+
+### 입력 — text/number/mask/date
+
+| 컨트롤 | 고유 옵션 |
+|---|---|
+| `InputText` | `InputType` |
+| `InputNumber` | `InputType` |
+| `InputMask` | `InputType`, `MaskType`, `UseNumberOnly`, `UseFixedDecimalPlaces`, `DecimalPlaces`, `RoundingMode` |
+| `InputDate` | `DateFormat`, `Dialog` |
+| `MultiInputBox` | — |
+
+### 선택 — combo/search/radio/check
+
+| 컨트롤 | 고유 옵션 |
+|---|---|
+| `Combo` | `DataSourceName`, `Dialog` |
+| `Search` | `DisplayValue`, `Dialog` |
+| `RadioBox` | `Items`, `DataSourceName`, `Direction`, `CategoryName`, `UseDataSource`, `UseCategory`, `UseAlignRight`, `UseDefaultValue`, `UseItemDesign`, `ItemBgStyle`, `ItemDesign`, `SaveNameKey` / `SaveNameName` / `SaveValueKey`, `UniqueKey`, `CollectionMapper`, `AfterScript` |
+| `CheckBox` | `CheckBoxType`, `Items`, `SaveValueKey`, `UseAlignRight`, `UseTriming`, `ItemBgStyle` |
+
+### 표시 — label/image/button
+
+| 컨트롤 | 고유 옵션 |
+|---|---|
+| `Label` | `LabelCKey`, `LabelType`, `labeltext`, `ImageStyle`, `MoveStepOrder`, `MoveSteps`, `UseMove`, `UseClickEvent`, `UseFullShape`, `UseTriming`, `TooltipCKey`, `TooltipText`, `TooltipType` |
+| `ImageBox` | `ImageBoxType`, `DefaultViewGroup`, `EditGroup`, `ViewGroup`, `UseDefaultValue`, `UseMultiData` |
+| `Button` | `ButtonName`, `ButtonValue`, `ButtonValueCKey`, `ImageStyle`, `UseClickEvent` |
+
+### 복합 — tab/tree/embed/calendar/calendar-navigator/input-file
+
+| 컨트롤 | 고유 옵션 |
+|---|---|
+| `Tab` | `TabHeader`, `TabHeaderItem`, `SelectTabHeader`, `SelectTabHeaderItem`, `ArrangeItems`, `ArrangeItemsStyle`, `Items`, `ItemName`, `ItemValue`, `LinkedStepId`, `Click` |
+| `Tree` | `CategoryName`, `DataSourceName`, `CollectionMapper`, `MapperOrder`, `TreeType`, `NodeId`, `ParentId`, `Title`, `SubTitle`, `Icon`, `SubIcon`, `ThumbNail`, `DCLinkCkey`, `UseDCLink`, `UseExpandAll`, `UseMultiData`, `UseParentAutoSelect`, `UseSearchBar`, `UseSelectAllData` |
+| `Embed` | `Embed` |
+| `Calendar` | `CalendarType`, `SelectType`, `DayDsKey` |
+| `CalendarNavigator` | `NavigatorType`, `NavigatorDateFormat`, `SingleDate`, `StartDate`, `EndDate`, `SelectDay`, `DayArea`, `DayDsKey`, `DaySetting`, `TypeDsKey`, `UseDayArea`, `UseDaySelector`, `UseDaySetting`, `UseTimeTable`, `UseDataConnection`, `OnChangeSwipe`, `ClickPrevNextBtn`, `CalendarNaviEventsOrder` |
+| `InputFile` | `Title`, `Description`, `Limit`, `AllowExtensions`, `Directory`, `FileName`, `FolderRoute`, `FlexKey`, `Module`, `Const`, `Attributes`, `SharedTarget`, `InnerCKey`, `ckey`, `CategoryName`, `UseCategory`, `UseClickdownload` |
+
+## 자주 헷갈리는 매핑
+
+| 의도 | 정답 |
+|---|---|
+| 1000단위 콤마 (금액) | `InputMask` + `InputType:"money"` + `MaskType:"Money"` (★대소문자 정확히 — `money`/`time` 아님; InputType↔MaskType 짝: hhmm↔Time, money↔Money, yyyymmdd↔Date, phone↔Phone) |
+| 라벨 표시 종류 (`LabelType`) | 정적 문구 → `LabelType:"labeltext"` + `labeltext:"값"` / 카테고리 필드값 표시 → `LabelType:"LabelCKey"` + `LabelCKey:"키"`. **임의값 금지** (`ckey`/`labelvalue` 등 — 정확값은 `labeltext` 또는 `LabelCKey` 둘뿐) |
+| 버튼 클릭 이벤트 | `BottomButton` → `Events:{ "Click":"<핸들러>" }` (★`Events` 안에 — top-level `Click` 아님; 값=`scenario.Events` 핸들러 이름). Step 이동은 `MoveTo:"Next"` + `Next:{ "MoveStepOrder":["StepN"] }` (또는 `Prev`). `Button` 컨트롤 → `UseClickEvent:true` + `Events.Click`. **금지**: top-level `Click`, `ClickEvent`/`SubmitEvent` 임의 키, BottomButton 에 `UseClickEvent` |
+| Step 이벤트 키 (`Step.Events`) | 허용 키만: `Init`/`Loaded`/`OnBackLoaded`/`OnLeave`/`OnForeground`/`ScrollEnd` (+`StepEventOrder`). 값은 `scenario.Events` 핸들러 **이름(문자열)** — 임의 키(`SubmitEvent` 등)나 인라인 액션 배열 금지(핸들러 본문은 `scenario.Events` 에) |
+| 파일 첨부 (`InputFile`) | `Module` **필수**(기본 `"FlexFile"`; 5종 enum) + Module별 `Attributes` shape (상세 `docs/control/input-file.md`). `AllowExtensions` 는 소문자 확장자 **배열** `["jpg","pdf"]` (콤마 문자열 아님) |
+| 날짜 입력 | `InputDate` + `DateFormat` |
+| 라벨 문자열 | 컨트롤 본체의 `Caption` |
+| 라벨 글자 크기 | `design.caption.text` |
+| Group vs Control 분리 | Group 의 `Contents` 배열 아이템 = Control 노드 |
+| 이벤트 핸들러 본문 | `scenario.Events` 에 정의 |
+| 비연결 Group 명시 | 모든 Group 에 `UseDataConnection: false` 도 명시(생략 금지, `[group-dc]`) → 상세 `group.md` "함정" |
+| 날짜 캘린더 Ckeys | 아래 "Calendar — SelectType / Ckeys 결정표" 참조 (페어 객체는 항상, `Ckeys` 채움만 조건부) |
+
+## Calendar — SelectType / 페어객체 / Ckeys / 데이터연결 결정표
+
+`Calendar`(InputDate 자식 또는 단독)의 `SelectType` 별 필수 구조. **페어 객체(`SingleDate`/`StartDate`/`EndDate`)는 항상 필수이고, `Ckeys` 를 채우느냐만 데이터연결 컨텍스트에 따라 갈린다** (`[date]` cross-check = `core/validators.mjs` checkInputDateConsistency).
+
+| SelectType | 필수 페어 객체 | Ckeys — 조상 Group `UseDataConnection:true` | Ckeys — 비연결(프로토타이핑) |
+|---|---|---|---|
+| `SingleDate` | `SingleDate` (항상) | `["..."]` 1개 이상 필수 | `[]` 허용 |
+| `FromTo` (dayCalendar 전용) | `StartDate` + `EndDate` (둘 다 항상) | 각 `["..."]` 1개 이상 | 각 `[]` 허용 |
+
+- `monthCalendar` / `yearCalendar` → `SelectType` 은 `SingleDate` 만.
+- `SingleDate: {}` 빈 객체 금지 — `Ckeys` 키는 항상 두되 값만 `[]` / `["..."]` (런타임 `dlgJson.SingleDate.Ckeys` 접근 안전).
+- 상세: `schema/v1/control/calendar.md`, `schema/v1/control/input-date.md`.
+
+## Combo / Search / InputDate 의 Dialog 호스트
+
+| 본체 | Dialog 자식 |
+|---|---|
+| `Combo` | `ComboList` |
+| `Search` | `List` |
+| `InputDate` | `Calendar` |

package/skill/skill-guides/events.md

@@ -0,0 +1,61 @@
+# 이벤트(Events) 가이드
+
+> 핸들러가 어떻게 정의·연결·실행되는지, 그리고 더 깔끔하게 구성하는 법.
+> 진실원본: [schema/v1/events.md](../schema/v1/events.md) · [core/validators.mjs](../core/validators.mjs)
+
+## 개념 — 이벤트가 동작하는 방식
+
+이벤트는 세 부분으로 나뉜다.
+
+1. **핸들러 맵** — `scenario.Events` 는 `이름 → Action 배열` 맵이다. Action 은 위에서
+   아래로 순차 실행된다.
+2. **호출자 연결** — Step/Group/Control/BottomButton 이 자신의 `Events.<eventKey>` 값에
+   핸들러 이름을 적어 연결한다.
+3. **실행 등록** — 호출자의 `*EventOrder` 배열(`StepEventOrder`, `ComboOrder` …)에 올라간
+   이벤트만 실제로 호출된다. 정의만 하고 EventOrder 에 없으면 동작하지 않는다.
+
+```jsonc
+"Events": {
+  "Init":    [ { "Action": "Script", "Script": "Current.step.set('UserName', '홍길동');" } ],
+  "getList": [ { "Action": "Script", "Script": "f.Content('f_3').reload();" } ]
+}
+// 호출자 — EventOrder 에 등록해야 실제 호출됨
+"Steps": { "Step1": { "StepEventOrder": ["Init"], "Events": { "Init": "Init", "Loaded": "getList" } } }
+```
+
+## 권장 방식 — 기본적으로 이렇게
+
+- **Action 은 `Script` 또는 `LinkedEvent` 만** 쓴다. 서버 호출(`Service`/`API`)은 운영 단계에서
+  사용자가 추가한다 — 생성 단계에서는 화면 동작과 샘플 데이터만 표현한다.
+- **Script 본문은 JSON 문자열 한 줄**로 박고 줄바꿈은 `\n` 이스케이프로 표현한다.
+  JS `+` 연결이나 raw newline 은 파싱을 깨뜨린다.
+  - ✓ `"Script": "if (cond) return;\nf.Content('f_3').reload();"`
+- **핸들러 이름은 영문**(`^[A-Za-z_][A-Za-z0-9_.]*$`). 한국어·공백·하이픈은 쓰지 않는다.
+- **Combo / Search / InputDate 의 이벤트는 자식 Dialog 안**(`Dialog.Layouts[0].Controls[0]`)에
+  둔다. 본체(root)에 `Events`/`UseEvents` 를 붙이지 않는다.
+
+## 더 좋게 — 한 단계 끌어올리는 법
+
+- **핸들러를 작게 쪼개고 `LinkedEvent` 로 조합한다.** 한 핸들러에 모든 로직을 몰아넣기보다
+  `validate → save → reloadList` 처럼 의미 단위로 나누면 재사용·가독성이 올라간다.
+
+  ```jsonc
+  "userCheck": [
+    { "Action": "Script",      "Script": "if (f.Setting.UserId === '') return;" },
+    { "Action": "LinkedEvent", "EventName": "getList" }
+  ]
+  ```
+- **이름으로 의도를 드러낸다.** `e1`·`onClick2` 대신 `SaveBookingEvent`·`reloadOrderList` 처럼
+  무엇을 하는지 이름만 봐도 읽히게 짓는다.
+- **EventOrder 를 흐름 문서처럼 쓴다.** `["Init", "Loaded"]` 순서가 곧 화면 생애주기다 —
+  순서를 읽으면 동작이 보이도록 정렬한다.
+- **데이터 갱신은 범위를 최소로.** 전체 Step reload(`Current.step.reload()`)보다 영향받는
+  그룹만 `f.Content('f_3').reload()` 로 갱신하면 깜빡임과 비용이 준다.
+
+## 자주 틀리는 점 — 짧은 체크리스트
+
+- [ ] 핸들러를 만들었는데 `*EventOrder` 에 안 넣음 → 호출 안 됨
+- [ ] `Events.<key>` / `LinkedEvent.EventName` 값이 `scenario.Events` 키와 불일치(오타) → `[event-ref]`
+- [ ] Combo/Search/InputDate **본체**에 이벤트 부착 → `[event]`
+- [ ] Action 에 `Service`/`API` 사용 → 생성 금지(`[no-service]`)
+- [ ] Script 를 `+` 연결/여러 줄로 작성 → 파싱 실패

package/skill/skill-guides/failure-discipline.md

@@ -0,0 +1,95 @@
+# Failure Discipline
+
+This file extends `SKILL.md` for the validate-failure path. Where
+`output-discipline` covers the emit step after `validate` returns `ok:true`,
+this file covers what happens when it returns `ok:false` — or returns
+something you did not expect. The failure mode here is not a broken delivery;
+it is wasted cycles chasing the wrong cause.
+
+## The prior
+
+**`ok:false` means your input is wrong, not the tool.** The schema is ground
+truth. `flex-scenario`, `ajv`, and the schema compiler are not under
+suspicion. Start every recovery from "the JSON I generated violates the
+contract" and stay there until the report proves otherwise.
+
+**A tool-bug hypothesis is the last resort, never the first.** "Maybe ajv
+mishandles cross-document `$ref`," "maybe `unevaluatedProperties` is a known
+limitation," "maybe the spec is ambiguous" — these are the most expensive and
+least likely explanations. If one forms, it is a signal that the prior has
+flipped. Re-suspect the input before opening any `node_module`.
+
+**Surprising output is still your output.** A materialized result that looks
+wrong, a fragment validation that comes back empty, a count you did not
+expect — treat it as a fact about what you produced, not a fault in the
+reporter.
+
+## Reading the report
+
+**`errorCount` is volume, not severity.** One violation can emit hundreds of
+errors. A report of hundreds errors is not the problems — it is usually one cause
+plus its cascade. Never let the headline number set the response.
+
+**Group by `kind` first, then read `schema`-kind from the deepest
+`instancePath` up.** The `schema` errors point at concrete contract
+violations (`must have required property 'X'`, `must match "then" schema`,
+`must be equal to constant`). The deepest path is closest to the real cause;
+shallower errors are usually consequences of it.
+
+**Treat `strict-fields` / `unevaluatedProperties` as derivative.** When a
+`oneOf` fails to resolve a branch, the strict variant flags *every* field —
+including valid ones like `ControlType` — as undefined. These are cascade
+noise, not the cause. Read them last, or not at all, until the `schema`
+errors are resolved.
+
+**A control that fails every branch failed the branch it was trying to be.**
+A node with `ControlType: "InputDate"` reporting `missing 'ContentsType'`
+(the Group branch) and `must be equal to constant` ×18 (the other control
+branches) is one failure refracted through the discriminator. Read only the
+InputDate branch's `schema` errors; discard the other branches' output.
+
+## Diagnose before editing
+
+**Read the actual cause before changing a byte.** No structural rewrite
+precedes diagnosis. "Rewrite it to match a known-good example" before knowing
+what failed produces the same failure with new line numbers.
+
+**Cheapest test first.** Before opening `validators.mjs`, `schemas.mjs`, or
+any validator internal: key-diff your failing node against the nearest passing
+example in `examples/`. The difference is almost always one field, and the
+diff finds it faster than reading the engine that reports it.
+
+## One change, re-validate
+
+**One minimal edit at the deepest violation, then re-run.** Fix the single
+`schema` error closest to the leaf, re-validate, re-read. Do not batch fixes
+or rewrite a whole control — batching destroys the mapping between a change
+and its effect, and a rewrite reintroduces causes you already cleared.
+
+## Recovery cues
+
+The following are drift signals — when any appears, stop the current line of
+investigation and return to the prior.
+
+**About to hypothesize a bug in `ajv`, `flex-scenario`, or the schema
+compiler.** The prior has flipped. Re-suspect your input. The cause is in the
+report, not the engine.
+
+**About to open `validators.mjs`, `schemas.mjs`, or a file under
+`node_modules/`.** Did you read the `schema`-kind errors at the deepest
+`instancePath` first? The validator internals explain *why noise is emitted*;
+they do not contain the fix. The fix is the one contract violation that
+triggered the cascade.
+
+**The error count is large and urgency rises.** Count is cascade volume.
+Collapse the `strict-fields` errors, find the handful of `schema` errors,
+work the deepest one. Panic scales with the number; the work does not.
+
+**About to rewrite a whole control, group, or step.** You have not isolated a
+single cause. Narrow to one `instancePath`, fix that, re-validate. Rewriting
+is diagnosis avoidance.
+
+**The thought "I'm going in circles" appears.** That *is* the signal — not a
+prompt to theorize harder. Stop. Either run a key-diff against a passing
+example, or make the single deepest-error edit and re-validate. Action on one
+concrete error beats another pass over the theory.

package/skill/skill-guides/index.json

@@ -0,0 +1,40 @@
+{
+  "count": 6,
+  "guides": [
+    {
+      "id": "control-options",
+      "path": "control-options.md",
+      "title": "Control Options — 컨트롤별 옵션 매트릭스",
+      "summary": "어떤 컨트롤에 어떤 옵션 키가 허용되는가."
+    },
+    {
+      "id": "events",
+      "path": "events.md",
+      "title": "이벤트(Events) 가이드",
+      "summary": "핸들러가 어떻게 정의·연결·실행되는지, 그리고 더 깔끔하게 구성하는 법."
+    },
+    {
+      "id": "failure-discipline",
+      "path": "failure-discipline.md",
+      "title": "Failure Discipline"
+    },
+    {
+      "id": "prompt-interview",
+      "path": "prompt-interview.md",
+      "title": "Prompt Interview — 비대화형 5질문 자기-답변",
+      "summary": "CLI 파이프(`flex-scenario gen`) 는 사용자에게 되묻는 통로가 없다. 모호 입력(L1~L2) 에서도 산출물은 **JSON 한 덩어리** 로 떨어진다. 그 결과 모델이 어떤 가정으로 시나리오를 만들었는지 외부에서 보이지 않아 사용자가 redirect 할 수 없는 게 병목 6."
+    },
+    {
+      "id": "scripts",
+      "path": "scripts.md",
+      "title": "Script 본문 가이드",
+      "summary": "이벤트 핸들러의 `Action:'Script'` 본문은 **intent short-form 을 1순위로 사용**한다. raw JS 본문은 intent 가 표현 못 하는 분기/조건이 있을 때만 escape hatch."
+    },
+    {
+      "id": "step-navigation",
+      "path": "step-navigation.md",
+      "title": "Step 이동 가이드",
+      "summary": "헤더 뒤로가기·하단 버튼·리스트 카드 클릭 등 Step 간 이동을 메타 채널로 표현하는 법."
+    }
+  ]
+}

package/skill/skill-guides/prompt-interview.md

@@ -0,0 +1,92 @@
+# Prompt Interview — 비대화형 5질문 자기-답변
+
+> CLI 파이프(`flex-scenario gen`) 는 사용자에게 되묻는 통로가 없다. 모호 입력(L1~L2) 에서도 산출물은 **JSON 한 덩어리** 로 떨어진다. 그 결과 모델이 어떤 가정으로 시나리오를 만들었는지 외부에서 보이지 않아 사용자가 redirect 할 수 없는 게 병목 6.
+>
+> 이 가이드는 그 병목을 **모델이 자기 자신에게 5질문을 던지고 답을 시나리오에 명시적으로 기록** 하는 절차로 해소한다. 모드는 **비대화형 한 가지** — Claude Code 대화형은 별도 운용 (사람이 직접 묻고 답함).
+
+## 적용 시점
+
+- SKILL.md §시퀀스 **3 (요청 분석) 직후, 4 (examples Read) 직전**.
+- 케이스 한 줄에 도메인만 적힌 L1 / 도메인+기능만 적힌 L2 케이스에서 특히 중요. L4~L5 풀스펙 케이스는 사실상 no-op (이미 답이 다 적혀 있음).
+
+## 5질문 — 자기 답변 체크리스트
+
+비대화형이므로 **모델이 직접 답을 만든다**. 답은 케이스 본문에서 추출 가능한 것 → 도메인 상식 추론 → 시나리오 표준 default 순으로 선택.
+
+| # | 질문 | 답의 형식 | 추출 단서 / 기본값 |
+|---|---|---|---|
+| Q1 | **무슨 화면인가** (한 문장 정의) | 자유서술 1줄 | 케이스 첫 문장 우선 |
+| Q2 | **Step 수와 흐름** | `N step (Step1: ... → Step2: ... → ...)` | 케이스에 명시 없으면 — 단순 입력 폼: 1, 입력→확인: 2, 입력→내역→확인: 3, 다중 입력 단계: 3~5 |
+| Q3 | **각 Step 의 핵심 필드/컨트롤** | Step 별로 1줄: `Step1: 필드a/필드b/...` | 케이스에서 콤마/줄바꿈으로 묶인 항목 추출 |
+| Q4 | **DataConnection 모드** | `query / new / update / detail` 중 어떤 조합 | 리스트/반복 표시 → `query`, 신규 입력 → `new` (mock 면제), 활성 섹터 편집 → `update`, 단건 조회 → `detail` |
+| Q5 | **완료 후 동작** | `Step.Next` / 닫기 / 메시지 / 다음 화면 | 케이스에 명시 없으면 — 최종 Step 의 "제출/저장" 버튼 → `intent.script:{kind:'dialog', type:'Completed'}` + `MOVETYPE_INIT` 로 처음으로 복귀 |
+
+> 5질문 외에 추가로 결정해야 할 슬롯(예: BackButton 표준 적용 여부 / Combo 의 다이얼로그 호스트 자식 / 카테고리명 컨벤션) 은 SKILL.md §"절대 금지" 와 cross-check 가 강제하므로 5질문에 포함하지 않는다 — 표준 자체로 결정됨.
+
+## `__notes` 슬롯 — 답을 시나리오 root 에 기록
+
+자기-답변 결과는 시나리오 root 의 `__notes` 슬롯에 **5~7줄, 한 줄 한 답** 으로 기록한다. 이 슬롯은 `schema/v1/scenario.schema.json` 에 화이트리스트로 등재되어 strict-fields 를 통과한다.
+
+### 형식
+
+```jsonc
+{
+  "Steps": { ... },
+  "StartSteps": [ "Step1" ],
+  "__notes": [
+    "Q1: 출장 경비 정산 — 3-step (기본정보 → 비용항목 → 확인) 입력 화면",
+    "Q2: 3 step — 케이스에 'Step 1/2/3' 명시되어 그대로 채택",
+    "Q3-Step1: 출장지/부서/시작일/종료일/목적",
+    "Q3-Step2: 비용 시트 (사용일/항목/금액/영수증/비고) + read-only 합계",
+    "Q3-Step3: Step1+Step2 요약 (read-only Label / Input)",
+    "Q4: Step2 비용 시트는 DataUsage:'query' (반복 입력). 그 외 Step 은 단일 입력 폼이라 명시적 DC 불필요",
+    "Q5: Step3 '제출' 버튼 → dialog(type:'Completed') + MOVETYPE_INIT 으로 첫 Step 복귀"
+  ]
+}
+```
+
+### 기록 원칙
+
+1. **각 줄은 `Q<번호>: ...` 또는 `Q<번호>-Step<N>: ...` 로 시작** — 사용자가 어떤 질문에 답한 줄인지 즉시 파악 가능.
+2. **케이스 본문에서 추출했는지 / 추론했는지 구분** — 추론한 경우 답 뒤에 짧은 근거 (`(케이스에 명시 없어 N step 단순 폼으로 추정)`) 한 마디 덧붙임. 사용자가 redirect 할 때 추론 부분만 골라 수정 가능.
+3. **5~7줄 권장, 12줄 한도** (schema `maxItems:12`). 그 이상 필요하면 케이스가 충분히 구체적이라 자기-인터뷰가 불필요한 단계 — 그대로 본문 작성에 집중.
+4. **결정만 기록, 설명 금지** — "그래서 이렇게 했다" 는 적지 않는다. 결정 자체가 시나리오 본문에 펼쳐져 있다.
+
+## 모드 판별
+
+CLI 비대화형 호출에서만 `__notes` 를 채운다. 사람이 Claude Code 에서 직접 SKILL 을 호출한 대화형 흐름에선 모델이 사용자에게 1~2개 되묻고 진행하므로 `__notes` 슬롯은 비워둔다 (또는 사용자가 결정한 답을 같은 형식으로 기록).
+
+```
+case.md → 사용자 통로 없음? (CLI 파이프 / OneShot)
+  ├─ Yes → 5질문 자기-답변 → __notes 기록 → 시나리오 작성
+  └─ No  → 모호 슬롯 1~2개 사용자에게 되묻기 → 답 받고 진행 (__notes 비움)
+```
+
+판별 단서:
+- 환경변수 `FLEX_INTERACTIVE=1` 이 있으면 대화형.
+- 그 외엔 비대화형으로 가정 — `flex-scenario gen` 은 항상 비대화형.
+
+## L1/L2 케이스 — 무엇을 추정해야 하나
+
+L1 (도메인 한 단어), L2 (도메인+기능) 케이스에서 자주 빈 슬롯이 되는 항목과 표준 default:
+
+| 빈 슬롯 | 표준 default | 비고 |
+|---|---|---|
+| Step 수 | 단순 폼 1 / 입력→확인 2 / 입력→내역→확인 3 | 케이스에 "한 화면" 같은 단서가 있으면 1, "확인" / "결재" 가 있으면 2~ |
+| 필드 종류 | 도메인 상식 5~7개 + 메모/비고 1개 | 휴가신청: 신청자/부서/시작일/종료일/사유. 견적서: 거래처/품목/수량/단가/금액 |
+| 데이터 모드 | 단건 폼은 명시 안 함. 시트/리스트가 있으면 `query` | `new` / `update` 는 케이스에 "수정/등록" 명시될 때만 |
+| BackButton | 모든 Step `UseBackButton:true` + 첫 Step 닫기 / 후속 Step 이전 Step 복귀 | 표준이므로 5질문 외 자동 |
+| 완료 동작 | `intent.script(dialog)` + `MOVETYPE_INIT` | "처리되었습니다" 한 줄 |
+
+## 안티패턴
+
+- **`__notes` 에 본문 설명을 적는다** — 결정 자체는 본문에 펼쳐져 있어야 한다. `__notes` 는 *결정 근거* 만.
+- **5질문 모두 그대로 적는다** — 케이스에 이미 답이 있는 질문은 생략 가능 (L4~L5). `__notes` 는 결정한 *추론 부분* 만 적어도 충분.
+- **`{=Field}` 토큰으로 Step 간 값 전달을 적는다** — Step 간 값 전달은 [INTENT.md §`copyStepValues`](../runtime/v1/intent-system/INTENT.md) 가 정답. `__notes` 와 무관.
+- **사용자에게 되묻는 문구를 답에 적는다** — 비대화형에서 "어떤 도메인을 원하시나요?" 는 의미 없다. 자기 답을 만들어 기록.
+
+## 측정
+
+- 비대화형 호출에서 `__notes` 가 비어 있으면 (L1/L2 인데도) 자기-인터뷰 누락 — 회귀.
+- `__notes` 가 7줄 초과 + L4/L5 인 경우 — 과잉 기록 (케이스가 이미 구체적이라 자기-인터뷰 불필요).
+- 사용자가 결과를 보고 "이 가정이 틀렸다" 며 redirect 한 경우, 어떤 Q 항목이 어긋났는지 `__notes` 가 즉시 보여줘야 한다.

package/skill/skill-guides/scripts.md

@@ -0,0 +1,169 @@
+# Script 본문 가이드
+
+> 이벤트 핸들러의 `Action:'Script'` 본문은 **intent short-form 을 1순위로 사용**한다. raw JS 본문은 intent 가 표현 못 하는 분기/조건이 있을 때만 escape hatch.
+>
+> 정본:
+> - **intent 카탈로그**: [runtime/v1/intent-system/INTENT.md](../runtime/v1/intent-system/INTENT.md) (슬롯·scope·kind 매트릭스)
+> - **intent 인프라**: [runtime/v1/intent-system/README.md](../runtime/v1/intent-system/README.md)
+> - raw API 진실원본 (fallback 참고용): [scenario-gen-rules.md](../runtime/v1/script/scenario-gen-rules.md) · [_c.md](../runtime/v1/collection/_c.md) · [f_messagebox.md](../runtime/v1/script/f_messagebox.md) · [f_collection.md](../runtime/v1/script/f_collection.md) · [f_content.md](../runtime/v1/script/f_content.md)
+> - 검증: [core/validators.mjs](../core/validators.mjs) `SCRIPT_DENY_PATTERNS` (펼침 후 결과까지 검사)
+
+## 의도 → intent 매핑 (1순위)
+
+| 의도 | intent 표기 | scope |
+|---|---|---|
+| Init 단계 mock 데이터 박기 | `intent.mock: { CtgX: [{...}, ...] }` | `event-script-init` (Step.Events.Init Action) |
+| 활성 섹터의 N개 필드 일괄 갱신 | `intent.script: { kind:'updateActive', cat, set:{...}, reload? }` | `event-script` |
+| 활성 섹터 삭제 | `intent.script: { kind:'deleteActive', cat, reload? }` | `event-script` |
+| 카테고리 통째로 비우기 | `intent.script: { kind:'clearCategory', cat, reload? }` | `event-script` |
+| 그룹 부분 재렌더만 | `intent.script: { kind:'reloadGroup', fid }` | `event-script` |
+| 모달 다이얼로그 (확인/취소·에러) | `intent.script: { kind:'dialog', type, title, body?, buttons:[...] }` | `event-script` |
+
+> Categories 정의 / `Collections` 슬롯 / `Panel.*` 은 **스튜디오 자동 재생성** — AI 단에서 채우지 않음. 카테고리 사용 사실은 `intent.mock` 의 카테고리명 + `DataConnection.CategoryName` 으로 cross-check 가 자동 추출.
+
+이 매트릭스의 의도면 intent 로 표현 가능. **intent 펼침 결과가 raw 와 동등** — `[script-allow]` / `[mock-init]` / `[event-ref]` cross-check 모두 통과.
+
+## intent 사용 — 6 가지 표준 패턴
+
+### A. Init mock 데이터 — `intent.mock`
+
+```jsonc
+{
+  "Steps": {
+    "Step1": {
+      "Events": {
+        "Init": [{
+          "Action": "Script",
+          "intent": {
+            "mock": {
+              "CtgEmployee": [
+                { "fName": "홍길동", "fAge": 30 },
+                { "fName": "김철수", "fAge": 25 }
+              ]
+            }
+          }
+        }]
+      }
+    }
+  }
+}
+```
+
+가드: 카테고리명 `^Ctg[A-Z]…` / 섹터 키는 [naming-objects.schema.json](../schema/v1/naming-objects.schema.json) 의 `sectorReservedKeys` + `jsReservedWords` 와 case-insensitive 충돌 차단 (`Status` / `STATUS` / `Length` 등).
+
+### B. 활성 섹터 일괄 갱신 — `intent.script.updateActive`
+
+```jsonc
+{ "Action": "Script", "intent": { "script": {
+    "kind": "updateActive",
+    "cat": "CtgList",
+    "set": { "fStatus": "확정", "fApprovedAt": "2024-01-01" },
+    "reload": "f_3"
+}}}
+```
+
+펼침 결과: 가드 2단 (`if (!_c.CtgList) return; … if (!cur) return;`) + 직접 대입 N + `f.Content('f_3').reload();`
+
+### C. 활성 섹터 완전삭제 — `intent.script.deleteActive`
+
+```jsonc
+{ "Action": "Script", "intent": { "script": {
+    "kind": "deleteActive", "cat": "CtgCart", "reload": "f_5"
+}}}
+```
+
+펼침 결과: 가드 2단 + `cur.release();` (완전삭제) + reload. ★ raw `.delete()` 는 added 가 아닌 섹터를 deleted 상태로 남겨 집계/루프를 오염시키므로 금지 (`[script-allow]` 차단) — 완전삭제는 `release()`.
+
+### D. 카테고리 비우기 — `intent.script.clearCategory`
+
+```jsonc
+{ "Action": "Script", "intent": { "script": {
+    "kind": "clearCategory", "cat": "CtgOrderHistory", "reload": "f_3"
+}}}
+```
+
+### E. 그룹 재렌더만 — `intent.script.reloadGroup`
+
+```jsonc
+{ "Action": "Script", "intent": { "script": { "kind": "reloadGroup", "fid": "f_3" } } }
+```
+
+### F. 모달 다이얼로그 — `intent.script.dialog`
+
+```jsonc
+{ "Action": "Script", "intent": { "script": {
+    "kind": "dialog",
+    "type": "Alert",
+    "title": "삭제하시겠습니까?",
+    "body": "이 작업은 되돌릴 수 없습니다.",
+    "buttons": [
+      { "label": "확인", "event": "DeleteConfirmEvent" },
+      { "label": "취소", "color": "sub" }
+    ]
+}}}
+```
+
+- 종결자는 항상 펼침 단계에서 `.show()` — `.send()` 오타 불가능.
+- 버튼 액션은 `event` 문자열 (scenario.Events 키) 또는 생략 (닫기만). inline function 표현 불가.
+
+## intent + raw 머지
+
+같은 Action 안에 `intent` 와 raw `Script` 가 공존 가능. **펼침 결과가 raw 앞에 prepend**:
+
+```jsonc
+{
+  "Action": "Script",
+  "Script": "// 후속 로직 (intent 가 표현 못 하는 부분)",
+  "intent": { "script": { "kind": "updateActive", "cat": "CtgX", "set": { "fA": 1 } } }
+}
+```
+
+펼친 결과:
+```
+if (!_c.CtgX) return;
+const cur = _c.CtgX.activeSector;
+if (!cur) return;
+cur.fA = 1;
+// 후속 로직 (intent 가 표현 못 하는 부분)
+```
+
+## raw escape hatch — intent 미지원 영역
+
+intent 매트릭스에 없는 의도는 raw 본문으로. 대표적인 경우:
+
+| 의도 | raw 표기 | 정본 |
+|---|---|---|
+| 런타임 단건 섹터 추가 (Init 외) | `f.Collection.addSector({...}, 'CtgX')` | [f_collection.md](../runtime/v1/script/f_collection.md) |
+| 다중 카테고리에 상태 조건부 섹터 제거 | `f.Collection.removeSector('deleted', 'CtgX')` | 동상 |
+| 분기 조건 (`if (_c.CtgX.length > 5) { ... }`) | raw JS — 절제 사용 | [_c.md](../runtime/v1/collection/_c.md) |
+| 날짜 계산 | `f.Date('${rawDate}').format('YYYY-MM-DD')` | [scenario-gen-rules.md §2-3](../runtime/v1/script/scenario-gen-rules.md) |
+| 다음 이벤트 호출 / 중단 | `f.Event(name).runNext()` / `.break()` | 동상 |
+| 외부 스크립트 로드 | `f.Script.load('https://...', null, null)` | 동상 |
+| Step 전체 재렌더 | `Current.step.reload()` | [current_step.md](../runtime/v1/script/current_step.md) |
+| 섹터로 좁힌 부분 재렌더 (Embed `{%Load.sector%}` 바인딩 갱신 등) | `f.Content('<부모그룹 fid>', <그 그룹을 그린 섹터>).reload()` — sector 인자 필수, DC 그룹 자체 fid 금지(비연결 래퍼로) | [f_content.md §3-1·§5-4](../runtime/v1/script/f_content.md), [embed.md](../schema/v1/control/embed.md) |
+
+raw 본문 작성 시 가드:
+- **`activeSector` 사용 전 카테고리 + active 가드 2단** — intent.script.updateActive / deleteActive 는 자동 emit, raw 는 직접 적기.
+- **다량 변경은 직접 대입 + 마지막 한 번만 reload**. `set` 호출 매번 reload 트리거하지 말 것.
+- **카테고리명 / 컬렉션키 예약어 충돌 검사** — [naming-objects.schema.json](../schema/v1/naming-objects.schema.json) 의 두 enum. `Status` / `Length` / `IsActive` 등 case-insensitive 충돌은 `[script-allow]` 가 차단하지 않으므로 raw 작성 시 직접 회피.
+
+## 자주 틀리는 점 — 짧은 체크리스트
+
+- [ ] `intent.script.dialog` 가 표현 가능한 다이얼로그를 raw `f.MessageBox()` 로 박음 — **intent 우선**, raw 는 표현 한계 시 (예: 동적 button label).
+- [ ] `intent.mock` 대신 raw `addSector` 를 Init 에 박음 — intent 가 카테고리명 / 예약어 / 인자 순서 모두 자동 가드.
+- [ ] `f.MessageBox().send(...)` / `.setBody(...)` / `.chain(...)` — **가짜 메서드**. intent 사용 시 구조적으로 차단.
+- [ ] `_c.<Cat>.clear()` / `_c.<Cat>.deleteActiveSector()` / `_c.<Cat>.activeSector()` / `_c.<Cat>.sectors()` — 가짜. intent.script.clearCategory / deleteActive 권장.
+- [ ] `f.Message()` (인스턴스) — 차단된 채널. `f.MessageBox` 또는 intent.script.dialog 만.
+- [ ] `f.Notification` — 전체 발송 차단. 다이얼로그는 intent.script.dialog.
+- [ ] `Current.step.moveToNext(...)` 같은 명령형 흐름 제어 — 메타 채널 (`BottomButton.MoveTo` / `UseMove + MoveSteps`).
+- [ ] `f.Frame.popUp(...)` — 같은 시나리오 PopUp 은 메타 (`StepDialogType`).
+- [ ] `{=Field}` 가 event Script 본문에 박힘 — display 토큰 전용. event Script 안에서는 `_c.<Cat>.activeSector.<Field>` 로 명시 참조.
+
+## 가짜 핸들이 의심될 때
+
+1. **intent 매트릭스에 의도가 있나?** 있으면 intent 사용.
+2. **본 파일의 raw escape 표에 있나?** 있으면 raw fallback OK.
+3. **공식 자동완성에 잡히나?** 스튜디오 IDE 에서 `f.<X>().` / `_c.<Cat>.` 를 쳐서 노출되는 것 외엔 가짜.
+4. **`runtime/v1/script/` 또는 `runtime/v1/collection/` 에 명시되어 있나?** 없으면 가짜.
+
+그래도 모호하면 `feedback/` 에 한 줄 머지 → ready-to-promote → 검증.