docs(ai): add packaged AI guides for Web, SW and OrgChart

- Shared entry point docs/ai/AI_GUIDE.md (type selection Web / SW / OrgChart / mixed,
  steps 1-7, package style separation, report format, examples A-D) and
  AGENTS_SNIPPET.md, copied into every package ai/ folder
- New ai/ docs for @hm-design/ui and @hm-design/org-chart (+ org-chart-react pointer):
  AI_USAGE, COMPONENT_CATALOG, DESIGN_RULES, COMPOSITION_PATTERNS
- SW ai/ linked to the shared guide; catalog lists every Props type explicitly
- "ai" added to package files of ui, org-chart, org-chart-react
- scripts/ai-docs.mjs: sync:ai-docs / check:ai-docs (copies, files, catalog <-> exports, links)
- Maintenance guide and verification record under docs/ai

docs/ai/AGENTS_SNIPPET.md

@@ -0,0 +1,16 @@
+## HMDesign 디자인 시스템
+
+<!-- HMDesign 패키지의 ai/AGENTS_SNIPPET.md에서 복사. 아래 "사용 유형"을 프로젝트에 맞게 고치거나, 정하지 않았으면 그 줄을 지운다. -->
+
+HMDesign 사용 유형: Web | SW | OrgChart | 혼합(영역별로 적기)
+
+화면·컴포넌트를 구현하거나 수정하기 전에 다음을 지킨다.
+
+1. 설치된 HMDesign 패키지의 공통 가이드를 먼저 읽는다: `node_modules/@hm-design/<설치된 패키지>/ai/AI_GUIDE.md` (`ui`, `sw`, `org-chart`, `org-chart-react` 중 아무 사본이나 내용이 같다).
+2. 위 "사용 유형"이 없고 요청으로도 정할 수 없으면 코드 작성 전에 "어떤 HMDesign 디자인 시스템을 사용하시겠습니까? 1. Web 2. SW 3. OrgChart 4. 혼합 사용"을 묻는다. 정해져 있으면 다시 묻지 않는다.
+3. 선택한 패키지의 `ai/AI_USAGE.md` → `COMPONENT_CATALOG.md` → `DESIGN_RULES.md` → `COMPOSITION_PATTERNS.md` 순으로 필요한 절을 읽는다.
+   - Web: `node_modules/@hm-design/ui/ai/`
+   - SW: `node_modules/@hm-design/sw/ai/`
+   - OrgChart: `node_modules/@hm-design/org-chart/ai/` (React는 `node_modules/@hm-design/org-chart-react/ai/AI_USAGE.md`도)
+4. 기존 컴포넌트 → Props → 조합 → (없는 부분만) 패키지 토큰으로 신규 구현 순서를 지킨다. 패키지 파일 수정·내부 경로 import·구현 복사·새 디자인 값 생성은 하지 않는다.
+5. Web / SW / OrgChart 스타일을 영역별로 분리하고, 완료 후 AI_GUIDE의 결과 보고 형식으로 재사용·신규·토큰·검증·NOT VERIFIED를 보고한다.

docs/ai/AI_GUIDE.md

