@things-factory/board-ai 10.0.0-beta.64 → 10.0.0-beta.65

package/PLAN-styling-tools.md

@@ -0,0 +1,1253 @@
+# Component Styling Tools — Plan
+
+> **Goal**: AI 어시스턴트가 컴포넌트의 2D / 3D 스타일링을 델리키트하고 정확하게
+> 처리하도록 — fillStyle (4 modes), strokeStyle, text/font, shadow, 3D material,
+> texture 까지 보편 속성 모두 다루는 tool 군 설계 + 구현.
+>
+> 스타일링 품질 = AI 서포트 효용성 + 생산성 직결. AI 가 "원샷에 모드 전환 + 색
+> 변경 + 부분 업데이트" 같은 케이스를 자연스럽게 처리해야 한다.
+>
+> **Status**: planning (작성 2026-04-28). 단계별 구현 진행.
+
+---
+
+## 1. 스타일 표면 inventory
+
+things-scene 의 styling 표면 audit 결과. 각 인터페이스가 그대로 컴포넌트 state 에
+존재 (e.g., `state.fillStyle` / `state.strokeStyle` / `state.fontFamily` / `state.material3d`).
+
+### 1.1 `FillStyle` — 4 modes (`src/interfaces/rendering.ts:32`)
+
+```ts
+interface FillStyle extends StyleOptions {
+  type: 'solid' | 'gradient' | 'pattern' | 'image'
+  color?: string
+  opacity?: number
+  // gradient extras
+  gradientType?: string  // 'linear' | 'radial'
+  rotation?: number
+  colors?: string[]
+  stops?: number[]
+  // pattern/image extras
+  image?: string  // URL or asset ref
+  // 그 외 모드별 임의 키 (additionalProperties: true)
+}
+```
+
+**Modes (사용자 의도)**:
+- **none**: `state.fillStyle` undefined / null / `{type:'none'}` — 배경 없음
+- **solid**: `{type:'solid', color, opacity?}` — 단색
+- **gradient**: `{type:'gradient', gradientType:'linear'|'radial', colors:[], stops:[], rotation?, opacity?}`
+- **pattern**: `{type:'pattern', image, opacity?, repeat?, ...}` — 이미지 반복
+- **image**: `{type:'image', image, ...}` — 이미지 1회 (stretch/contain)
+
+### 1.2 `StrokeStyle` (`src/interfaces/rendering.ts:41`)
+
+```ts
+interface StrokeStyle {
+  width?: number
+  color?: string
+  opacity?: number
+  lineCap?: 'butt' | 'round' | 'square'
+  lineJoin?: 'miter' | 'round' | 'bevel'
+  lineDash?: number[]      // [] = solid, [4,4] = dashed, [1,4] = dotted...
+  lineDashOffset?: number
+}
+```
+
+**Dash presets (시멘틱)**: solid / dashed / dotted / dashdot — 사용자 의도 → 배열 변환.
+
+### 1.3 `TextStyle` (`src/interfaces/rendering.ts:54`)
+
+```ts
+interface TextStyle {
+  font?: string  // shorthand
+  fontSize?: number
+  fontColor?: string
+  fontFamily?: string
+  fontStyle?: string   // 'normal' | 'italic' | 'oblique'
+  fontWeight?: string  // 'normal' | 'bold' | '100'..'900'
+  textAlign?: 'left' | 'center' | 'right' | 'start' | 'end'
+  textBaseline?: 'top' | 'middle' | 'bottom' | 'hanging' | 'alphabetic' | 'ideographic'
+  lineHeight?: number
+}
+```
+
+**참고**: text content (`state.text`) 는 별도 필드. font 스타일과 분리 처리.
+
+### 1.4 `Shadow` (`src/interfaces/rendering.ts:69`)
+
+```ts
+interface Shadow {
+  color?: string
+  offsetX?: number
+  offsetY?: number
+  blur?: number
+}
+```
+
+### 1.5 `Material3D` (`src/threed/material-3d.ts`)
+
+```ts
+interface Material3D {
+  preset?: 'default' | 'metal' | 'glass' | 'plastic' | 'wood' | 'ceramic' | 'rubber' | 'custom'
+  metalness?: number       // 0..1
+  roughness?: number       // 0..1
+  emissive?: string        // 발광색 hex
+  emissiveIntensity?: number  // 0..5
+  opacity?: number         // 0..1 (component alpha 와 독립)
+  envMapIntensity?: number // 0..3 환경맵 반사 강도
+  side?: 'double' | 'front' | 'back'
+  castShadow?: boolean     // default true
+  receiveShadow?: boolean  // default false
+}
+```
+
+**Preset 베이스 + override**: `resolveMaterial3d(material)` 함수가 preset 의 default 위에
+명시 속성 덮어쓰는 구조. preset 만 주면 그 시맨틱 재질, 개별 속성 추가 시 fine-tune.
+
+### 1.6 Texture / UV (3D)
+
+`src/threed/texture/fillstyle-texture.ts:58` `buildPatternTexture` / `:180` `buildFillStyleTexture` —
+2D fillStyle 을 3D mesh 의 texture 로 변환하는 시스템. UV offset/repeat 자동 계산.
+
+**현재는 자동 처리** — AI 가 직접 UV 조작할 일 적음. Phase 후반에 manual 조정 tool 추가 가능.
+
+### 1.7 Scene-level Lighting (`src/threed/managers/types.ts:19`)
+
+```ts
+interface LightingConfig {
+  hemisphere: { skyColor, groundColor, intensity }
+  directional?: { color, intensity, attachToCamera?, position?, castShadow?, ... }
+  point?: { color, intensity, decay, power, castShadow, position, ... }
+}
+```
+
+씬 전체 조명 — 별도 phase (Environment + Light Mood 프리셋이 이미 있음, 메모리
+[project_preset_architecture.md] 참고).
+
+---
+
+## 2. 설계 철학
+
+### 2.1 8가지 핵심 원칙
+
+| # | 원칙 | 실천 |
+|---|---|---|
+| 1 | **Mode-aware** | 'solid' → 'gradient' 같은 모드 전환 시 fillStyle 통째 교체. partial merge X. |
+| 2 | **Idempotent** | 같은 입력 반복 = 같은 결과. 누적 X. inverse op 정확. |
+| 3 | **Partial-update friendly** | "투명도만" / "stroke 색만" 자연스럽게. 다른 속성 보존. |
+| 4 | **Semantic-first** | `applyEmphasis('subtle')` / `applySemantic('warning')` 같은 시맨틱 우선. raw 는 fallback. |
+| 5 | **Inverse 자동** | 모든 styling tool 이 inverse op 생성 → 기존 patch revert 시스템과 통합. |
+| 6 | **Multi-target** | 한 번에 여러 컴포넌트 (refids 배열). |
+| 7 | **Validation graceful** | 잘못된 색/숫자 → 명확한 에러 + 정정 제안 (AI 가 다시 시도 가능). |
+| 8 | **Data-binding 인지** | 데이터 바인딩 적용 중 컴포넌트는 충돌 경고 (또는 unbind 후 적용 옵션). |
+
+### 2.2 토큰 효율
+
+AI 가 자주 쓰는 의도를 **짧은 호출** 로 표현 가능해야 한다. 예시:
+
+```js
+// 길고 모호 (BAD)
+modifyComponentByRefid(refid=35, patch={
+  fillStyle: { type: 'solid', color: '#ff0000', opacity: 0.5 },
+  strokeStyle: { color: '#000000', width: 2, lineDash: [4, 4] }
+})
+
+// 짧고 명확 (GOOD)
+setFill(refids=[35], mode='solid', color='red', opacity=0.5)
+setStroke(refids=[35], color='black', width=2, dash='dashed')
+```
+
+### 2.3 시맨틱 Layer
+
+다단계 추상화:
+
+```
+Tier 3: applySemantic('warning')           — 의도 (Material 3 토큰)
+Tier 2: applyStylePreset('card-elevated')  — 명명된 스타일
+Tier 1: setFill(mode='solid', color='red') — 구조화 raw
+Tier 0: modifyComponentByRefid(...)        — full raw (escape hatch)
+```
+
+AI 는 의도 명확하면 Tier 3 / 2 사용, 정밀 제어 필요 시 Tier 1, 모르는 영역은 Tier 0.
+
+---
+
+## 3. Tool 카탈로그
+
+### 3.1 Tier 1 — Core Styling (10 tools)
+
+#### `setFill`
+컴포넌트 배경 (fillStyle) 설정. mode 명시 필수.
+
+```ts
+input: {
+  refids: number[]
+  mode: 'none' | 'solid' | 'gradient' | 'pattern' | 'image'
+  // solid:
+  color?: string
+  // gradient:
+  gradientType?: 'linear' | 'radial'   // default 'linear'
+  gradientStops?: Array<{ color: string; position: number }>  // position 0..1
+  rotation?: number  // degrees, default 0
+  // pattern/image:
+  image?: string  // URL or asset ref
+  // 공통:
+  opacity?: number  // 0..1
+}
+```
+
+**Mode 전환 룰**: 새 mode 명시 시 fillStyle 통째 교체. 같은 mode 면 부분 merge.
+
+#### `setStroke`
+컴포넌트 테두리.
+
+```ts
+input: {
+  refids: number[]
+  enabled?: boolean  // false → strokeStyle 제거
+  color?: string
+  width?: number
+  dash?: 'solid' | 'dashed' | 'dotted' | 'dashdot' | number[]  // preset → 배열 변환
+  lineCap?: 'butt' | 'round' | 'square'
+  lineJoin?: 'miter' | 'round' | 'bevel'
+  opacity?: number
+}
+```
+
+#### `setText`
+텍스트 *내용* 변경. 폰트 스타일은 `setFont` 별개.
+
+```ts
+input: {
+  refids: number[]
+  text: string
+}
+```
+
+#### `setFont`
+폰트 / 텍스트 스타일.
+
+```ts
+input: {
+  refids: number[]
+  fontFamily?: string
+  fontSize?: number
+  fontWeight?: 'normal' | 'bold' | 'lighter' | 'bolder' | number
+  fontStyle?: 'normal' | 'italic' | 'oblique'
+  fontColor?: string
+  textAlign?: 'left' | 'center' | 'right' | 'justify'
+  textBaseline?: 'top' | 'middle' | 'bottom'
+  lineHeight?: number
+}
+```
+
+#### `setShadow`
+그림자.
+
+```ts
+input: {
+  refids: number[]
+  enabled?: boolean  // false → shadow 제거
+  color?: string
+  blur?: number
+  offsetX?: number
+  offsetY?: number
+}
+```
+
+#### `setOpacity`
+컴포넌트 전체 알파 (`state.alpha` 또는 `state.opacity`).
+
+```ts
+input: {
+  refids: number[]
+  opacity: number  // 0..1
+}
+```
+
+#### `setVisible`
+표시 / 숨김 (`state.hidden`).
+
+```ts
+input: {
+  refids: number[]
+  visible: boolean
+}
+```
+
+#### `setMaterial`
+3D PBR 재질.
+
+```ts
+input: {
+  refids: number[]
+  preset?: 'default' | 'metal' | 'glass' | 'plastic' | 'wood' | 'ceramic' | 'rubber' | 'custom'
+  metalness?: number       // 0..1
+  roughness?: number       // 0..1
+  emissive?: string
+  emissiveIntensity?: number  // 0..5
+  opacity?: number         // 0..1, 3D-only (component alpha 와 별개)
+  envMapIntensity?: number // 0..3
+  side?: 'double' | 'front' | 'back'
+}
+```
+
+#### `setShadowProperties`
+3D 그림자 동작.
+
+```ts
+input: {
+  refids: number[]
+  castShadow?: boolean
+  receiveShadow?: boolean
+}
+```
+
+#### `clearStyle`
+특정 styling aspect 초기화 — 데이터 바인딩 / preset 으로 돌리기 전.
+
+```ts
+input: {
+  refids: number[]
+  aspects: Array<'fill' | 'stroke' | 'shadow' | 'material' | 'font'>
+}
+```
+
+### 3.2 Tier 2 — Productivity (5 tools)
+
+#### `copyStyle`
+한 컴포넌트의 스타일을 다른 컴포넌트들에 복사.
+
+```ts
+input: {
+  sourceRefid: number
+  targetRefids: number[]
+  aspects?: Array<'fill' | 'stroke' | 'font' | 'shadow' | 'material' | 'opacity'>
+  // default: 모든 styling aspect 복사
+}
+```
+
+#### `harmonizeStyles`
+선택된 컴포넌트들의 한 aspect 를 동일하게 (가장 흔한 값으로).
+
+```ts
+input: {
+  refids: number[]
+  aspect: 'fill' | 'stroke' | 'font' | 'shadow'
+}
+```
+
+#### `getComponentStyle`
+현재 styling 전체 또는 부분 조회 (read-only).
+
+```ts
+input: {
+  refid: number
+  aspects?: Array<'fill' | 'stroke' | 'font' | 'shadow' | 'material' | 'opacity'>
+}
+output: { fillStyle?, strokeStyle?, fontStyle?, shadow?, material3d?, opacity? }
+```
+
+#### `summarizeStyles`
+여러 컴포넌트 스타일 요약 — AI 컨텍스트 토큰 절감.
+
+```ts
+input: { refids: number[] }
+output: string  // "5개 컴포넌트: 모두 빨간 solid + 검정 1px stroke + shadow 없음"
+```
+
+#### `applyEmphasis`
+강조 단계 시맨틱.
+
+```ts
+input: {
+  refids: number[]
+  level: 'none' | 'subtle' | 'medium' | 'strong'
+}
+// 구현: level → shadow + stroke + opacity 자동 조합
+```
+
+### 3.3 Tier 3 — Semantic & Theming (6 tools)
+
+#### `applySemantic`
+Material 3 시맨틱 컬러 적용.
+
+```ts
+input: {
+  refids: number[]
+  intent: 'success' | 'warning' | 'error' | 'info' | 'primary' | 'neutral'
+  variant?: 'filled' | 'outlined' | 'tonal'  // default 'filled'
+}
+```
+
+#### `applyState`
+UI 상태 시맨틱.
+
+```ts
+input: {
+  refids: number[]
+  state: 'active' | 'disabled' | 'highlighted' | 'preview'
+}
+```
+
+#### `getStylePresets`
+사용 가능한 preset 목록 (시스템 + 사용자 정의).
+
+```ts
+output: Array<{ name: string; description?: string; aspects: string[] }>
+```
+
+#### `applyStylePreset`
+이름으로 preset 적용.
+
+```ts
+input: { refids: number[]; presetName: string }
+```
+
+#### `extractColorPalette`
+컴포넌트들에서 사용 색상 추출 → 팔레트.
+
+```ts
+input: { refids: number[] }
+output: Array<{ color: string; usage: number; sources: string[] }>
+```
+
+#### `recolor`
+일괄 색상 매핑 변경.
+
+```ts
+input: {
+  refids: number[]
+  mapping: Array<{ from: string; to: string }>
+  // tolerance?: number  // 색상 유사 매칭 허용 (later)
+}
+```
+
+### 3.4 Tier 4 — 3D Advanced (4 tools)
+
+#### `setTexture`
+3D mesh 의 텍스처 매핑 manual 조정.
+
+```ts
+input: {
+  refids: number[]
+  url?: string
+  repeat?: { x: number; y: number }
+  offset?: { x: number; y: number }
+  rotation?: number
+  encoding?: 'sRGB' | 'linear'
+}
+```
+
+#### `setMaterialMood`
+씬 환경 감각에 맞는 material 보정 — Environment preset 과 결합.
+
+```ts
+input: {
+  refids: number[]
+  mood: 'studio' | 'outdoor-sunny' | 'outdoor-cloudy' | 'warm-indoor' | 'cool-night'
+}
+```
+
+#### `setEmissive`
+발광 quick-access — 전구 / LED / 화면 표현.
+
+```ts
+input: {
+  refids: number[]
+  color?: string
+  intensity?: number  // 0..5
+}
+```
+
+#### `set3DTransform`
+3D 위치/회전/크기 (위치는 2D centerTo 로도 가능하지만 3D 만 의미 있는 회전/오프셋).
+
+```ts
+input: {
+  refids: number[]
+  rotation3D?: { x?: number; y?: number; z?: number }  // degrees
+  offset3D?: { x?: number; y?: number; z?: number }
+  scale3D?: { x?: number; y?: number; z?: number }
+}
+```
+
+### 3.5 Tier 5 — Animation / Interaction (later, optional)
+
+- `setHoverStyle(refids, ...)` — hover 시 변경 스타일
+- `setActiveStyle(refids, ...)` — active 시 변경 스타일
+- `setTransitionDuration(refids, ms)` — animation 속도
+
+---
+
+## 4. Mode 전환 매트릭스
+
+### 4.1 setFill mode 전환
+
+| from → to | 처리 |
+|---|---|
+| `solid` → `gradient` | 기존 `color` 가 첫 stop, 자동 생성 두 번째 stop (어두운 변형) — 사용자가 stops 명시하면 그대로 |
+| `gradient` → `solid` | 첫 stop 색 또는 평균색이 새 `color` |
+| `solid` → `pattern`/`image` | 색상 정보 버림, image 필수 |
+| `*` → `none` | fillStyle 제거 (state 에서 delete) |
+| 같은 mode | 부분 merge (color 만 줘도 stops/rotation 보존) |
+
+### 4.2 setMaterial preset 처리
+
+| 입력 | 결과 |
+|---|---|
+| `preset` 만 | preset 의 기본값 reset (resolveMaterial3d) |
+| `preset` + 개별 속성 | preset 위에 개별 속성 override |
+| 개별 속성만 | 기존 preset 유지 + 개별 속성만 변경 |
+| `preset='custom'` + 속성 | preset 효과 X, 속성만 raw 적용 |
+
+### 4.3 색상 입력 정규화
+
+- hex (`#ff0000`, `#f00`)
+- 명명 색 (`red`, `transparent`, ...) → CSS named colors 매핑
+- rgb/rgba/hsl/hsla — 파싱 후 hex 또는 그대로 보존
+- Material 3 토큰 (`var(--md-sys-color-primary)`) — board theme 적용 시점에 resolve
+
+---
+
+## 5. 검증 (Validation) 정책
+
+### 5.1 입력 검증
+
+각 tool 의 검증 책임:
+- 색상 — CSS color string 파싱 가능?
+- 숫자 범위 — opacity 0..1, metalness 0..1, fontSize > 0 등
+- 모드별 필수 필드 — `mode='gradient'` 면 `gradientStops` 또는 자동 생성
+
+### 5.2 충돌 감지
+
+- 데이터 바인딩 적용 컴포넌트 → 경고 + `force` 옵션 또는 에러
+- Group / 잠긴 컴포넌트 → 정책 결정 필요
+
+### 5.3 에러 메시지
+
+AI 가 자동 회복 가능하도록:
+```json
+{
+  "error": "Invalid color value: 'reddish'. Did you mean 'red'? Valid: hex (#ff0000) or CSS named colors.",
+  "suggestion": "red"
+}
+```
+
+---
+
+## 6. 구현 전략
+
+### 6.1 파일 구성
+
+```
+packages/board-ai/server/service/
+├── styling/
+│   ├── index.ts                  — tool 등록 + dispatch
+│   ├── color-utils.ts            — 색상 파싱/정규화/시맨틱 매핑
+│   ├── fill-tools.ts             — setFill / mode 전환 로직
+│   ├── stroke-tools.ts           — setStroke / dash preset
+│   ├── text-tools.ts             — setText / setFont
+│   ├── shadow-tools.ts           — setShadow
+│   ├── material-tools.ts         — setMaterial / setShadowProperties (3D)
+│   ├── opacity-visibility.ts     — setOpacity / setVisible
+│   ├── compose-tools.ts          — copyStyle / harmonizeStyles
+│   ├── read-tools.ts             — getComponentStyle / summarizeStyles
+│   ├── semantic-tools.ts         — applyEmphasis / applySemantic / applyState
+│   ├── preset-tools.ts           — getStylePresets / applyStylePreset
+│   ├── color-palette-tools.ts    — extractColorPalette / recolor
+│   └── 3d-advanced-tools.ts      — setTexture / setEmissive / set3DTransform
+├── styling-presets/
+│   ├── system-presets.ts         — 빌트인 preset 정의
+│   └── semantic-tokens.ts        — Material 3 시맨틱 매핑
+└── assistant.ts                  — tool registry 통합
+```
+
+### 6.2 dispatch 통합
+
+각 tool 은 기존 `apply-patch.ts` 의 op 형태로 변환되어 적용. 새 op type 필요 없음 —
+`modify` op 의 patch 부분으로 흡수 (기존 inverse 자동 생성 시스템 그대로 활용).
+
+```ts
+// 예: setFill(refids=[35], mode='solid', color='red')
+// → BoardEditPatch:
+{
+  ops: [
+    { op: 'modify', refid: 35, patch: { fillStyle: { type: 'solid', color: '#ff0000' } } }
+  ]
+}
+```
+
+inverse 는 dispatcher 가 적용 직전 state 에서 자동 추출.
+
+### 6.3 테스트 전략
+
+각 tool 별:
+- Unit: input validation, mode 전환, 색상 정규화
+- Integration: apply → assertions on resulting state, inverse 정확성
+- Edge: 데이터 바인딩 충돌, 빈 refids, 잘못된 mode
+
+### 6.4 AI prompt 갱신
+
+- Tool 별 description 에 사용 예시
+- "AI: Fill 변경 시 setFill 우선 사용. modifyComponentByRefid 는 위 tool 들이 못
+  처리하는 fallback 만." 같은 가이드
+- Semantic tool 우선 (Tier 3) → Tier 2 → Tier 1 → Tier 0 (raw modify)
+
+---
+
+## 7. Phasing
+
+| Phase | 범위 | 추정 | Deliverable |
+|---|---|---|---|
+| **P0** | 추가 audit (Component state 키 정리, 컴포넌트별 specific styling) + plan 보완 | 0.5 일 | 문서 갱신 |
+| **P1** | Tier 1 — 10 tools 구현 + 테스트 | 2 일 | 핵심 styling 동작 |
+| **P2** | Tier 2 — 5 tools (productivity) | 1 일 | copy / harmonize / read |
+| **P3** | Tier 3 — 6 tools (semantic / theming) | 1.5 일 | applyEmphasis / Semantic / preset |
+| **P4** | Tier 4 — 4 tools (3D advanced) | 1 일 | texture / emissive / mood |
+| **P5** | AI prompt 갱신 + 통합 테스트 + 사용자 가이드 | 0.5 일 | 사용 준비 완료 |
+
+**총 6 ~ 7 일** — 신중히 진행.
+
+---
+
+## 8. 결정 필요 사항 (체크리스트)
+
+- [ ] **Tier 5 (Animation/Interaction) 포함 여부** — 후순위? 별도 phase?
+- [ ] **시맨틱 색 출처** — Material 3 시스템 토큰 vs board theme 자체 정의 vs 둘 다
+- [ ] **데이터 바인딩 충돌 정책** — error / warn+force / auto-unbind
+- [ ] **Group 컴포넌트 처리** — 자식까지 propagate? 자식만? 그룹 자체만?
+- [ ] **Locked / readonly 컴포넌트** — error / 무시 / 경고
+- [ ] **호버/액티브 스타일 영속 모델** — 별도 state 필드 vs 기존 변형
+- [ ] **Color 입력 normalize 정책** — hex 변환 후 저장? 입력 형태 보존?
+- [ ] **Multi-target 의 partial failure** — 일부 실패 시 전체 롤백 vs 성공한 것만 적용
+- [ ] **사용자 정의 preset 영속** — 도메인별? 사용자별? 보드별?
+
+---
+
+## 9. 향후 확장 가능성
+
+- **Style snapshot / version**: 컴포넌트의 스타일 시점별 저장 → 롤백
+- **Style diff visualization**: 두 컴포넌트 / 두 시점 스타일 비교 시각화
+- **AI 의 색감 학습**: 사용자가 자주 쓰는 색조합 → 추천
+- **외부 디자인 시스템 import**: Figma 토큰 / Material 3 파일 가져오기
+- **접근성 검증**: 대비비 (contrast ratio) 자동 체크 + 개선 제안
+
+---
+
+## 10. 사용자에게 보일 결과 (예시)
+
+**Before** (현재):
+> 사용자: "이 모터들을 빨간 solid 배경으로 + 파란 dashed 1px 테두리로 + 0.5 투명도"
+>
+> AI: `modifyComponentByRefid(refid=35, patch={fillStyle:{type:'solid', color:'#ff0000', opacity:0.5}, strokeStyle:{color:'#0000ff', width:1, lineDash:[4,4]}})` × N번
+>
+> 토큰 많고 모드 전환 시 실수 빈도 높음.
+
+**After** (구현 완료):
+> AI: `setFill(refids=[35,36,37], mode='solid', color='red', opacity=0.5)` +
+>      `setStroke(refids=[35,36,37], color='blue', width=1, dash='dashed')`
+>
+> 토큰 1/3, 의도 명확, 모드 전환 안전, multi-target 한 번.
+
+---
+
+**다음 액션**: P0 (추가 audit) → P1 (Tier 1 구현) 시작. 결정 사항 (Section 8) 확인하며 진행.
+
+---
+
+## 11. Critical Success Factors
+
+> 이 기능의 성공이 board-ai 전체의 성공을 좌우한다.
+> 단순 tool 25개 추가 ≠ 성공. 사용자가 자연어로 의도를 표현하면 AI 가 정확한
+> tool 을 골라 정확한 인자로 호출, 결과가 의도와 일치 — 이게 됐을 때 성공.
+
+### 11.1 Discoverability — AI 가 올바른 tool 을 고르게
+
+25+ tool 중 AI 가 옳은 걸 고르려면:
+
+**Tool naming convention**
+- 동사 + 대상 일관: `setFill` / `setStroke` / `setText` (`update*`/`change*` 혼재 X)
+- 시맨틱 tier 는 `apply*` 접두 (`applyEmphasis` / `applySemantic`) — Tier 구분 시각화
+- 읽기는 `get*` (`getComponentStyle`)
+- 일괄/관계는 `copy*` / `harmonize*` / `extract*`
+
+**Tool description 의 우선순위 가이드**
+각 tool description 에 명시:
+```
+"Use this when the user asks to change the BACKGROUND/FILL of components.
+ Prefer this over modifyComponentByRefid for fill changes — handles mode
+ transitions safely."
+```
+AI 는 description 의 "Use this when" 으로 매칭. 따라서 자연어 의도 키워드를 description 에 풍부하게.
+
+**Tool grouping in system prompt**
+```
+Styling tools (in order of preference):
+  - Semantic: applySemantic, applyEmphasis, applyState
+  - Specific: setFill, setStroke, setFont, setShadow, setMaterial
+  - Read: getComponentStyle, summarizeStyles
+  - Compose: copyStyle, harmonizeStyles
+  - Raw fallback: modifyComponentByRefid
+```
+
+### 11.2 AI prompting 전략
+
+**원칙: AI 가 선호 순서를 학습하도록 system prompt 가 명시**
+
+```
+1. 사용자 의도가 시맨틱하면 (강조 / 경고 / 비활성)
+   → applySemantic / applyEmphasis / applyState 우선
+2. 명시적 색/굵기 지정이면
+   → setFill / setStroke / setFont
+3. 여러 컴포넌트 동일 변경이면
+   → 한 번의 tool call 에 refids 배열로
+4. 한 컴포넌트 → 다른 컴포넌트 같게
+   → copyStyle
+5. 위 어디에도 안 맞으면
+   → modifyComponentByRefid (raw fallback)
+```
+
+**현재 상태 인지**
+AI 가 변경 전에 `getComponentStyle` / `summarizeStyles` 호출 → 현재 상태 파악 후
+의도적 변경. "이미 빨간 모터를 더 빨갛게 해줘" 같은 모호 케이스 정확히 처리.
+
+**색상 입력 변환**
+AI 가 "warm red" 같은 자연어 색을 입력 시 tool 이 자체 변환 — color-utils 가 시맨틱
+이름 → hex 매핑. AI prompt 에 "named colors are accepted: red, warm-red, ..." 명시.
+
+### 11.3 사용자 시나리오 (실제)
+
+**Scenario 1 — 일괄 디자인 변경**
+> "이 대시보드의 게이지 3개를 모두 다크 배경 + 청록 강조 + 그림자 살짝"
+>
+> AI:
+> 1. `findComponents(query='gauge')` → refids
+> 2. `setFill(refids, mode='solid', color='#0a1929')`
+> 3. `setStroke(refids, color='#06b6d4', width=2)`
+> 4. `setShadow(refids, blur=8, offsetY=2, color='rgba(0,0,0,0.3)')`
+
+**Scenario 2 — 시맨틱**
+> "이 알람 영역들 위험 표시 강조"
+>
+> AI:
+> 1. `findComponents(query='alarm')`
+> 2. `applySemantic(refids, intent='error', variant='filled')`
+> 3. `applyEmphasis(refids, level='strong')`
+
+**Scenario 3 — 반복 작업 (copy 패턴)**
+> "1번 모터처럼 다른 모터들도 같게 만들어줘"
+>
+> AI:
+> 1. `findComponents(query='motor')` → refids
+> 2. `copyStyle(sourceRefid=35, targetRefids=[36,37,38], aspects=['fill','stroke'])`
+
+**Scenario 4 — 점진 조정**
+> "조금 더 부드럽게" (이전 대화: 빨강 적용)
+>
+> AI:
+> 1. `getComponentStyle(refid=35)` — 현재 색 #ff0000 파악
+> 2. `setFill(refids=[35], color='#ff6666', opacity=0.85)` — saturation/lightness 조정
+
+**Scenario 5 — 3D 재질 시맨틱**
+> "이 트랙들은 닳은 고무 느낌으로"
+>
+> AI:
+> 1. `setMaterial(refids, preset='rubber', roughness=0.95)` — preset + roughness override
+
+**Scenario 6 — 모드 전환**
+> "이 영역 단색 빨강 대신 위→아래 빨강→어두운빨강 그라디언트"
+>
+> AI:
+> 1. `setFill(refids=[35], mode='gradient', gradientType='linear', rotation=90,
+>           gradientStops=[{color:'#ff0000', position:0},{color:'#660000', position:1}])`
+
+### 11.4 품질 지표 (성공 측정)
+
+**Tool 사용 정확도**
+- AI 가 첫 호출에 올바른 tool 선택 비율 — 목표 ≥ 90%
+- modifyComponentByRefid (raw fallback) 사용 비율 — 목표 ≤ 5% (styling 영역에서)
+- 평균 tool call 수 / 의도 — 단순할수록 좋음 (한 의도 1~2 call)
+
+**사용자 만족도**
+- "다시 시도" / 수정 요청 빈도 — 낮을수록
+- 완료 후 사용자 직접 후가공 빈도 — 낮을수록
+
+**견고성**
+- 잘못된 색/숫자 입력 시 graceful 회복 — AI 가 에러 보고 재시도 성공
+- Mode 전환 시 의도치 않은 결과 — 0 목표
+
+**관찰 방법**
+- ChatMessage 의 toolUsages 에 styling tool 사용 trace 영속됨 (이미 구현)
+- 추후 dashboard / 분석으로 위 지표 측정 가능
+
+### 11.5 디테일 매개체 — Color Utils
+
+`color-utils.ts` 가 핵심 보조. 잘 만들면 AI 호출이 자연스러움:
+
+**파싱 / 정규화**
+- hex / hex-short / rgb / rgba / hsl / hsla / 명명 색 / Material 3 토큰
+- → 정규 hex (저장용) / hex+alpha 분리 (opacity 별도)
+
+**시맨틱 매핑**
+- 'warm-red' → `#e74c3c`
+- 'forest-green' → `#228b22`
+- 색 위계 (light/dark/muted/vibrant) — `lighten('red', 30%)` / `darken` / `desaturate`
+
+**색상 추론**
+- `complement(color)` — 보색
+- `analogous(color, n)` — 인접 색
+- `pickContrast(bg, options)` — 가독성 좋은 텍스트 색
+
+**Material 3 토큰 resolve**
+- `--md-sys-color-primary` → 현재 board theme 의 hex
+
+이 utils 가 두꺼울수록 AI 가 자연어 색상 표현 자유로워짐.
+
+### 11.6 Iteration loop 존중
+
+사용자가 한 번에 끝내는 경우 거의 없음 — 점진 조정이 정상.
+
+**상태 보존 패턴**
+- AI 가 "조금 더 어둡게" 하면 → 직전 상태에서 -10% lightness, 다른 속성 보존
+- AI 가 시맨틱 후 raw 조정 → 시맨틱 메타 보존 (다음에 시맨틱 변경 시 raw 변경 무시 X)
+
+이를 위해 `getComponentStyle` 응답에 "마지막 styling op type" 메타 같이 — 이건 P3
+이후 검토.
+
+### 11.7 Anti-patterns (금지)
+
+- ❌ Tool 마다 input 형식 제멋대로 (어떤 건 `refid: number`, 어떤 건 `target: id` — 일관성 X)
+- ❌ Mode 전환 시 partial merge 시도 (예: solid → gradient 인데 기존 color 만 바꾸려 함)
+- ❌ "이 tool 은 fillStyle 만 다룸" 같은 좁은 description — AI 가 의도 매칭 못 함
+- ❌ AI 가 raw modifyComponentByRefid 자주 사용 → 시맨틱 tool 가이드 부족
+- ❌ Validation 에러를 raw "Bad input" 메시지로 — 자동 회복 불가
+
+### 11.8 무엇이 "완성" 인가
+
+> "사용자가 디자인을 자연어로 설명하면, AI 가 우리 tool 군으로 정확히 표현하고,
+> 결과가 사용자 의도와 90%+ 일치한다."
+
+이게 안 되면 AI 가치 = 0. 위 11.1 ~ 11.6 항목들이 다 작동해야 비로소 "완성".
+
+---
+
+## 12. **데이터 바인딩 styling — 생산성의 핵심**
+
+> 정적 스타일링은 시작점일 뿐. **스타일과 데이터가 결합된 동적 표현**이 things-scene
+> 의 진짜 가치이고, AI 가 이걸 자연스럽게 다루면 사용자 생산성이 폭증한다.
+> 동시에 가장 어려운 영역 — 룰 / accessor / converter / 조건 / 상태 모두 다뤄야.
+
+### 12.1 things-scene 의 데이터 바인딩 모델
+
+`src/interfaces/data.ts:4` `Mapping`:
+
+```ts
+interface Mapping {
+  rule: string         // 평가식 (값 가공 — jsonata-style 또는 함수)
+  target: string       // 적용 대상 — 'fillStyle' / 'strokeStyle' / '[fillStyle:color]'
+  property?: string    // 타입 힌트 — 'fillStyle' / 'strokeStyle' / 'ref' 등
+  accessor?: string    // 데이터 소스 경로 — 'tags.MOTOR1.value'
+  source?: any         // 데이터 소스 참조
+  converter?: string   // 추가 변환 함수
+  param?: any          // 룰에 전달되는 파라미터
+}
+```
+
+컴포넌트의 `state.mappings: Mapping[]` 으로 영속. 런타임에 `_mappings` 가 binding
+객체로 활성화되어 데이터 변경 시 자동 styling 업데이트.
+
+**Target 표현법**:
+- `fillStyle` — fillStyle 전체 교체
+- `[fillStyle:color]` — fillStyle.color 만 변경 (sub-property)
+- `[strokeStyle:width]` — strokeStyle.width
+- `[material3d:emissive]` — 3D 발광색
+- `hidden` — 표시 여부
+- `text` — 텍스트 내용
+
+### 12.2 Common 시나리오 (실제 사용)
+
+#### 시나리오 A — 임계치 색상
+> "온도 80도 넘으면 빨강, 50~80은 주황, 그 아래는 초록"
+
+이 한 문장이 mapping 으로 변환:
+```js
+{
+  accessor: 'tags.TEMP.value',
+  target: '[fillStyle:color]',
+  rule: 'value > 80 ? "#ef4444" : value > 50 ? "#f59e0b" : "#22c55e"'
+}
+```
+
+#### 시나리오 B — 값-색상 그라디언트 매핑
+> "0~100 값을 파랑→빨강 색 스펙트럼으로"
+
+```js
+{
+  accessor: 'tags.LEVEL.value',
+  target: '[fillStyle:color]',
+  rule: 'interpolateColor(value, 0, 100, "#3b82f6", "#ef4444")'
+}
+```
+
+#### 시나리오 C — 상태 기반 발광 (3D)
+> "MOTOR 가 running 일 때 노란 발광, stopped 면 끄기"
+
+```js
+{
+  accessor: 'tags.MOTOR.status',
+  target: '[material3d:emissive]',
+  rule: 'value === "running" ? "#fde047" : "#000000"'
+},
+{
+  accessor: 'tags.MOTOR.status',
+  target: '[material3d:emissiveIntensity]',
+  rule: 'value === "running" ? 2 : 0'
+}
+```
+
+#### 시나리오 D — 알람 시 표시 / 깜빡임
+> "ALARM 활성 시 빨간 테두리 굵게 + 점멸"
+
+```js
+{
+  accessor: 'tags.ALARM.value',
+  target: '[strokeStyle:color]',
+  rule: 'value ? "#dc2626" : "#94a3b8"'
+},
+{
+  accessor: 'tags.ALARM.value',
+  target: '[strokeStyle:width]',
+  rule: 'value ? 3 : 1'
+},
+// 점멸은 animation API 와 결합 — 별 phase
+```
+
+#### 시나리오 E — 조건부 가시성
+> "REJECT 갯수가 0이면 알람 패널 숨김"
+
+```js
+{
+  accessor: 'tags.REJECT_COUNT.value',
+  target: 'hidden',
+  rule: 'value === 0'
+}
+```
+
+#### 시나리오 F — 텍스트 + 색상 동시
+> "현재 가동률을 큰 글자로 보여주고, 90% 미만이면 빨간색"
+
+```js
+[
+  { accessor: 'tags.UTIL.value', target: 'text', rule: 'value + "%"' },
+  { accessor: 'tags.UTIL.value', target: '[fontColor]',
+    rule: 'value < 90 ? "#ef4444" : "#0f172a"' }
+]
+```
+
+### 12.3 Tool 카탈로그 — 데이터 바인딩 styling
+
+**대원칙**: AI 가 "온도 80 넘으면 빨강" 같은 자연어 → 정확한 mapping 객체로 변환.
+정적 styling tool 의 high-level 시맨틱과 **동일한 톤** 으로 설계. 차이는 "값에 따라"
+가 들어가는 것.
+
+#### Tier B1 — Read
+
+##### `getDataBindings`
+컴포넌트의 현재 mapping 들 조회 (요약 포함).
+
+```ts
+input: { refid: number }
+output: Array<{
+  index: number
+  target: string             // 'fillStyle' / '[fillStyle:color]' 등
+  accessor: string           // 데이터 소스 경로
+  rule: string               // 평가식 요약 (긴 경우 압축)
+  ruleType: 'threshold' | 'range-map' | 'state-map' | 'expression'  // AI 가 의도 추론 가능
+  description: string        // 사람 친화 설명 — "TEMP 값이 80 초과 시 빨강"
+}>
+```
+
+##### `summarizeDataBindings`
+여러 컴포넌트의 binding 패턴 요약 — AI 토큰 절감.
+
+```ts
+input: { refids: number[] }
+output: string  // "5개 컴포넌트가 모두 tags.LEVEL.value 의 임계치 (>80 빨강) 로 fillStyle 바인딩"
+```
+
+##### `findComponentsWithBinding`
+특정 데이터 소스 사용하는 컴포넌트 검색.
+
+```ts
+input: {
+  accessor?: string       // 'tags.TEMP.*' (와일드카드)
+  targetPattern?: string  // 'fillStyle' / '[material3d:*]'
+}
+output: Array<{ refid, target, rule }>
+```
+
+#### Tier B2 — Create / Modify (semantic high-level)
+
+##### `bindThresholdStyle`
+**가장 자주 쓸 tool**. 임계치 기반 색상/속성 매핑.
+
+```ts
+input: {
+  refids: number[]
+  accessor: string                          // 데이터 소스 경로
+  target: 'fill' | 'stroke' | 'emissive' | 'border-color' | 'text-color' | 'opacity' | string
+  thresholds: Array<{ above: number; value: any; label?: string }>
+  default?: any                             // 어느 임계치도 안 맞으면
+}
+// 예: above 80 → red, above 50 → orange, default → green
+```
+
+서버가 자동으로 `Mapping` 객체로 변환 (rule expression 생성).
+
+##### `bindValueRangeStyle`
+값 범위 → 연속 색상 그라디언트.
+
+```ts
+input: {
+  refids: number[]
+  accessor: string
+  target: 'fill' | 'emissive' | string
+  range: { min: number; max: number }
+  colors: { atMin: string; atMax: string; atMid?: string }
+  // 또는 colorStops: [{ position, color }]
+}
+```
+
+##### `bindStateStyle`
+상태 (state machine) 기반 매핑.
+
+```ts
+input: {
+  refids: number[]
+  accessor: string
+  target: string
+  states: Record<string, any>  // { running: '#fde047', stopped: '#000000', error: '#ef4444' }
+  default?: any
+}
+```
+
+##### `bindConditionalVisibility`
+값 조건 → 표시/숨김.
+
+```ts
+input: {
+  refids: number[]
+  accessor: string
+  condition: 'truthy' | 'falsy' | 'equals' | 'not-equals' | 'gt' | 'lt' | 'between' | 'in' | 'expression'
+  param?: any  // condition 별 인자
+  hideWhen: 'matches' | 'not-matches'
+}
+```
+
+##### `bindTextValue`
+값 → 텍스트 (포맷 옵션 포함).
+
+```ts
+input: {
+  refids: number[]
+  accessor: string
+  format?: 'number' | 'percent' | 'currency' | 'date' | 'time' | 'custom'
+  customFormat?: string  // e.g., '{value} ℃' 또는 strftime-like
+  precision?: number     // 소수점 자릿수
+}
+```
+
+##### `bindExpression` (raw escape hatch)
+임의 룰 — 위 시맨틱 tool 로 표현 안 되는 케이스.
+
+```ts
+input: {
+  refids: number[]
+  accessor: string
+  target: string
+  rule: string  // jsonata 또는 함수 표현식
+  description?: string  // AI 가 의도 기록 (디버깅용)
+}
+```
+
+#### Tier B3 — Remove / Inspect
+
+##### `removeBinding`
+특정 binding 제거.
+
+```ts
+input: {
+  refid: number
+  target?: string  // 특정 target 만 / 미지정 시 모든 binding
+  index?: number   // 특정 index 의 binding (precise)
+}
+```
+
+##### `clearBindings`
+모든 binding 제거 (정적 styling 으로 복귀).
+
+```ts
+input: { refids: number[] }
+```
+
+##### `replaceBinding`
+기존 binding 통째 교체 (안전한 in-place 수정).
+
+```ts
+input: {
+  refid: number
+  index: number
+  newBinding: { accessor, target, rule, ... }
+}
+```
+
+#### Tier B4 — Composite
+
+##### `copyBindings`
+한 컴포넌트의 binding 들을 다른 컴포넌트들에 복제.
+
+```ts
+input: {
+  sourceRefid: number
+  targetRefids: number[]
+  rebindAccessor?: { from: string; to: string }
+  // 예: tags.MOTOR1.value → tags.MOTOR{n}.value 식 패턴
+}
+```
+
+##### `harmonizeBindings`
+여러 컴포넌트의 styling binding 통일 — 일관된 임계치/색상.
+
+```ts
+input: {
+  refids: number[]
+  master: number  // 이 컴포넌트의 binding 을 기준으로
+  aspects?: Array<'fill' | 'stroke' | 'visibility' | ...>
+}
+```
+
+##### `convertStaticToBinding`
+정적 styling 을 데이터 바인딩으로 전환 — 디자인 → 동적 변환 헬퍼.
+
+```ts
+input: {
+  refids: number[]
+  aspect: 'fill' | 'stroke' | 'visibility' | ...
+  accessor: string
+  // 자동 추론: 현재 색상 보존 + accessor 의 임계치 고민 → AI 와 협업해 thresholds 결정
+}
+```
+
+### 12.4 핵심 도전 과제
+
+#### Rule expression 생성
+
+AI 가 자연어 → `rule` (코드) 로 변환해야 하는데:
+- jsonata 와 일반 JS 표현식 구별
+- 보안: arbitrary code 실행 방지 — sandbox / whitelist
+- 검증: 평가 시도 + 에러 잡기
+- AI 가 자체 생성한 rule 이 동작하는지 server-side 사전 평가 필요
+
+**해결**:
+- 시맨틱 tool (bindThresholdStyle 등) 이 rule 을 자동 생성 — AI 는 raw rule 거의 안 씀
+- bindExpression (raw) 만 rule 받지만 server 가 sandbox 평가 + 결과 타입 검증
+
+#### Accessor 자동완성
+
+사용자: "MOTOR1 의 값으로 색 바꿔줘"
+AI: 어떤 accessor 가 MOTOR1 인지 모름. → `findDataSources(query)` tool 필요.
+
+##### `findDataSources` (B1 추가)
+```ts
+input: { query: string; limit?: number }
+output: Array<{ accessor: string; type: string; sample?: any; description?: string }>
+```
+
+things-factory 의 데이터 시스템과 연동 — tags / variables / metrics / sensors 등.
+이 tool 의 품질이 binding 정확도 결정.
+
+#### Type 호환성
+
+target `fillStyle` 은 string 또는 객체 받음. AI 가 임계치로 `'#ff0000'` 같은 string
+을 정확히 생성해야. type hint (mapping.property) 가 helping.
+
+#### Mapping 충돌
+
+같은 컴포넌트에 fillStyle 과 [fillStyle:color] 동시 binding 시 충돌. server 가 감지 +
+경고 + 자동 정리 옵션.
+
+### 12.5 사용자 시나리오 (binding)
+
+**Scenario 1 — 한 줄 자연어 → 작동하는 dashboard**
+> "이 게이지 5개를 각자의 sensor 값에 맞게 0~100 범위 파랑→빨강 그라디언트로"
+
+AI:
+1. `findDataSources(query='sensor')` → [tags.S1.value, tags.S2.value, ...]
+2. `findComponents(query='gauge')` → [refids]
+3. `bindValueRangeStyle(refids[i], accessor='tags.S{i}.value', target='fill',
+                        range={min:0,max:100}, colors={atMin:'#3b82f6',atMax:'#ef4444'})`
+
+**Scenario 2 — 기존 mapping 패턴 복제**
+> "MOTOR1 처럼 다른 모터들도 같은 룰로 emissive 변경"
+
+AI:
+1. `getDataBindings(refid=motor1_refid)` → 룰 파악
+2. `copyBindings(sourceRefid=motor1, targetRefids=[m2,m3,m4],
+                 rebindAccessor={from:'tags.MOTOR1.', to:'tags.MOTOR{n}.'})`
+
+**Scenario 3 — 디자인 → 동적 전환**
+> "이 빨간 박스들을 ALARM 값에 따라 켜지는 걸로 바꿔"
+
+AI:
+1. `getComponentStyle(refid)` → 현재 빨강 #ef4444 파악
+2. `convertStaticToBinding(refids, aspect='fill', accessor='tags.ALARM.value')`
+3. AI 가 임계치 추론 (값 truthy 일 때 빨강, falsy 일 때 회색) → `bindStateStyle`
+   호출 with `{1: '#ef4444', 0: '#94a3b8'}`
+
+### 12.6 binding tool 의 phasing
+
+기존 plan 에 추가:
+
+| Phase | 추가 범위 | 추정 |
+|---|---|---|
+| **PB0** | data-binding 모델 정밀 audit (evaluator / accessor / converter 동작) | 0.5 일 |
+| **PB1** | Tier B1 (read) — getDataBindings / summarize / findComponentsWithBinding / findDataSources | 1 일 |
+| **PB2** | Tier B2 (create) — bindThresholdStyle / bindValueRangeStyle / bindStateStyle / bindConditionalVisibility / bindTextValue | 2 일 |
+| **PB3** | Tier B3 (remove) + Tier B4 (composite — copyBindings / convertStaticToBinding) | 1 일 |
+| **PB4** | bindExpression (raw) + sandbox 평가 + 검증 | 1 일 |
+| **PB5** | AI prompt 갱신 + 시나리오 통합 테스트 | 0.5 일 |
+
+**총 binding 부분 6 일** + 정적 styling 6~7 일 = **약 12~13일** 의 풀 풀 plan.
+
+### 12.7 왜 이게 게임 체인저인가
+
+**정적 styling 만**: AI 는 멋진 디자인 만들 수 있음. 그러나 "운영 화면" 으로 가면
+값에 따라 변하는 표현이 필수. AI 가 정적까지만 하면 사용자가 손으로 binding 작업 →
+AI 의 도움 가치 50%.
+
+**Binding 까지 잘하면**: 사용자 한 문장 → 동적 dashboard 완성. 디자인 + 데이터 흐름
+같이 자동화. 진짜 "operator AI" 가 됨. 생산성 차이 10배 이상.
+
+특히 things-factory 의 도메인 (제조 / 공정 / 시설 모니터링) 에서는 정적 디자인 가치
+보다 **동적 운영 화면** 가치가 훨씬 큼. binding tool 이 약하면 board-ai 는 디자인
+도구에 머물고, 운영 도구로 못 큼.
+
+### 12.8 priorities — 정적 vs binding
+
+**같이 가야 함**. 둘 중 하나만 잘 만들면 의미 적음:
+- 정적 styling 좋고 binding 약함 → "예쁜 게 다는 아니다" — 사용자 실망
+- binding 좋고 정적 styling 약함 → "기능은 되는데 못생겼다" — 사용자 실망
+
+**제 권고 phasing**:
+1. P1 정적 Tier 1 (10 tools) ← 시각적 즉각 가치
+2. PB1 binding read tools ← AI 가 컨텍스트 파악
+3. PB2 binding create (high-level — threshold/range/state) ← 핵심 가치
+4. P2~P3 정적 productivity & semantic
+5. PB3+ binding 마무리
+
+순환식 — 정적과 binding 을 번갈아 layer 쌓는 게 양쪽 다 단단해짐.
+
+---