@conscience-technology/ctds 0.0.0-stage → 0.1.0

package/assets/prompts/tokens/radius.md

@@ -0,0 +1,33 @@
+# Radius
+
+### 원칙
+컴포넌트 크기별 상대 위계. 이름은 고정, 값은 Shape 축이 결정.
+Tooltip < Button < Card < Modal 순서는 어떤 프로젝트에서도 유지.
+
+### Do
+- 컴포넌트 크기에 맞춰 스케일 선택: 작을수록 작은 radius.
+- 완전한 원형(Avatar, Pill Chip)은 `radius-full`.
+- 각져야 하는 표·시트 셀은 `radius-none`.
+
+### Don't
+- px 하드코딩 금지. Shape 축이 값 스왑을 담당.
+- Modal에 `radius-sm`, Tooltip에 `radius-xl` 같은 위계 역전 금지.
+
+### Fallback
+애매하면 `radius-sm` (Button·Input 기본 스케일).
+
+### 관련
+- [[axes/shape]] — radius 값을 스왑
+
+### 토큰 표
+| Token | 용도 |
+|---|---|
+| `radius-none` | 표·시트 셀, 각져야 하는 경계 |
+| `radius-xs` | Chip, Badge, Tooltip |
+| `radius-sm` | Input, Button, Icon Button (기본) |
+| `radius-md` | Card, Panel |
+| `radius-lg` | Modal, Popover, Dropdown |
+| `radius-xl` | 대형 카드 |
+| `radius-2xl` | 히어로 카드 |
+| `radius-3xl` | 랜딩·대형 오버레이 |
+| `radius-full` | Avatar, Pill Chip, 원형 버튼 |

package/assets/prompts/tokens/shadow.md

@@ -0,0 +1,35 @@
+# Shadow
+
+### 원칙
+표면이 얼마나 위로 떠 있는가 — 시각 위계(elevation). Shape 축이 스타일 스왑.
+
+### Do
+- 컴포넌트 elevation에 맞춰 스케일 선택.
+- Input focus·미세한 depth: `shadow-xs`.
+- Card: `shadow-sm`. Dropdown·Popover: `shadow-md`. Modal: `shadow-lg`. Command Palette: `shadow-xl`.
+- 눌린 상태(pressed inset)는 `shadow-inner`.
+
+### Don't
+- `box-shadow` 리터럴 하드코딩 금지. 색도 포함 — `rgba(0,0,0,...)`·`oklch(0 0 0 / ...)` 직접 쓰지 말고 `--shadow-*` 토큰 경유.
+- 아래 요소(카드)가 위 요소(Modal)보다 강한 그림자 갖지 않는다 (elevation 역전 금지).
+
+### Shadow 색
+- `--shadow-color`: oklch(L C H) 세 성분. 알파는 shadow 단계별 상수로 보존.
+- 기본은 중성 검정(`0 0 0`), 다크 모드도 동일(그림자는 "빛의 반대", Mode 반전 안 함) — 알파만 다크에서 상향.
+- 테마가 override 하면 전체 shadow 톤이 스왑: 예 `--shadow-color: 0.15 0.03 40` → warm 브랜드의 갈색 틴트 그림자.
+
+### Fallback
+카드·패널이면 `shadow-sm`, 오버레이면 `shadow-md`.
+
+### 관련
+- [[axes/shape]] — Shape가 그림자 스타일을 스왑
+
+### 토큰 표
+| Token | 용도 |
+|---|---|
+| `shadow-xs` | Input focus, 미세 depth |
+| `shadow-sm` | Card 기본 |
+| `shadow-md` | Dropdown, Popover, Hover Card |
+| `shadow-lg` | Modal, Drawer |
+| `shadow-xl` | Command Palette, 화면 중심 |
+| `shadow-inner` | 눌린 상태 (inset) |

package/assets/prompts/tokens/spacing.md