@@ -0,0 +1,213 @@
+# HMDesign AI 작업 가이드 — 공통 진입점
+
+> 이 파일은 HMDesign 패키지(`@hm-design/ui`, `@hm-design/sw`, `@hm-design/org-chart`, `@hm-design/org-chart-react`)의 `ai/AI_GUIDE.md`에 **같은 내용으로** 들어 있습니다. 원본은 HMDesign 저장소 `docs/ai/AI_GUIDE.md`이며 패키지 사본은 `npm run sync:ai-docs`로 갱신합니다. 사본을 직접 고치지 않습니다.
+
+사용자가 "HMDesign 패키지를 기준으로 화면을 구현해 주세요"처럼 요청하면 AI 코딩 도구는 이 파일의 1~6단계를 순서대로 따릅니다. 이 문서와 각 패키지의 `ai/` 문서는 실제 공개 API·CSS에서 확인한 내용만 적습니다. 여기에 없는 컴포넌트·Props·토큰은 없는 것으로 취급합니다.
+
+## 0. 읽는 순서
+
+1. **이 파일**(어느 패키지의 사본이든 같음)
+2. 선택한 패키지의 `ai/AI_USAGE.md` → `ai/COMPONENT_CATALOG.md` → `ai/DESIGN_RULES.md` → `ai/COMPOSITION_PATTERNS.md`
+3. API가 의심스러우면 그 패키지의 `dist/*.d.ts`(공개 진입점에서 export되는 것만)
+
+| 유형 | 패키지 | 지침 위치(설치 후) | JS 진입점 | CSS |
+|---|---|---|---|---|
+| ① Web UI | `@hm-design/ui` | `node_modules/@hm-design/ui/ai/` | `@hm-design/ui`, `@hm-design/ui/theme` | `@hm-design/ui/tailwind.css` + `@hm-design/ui/theme.css`(Tailwind CSS 4 필요), 선택 `@hm-design/ui/dashboard-status.css` |
+| ② SW UI | `@hm-design/sw` | `node_modules/@hm-design/sw/ai/` | `@hm-design/sw` | `@hm-design/sw/styles.css` |
+| ③ OrgChart | `@hm-design/org-chart`(Core) + React면 `@hm-design/org-chart-react` | `node_modules/@hm-design/org-chart/ai/` (React 어댑터 안내는 `node_modules/@hm-design/org-chart-react/ai/AI_USAGE.md`) | `@hm-design/org-chart`, `@hm-design/org-chart-react`, 선택 `@hm-design/org-chart-react/hm-dialog` | `@hm-design/org-chart/engine.css`, `@hm-design/org-chart/style.css`(URL로 전달 — Shadow DOM 안에 로드) |
+| 기타 | `@hm-design/center-graphic` | AI 지침 없음. 패키지 `README.md`만 | `@hm-design/center-graphic` | 자동 import |
+
+모든 패키지는 서로 독립입니다(`@hm-design/org-chart-react`만 Core에 의존, `@hm-design/ui`는 `/hm-dialog`를 쓸 때만 선택 peer). React·React DOM `^19`는 peer입니다.
+
+## 1단계. 사용 목적 확인
+
+다음 순서로 판단하고, **판단되면 다시 묻지 않습니다.**
+
+1. 소비 프로젝트의 `AGENTS.md`·`CLAUDE.md` 등에 `HMDesign 사용 유형:` 설정이 있으면 그대로 따릅니다(§9).
+2. 사용자 요청이 유형을 분명히 말하면 그대로 따릅니다.
+   - Web: 웹 화면, 관리자·업무 화면, 목록·검색·Form, 대시보드, GNB/LNB, Dialog, Table …
+   - SW: 데스크톱 SW, 뷰어, 도면·CAD, SW Header, 툴바, 레이어/색상/선스타일, 속성창·SW Popup …
+   - OrgChart: 조직도, 조직 계층·직원 카드, 조직 JSON/CSV/Excel 시각화 …
+   - 둘 이상이 함께 나오면 ④ 혼합(예: "업무 화면 안에 조직도" = Web + OrgChart).
+3. 위로 정할 수 없으면 코드 작성 전에 **그대로** 묻습니다.
+
+> 어떤 HMDesign 디자인 시스템을 사용하시겠습니까?
+>
+> 1. Web
+> 2. SW
+> 3. OrgChart
+> 4. 혼합 사용
+
+- `package.json`에 설치된 패키지가 하나뿐이어도 그것만으로 유형을 확정하지 않습니다(설치가 덜 된 상태일 수 있음). 요청 내용과 맞을 때만 근거로 씁니다.
+- 혼합을 고르면 영역별 패키지(예: "페이지 = Web, 가운데 영역 = OrgChart")를 확인합니다.
+- **OrgChart가 포함되고 생성 방식이 없으면** 같은 메시지에서 다음도 묻습니다(이미 말했으면 묻지 않음): "조직도만 기존 페이지에 삽입할까요(Chart Only), 아니면 레이아웃까지 구성한 새 페이지 전체를 생성할까요(Full Page)?" 상세는 `@hm-design/org-chart/ai/AI_USAGE.md` §1.
+- 선택한 패키지가 설치되어 있지 않으면 설치가 필요하다고 보고합니다. 다른 HMDesign 패키지나 임의 라이브러리로 대신하지 않습니다.
+
+## 2단계. 패키지 분석
+
+1. `node_modules/@hm-design/<패키지>/package.json`의 `version`·`exports`·`peerDependencies`를 확인합니다. `exports`에 없는 경로(`src/...`, `dist/components/...`)는 import하지 않습니다.
+2. 그 패키지의 `ai/` 문서를 §0 순서로 읽습니다. 필요한 절만 읽고 전체 `dist`를 훑지 않습니다.
+3. 카탈로그와 실제 `dist/index.d.ts`가 다르면 **`.d.ts`가 기준**입니다. 차이를 결과 보고에 적습니다.
+4. 소비 프로젝트의 기존 CSS 진입점·폰트·빌드 도구(Vite 등)·이미 쓰는 디자인 시스템을 확인합니다. 기존 프로젝트의 디자인 시스템을 바꾸지 않습니다.
+
+## 3단계. 화면 분석
+
+요청 화면을 항목으로 나누고 항목마다 판단을 기록합니다.
+
+| 요청 항목 | 판단 | 근거(카탈로그의 실제 이름) |
+|---|---|---|
+| 예: 상단 메뉴 | 재사용 | Web `GNB` + `GNBMobileMenu` |
+| 예: 레이어 선택 | 재사용 | SW `SWHeaderLayerMenu` |
+| 예: 검색 상자(SW) | 신규 | SW 카탈로그에 없음 → `SWHeaderInput` 재사용 + SW 토큰 |
+
+판단 값은 **재사용**(그대로) / **Props 설정**(기존 Variant·Props) / **조합**(기존 컴포넌트 배치) / **신규**(소비 프로젝트에 최소 구현) 중 하나입니다.
+
+## 4단계. UI 구현
+
+우선순위(위가 먼저):
+
+1. 선택 패키지의 기존 컴포넌트·Pattern을 그대로 사용
+2. 기존 Variant / Props / Callback으로 해결
+3. 기존 컴포넌트 조합(배치용 CSS만 소비 프로젝트에 작성)
+4. 조합으로 안 되는 부분만 **소비 프로젝트에** 새로 구현 — 패키지 토큰만 읽고, 안쪽에 기존 컴포넌트를 재사용
+
+규칙:
+
+- `node_modules` 안 패키지 파일을 수정하지 않습니다. 패키지 `dist` 구현이나 내부 CSS 블록을 복사해 같은 컴포넌트를 다시 만들지 않습니다.
+- 이미 있는 컴포넌트와 같은 역할의 컴포넌트를 새로 만들지 않습니다(예: Web에 `Dialog`가 있는데 자체 Modal 작성 금지).
+- 새 디자인 값을 만들지 않습니다. 색·크기·간격·radius·그림자는 각 패키지 `DESIGN_RULES.md`의 토큰·확인값만 씁니다. 값이 없으면 추측하지 말고 사용자에게 확인합니다.
+- 공통: Font Weight는 400 / 500 / 700만 씁니다(600 없음). Light/Dark 분기를 만들지 않습니다. 새 컴포넌트 CSS에 `html`·`body`·`*` 전역 규칙을 넣지 않습니다. 새 class는 소비 프로젝트 접두사(예: `app-`)를 씁니다.
+- 요청에 없는 메뉴·통계·설명·다운로드·외부 API·AI 입력 UI를 추가하지 않습니다. 필요해 보이면 제안으로만 보고합니다.
+
+### 없는 UI를 같은 스타일로 만들 때 확인할 항목
+
+신규 항목마다 아래를 선택 패키지 `DESIGN_RULES.md`에서 찾아 그대로 적용합니다. 찾을 수 없는 항목은 "값 없음 — 사용자 확인 필요"로 보고합니다.
+
+| 항목 | Web(`@hm-design/ui`) | SW(`@hm-design/sw`) | OrgChart |
+|---|---|---|---|
+| 토큰·CSS 변수 | `--hm-sem-*`, `--hm-color-*`, `--hm-radius-*`(`:root`) | `--hm-sw-header-*`, `--hm-sw-property-*`(`SWTheme` 범위) | `--hm-orgchart-*` 공개 입력(Shadow DOM 상속) |
+| 색·Typography | DESIGN_RULES §2·§3 | DESIGN_RULES §2·§3 | DESIGN_RULES §2·§3 |
+| 크기·여백 | DESIGN_RULES §4 | DESIGN_RULES §1 | 카드·간격 변경 금지(승인 디자인) |
+| Border·Radius·배경·그림자 | DESIGN_RULES §2·§4 | DESIGN_RULES §2·§8 | 공개 입력만 |
+| 아이콘 | `lucide-react`(패키지 의존성) | 패키지 내장 SVG만, 새 아이콘은 사용자 제공 | Core 내장 |
+| 스크롤바 | `ScrollArea`(Radix), DESIGN_RULES §6 | 전용 디자인 없음 — 브라우저 기본(AI_USAGE §2) | Core 내부 Zoom/Pan |
+| Hover / Active / Focus / Disabled | DESIGN_RULES §5 | DESIGN_RULES §4 | Core 내장 |
+| Popup·Panel | `Dialog`·`AlertDialog`·`Sheet`·`Drawer`·`Popover` | `SWPopup` + `SWPopupSection`/`SWPopupRow` | Core 팝업 / HM Dialog / 어댑터 |
+| 동작·키보드 | Radix 동작 유지 | 카탈로그 "공통 키보드" | Core 키보드(Pan, Alt+M 이동 등) |
+
+## 5단계. 패키지별 디자인 분리 (혼합 사용 포함)
+
+각 패키지의 스타일 범위는 다음과 같습니다(실제 CSS 기준).
+
+| 패키지 | 스타일이 적용되는 범위 | 주의 |
+|---|---|---|
+| Web | `theme.css`의 토큰은 `:root, [data-hm-theme]`. `tailwind.css`는 Tailwind base에서 `*`(border·outline), `body`(배경·글자), `html`(글꼴)을 **문서 전체에** 적용. 앱이 import하는 `tailwindcss`의 Preflight도 전역 | Web CSS를 넣은 문서에서는 다른 영역에도 전역 초기화가 적용됨 |
+| SW | 토큰은 `.hm-sw-header`와 `.hm-sw-theme`(`<SWTheme>`)에만 정의. 전역 선택자 없음 | Header 밖 SW 부품은 반드시 `<SWTheme>` 안 |
+| OrgChart | Core가 자기 open Shadow DOM에만 CSS 로드. 호스트 CSS selector는 안쪽에 닿지 않고 **Custom Property 상속만** 통과 | 호스트 class로 카드 모양을 바꾸려 하지 않음 |
+
+혼합 규칙:
+
+1. 영역마다 하나의 패키지를 정하고 그 영역의 신규 UI는 그 패키지의 토큰만 읽습니다. Web 토큰(`--hm-sem-*`)을 SW 영역에, SW 토큰(`--hm-sw-*`)을 Web 영역에 쓰지 않습니다. OrgChart 내부는 `--hm-orgchart-*`만 씁니다.
+2. 다른 패키지 컴포넌트는 **문서에 허용된 지점에서만** 씁니다.
+   - SW `SWPopup`의 `children` 안 Web 컨트롤(SW 카탈로그가 허용, 예: Popup 하단 `Button`)
+   - OrgChart Full Page의 바깥 레이아웃 = Web(또는 요청된 패키지)
+   - OrgChart React의 직원 팝업 = 선택 `@hm-design/org-chart-react/hm-dialog`(Web `Dialog`, Web Theme CSS 필요)
+3. 패키지 class(`hm-sw-*`, `hm-orgchart-*`, Web `data-slot`)를 소비 코드에서 덮어쓰지 않습니다. 배치는 `className`·`style`과 소비 프로젝트 class로 합니다.
+4. **Web + SW를 한 문서에 함께 쓰면** Web의 전역 base(위 표)가 SW 화면에도 적용됩니다. SW는 자기 범위에서 버튼 등을 초기화하지만 이 조합의 시각 결과는 패키지에서 검증된 적이 없습니다(NOT VERIFIED). 이 조합이면 브라우저에서 SW 부품의 글꼴·테두리·배경을 직접 확인하고 차이를 보고합니다. 가능하면 Web CSS가 없는 SW 전용 화면(별도 entry)으로 분리합니다.
+5. Web Scoped Theme(`[data-hm-theme]`)는 body Portal(Select·Popover·DatePicker 팝업)에 전달되지 않습니다. Web 영역만 다른 테마로 바꾸려면 Global Theme를 쓰거나 차이를 보고합니다.
+
+## 6단계. 디자인 검증
+
+소비 프로젝트에서 실제로 실행한 것만 PASS로 적습니다.
+
+1. Typecheck(`tsc --noEmit` 등)와 Production Build
+2. 브라우저 렌더링: 재사용한 컴포넌트가 HM 외형으로 보이는지(CSS 진입점 누락 확인), 신규 UI가 같은 토큰을 쓰는지
+3. 상태·동작: Hover / Focus(키보드) / Disabled, Popup 열기·닫기·Escape·Focus 복귀, 선택 패키지의 핵심 동작
+4. 폭: Web 390 / 768 / 1280 / 1440px, SW는 대상 창 폭(Header는 반응형 More 포함), OrgChart는 캔버스 크기·초기 Fit
+5. 혼합이면 영역 경계에서 스타일 침범이 없는지(§5)
+6. 실행하지 못한 항목은 `NOT VERIFIED`로 남깁니다.
+
+## 7단계. 결과 보고 형식
+
+```md
+## HMDesign 적용 결과
+- 사용 유형: Web | SW | OrgChart(Chart Only|Full Page) | 혼합(영역별: …)
+- 패키지·버전: @hm-design/ui 0.1.0, …
+- 재사용한 컴포넌트: …(Props 설정 포함)
+- 조합한 부분: …
+- AI가 새로 구현한 부분: 파일 경로 · 이유(카탈로그에 없음) · 안쪽에서 재사용한 컴포넌트
+- 적용한 디자인 토큰: --hm-… (신규 UI가 읽은 것)
+- 카탈로그와 .d.ts 차이: 없음 | …
+- 검증: Typecheck PASS · Build PASS · 브라우저(폭/상태) … · NOT VERIFIED: …
+- 제안(구현하지 않음): …
+```
+
+## 8. 상황별 예시
+
+### 예시 A — Web 화면 (목록 + 검색)
+
+- 읽기: `node_modules/@hm-design/ui/ai/` → COMPOSITION_PATTERNS "목록 화면"
+- 재사용: `LNB`(또는 `GNB`) 중 **하나**, `PageHeader`, `Card`, `FilterBar` + `FilterBarSearch` + `FilterBarActions`, `DataTable` + `useDataTable`, `Button`
+- 신규(필요 시만): 카탈로그에 없는 콘텐츠 블록 → 소비 프로젝트 컴포넌트, `--hm-sem-*` 토큰과 `Card` 재사용
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@import "@hm-design/ui/tailwind.css";
+@import "@hm-design/ui/theme.css";
+```
+
+```tsx
+import { Button, Card, CardContent, FilterBar, FilterBarActions, FilterBarSearch, PageHeader, PageHeaderContent, PageHeaderTitle } from "@hm-design/ui"
+```
+
+### 예시 B — SW 뷰어
+
+- 읽기: `node_modules/@hm-design/sw/ai/` → COMPOSITION_PATTERNS "6. 파일 열기 + 도구 막대", 예제 `ai/examples/ExampleF-ViewerToolbar.tsx`
+- 재사용: `SWHeader`(`documentOpenPlacement="header"`, `controls`, `tools`), `SWToolGroup` + `SWToolButton`(Model/Layout 탭, Fit 등), `SWPopup` + `SWPopupSection` + `SWPopupRow` + `SWHeaderInput`(설정 Popup)
+- 신규: SW에 없는 기능(예: 검색) → 소비 프로젝트 컴포넌트, `<SWTheme>` 안, `--hm-sw-header-*` 토큰, 안쪽 입력은 `SWHeaderInput`(예제 `ExampleD-SearchExtension.tsx`)
+
+```tsx
+import { SWHeader, SWPopup, SWTheme, SWToolButton, SWToolGroup } from "@hm-design/sw"
+import "@hm-design/sw/styles.css"
+```
+
+### 예시 C — 조직도만 (Chart Only)
+
+- 읽기: `node_modules/@hm-design/org-chart/ai/` → COMPOSITION_PATTERNS "1. Chart Only"
+- 재사용: React `OrgChart`(`@hm-design/org-chart-react`) 또는 Vanilla `createOrgChart`, 데이터 `JsonOrgChartDataSource` + `validateOrgChartDataset`
+- 필수 옵션: `layoutMode="auto"` + `presentationMode="chart-only"`(초기 Fit·직접 휠 Zoom이 기본)
+- **추가하지 않음:** 페이지 제목·통계·설명·Zoom 버튼 바·외부 회색 배경·Navigation. Fixed Chart Only는 미지원(`TypeError`)
+
+```tsx
+import { OrgChart } from "@hm-design/org-chart-react"
+import { JsonOrgChartDataSource } from "@hm-design/org-chart"
+import engineUrl from "@hm-design/org-chart/engine.css?url" // Vite. 다른 도구는 실제 배포 URL
+import coreUrl from "@hm-design/org-chart/style.css?url"
+```
+
+### 예시 D — Web + OrgChart (Full Page)
+
+- 영역: 페이지 레이아웃·제목·필터 = Web, 조직도 영역 = OrgChart
+- 읽기: Web `ai/` + OrgChart `ai/COMPOSITION_PATTERNS.md` "2. Full Page"
+- 재사용: Web `LNB`/`GNB` 중 하나, `PageHeader`, `Card`, `Select`·`Label`(회사 선택 등 요청된 컨트롤만) + OrgChart `OrgChart`(`selectedCompanyIds` 등 Props로 연결)
+- 직원 팝업을 Web Dialog로: `import { OrgChart } from "@hm-design/org-chart-react/hm-dialog"` + `employeePopup="hm-dialog"`(Web CSS 진입점 필요)
+- 분리: 조직도 카드·색은 OrgChart 기본 유지. Web 토큰을 조직도에 넣지 않음(바꿔야 하면 `--hm-orgchart-*` 공개 입력만)
+
+## 9. 소비 프로젝트 설정 — AI가 이 지침을 찾게 하기
+
+AI 코딩 도구는 보통 **프로젝트 루트의** `AGENTS.md`(Codex 등)·`CLAUDE.md`(Claude Code)·도구별 규칙 파일만 자동으로 읽고 `node_modules`는 읽지 않습니다. 패키지 설치만으로 지침이 자동 적용되지는 않으므로 소비 프로젝트에서 한 번 연결합니다.
+
+1. 패키지에 들어 있는 `ai/AGENTS_SNIPPET.md`를 루트 `AGENTS.md`(없으면 새로 만듦)에 붙여 넣고 `HMDesign 사용 유형:` 줄을 프로젝트에 맞게 고칩니다. 정하지 않았으면 그 줄을 지워 AI가 1단계에서 묻게 합니다.
+   ```bash
+   cat node_modules/@hm-design/ui/ai/AGENTS_SNIPPET.md >> AGENTS.md
+   ```
+   (PowerShell: `Get-Content node_modules/@hm-design/ui/ai/AGENTS_SNIPPET.md | Add-Content AGENTS.md`. 설치한 아무 HMDesign 패키지의 사본이나 같습니다.)
+2. Claude Code는 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두면 같은 내용을 읽습니다. 다른 도구(Cursor 규칙 등)는 그 도구의 규칙 파일에 같은 내용을 넣습니다.
+3. 패키지를 업데이트한 뒤 스니펫이 바뀌었는지 확인합니다(스니펫은 경로 안내만 하므로 보통 그대로 둡니다).
+
+자동으로 되지 않는 것: 패키지 설치 시 루트 파일 생성(`postinstall` 없음), 도구가 `node_modules`를 스스로 탐색하는 것. 위 연결이 없으면 사용자가 "node_modules/@hm-design/…/ai/AI_GUIDE.md를 먼저 읽어"라고 요청해야 합니다.
+
+## 10. 문서 갱신 (HMDesign 저장소 유지보수자)
+
+컴포넌트를 추가·수정하면 같은 변경에서 해당 패키지 `ai/COMPONENT_CATALOG.md`와 필요한 `DESIGN_RULES.md`·`COMPOSITION_PATTERNS.md`를 갱신하고 `npm run check:ai-docs`를 통과시킵니다. 절차는 저장소 `docs/ai/MAINTAINING.md`(패키지 미포함)에 있습니다.

docs/ai/MAINTAINING.md

@@ -0,0 +1,52 @@
+# HMDesign 패키지 AI 지침 유지보수
+
+이 문서는 HMDesign 저장소 유지보수자용이며 패키지에 포함되지 않습니다. 패키지에 포함되는 AI 지침은 소비 프로젝트의 AI 코딩 도구가 읽는 **실행 규칙**이므로, 코드와 다른 내용이 남지 않게 아래 절차로 함께 갱신합니다.
+
+## 1. 구조
+
+| 위치 | 역할 | 패키지 포함 |
+|---|---|---|
+| `docs/ai/AI_GUIDE.md` | 공통 진입점 원본(사용 유형 선택, 1~7단계, 패키지 분리, 예시 A~D, 소비 프로젝트 설정) | 사본으로 포함 |
+| `docs/ai/AGENTS_SNIPPET.md` | 소비 프로젝트 루트 `AGENTS.md`에 붙일 연결 문구 원본 | 사본으로 포함 |
+| `docs/ai/MAINTAINING.md` | 이 문서 | 미포함 |
+| `packages/ui/ai/` | Web: `AI_USAGE`, `COMPONENT_CATALOG`, `DESIGN_RULES`, `COMPOSITION_PATTERNS` | 포함(`files`) |
+| `packages/sw/ai/` | SW: 위 4종 + `examples/` | 포함 |
+| `packages/org-chart/ai/` | OrgChart(Core + React 어댑터 API): 위 4종 | 포함 |
+| `packages/org-chart-react/ai/` | `AI_USAGE`(Core `ai/` 안내) | 포함 |
+| `scripts/ai-docs.mjs` | 동기화(`--sync`)·검사(`--check`) | — |
+
+`@hm-design/center-graphic`에는 AI 지침이 없습니다(공통 가이드에 "README만"으로 안내). 추가하려면 같은 4종 구조로 만들고 `scripts/ai-docs.mjs`의 `packages`에 등록합니다.
+
+저장소 루트 `AGENTS.md`·`CLAUDE.md`는 **이 저장소를 개발하는 AI**용 규칙이고, `packages/*/ai/`는 **패키지를 설치해 쓰는 소비 프로젝트의 AI**용 규칙입니다. 내용이 겹쳐도 서로를 대신하지 않습니다. 패키지 `ai/` 문서는 패키지 밖(`../../docs/…`)을 링크하지 않습니다(설치 후 존재하지 않음).
+
+## 2. 컴포넌트를 추가·수정할 때
+
+같은 변경(같은 Commit)에서 처리합니다.
+
+1. **공개 Export가 바뀌면** 해당 패키지 `ai/COMPONENT_CATALOG.md`에 이름·용도·HM Props(기본값)를 추가·수정·삭제합니다. 내부 전용 이름은 "공개하지 않은 것" 절에만 적습니다.
+2. **Props·Variant 기본값·허용 조합이 바뀌면** 카탈로그 표와 `COMPOSITION_PATTERNS.md`의 예시 코드를 함께 고칩니다.
+3. **토큰·CSS 값이 바뀌면** `DESIGN_RULES.md`의 표를 실제 CSS 선언과 맞춥니다(값은 CSS에서 복사, 추측 금지).
+4. **새 화면 유형·조합 규칙이 생기면** `COMPOSITION_PATTERNS.md` §0 표에 행을 추가합니다.
+5. 공통 규칙(유형 선택·혼합·보고 형식)이 바뀌면 `docs/ai/AI_GUIDE.md`만 고치고 `npm run sync:ai-docs`로 사본을 갱신합니다. 패키지 사본을 직접 고치지 않습니다.
+6. `npm run check:ai-docs`를 실행해 PASS를 확인합니다.
+7. 버전을 올리면 카탈로그 첫 줄의 기준 버전을 같이 바꿉니다.
+
+## 3. `npm run check:ai-docs`가 검사하는 것
+
+1. `docs/ai`의 공유 파일과 각 패키지 사본이 같은지
+2. 각 패키지 `package.json`의 `files`에 `ai`가 있는지
+3. 공개 진입점(`src/index.ts` 등, `export *` 재귀 포함)의 **모든 Export 이름이 카탈로그에 나오는지**
+4. 카탈로그에 Export처럼 보이지만(기존 Export 이름으로 시작) 실제로는 없는 이름이 없는지 — 예: `DialogFancyPanel`. "공개하지 않은 것"·"없는 것"·"지원하지 않는" 절은 제외
+5. `ai/` 문서의 상대 링크가 존재하고 패키지 밖(저장소 전용 문서)을 가리키지 않는지
+
+검사하지 않는 것: Props 이름·기본값·토큰 값의 정확성, 예시 코드의 컴파일. 이 부분은 리뷰와 소비 프로젝트 검증(§4)으로 확인합니다.
+
+## 4. 소비 프로젝트 검증 (배포 전 권장)
+
+1. `npm run build:packages` 후 `npm pack -w <패키지> --ignore-scripts --pack-destination <임시 폴더>`
+2. 임시 소비 프로젝트(React 19 + Vite + Tailwind CSS 4)에 tarball 설치
+3. `node_modules/@hm-design/*/ai/AI_GUIDE.md`가 있는지, 링크가 설치 위치에서 열리는지 확인
+4. `COMPOSITION_PATTERNS.md`의 예시를 옮겨 `tsc --noEmit`·`vite build`·브라우저 렌더링 확인
+5. 결과와 NOT VERIFIED를 기록
+
+`npm pack`의 `prepack`은 build를 다시 실행합니다. 공유 `dist`를 쓰는 build를 동시에 돌리지 않습니다.

docs/ai/verification-2026-10-19.md

@@ -0,0 +1,28 @@
+# 패키지 AI 지침 구축 검증 기록 (2026-10-19)
+
+범위: 공통 진입점(`docs/ai/AI_GUIDE.md` → 각 패키지 `ai/AI_GUIDE.md`), Web(`packages/ui/ai/`)·OrgChart(`packages/org-chart/ai/`, `packages/org-chart-react/ai/`) 신규 문서, SW 기존 `ai/` 연결, 패키지 `files`에 `ai` 추가, `scripts/ai-docs.mjs`. 런타임 코드·CSS·Storybook·공개 API 변경 없음.
+
+## 실행한 검증
+
+| 항목 | 결과 |
+|---|---|
+| `npm run check:ai-docs` (사본 일치, `files`, 카탈로그 ↔ 공개 Export 양방향, `ai/` 링크) | PASS |
+| 검사기 음성 테스트(Export 누락, 가짜 이름 `DialogFancyPanel`, 사본 불일치, 패키지 밖 링크를 임시 주입) | 4건 모두 FAIL로 검출 후 원복, 재검사 PASS |
+| `npm run build:packages` | PASS |
+| `npm pack --ignore-scripts` 4종(ui 0.1.0, sw 0.2.0, org-chart 0.1.0, org-chart-react 0.1.0) | 모든 tarball에 `package/ai/AI_GUIDE.md`·`AGENTS_SNIPPET.md`와 패키지별 문서 포함 |
+| 독립 소비 프로젝트(React 19.3.0, Vite 8.3.0, Tailwind CSS 4.3.3, TypeScript 7.0.2)에 tarball 설치 | `node_modules/@hm-design/*/ai/` 4곳 존재, 설치 위치 기준 상대 링크 42개 모두 해석, `AI_GUIDE.md` 4사본 동일 |
+| `AI_GUIDE.md` §9의 스니펫 연결 명령(`cat … >> AGENTS.md`) | 동작 |
+| 문서만 근거로 구현: Web+OrgChart 페이지(LNB ONLY, PageHeader, 신규 StatCard = Card + 토큰, FilterBar + DataTable, AlertDialog, OrgChart Full Page + `/hm-dialog`), Chart Only 미리보기, SW 뷰어(SWHeader + SWToolGroup + SWPopup, 별도 entry) | `tsc --noEmit`(strict, skipLibCheck false) PASS, `vite build` PASS |
+| 브라우저(1440px) | HM 외형 렌더링(글꼴 Noto Sans KR, Card·Button 토큰 값), 조회 1건 → 초기화 3건, 삭제 확인창 열림·Escape 닫힘·Trigger Focus 복귀, 조직도 직원 카드 → Web Dialog 표시·Escape 닫힘, 회사 Select → `selectedCompanyIds` 반영, 콘솔 오류 0, 가로 넘침 없음 |
+| 브라우저(390px) | LNB Desktop 숨김·LNB Mobile Header 표시, 문서 가로 넘침 없음 |
+| Chart Only(1280px) | 흰 캔버스 + 노드 + 연결선만, 외부 제목·버튼·요약 없음, 중앙 Fit |
+| SW 뷰어 | Popup 열림·내부 Focus·Escape 닫힘·Trigger 복귀, `--hm-sw-header-*`가 `body`에는 없고 `.hm-sw-theme` 범위에만 존재 |
+
+검증 프로젝트는 세션 임시 폴더에서 수행했고 저장소에 추가하지 않았다.
+
+## NOT VERIFIED
+
+- 다른 AI 코딩 도구(Codex·Cursor 등)가 소비 프로젝트의 `AGENTS.md`만 보고 스스로 `ai/` 문서를 찾아가는지. 이번 시나리오는 이 문서를 작성한 같은 AI가 수행했으므로 독립 Cold-start 검증이 아니다.
+- Web CSS와 SW를 **한 문서**에서 함께 쓰는 경우의 시각 결과(문서에 NOT VERIFIED로 명시, 별도 entry 권장).
+- 768px 화면, 실제 터치·스크린리더, Registry publish 후 설치.
+- 문서의 Props 기본값·토큰 값 전부를 기계적으로 대조하지는 않았다(검사기는 Export 이름·링크·사본만 검사). 이번 작성은 소스를 직접 확인했다.