@flextudio/scenario 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,260 @@
+# @flextudio/scenario
+
+flextudio meta-contract v1 시나리오를 **MCP 서버 없이** Claude Code Skill + 자체 CLI 만으로 생성하고 검증한다.
+
+## 2종 빌드 프로파일 (단일 소스)
+
+> **배포는 항상 base(otel 없음).** otel 프로파일은 벤치 트레이싱 전용이며 배포 산출물이 아니다.
+
+| 프로파일 | 패키지명 | otel | 용도 |
+|---|---|---|---|
+| **base** (기본·배포) | `@flextudio/scenario` | 없음 | 배포 — 사람들이 `npm i -g` 해서 직접 쓰는 일반 버전 |
+| **otel** | `@flextudio/scenario-gen-otel` | 포함(@opentelemetry/* + collector) | 벤치 트레이스 span 방출 전용 (**배포 아님**) |
+
+```bash
+# repo 루트에서
+npm run pack         # 배포용 = base alias (otel 없음) → flextudio-scenario-gen-0.1.0.tgz
+npm run pack:base    # 위와 동일 (명시)
+npm run pack:otel    # 벤치 전용, 배포 아님            → flextudio-scenario-gen-otel-0.1.0.tgz
+```
+
+**스킬/커맨드는 "설치한 폴더" 로컬에, schema 데이터는 전역에.** `npm i -g` 를 실행한 폴더(npm `INIT_CWD`)에 한 번이면:
+- `<설치폴더>/.claude/skills/scenario-gen/` 에 SKILL.md + 펼친 자산 배치 (그 폴더에서 Claude Code 가 자동 인식)
+- `<설치폴더>/.claude/commands/flex-spec.md` 에 `/flex-spec` 슬래시 커맨드 배치
+- `~/.flex-scenario/contract-root/` 에 schema/+rules.md/+catalog.json/+examples 진실원본 복사 (**전역 1개 공유** — 없으면 글로벌 패키지 내부 `contract-data/` 폴백)
+- (otel 프로파일만) `~/.flex-scenario/otel-collector.yaml` 에 OTel Collector 템플릿 배치
+- 전역 PATH 에 `flex-scenario` 실행 파일 등록
+
+> **다른 폴더에서 쓰려면** 그 폴더로 이동해 `flex-scenario init` 을 한 번 실행 → 그 폴더의 `.claude/` 에 복제된다.
+> 전역 `~/.claude` 는 건드리지 않는다(홈에서 `npm i -g` 한 경우만 예외 — 경고 출력). `uninstall` 은 삭제 범위
+> 메뉴(현재 폴더/모든 설치 폴더/완전 삭제)로 전역 receipt 의 설치 폴더를 정리하고, 완전 삭제는
+> `npm uninstall -g` 까지 자동 실행한다.
+
+## 버전별 사용법 정리 (base / otel)
+
+> **글로벌엔 둘 중 하나만.** 두 패키지는 같은 bin(`flex-scenario`)·같은 전역 경로(`~/.flex-scenario`)와
+> 폴더 로컬 `.claude/skills/scenario-gen` 규칙을 공유하므로 동시에 글로벌 설치하면 서로 덮어쓴다.
+> 역할이 처음부터 분리돼 있다 — **base = 사람 설치 / otel = repo 안 벤치 전용(글로벌 설치 안 함)**.
+
+### A. base (일반 — 사람들이 직접 사용)
+
+```bash
+# 1) 빌드 (repo 루트)
+npm run pack:base                                  # → cli/flextudio-scenario-gen-0.1.0.tgz
+
+# 2) 설치 — 스킬/커맨드는 "지금 있는 폴더"의 .claude 에 깔린다. 먼저 쓸 프로젝트로 이동:
+cd /path/to/your-project
+npm i -g <repo>/cli/flextudio-scenario-gen-0.1.0.tgz   # base 엔 protobufjs 없음 → postinstall 자동 실행
+#   ↳ 어떤 의존 postinstall 이 깨지면: --ignore-scripts 붙이고 → 그 폴더에서 flex-scenario init
+
+# 3) 사용
+#   (a) claude 터미널에서 자연어:  "휴가신청 화면 만들어줘"  → scenario-gen 스킬 자동 발동
+#   (b) CLI 직접:
+flex-scenario validate <scenario.json>             # 전체 검증
+flex-scenario catalog --section controlTypes
+flex-scenario examples list / cat <relpath>
+flex-scenario gen --input case.md --out out.json   # 비대화형 생성 (트레이싱 없음)
+flex-scenario doctor                               # otel 항목은 ○ optional 로 표시
+
+# 다른 폴더에서도 쓰려면 — 그 폴더로 이동해 한 번 실행 (그 폴더의 .claude 에 복제)
+cd /path/to/another-project && flex-scenario init
+
+# 4) 삭제 — 한 번이면 끝. 삭제 범위 메뉴(현재 폴더/모든 설치 폴더/완전 삭제/취소)
+flex-scenario uninstall                            # "완전 삭제" 선택 시 cleanup + npm uninstall -g 자동
+```
+
+- 스킬/커맨드는 **설치/`init` 한 폴더의 `.claude/` 에만** 있다. 그 폴더(또는 하위)에서 Claude Code 를 열어야 인식된다. 전역 `~/.claude` 는 건드리지 않는다.
+
+### B. otel (벤치 — repo 안에서만)
+
+otel 버전은 **글로벌 설치하지 않는다.** 벤치는 워크스페이스 bin 을 직접 호출하고, 워크스페이스엔 `otel-common` 이 이미 링크돼 있어 트레이싱이 자동으로 가능하다.
+
+```bash
+# 1) 1회 세팅 (project-local — ~/.claude·글로벌 안 건드림)
+./bench/setup-bench.sh
+
+# 2) 실행 (병렬 OK). 기본은 트레이싱 OFF
+./bench/run-case.sh flex-cli-skill L1-01
+
+#    트레이스를 보고 싶으면: Phoenix 띄우고 telemetry ON
+./bench/scripts/start.sh
+BENCH_DISABLE_TELEMETRY=0 ./bench/run-case.sh flex-cli-skill L1-01
+
+# 3) 정리
+./bench/teardown-bench.sh
+./bench/scripts/stop.sh        # Phoenix 내렸을 때
+```
+
+- `npm run pack:otel` 로 만드는 `@flextudio/scenario-gen-otel` tgz 는 **벤치/외부 트레이스 전용** 산출물이다 — **배포 대상이 아니다(배포는 항상 base).** 굳이 글로벌로 쓰려면 `npm i -g ./cli/flextudio-scenario-gen-otel-0.1.0.tgz --ignore-scripts && flex-scenario init` (otel transitive `protobufjs` 때문에 `--ignore-scripts` 필요). 단 위 경고대로 **base 와 동시 글로벌 설치는 불가**.
+
+## cli/skill 구성 — authored(관리) vs 자동생성(빌드)
+
+`cli/skill/` 안은 두 종류가 섞여 있다. **authored 만 손으로 고치고, 자동생성은 ①계약코어 원본을 고친 뒤 재빌드**한다.
+
+| 구분 | 항목 | 어디서 관리 |
+|---|---|---|
+| **authored (직접 수정)** | `SKILL.md`, `references/**` | `cli/skill/` 안에서 직접 편집 (빌드 비대상, git 추적) |
+| **자동생성 (빌드 산출 · 직접수정 금지 · gitignore)** | `docs/` `schemas/` `patterns/` `examples/` `skill-guides/` `catalog.json` `rules.md` `README.md` `design-rules.md` `design-system.md` `intent-rules.md` `intent-system.md` | `scripts/build-skill-payload.mjs` 가 루트 ①영역에서 펼침 |
+
+자동생성 항목의 **진짜 원본**(여기를 고침):
+
+| skill 산출물 | 원본 (repo 루트) |
+|---|---|
+| `schemas/` | `schema/v1/**/*.schema.json` |
+| `docs/` | `schema/v1/**/*.md` |
+| `patterns/` | `core/contract.mjs` (`listPatterns`/`getPattern`) |
+| `examples/` | `examples/**` |
+| `skill-guides/` | `skill-guides/**` (루트 별도 관리 폴더) |
+| `catalog.json` `rules.md` | `spec/catalog.json` `spec/rules.md` |
+| `design-rules.md` `design-system.md` | `schema/v1/design-system/{DESIGN,README}.md` |
+| `intent-rules.md` `intent-system.md` | `runtime/v1/intent-system/{INTENT,README}.md` |
+
+```bash
+# 원본 수정 후 재빌드 (= node cli/scripts/build-skill-payload.mjs)
+npm run build:skill
+```
+
+> 전체 "빌드 산출물 ↔ 원본" 매핑·전파 절차의 단일 진실원본은 [../SOURCE-MAP.md](../SOURCE-MAP.md).
+
+## 설치
+
+```bash
+# 옵션 1: npm 전역 (base — 일반 사용)
+npm i -g @flextudio/scenario --ignore-scripts
+flex-scenario init
+
+# 옵션 2: 로컬 tarball
+npm run pack:base          # repo 루트에서 → cli/flextudio-scenario-gen-0.1.0.tgz
+npm i -g ./cli/flextudio-scenario-gen-0.1.0.tgz --ignore-scripts
+flex-scenario init
+
+# 옵션 3: npx 즉시 실행
+npx @flextudio/scenario doctor
+```
+
+> **왜 `--ignore-scripts` 인가?**
+> OTel transitive 의존성인 `protobufjs@7.6.0` 의 npm registry tarball 에 `scripts/postinstall.js`
+> 가 빠져 있어 (registry 패키징 버그) 글로벌 install 시점에 그 패키지의 postinstall
+> hook 이 `Cannot find module` 으로 깨진다. 우리 패키지는 그 파일을 실제로 필요로
+> 하지 않으므로 `--ignore-scripts` 로 모든 의존성 postinstall 을 차단하고, 그 직후
+> `flex-scenario init` 으로 우리만의 postinstall (skill 배치 + contract-root 복사 등)
+> 을 수동 실행한다. 동일 효과, 깨지지 않음.
+
+설치 직후 자동으로 다음이 출력됩니다 (base 프로파일 예 — collector 줄은 otel 프로파일만):
+
+```
+✔ /Users/<you>/.claude/skills/scenario-gen
+✔ /Users/<you>/.flex-scenario/contract-root
+· otel collector 템플릿 없음 (base 프로파일) — skip
+
+next step: flex-scenario doctor
+```
+
+## 서브커맨드
+
+| 명령 | 역할 |
+|---|---|
+| `flex-scenario init` | postinstall 을 수동 재실행 |
+| `flex-scenario gen --input <case.md> --out <scenario.json>` | claude -p 를 spawn → stream-json → (otel 프로파일이면 OTel adapter) → 결과 파일. base 프로파일은 트레이싱 없이 동작 |
+| `flex-scenario validate <file>` | 전체 시나리오 검증 (ajv + cross-check 21종) |
+| `flex-scenario validate --schema <name> <file>` | 단편 검증 |
+| `flex-scenario catalog --section <name>` | catalog.json 의 한 섹션 출력 |
+| `flex-scenario examples list / cat <relpath>` | examples 디렉토리 트리 / 본문 |
+| `flex-scenario trace ui` | Phoenix 기동 안내 (docker run …) |
+| `flex-scenario doctor` | claude / OTel endpoint / SKILL.md / contract-core 점검 |
+| `flex-scenario uninstall [--scope here\|all\|full]` | 삭제 범위 메뉴 — full 은 cleanup + `npm uninstall -g` 자동 (완전 삭제) |
+
+## 환경변수
+
+| 변수 | 기본 | 용도 |
+|---|---|---|
+| `FLEX_CONTRACT_ROOT` | (auto) | schema/+rules.md 가 있는 디렉토리. 명시하면 우선. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | Collector/Phoenix URL |
+| `OTEL_SERVICE_NAME` | (none) | 트레이스 service.name |
+| `CLAUDE_CODE_ENABLE_TELEMETRY` | (off) | Claude Code 내장 telemetry. 끄면 API 요청·토큰 metric 안 나감 |
+| `FLEX_METHOD / FLEX_CASE / FLEX_ITER` | `flex-cli-skill / <case basename> / 1` | adapter 가 root span 에 박는 flex.* attribute |
+| `TRACE_PARENT` | (auto) | W3C traceparent. 비어 있으면 매 gen 호출마다 자체 생성. |
+
+## 동작 모델 (어떻게 MCP 없이 검증까지?)
+
+```
+사용자 프롬프트
+  │
+  ▼
+claude -p "$(cat case.md)"  ← --append-system-prompt 으로 SKILL.md 본문 주입
+  │   (SKILL.md 안에 schema 요약·catalog·패턴이 인라인되어 있어 모델이 그것만 보고 JSON 작성)
+  ▼
+stream-json (stdout)
+  │
+  ▼
+(otel 프로파일) stream-json-otel-adapter  ← @flextudio/otel-common 의 bin. OTLP 로 span 전송
+(base 프로파일) adapter 없이 claude.stdout 직결 (트레이싱 없음)
+  │
+  ▼
+flex-scenario.mjs 가 결과 텍스트에서 JSON 한 덩어리 추출 → --out
+  │
+  ▼
+flex-scenario validate <out>  ← @flextudio/contract-core 의 buildAjv + runAllCrossChecks 직접 호출
+                                 (검증 진입점은 모두 동일 core 호출 — 단일 진실원본).
+```
+
+핵심: MCP 호출이 없으므로 모델이 외부 시스템과 왕복하지 않는다. 대신 SKILL.md 가 컨텍스트에 그대로 들어가 한 번에 큰 본문을 인지한다. 그래서 토큰 분포가 cache_creation 쪽에 쏠리는 게 정상.
+
+## 제거 절차
+
+postinstall 이 npm 책임 영역 **밖** (`<설치폴더>/.claude/`, 전역 `~/.flex-scenario/`) 에 만든 산출물은
+`npm uninstall` 만으로는 안 지워진다. 그리고 **npm 7+ 는 uninstall lifecycle(preuninstall)을 실행하지
+않는다** ("While npm v6 had uninstall lifecycle scripts, npm v7 does not" — npm 공식 문서). 자동 훅은
+존재하지 않으므로 **제거의 단일 진입점은 `flex-scenario uninstall`** 이다.
+
+### 기본 — flex-scenario uninstall (삭제 범위 메뉴)
+```bash
+flex-scenario uninstall
+```
+```
+삭제 범위를 선택하세요. (↑/↓ 이동 · Enter 선택)
+❯ 현재 폴더만 — 이 폴더의 스킬/커맨드 삭제
+  모든 설치 폴더 — 설치된 모든 폴더의 스킬/커맨드 삭제
+  완전 삭제 — 모든 설치 폴더 + ~/.flex-scenario 삭제 후 전역 패키지 제거
+  취소
+```
+- "현재 폴더만" 은 cwd 가 전역 receipt(`installs[]`)에 기록된 설치 폴더일 때만 나타난다.
+- 현재 폴더만 / 모든 설치 폴더 → CLI 와 `~/.flex-scenario`(contract-root)는 유지, receipt 만 갱신.
+- 완전 삭제 → cleanup(.bak 복원 포함) 후 `npm uninstall -g @flextudio/scenario` 까지 자동 실행.
+  단, repo 워크스페이스(dev)에서 실행하면 전역 npm 패키지는 건드리지 않는다
+  (`FLEX_SCENARIO_FORCE_UNINSTALL=1` 로 강제 가능).
+- 비대화형(CI·파이프)에선 메뉴 대신 `--scope here|all|full` 을 명시해야 한다 — 묻지 못하면 지우지 않는다.
+
+### 수동 fallback
+`flex-scenario uninstall` 의 npm 단계가 실패했거나 bin 이 이미 깨진 경우:
+```bash
+npm uninstall -g @flextudio/scenario
+rm -rf ~/.flex-scenario "<설치폴더>/.claude/skills/scenario-gen" "<설치폴더>/.claude/commands/flex-spec.md"
+```
+
+### 벤치 환경 — bench.sh trap
+벤치 드라이버가 Ctrl+C 등으로 비정상 종료해도 `~/.claude` 가 더러운 상태로 남지 않도록
+`bench/bench.sh` 가 trap 으로 강제 cleanup 호출. (별도 도큐먼트.)
+
+### 백업 복원
+
+기존 `<설치폴더>/.claude/skills/scenario-gen/` 가 이미 있으면 postinstall 이 자동으로
+`scenario-gen.bak` 으로 백업(커맨드는 `flex-spec.md.bak`). uninstall 시 `.bak` 이 있으면 원위치로 되돌린다.
+같은 규칙이 전역 `~/.flex-scenario`(`otel-collector.yaml`, `contract-root`) 에도 적용된다.
+
+## base vs otel 프로파일 차이
+
+| 항목 | base (`@flextudio/scenario`) | otel (`@flextudio/scenario-gen-otel`) |
+|---|---|---|
+| `@opentelemetry/*` · otel-common | **없음** | 포함(bundle) |
+| collector 템플릿 배치 | skip | `~/.flex-scenario/otel-collector.yaml` |
+| `gen` 트레이싱 | 없음(claude.stdout 직결) | adapter 로 OTLP span 방출 |
+| `validate`/`catalog`/`examples` | 동일 | 동일 |
+| 대상 | 사람들이 직접 설치·사용 | 벤치(setup-bench) |
+
+> 두 프로파일은 **같은 소스**(`cli/`)에서 나온다. `cli/scripts/profile.mjs` + `prepack.mjs` 가
+> `FLEX_PROFILE` 에 따라 otel 동봉 여부와 패키지명만 가른다. 전체 구조: [../ARCHITECTURE.md](../ARCHITECTURE.md).
+
+## 라이선스
+
+UNLICENSED (사내).