@@ -0,0 +1,86 @@
+# Spacing
+
+### 원칙
+관계의 밀도를 시각화. 가까울수록 관련 강하고, 멀수록 문맥 분리.
+4px 배수(`--space-*`)만 사용. Density 축이 `--space-scale`로 계열을 통째로 스왑.
+
+### Do
+공간은 **"맥락"으로 선택**한다. 토큰에 고정 용도가 박혀있지 않다. 아래 두 리듬 중 하나를 먼저 고르고, 그 안에서 스케일을 쓴다.
+
+**앱·대시보드·콘솔 (디폴트 — 매일 쓰는 UI)**
+- 작은 컴포넌트 사이(버튼↔버튼, 칩↔칩, 아이콘 묶음): **`space-1`(4px) 고정.** 묶음으로 읽히는 밀도. `space-2` 이상 금지.
+- 컴포넌트 내부 요소(버튼의 아이콘-텍스트, chip 등): `space-1` ~ `space-2`.
+- 폼 필드 간, 카드 내부 블록 간: `space-2` ~ `space-3`.
+- 패널 헤더-바디, 카드 상하 padding: `space-3` 안팎 (상하는 좌우보다 한 단계 작게).
+- 패널·섹션 간 세로 gap: `space-3` ~ `space-4`. border나 bg-subtle이 분리를 담당하므로 공간은 좁게.
+- 페이지 body padding: `space-4` ~ `space-6`.
+
+**랜딩·마케팅·에디토리얼 (선언형 UI)**
+- 선언 섹션 간: `space-10` ~ `space-16`.
+- 페이지 최상단·히어로 상하 호흡: `space-16` 이상.
+- 큰 타이틀-서브헤드 간: `space-4` ~ `space-6`.
+
+**공통 규칙**
+- 어느 리듬이든, **카드·패널 그리드(border·bg로 이미 구분된 요소)의 가로/세로 gap은 균일하게.** 가로 `space-3`이면 세로도 `space-3`.
+- 어느 리듬이든, 선언 섹션(히어로)과 콘솔 섹션(테이블/리스트)을 **같은 화면에서 섞을 때는 콘솔 리듬을 베이스로 두고** 선언 섹션 하나만 큰 호흡을 허락한다. 반대로 하지 않는다 (화면 전체가 랜딩처럼 뜨고 머리가 비게 됨).
+
+**카드·패널 내부 padding — 시각적으로 상하좌우 동일**
+- 카드, 패널, 모달, Callout 같은 "닫힌 박스" 안쪽은 **상하좌우 padding이 시각적으로 같아 보이게** 쓴다. 기본은 네 면 같은 토큰(`padding: var(--space-N)` 하나).
+- 폰트는 line-height 여백을 품으므로, 콘텐츠가 큰 텍스트 블록이면 **상하를 수치상 한 단계 줄여** 시각 균형을 맞춘다 (line-height 보정). 예: 큰 타이틀 위주 카드면 `var(--space-2) var(--space-3)`. 이건 "비대칭을 쓰려는 게 아니라, 눈에 같아 보이게 하는 보정".
+- 리스트 row·테이블 row처럼 **반복되는 가로 긴 아이템**도 동일 원칙 — 기본은 정사각, 큰 텍스트가 들어가면 line-height 보정으로만 상하 한 단계 축소.
+- 예외는 panel 헤더(한 줄 고정 높이) 정도. 그 외엔 **"비대칭 padding이 눈에 보이면 틀린 것"**.
+
+### Don't
+- 스케일 밖의 임의 px 사용 금지. 필요하면 디자인 재검토 신호.
+- 인접 스케일을 나란히 반복 금지 — 위계가 사라짐. 최소 2단계 차이. (line-height 보정은 예외)
+- 컴포넌트 간 간격을 `space-2` 이하로 좁히기 금지 — **단, 버튼↔버튼·칩↔칩 등 "작은 컴포 묶음"은 역으로 `space-1`(4px) 고정.** 큰 섹션 간은 좁히지 말고, 작은 묶음은 넓히지 말라.
+- 카드 그리드의 세로 gap을 가로 gap보다 크게 잡지 않는다 — 격자가 세로로만 벌어져 "열은 붙고 행은 떨어진" 어긋남이 생긴다.
+- 카드 그리드끼리 또는 카드 그리드와 다음 패널을 `space-6` 이상 gap으로 분리하지 않는다 — 카드가 이미 border/배경으로 분리돼 있어 과한 공간은 "구조가 끊겨 보이는" 결과를 만든다.
+- 카드·패널 내부 padding을 눈에 띄게 비대칭으로 쓰지 않는다 — 상하좌우가 시각적으로 같아 보이는 게 디폴트. 비대칭을 쓰는 경우는 "line-height 여백 보정" 목적일 때만, 상하를 한 단계 줄이는 쪽으로.
+
+### Fallback
+관련성이 확실치 않으면 `space-4`부터 시도.
+
+### 관련
+- [[axes/density]] — `--space-scale`로 모든 spacing 값 스왑
+
+### 토큰 표
+토큰에는 **고정 용도가 없다.** 아래 "전형적인 자리"는 가장 자주 쓰는 예시일 뿐, "섹션 간은 반드시 space-8" 식으로 못박지 않는다. 어느 자리에 어느 스케일을 쓸지는 위의 Do(앱 리듬 vs 랜딩 리듬)에서 결정한다.
+
+| Token | 전형적인 자리 (예시) |
+|---|---|
+| `space-0.5` | 아이콘-텍스트 미세 간격 |
+| `space-1` | 텍스트-아이콘, 아이콘 묶음, **버튼↔버튼 gap(고정)** |
+| `space-1.5` | 컨트롤 내부 gap |
+| `space-2` | 작은 gap (컴포넌트 사이는 제외 — space-1 고정) |
+| `space-2.5` | 버튼 md 좌우 |
+| `space-3` | 카드 내부, 콘솔 패널 세로 리듬 |
+| `space-4` | 콘솔 패널 좌우 padding, 카드 그리드 gap |
+| `space-5` | 콘솔 body padding |
+| `space-6` | 콘솔 body padding (넉넉) / 랜딩 요소 간 |
+| `space-8` | 선언 섹션 상하 호흡 |
+| `space-10` | 랜딩 섹션 간 |
+| `space-12` | 랜딩 섹션 간 (넉넉) |
+| `space-16` | 랜딩 히어로·페이지 최상단 |
+
+### 전역 element selector로 padding/margin 걸지 않기
+`section`, `article`, `main`, `h1~h6` 등 **element selector에 전역 padding/margin을 걸면 그 태그를 쓰는 모든 자리를 오염**시킨다. 특히 `section`은 CTDS에서 "panel/카드 하나"를 뜻하는 자리로도 쓰이고 "docs의 스크롤 네비 섹션"으로도 쓰이므로, 두 자리의 리듬이 서로 다른 걸 하나의 전역 룰로 묶으면 반드시 한 쪽이 터진다.
+
+- 전역 룰은 **특정 wrapper 클래스 안으로 scope**한다 — `section` ❌ → `.docs section` ✅.
+- 섹션 간 호흡은 **부모 flex-column의 `gap`으로** 담당하고, 섹션 자체에는 padding을 걸지 않는 쪽을 선호.
+- 디버깅 체크리스트: 어떤 자리의 패딩이 "내가 안 걸었는데 들어있다"면 **상위 globals.css의 element selector 규칙**부터 의심한다.
+
+### 텍스트 gap·line-height
+- **섹션 타이틀(h1~h3)에는 반드시 명시적 `line-height` 지정.** 지정 없으면 body base(1.5)를 상속해 큰 폰트에서 "위가 뭉텅 비어 보임" 함정이 발생한다. 큰 선언형은 `--lh-tight`(1.2), 패널 헤더는 1.3 안팎.
+- 상하좌우 균일 padding의 함정: 모달 상단 텍스트(타이틀), 하단 버튼일 때 균일 padding이면 위가 넓어 보일 수 있다 — 이 때는 **먼저 타이틀의 line-height를 조이고**, 그래도 위가 뜨면 상단 padding을 한 단계 축소.
+- 텍스트 ↔ 텍스트 gap: 두 요소 모두 line-height를 품으므로 보수적으로. 라벨-값은 `space-1~2`.
+- 텍스트 ↔ 그래픽 gap: 그래픽은 line-height 여백이 없으므로 표준 스케일 그대로.
+- 그래픽 ↔ 그래픽: 필요하면 한 단계 크게.
+
+### 한 줄에 크기가 다른 요소 수직 정렬
+한 flex row 안에 폰트 크기가 다른 두 요소(큰 숫자값 + 작은 라벨/[[components/badge]]/작은 아이콘 등)가 나란히 올 때, `align-items`는 다음 기준으로 선택한다. 임의 기본값(특히 `baseline`) 금지.
+
+- **기본은 `center`.** 큰 글자와 작은 글자/배지의 중심을 맞춘다. 카드 안에서 "값 + 변화량 Badge" 같은 조합이 전형. baseline으로 맞추면 작은 요소가 아래로 쏠려 위쪽 패딩이 비어 보이고 카드 내부 균형이 깨진다.
+- **같은 폰트 크기의 텍스트끼리** 가로로 나열될 때만 `baseline`. 다른 크기 섞이면 금지.
+- 아이콘 ↔ 텍스트는 `center` 고정 (아이콘엔 baseline이 없다).
+- 패딩이 균일한 카드 안의 row는 `align-items: center` + 균일 padding으로 "실제로도, 시각적으로도" 가운데 정렬이 성립한다. 큰 요소 하나 때문에 상하 여백이 어긋나 보이면 **패딩이 아니라 정렬을 의심한다.**

package/assets/prompts/tokens/typography.md

@@ -0,0 +1,76 @@
+# Typography
+
+### 원칙
+텍스트 크기·라인하이트 스케일. 크기 위계는 항상 유지 (xs < sm < base < ...).
+스케일 전체는 [[axes/density]]의 `--font-scale`로 연쇄 스왑되지만 위계·라인하이트 비율은 불변.
+
+### Do
+- 본문은 `text-base`. 애매하면 이것부터.
+- Table·리스트 밀도가 중요한 곳은 `text-sm`.
+- 헤딩은 `text-xl` 이상, 페이지 타이틀은 `text-4xl` (h1) 관례.
+- line-height는 스케일에 이미 포함. 별도 조정하지 않는다.
+- **라벨/UI 텍스트(버튼, 메뉴, 사이드바 Item, Chip, Badge)는 `--label-{sm,md,lg}-size`**. 본문 스케일(`--text-*`)과 라벨 스케일은 분리돼 있고 라벨 쪽이 UI 전용으로 보정됨.
+
+### Don't
+- font-size에 임의 px 하드코딩 금지.
+- `line-height`를 spacing 토큰으로 조정하지 않는다 (별개 시스템).
+- 한 화면에서 3단계 이상 크기 건너뛰지 않는다 (위계 어색).
+- **20px(=`text-xl`) 미만에 `semibold`/`bold` 사용 금지**. 20px 이상이어도 **컴포넌트 내부 자체 타이틀/display에만** 허용 — 페이지의 섹션 타이틀, 범용 h2/h3처럼 "컴포넌트에 포함되지 않은" 자리에는 사용 금지. 그 외(본문·라벨·버튼·사이드바·메뉴·테이블·배지, 페이지 섹션 헤딩 전부)는 **`medium` 또는 `regular`만** 쓴다. 작은 글자에서 두꺼운 획은 가독성·시각 균형을 깨뜨린다. 강조가 필요하면 색(`fg-strong`) 또는 medium으로 해결.
+- **유령 토큰 금지**. 아래 "CSS 변수 whitelist" 밖의 이름(예: `--font-size-sm`, `--text-size-sm`, `--fs-sm`)은 **존재하지 않는 토큰**이고 참조 시 브라우저 base(≈16px)로 상속돼 사이즈감이 깨진다. 반드시 whitelist의 정확한 이름만 사용.
+
+### Fallback
+본문 `text-base`, 라벨 `text-sm`, 헤딩 `text-2xl`.
+
+### 관련
+- [[axes/font]] — 폰트 스택·포인트 폰트 범위 결정
+- [[axes/density]] — `--font-scale`로 사이즈 스케일 전체를 스왑 (compact 0.95× / default 1× / comfortable 1.05×)
+
+### CSS 변수 whitelist (이 이름만 유효 — 다른 접두어는 전부 유령 토큰)
+
+| 용도 | CSS 변수 | 참고 |
+|---|---|---|
+| 본문/캡션 크기 | `--text-{3xs,2xs,xs,sm,base,lg,xl,2xl,3xl,4xl,5xl}` | line-height는 `--lh-{...}` 짝으로 매칭 |
+| 라벨/UI 크기 | `--label-{sm,md,lg}-size` | 라벨 폰트는 `--label-font` |
+| 라인하이트 | `--lh-{3xs,2xs,xs,sm,base,lg,xl,2xl,3xl,4xl,5xl}` | font-size 토큰과 짝 |
+| Weight | `--font-weight-{regular,medium,semibold,bold}` | |
+| Font family | `--font-normal`, `--label-font` | |
+
+금지 예: `--font-size-sm`, `--font-size-xs`, `--text-size-sm`, `--fs-sm`, `--size-text-sm`. 이 중 어느 것도 globals.css에 정의돼 있지 **않다**.
+
+### 토큰 표
+
+**Font Size / Line-height**
+| Token | CSS 변수 | 용도 |
+|---|---|---|
+| `text-3xs` | `--text-3xs` / `--lh-3xs` | Micro meta (사용 자제) |
+| `text-2xs` | `--text-2xs` / `--lh-2xs` | Dense table meta, tag |
+| `text-xs` | `--text-xs` / `--lh-xs` | Caption, Helper, Badge |
+| `text-sm` | `--text-sm` / `--lh-sm` | Body Small, Table, Label |
+| `text-base` | `--text-base` / `--lh-base` | Body (기본) |
+| `text-lg` | `--text-lg` / `--lh-lg` | Lead 문단, 강조 본문 |
+| `text-xl` | `--text-xl` / `--lh-xl` | H4 |
+| `text-2xl` | `--text-2xl` / `--lh-2xl` | H3 |
+| `text-3xl` | `--text-3xl` / `--lh-3xl` | H2 |
+| `text-4xl` | `--text-4xl` / `--lh-4xl` | H1, Page Title |
+| `text-5xl` | `--text-5xl` / `--lh-5xl` | Display (Hero) |
+
+**Font Weight**
+| Token | 용도 | 허용 자리 |
+|---|---|---|
+| `regular` | 본문·대부분의 UI 텍스트 | 모든 자리 |
+| `medium` | 라벨, 강조 본문, 서브 헤딩, 작은 UI 강조 | 모든 자리 |
+| `semibold` | **20px(`text-xl`) 이상 + 컴포넌트 내부 자체 타이틀/display** | 아래 조건 모두 |
+| `bold` | **컴포넌트 내부 디스플레이·히어로만** (극히 제한적) | 아래 조건 모두 |
+
+**규칙 (semibold/bold 사용 조건):**
+1. `font-size ≥ var(--text-xl)` (20px) — 미만이면 무조건 금지
+2. **컴포넌트에 포함된 자리**여야 함 — Hero·MetricCard value·Dialog 내부 타이틀 등. 범용 섹션 h2/h3, 페이지 내부 heading처럼 "컴포넌트가 아닌 자리"에선 사이즈와 무관하게 금지.
+
+본문·라벨·버튼·메뉴·사이드바·테이블·배지·페이지 섹션 헤딩은 전부 `medium`/`regular`만. 강조는 색(`fg-strong`)·medium으로 해결.
+
+**Letter Spacing**
+| Token | 용도 |
+|---|---|
+| `tight` | 큰 헤딩(text-2xl 이상) |
+| `normal` | 본문 |
+| `wide` | 대문자 라벨, 뱃지 텍스트 |

package/assets/prompts/tokens/z-index.md

@@ -0,0 +1,35 @@
+# Z-index
+
+### 원칙
+겹침 순서(layering)의 계층. 이름 붙은 스케일만 사용해 stacking context 사고를 방지.
+Tooltip은 언제나 최상단.
+
+### Do
+- 오버레이 레이어는 이름 있는 z-index 토큰 사용.
+- Sticky header는 `z-sticky`, dropdown류는 `z-dropdown`.
+- Modal은 `z-modal`, 그 위 popover는 `z-popover`.
+- Tooltip은 `z-tooltip` (항상 최상단).
+
+### Don't
+- 임의 정수(9999 등) 하드코딩 금지.
+- Tooltip을 Modal 아래에 두지 않는다.
+- Toast를 Modal 아래에 두지 않는다 (Modal 열린 상태에서도 알림은 보여야 함).
+
+### Fallback
+정할 수 없으면 `z-base` (0).
+
+### 관련
+N/A
+
+### 토큰 표
+| Token | 용도 |
+|---|---|
+| `z-base` | 기본 |
+| `z-docked` | 도킹된 요소 (컨텐츠 내 sticky sub-header 등) |
+| `z-dropdown` | Dropdown, Select |
+| `z-sticky` | Page-level sticky header |
+| `z-overlay` | 배경 dim overlay |
+| `z-modal` | Modal, Drawer |
+| `z-popover` | Popover, Hover Card |
+| `z-toast` | Toast |
+| `z-tooltip` | Tooltip (최상단) |

package/assets/skill/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ctds
+description: CTDS 하이브리드 디자인 시스템. 8축(Mode/Palette/Hue/Shape/Icon/Density/Motion/Font) CSS 변수 스왑. 색/크기/시간/폰트 하드코딩 금지, 토큰·프리미티브 경유 강제. CTDS 작업 시작점 — 작업 유형 식별 후 하위 스킬로 라우팅.
+---
+
+# CTDS Design System — Foundation
+
+Layer 1(shadcn 방식 컴포넌트 코드) + Layer 2(AI 프롬프트 컨텍스트) 하이브리드. 상세는 `prompts/` 원본 문서 참조.
+
+## 발동 시 — 온보딩 페이지 자동 오픈
+
+1. `curl -sf http://localhost:3000 -o /dev/null && echo ok || echo down`
+2. ok → `open http://localhost:3000/onboarding`
+3. down → "dev 서버 꺼져있어요. `cd web && pnpm dev` 후 다시" 안내
+
+## 절대 규칙 (항상 적용)
+
+1. **하드코딩 금지** — 색(hex/rgb/oklch), 크기(px/rem/em), 시간(ms/s), 그림자, 폰트명. 전부 CSS 변수·토큰 경유. 예외: 1px border, 100%, 0.
+2. **축 우선** — 8축 값 확인 전에 컴포넌트 결정 금지.
+3. **접근성 > 축** — `prefers-reduced-motion:reduce`면 `motion=none`. WCAG AA 미달 금지.
+4. **플로팅 서페이스 = `.m-float`만** — Tooltip/Popover/ContextMenu/DropdownMenu/Select/DatePicker/HoverCard. 컴포넌트별 keyframe/animation 재정의 금지.
+5. **애매하면 묻는다** — 규칙으로 판단 안 서면 사용자 확인.
+
+전체 원칙: `prompts/PRINCIPLES.md`.
+
+## 작업 유형 → 스킬 라우팅
+
+| 작업 | 호출 스킬 |
+|---|---|
+| 컴포넌트 신규 제작·variant/prop 수정 (`web/components/<Name>/` 또는 `prompts/components/<name>.md`) | `ctds-component` |
+| 페이지·대시보드·레이아웃 조합 (`web/app/**/page.tsx`) | `ctds-page` |
+| 테마 프리셋 생성·수정 (`prompts/themes/*` 또는 `web/app/theme-demo/*`) | `ctds-theme` |
+| 코드 검증 (하드코딩·유령 토큰·메모리 규칙·문서-코드 동기화) | `ctds-validate` |
+| 3D 아이콘 일러스트 자산 생성 | `ctds-illust` |
+
+각 스킬이 자기 영역의 축·토큰 매트릭스를 들고 간다. foundation은 라우팅만.

package/bin/ctds.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * CTDS CLI entry.
+ *
+ * 사용법:
+ *   ctds init [--dry] [--force]
+ *   ctds update [--dry] [--force]
+ *   ctds --help
+ *   ctds --version
+ *
+ * 서브커맨드는 ../src/commands/<name>.js 로 디스패치.
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf8")
+);
+
+const [, , cmd, ...rest] = process.argv;
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  printHelp();
+  process.exit(0);
+}
+if (cmd === "--version" || cmd === "-v") {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const commands = {
+  init: () => import("../src/commands/init.js").then((m) => m.run(rest)),
+  update: () => import("../src/commands/update.js").then((m) => m.run(rest)),
+};
+
+if (!(cmd in commands)) {
+  console.error(`unknown command: ${cmd}`);
+  console.error("");
+  printHelp();
+  process.exit(1);
+}
+
+commands[cmd]().catch((err) => {
+  console.error("");
+  console.error("❌ 실패:", err?.message ?? err);
+  if (process.env.CTDS_DEBUG) console.error(err);
+  process.exit(1);
+});
+
+function printHelp() {
+  console.log(`
+CTDS — 하이브리드 디자인 시스템 CLI (v${pkg.version})
+
+Usage:
+  ctds <command> [options]
+
+Commands:
+  init           현재 Next.js 플젝에 CTDS 설치 (components, prompts, /ctds 라우트)
+  update         설치된 CTDS 자산을 최신으로 교체 (수정한 파일은 자동 보호)
+
+Options:
+  --help, -h     도움말
+  --version, -v  버전
+
+Examples:
+  ctds init
+  ctds init --dry       아무것도 쓰지 않고 어떤 파일이 생성될지만 출력
+  ctds init --force     기존 파일이 있어도 덮어쓰기
+  ctds update           최신으로 업데이트 (충돌 파일만 prompt)
+  ctds update --dry     어떤 파일이 바뀔지, 충돌이 몇 개인지만 보기
+  ctds update --force   수정 감지 무시, 전부 덮어쓰기 (git 커밋 후에만)
+`);
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@conscience-technology/ctds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CTDS — 하이브리드 디자인 시스템 설치 · 온보딩 CLI",
+  "type": "module",
+  "bin": {
+    "ctds": "./bin/ctds.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "bundle-assets": "node ./scripts/bundle-assets.mjs",
+    "prepublishOnly": "npm run bundle-assets"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ctds",
+    "design-system",
+    "cli"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Conscience-Technology/CTDS.git",
+    "directory": "packages/ctds-cli"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,215 @@
+/**
+ * `ctds init` — 사용자 Next.js 플젝에 CTDS 설치.
+ *
+ * 하는 일:
+ *   1) Next.js app router 플젝인지 감지. 아니면 중단.
+ *   2) 자산 복사 (components/ctds/, prompts/, .claude/skills/ctds/)
+ *   3) /ctds 라우트 생성 (app/ctds/page.tsx)
+ *   4) 사용자가 수동으로 넣어야 하는 코드 블록 출력
+ *      (layout.tsx wrapper, globals.css import — 자동 패치는 깨지기 쉬워서 안내만)
+ *
+ * 플래그:
+ *   --dry    실제 쓰기 없이 어떤 파일이 생성될지만 출력
+ *   --force  기존 파일 있어도 덮어쓰기
+ */
+
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectProject } from "../utils/detect.js";
+import { getAssetSources } from "../utils/assets.js";
+import { checkMissingDeps, renderInstallCmd } from "../utils/deps.js";
+import { c, step, success, warn, info, kv } from "../utils/log.js";
+import { computeFilesMap, writeMeta } from "../utils/meta.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PKG_PATH = join(__dirname, "..", "..", "package.json");
+function readCliVersion() {
+  try {
+    return JSON.parse(readFileSync(CLI_PKG_PATH, "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+export async function run(args) {
+  const dry = args.includes("--dry");
+  const force = args.includes("--force");
+
+  console.log("");
+  console.log(c.bold("CTDS 설치"));
+  console.log(c.dim("—").repeat(40));
+
+  const cwd = process.cwd();
+  const project = detectProject(cwd);
+  if (!project.ok) {
+    console.error(c.red("✗"), project.reason);
+    console.error("");
+    console.error("   CTDS는 Next.js App Router 플젝에서 사용합니다.");
+    console.error("   현재 폴더에 package.json과 app/ (또는 src/app/) 디렉토리가 필요합니다.");
+    process.exit(1);
+  }
+
+  kv("프로젝트", project.name);
+  kv("경로", cwd);
+  kv("app router", project.appDir);
+  kv("src/ 사용", project.useSrcDir ? "yes" : "no");
+  if (dry) kv("모드", c.yellow("dry run (쓰기 없음)"));
+  console.log("");
+
+  const assets = getAssetSources();
+  info(`자산 소스: ${assets.mode === "bundled" ? "번들" : "로컬 레포"}`);
+  console.log("");
+
+  // 복사 대상 매핑: [src 절대경로, dest 상대경로(사용자 플젝 기준), 레이블]
+  const copyPlan = [
+    [
+      assets.components,
+      project.useSrcDir ? "src/components/ctds" : "components/ctds",
+      "components",
+    ],
+    [assets.prompts, "prompts", "prompts"],
+    [assets.skill, ".claude/skills/ctds", "skill"],
+    [assets.publicAssets, "public/onboarding", "onboarding preview images"],
+  ];
+
+  // 1) 복사
+  for (const [src, to, label] of copyPlan) {
+    const dst = resolve(cwd, to);
+    if (!existsSync(src)) {
+      warn(`자산 누락 (스킵): ${label}`);
+      continue;
+    }
+    if (existsSync(dst) && !force) {
+      warn(`이미 존재 (스킵, 덮어쓰려면 --force): ${to}`);
+      continue;
+    }
+    step(dry ? `[dry] 복사` : `복사`, `${label} → ${to}`);
+    if (!dry) {
+      mkdirSync(dst, { recursive: true });
+      cpSync(src, dst, { recursive: true });
+    }
+  }
+
+  // 2) /ctds 라우트 생성
+  const ctdsRouteDir = resolve(cwd, project.appDir, "ctds");
+  const ctdsPagePath = join(ctdsRouteDir, "page.tsx");
+  if (existsSync(ctdsPagePath) && !force) {
+    warn(`이미 존재 (스킵): ${project.appDir}/ctds/page.tsx`);
+  } else {
+    step(dry ? `[dry] 생성` : `생성`, `${project.appDir}/ctds/page.tsx`);
+    if (!dry) {
+      mkdirSync(ctdsRouteDir, { recursive: true });
+      writeFileSync(ctdsPagePath, renderCtdsRoute(project), "utf8");
+    }
+  }
+
+  // 2.5) components/ctds/.ctds-meta.json 생성 — update가 참조하는 설치 시점 해시 스냅샷
+  const componentsDir = resolve(
+    cwd,
+    project.useSrcDir ? "src/components/ctds" : "components/ctds",
+  );
+  if (existsSync(componentsDir)) {
+    step(dry ? `[dry] 메타 생성` : `메타 생성`, `components/ctds/.ctds-meta.json`);
+    if (!dry) {
+      const files = computeFilesMap(componentsDir);
+      const now = new Date().toISOString();
+      writeMeta(componentsDir, {
+        version: readCliVersion(),
+        installedAt: now,
+        updatedAt: now,
+        files,
+      });
+    }
+  }
+
+  // 3) 수동 안내 — layout.tsx wrapper + globals.css import + AI 에이전트 안내
+  console.log("");
+  console.log(c.bold("설치 완료"));
+  console.log(c.dim("—").repeat(40));
+  success("자동으로 복사·생성된 파일은 위 리스트와 같습니다.");
+  console.log("");
+
+  console.log(c.bold("다음 두 가지를 수동으로 설정해주세요:"));
+  console.log("");
+
+  // 3-1) globals.css — tokens.css import (폰트 + CTDS 토큰 + 축 셀렉터 전부 포함)
+  const globalsRel = project.useSrcDir ? "src/app/globals.css" : "app/globals.css";
+  info(`${c.bold("1)")} ${c.cyan(globalsRel)} 최상단에 다음 한 줄을 추가:`);
+  console.log(c.dim("```css"));
+  console.log(`@import "../components/ctds/tokens.css";`);
+  console.log(c.dim("```"));
+  console.log(c.dim("    tokens.css가 폰트 로드 + CTDS 토큰 + Palette/Shape/Density/Motion/Mode"));
+  console.log(c.dim("    축 셀렉터까지 전부 담당합니다. 이 import 하나면 CTDS 작동 OK."));
+  console.log("");
+
+  // 3-2) layout.tsx wrapper
+  const layoutRel = project.useSrcDir ? "src/app/layout.tsx" : "app/layout.tsx";
+  info(`${c.bold("2)")} ${c.cyan(layoutRel)} 의 <html>·<body>를 아래 형태로 수정:`);
+  console.log(c.dim("```tsx"));
+  console.log(renderLayoutSnippet(project));
+  console.log(c.dim("```"));
+  console.log("");
+
+  // 3-3) 의존성 체크
+  const { missing } = checkMissingDeps(cwd);
+  if (missing.length > 0) {
+    info(`${c.bold("3)")} 다음 패키지를 설치해주세요 (CTDS 컴포넌트가 필요):`);
+    console.log(c.dim("```bash"));
+    console.log(renderInstallCmd(missing));
+    console.log(c.dim("```"));
+    console.log("");
+  } else {
+    success("필요한 의존성이 모두 설치돼 있어요.");
+    console.log("");
+  }
+
+  // 4) 다음 단계
+  console.log(c.bold("다음 단계"));
+  console.log(c.dim("—").repeat(40));
+  console.log("");
+  console.log(`  ${c.cyan("npm run dev")}`);
+  console.log(`  → ${c.cyan("http://localhost:3000/ctds")} 접속`);
+  console.log(`  → 온보딩 돌리고 "적용"하면 ${c.bold("ctds.config.json")}·${c.bold("DESIGN.md")}가 생성됩니다.`);
+  console.log("");
+  console.log(c.dim("이 두 파일을 커밋하면 AI 에이전트(Claude Code 등)가 참조해"));
+  console.log(c.dim("프로젝트의 축에 맞게 컴포넌트·페이지를 생성합니다."));
+  console.log("");
+}
+
+function renderCtdsRoute(project) {
+  // 사용자 플젝 alias 호환성 — 상대경로로 안전하게.
+  // app/ctds/page.tsx → ../../components/ctds/Onboarding (useSrcDir도 동일 레벨)
+  const importPath = "../../components/ctds/Onboarding";
+  return `/**
+ * CTDS 온보딩 라우트.
+ * 이 파일은 \`npx ctds init\`으로 생성됐습니다.
+ * 수정해도 됩니다 — 다음 init은 --force 없이는 덮어쓰지 않아요.
+ */
+import { OnboardingPage } from "${importPath}";
+
+export default function Page() {
+  return <OnboardingPage />;
+}
+`;
+}
+
+function renderLayoutSnippet(project) {
+  // app/layout.tsx → ../components/ctds/ThemeController
+  const importPath = "../components/ctds/ThemeController";
+  return `import { ThemeController } from "${importPath}";
+// 가능하면 ctds.config.json도 import — 적용 후 생성됩니다.
+// import ctdsConfig from "../../ctds.config.json";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ko">
+      <body>
+        <ThemeController /* initialConfig={ctdsConfig} */>
+          {children}
+        </ThemeController>
+      </body>
+    </html>
+  );
+}`;
+}