docs: standardize Git submodule and workspace installation

docs/guidelines/external-install-submodule.md

@@ -1,6 +1,6 @@
 # 외부 프로젝트 설치 — Git Submodule + npm Workspace
 
-> 2026-10-20 작성. 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 npm Workspace로 연결합니다.
+> 2026-10-20 작성, 2026-10-23 갱신(저장소 주소 `shkim4`, HM 패키지 npm Registry 미사용 명시). 현재 HMDesign을 다른 React 프로젝트에서 쓰는 공식 방식입니다. npm Registry publish 없이 Git 저장소를 Submodule로 연결하고, HMDesign 안에서 패키지를 빌드한 뒤 소비 프로젝트의 npm Workspace로 연결합니다.
 > 실제 적용 근거: 외부 DWG/DXF Viewer(React 19, `@hm-design/ui` + `@hm-design/sw`)가 이 절차로 연결되었습니다. 패키지 tarball 소비 검증은 `packages/sw/tests/integrated-consumer.mjs`가 별도로 수행합니다.
 
 ## 1. 전제
@@ -9,7 +9,7 @@
 |---|---|
 | Node.js / npm | `package-lock.json`의 엔진 조건 `^20.19.0 \|\| >=22.12.0`(Node 21 제외). 검증 기록: Node 20.20.1 / npm 10.8.2(2026-10-11), Node 22.23.2 / npm 10.9.8(2026-10-20) |
 | React | 소비 프로젝트 `react`·`react-dom` `^19.0.0`(모든 패키지의 peer) |
-| 네트워크 | 최초 설치에 Gitea(`https://gitea.hmac.kr/b25027/HMDesign.git`)와 npm Registry 접근 필요 |
+| 네트워크 | 최초 설치에 Gitea(`https://gitea.hmac.kr/shkim4/HMDesign.git`)와 외부 dependency용 공개 npm Registry(`registry.npmjs.org`) 접근 필요. HM 패키지용 Gitea npm Registry·`.npmrc` 설정은 쓰지 않음 |
 | Git | 패키지 `dist/`는 Git에 포함되지 않습니다(`.gitignore`). Clone·Commit 변경 후에는 항상 HMDesign 안에서 다시 빌드합니다. |
 
 ## 2. Submodule 연결과 검증 Commit 고정
@@ -17,7 +17,7 @@
 소비 프로젝트 루트에서 실행합니다. `<검증 Commit>`은 사용할 HMDesign Commit의 전체 SHA입니다(브랜치 이름을 그대로 쓰지 않습니다).
 
 ```bash
-git submodule add https://gitea.hmac.kr/b25027/HMDesign.git HMDesign
+git submodule add https://gitea.hmac.kr/shkim4/HMDesign.git HMDesign
 git -C HMDesign fetch origin
 git -C HMDesign checkout <검증 Commit>
 git add .gitmodules HMDesign
@@ -26,6 +26,7 @@ git commit -m "chore: pin HMDesign <검증 Commit>"
 
 - 소비 프로젝트에 기록되는 것은 Submodule Commit 포인터입니다. 다른 사람·CI는 `git submodule update --init --recursive`로 같은 Commit을 받습니다.
 - Submodule 안에서 HMDesign 파일을 직접 수정하지 않습니다. `git status`에 `HMDesign (modified content)` / `-dirty`가 보이면 고정 Commit과 다른 코드로 빌드된 상태입니다. 그 상태의 검증 결과는 해당 Commit의 결과로 보고하지 않습니다.
+- 이전 주소(`https://gitea.hmac.kr/b25027/HMDesign.git`)로 연결한 Submodule은 리다이렉트로 동작하지만 현재 주소로 바꿉니다. `git submodule set-url HMDesign https://gitea.hmac.kr/shkim4/HMDesign.git` → `git submodule sync` → `.gitmodules` Commit. Submodule Commit 포인터와 `npm ci`·빌드 절차는 바뀌지 않습니다.
 
 ## 3. HMDesign 안에서 설치·빌드
 
@@ -98,4 +99,5 @@ git commit -m "chore: update HMDesign to <새 검증 Commit>"
 - `dist/`가 Git에 없으므로 Clone·Commit 변경·CI마다 HMDesign 빌드(§3)가 필요합니다. CI에서도 Submodule 초기화와 `npm ci && npm run build:packages`를 실행합니다.
 - HMDesign 빌드 도구와 소비 프로젝트 도구가 따로 설치됩니다(예: 외부 Viewer는 TypeScript 5.9·Vite 5, HMDesign은 TypeScript 7·Vite 8). 패키지는 HMDesign 도구로 빌드되고 소비 프로젝트는 결과물만 사용합니다.
 - 버전 식별은 Submodule Commit SHA입니다. SW 패키지는 `dist/build-info.json`에 빌드한 Commit과 dirty 여부를 기록합니다.
-- npm Registry publish는 현재 필수가 아닙니다. Registry 배포를 도입하면 이 문서와 별도로 [운영/배포 가이드](./운영-배포-가이드.md)에 절차를 둡니다.
+- HM 패키지는 npm Registry로 배포하지 않습니다. `npm install @hm-design/<패키지>@<버전>`으로 설치하거나 `.npmrc`에 `@hm-design:registry`를 추가하지 않습니다. 2026-10-07 Gitea npm Registry에 시험 게시한 `@hm-design/ui@0.1.0`·`@hm-design/center-graphic@0.1.0`은 현재 소스와 다른 이전 산출물입니다.
+- `package.json`의 `version`(예: `0.1.0`)은 Workspace 연결과 peer 범위용 값이며 Registry 배포 버전이 아닙니다. Theme CDN 등 운영 배포는 [운영/배포 가이드](./운영-배포-가이드.md)를 따릅니다.

docs/guidelines/publisher-distribution-guide.md

@@ -1,6 +1,6 @@
 # 퍼블리셔 Git 테스트 공유·실행 안내
 
-현재 공유 기준은 [공식 Gitea HMDesign](https://gitea.hmac.kr/b25027/HMDesign)의 Git Clone입니다. 먼저 [AGENTS.md](../../AGENTS.md)를 확인합니다. 과거 ZIP 제작·압축 해제 검증은 [추가 수정 보고서](publisher-additional-review-2026-10-10.md)의 당시 기록이며 현재 설치 방법을 대체하지 않습니다. 이번 공유에는 신규 ZIP·포터블 패키지를 만들지 않습니다.
+현재 공유 기준은 [공식 Gitea HMDesign](https://gitea.hmac.kr/shkim4/HMDesign)의 Git Clone입니다. 먼저 [AGENTS.md](../../AGENTS.md)를 확인합니다. 과거 ZIP 제작·압축 해제 검증은 [추가 수정 보고서](publisher-additional-review-2026-10-10.md)의 당시 기록이며 현재 설치 방법을 대체하지 않습니다. 이번 공유에는 신규 ZIP·포터블 패키지를 만들지 않습니다.
 
 ## 설치 조건과 Storybook 열람
 
@@ -11,7 +11,7 @@ Node.js를 별도로 설치하고 PATH에서 `node`와 `npm`을 사용할 수
 로컬 개발 Storybook이 필요하면 Clone 후 루트에서 다음을 실행합니다.
 
 ```powershell
-git clone https://gitea.hmac.kr/b25027/HMDesign.git
+git clone https://gitea.hmac.kr/shkim4/HMDesign.git
 cd HMDesign
 node --version
 npm --version

docs/guidelines/theme-delivery.md

@@ -2,7 +2,7 @@
 
 ## Repository와 배포 단위
 
-하나의 Git Repository에서 소스·Theme·Storybook·문서를 관리한다. UI, CENTER Graphic, Theme JSON은 각각 별도 배포 단위다. 현재 두 패키지는 `private: false`이며 compiled dist(JS·타입·CSS)를 export한다. Library build는 `npm run build:packages`로 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 테스트 ZIP 실행에는 Registry 접근·publish가 필요하지 않다. Theme JSON의 독립 산출 경로는 구현했다. 실제 CDN URL·인프라·인증·CI publish는 미정이다.
+하나의 Git Repository에서 소스·Theme·Storybook·문서를 관리한다. UI, CENTER Graphic, Theme JSON은 각각 별도 배포 단위다. 현재 두 패키지는 `private: false`이며 compiled dist(JS·타입·CSS)를 export한다. Library build는 `npm run build:packages`로 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않으며 소비 프로젝트는 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. Theme JSON의 독립 산출 경로는 구현했다. 실제 CDN URL·인프라·인증·CI publish는 미정이다.
 
 운영 배포 경계는 `packages/ui` → UI package, `packages/center-graphic` → Graphic package, `themes/*.json` → Theme CDN이다. **Git push ≠ Theme CDN publish**다. 운영 CI/CD는 JSON 검증·독립 artifact 산출 후 CDN에 배포하는 별도 단계로 구성하며, 현재 저장소에는 실제 CDN publish pipeline이 구현되어 있지 않다.
 

docs/guidelines/개발-적용-가이드.md

@@ -4,7 +4,7 @@
 
 페이지 구현 전에 [Navigation Single Mode Policy](navigation-single-mode.md)를 적용한다. AI 코드 생성·제안, 신규/기존 화면, 프로토타입, Production 모두 GNB / LNB / DASHBOARD 중 정확히 하나만 선택한다. 모바일도 같은 체계의 Responsive Variant를 사용하며 별도 요청 없이 Navigation 조합을 생성하거나 제안하지 않는다.
 
-> 대상: 디자인팀과 서비스 개발팀. 현재 UI/CENTER compiled dist build/export, JSON Default/서비스 partial, 공개 Runtime 검증·Global/Scoped Apply와 URL Loader, Storybook JSON Preview, Theme-only artifact 산출이 구현되었다. 현재 테스트 공유는 Git Clone → npm ci → npm run build:packages → npm run storybook(6024)이다. [현재 Git 설치·실행 안내](../../README.md#git-clone-설치실행-현재-테스트-공유-기준)를 먼저 따른다. Registry publish 이력은 Git 테스트 공유 검증 범위 밖이며 실제 CDN infrastructure/publish pipeline은 다음 단계다. Git Clone은 로컬 workspace를 빌드하므로 HM Registry 접근·publish가 필요하지 않다. 아래 장기 운영 예시의 `@company/ui`는 목표명이며 현재 import는 `@hm-design/ui`다. 현재 실제 API/독립 배포 절차는 [Theme delivery](theme-delivery.md), 디자인팀 workflow는 [Theme guide](designer-theme-guide.md)를 따른다.
+> 대상: 디자인팀과 서비스 개발팀. 현재 UI/CENTER compiled dist build/export, JSON Default/서비스 partial, 공개 Runtime 검증·Global/Scoped Apply와 URL Loader, Storybook JSON Preview, Theme-only artifact 산출이 구현되었다. 현재 테스트 공유는 Git Clone → npm ci → npm run build:packages → npm run storybook(6024)이다. [현재 Git 설치·실행 안내](../../README.md#git-clone-설치실행-현재-테스트-공유-기준)를 먼저 따른다. HM 패키지는 npm Registry로 배포하지 않으며 실제 CDN infrastructure/publish pipeline은 다음 단계다. Git Clone은 로컬 workspace를 빌드하고 다른 프로젝트는 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결하므로 HM Registry 접근·publish가 필요하지 않다. 아래 장기 운영 예시의 `@company/ui`는 목표명이며 현재 import는 `@hm-design/ui`다. 현재 실제 API/독립 배포 절차는 [Theme delivery](theme-delivery.md), 디자인팀 workflow는 [Theme guide](designer-theme-guide.md)를 따른다.
 
 ## 1. 착수 순서
 

docs/guidelines/운영-배포-가이드.md

@@ -1,6 +1,6 @@
 # 운영·배포 가이드 (검토용 개정안)
 
-> 이 문서는 장기 운영 목표도 포함한다. 현재 UI/CENTER compiled dist build/export, JSON Default/partial과 공개 URL Loader/Apply, Designer JSON Preview, `npm run build:themes` 독립 artifact 산출이 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 Theme Admin, 실제 CDN/pipeline은 미구현이다. 테스트 ZIP은 포함 dist와 로컬 workspace를 사용하며 Registry 접근·publish는 필수가 아니다. 아래 `@company/ui`는 목표명이며 현재 패키지는 `@hm-design/ui`다. 이번 단계의 실제 배포/캐시/롤백은 [Theme delivery](theme-delivery.md)를 따른다. MVP 수동 운영과 향후 자동화를 구분한다.
+> 이 문서는 장기 운영 목표도 포함한다. 현재 UI/CENTER compiled dist build/export, JSON Default/partial과 공개 URL Loader/Apply, Designer JSON Preview, `npm run build:themes` 독립 artifact 산출이 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. Theme Admin, 실제 CDN/pipeline은 미구현이다. 아래 `@company/ui`는 목표명이며 현재 패키지는 `@hm-design/ui`다. 이번 단계의 실제 배포/캐시/롤백은 [Theme delivery](theme-delivery.md)를 따른다. MVP 수동 운영과 향후 자동화를 구분한다.
 
 단일 `HMDesignSystem` Git 저장소에서 컴포넌트 소스·기본 CSS, Storybook, Theme 초안을 함께 관리한다. **Git 커밋, 패키지 릴리스, Theme Publish는 서로 다른 단계**다. 소스에 CSS/JSON을 수정하거나 Storybook을 빌드하는 것만으로 사용 중인 앱에 변경이 전달되지 않는다.
 
@@ -68,7 +68,7 @@ Draft 값 수정 → 실제 @company/ui Storybook Preview → 자동 검증
 
 | 단계 | 운영 방식 | 필수 증거 |
 |---|---|---|
-| 현재 구현 | compiled dist build/export 패키지·JSON Theme/URL Loader/Apply·Designer Preview·Theme-only artifact. Registry publish 이력은 ZIP 검증 범위 밖; 운영 CDN Publish 미구현 | JSON/Runtime/Default parity/레이아웃 및 URL 실패 fallback 검증 |
+| 현재 구현 | compiled dist build/export 패키지·JSON Theme/URL Loader/Apply·Designer Preview·Theme-only artifact. HM 패키지는 Git Submodule + npm Workspace 연결(npm Registry 미사용); 운영 CDN Publish 미구현 | JSON/Runtime/Default parity/레이아웃 및 URL 실패 fallback 검증 |
 | MVP 서비스 도입 | 구현된 패키지 빌드·로컬 Theme JSON·Storybook Preview를 서비스 앱에 연결하고 수동 검증. Production Publish 없음 | 동일 패키지 컴포넌트의 override/fallback, 새로고침 확인 |
 | 운영 기반 | Registry, 불변 버전, 검증 API, 승인 기록, 환경별 활성 포인터, API/CDN, 롤백 절차 | STG→PROD 발행과 이전 버전 복귀의 실제 앱 검증 |
 | 운영 확장 | Theme Admin, 역할별 권한, 감사 로그, 자동 시각·접근성 검사, 관측 | 승인·배포·복구 이력과 서비스별 적용 버전 추적 |

docs/guidelines/프로젝트-지침.md

@@ -1,6 +1,6 @@
 # Runtime Theme 기반 Design System 프로젝트 지침 (개정안)
 
-> 상태: 현재 하나의 Git Repository에서 UI/CENTER npm workspaces의 compiled dist build/export, JSON 컬러 원본, Global/Scoped Runtime Apply·URL Loader, 통합 Storybook/Designer JSON Preview, Theme-only artifact를 관리한다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 실제 CDN/API/Publish pipeline은 미구현이다. 현재 구현의 운영·배포 절차는 [Theme delivery](theme-delivery.md)를 따른다.
+> 상태: 현재 하나의 Git Repository에서 UI/CENTER npm workspaces의 compiled dist build/export, JSON 컬러 원본, Global/Scoped Runtime Apply·URL Loader, 통합 Storybook/Designer JSON Preview, Theme-only artifact를 관리한다. HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결하며 실제 CDN/API/Publish pipeline은 미구현이다. 현재 구현의 운영·배포 절차는 [Theme delivery](theme-delivery.md)를 따른다.
 
 > **2026-10-07 사용자 확정 정책은 개정안 상태와 관계없이 필수 적용한다.** AI의 모든 신규·수정 UI는 사용자의 별도 지시 없이 기존 Component / Storybook Reference를 먼저 확인하고 Theme / Semantic Token과 단일 Navigation Mode를 기본 적용하며 Custom은 최소화한다. 필수 요약은 [AGENTS.md](../../AGENTS.md), 상세 구현 정책은 [shadcn 기반 구현 원칙](shadcn-기반-구현-원칙.md), Theme 정책은 [테마 토큰 가이드](테마-토큰-가이드.md), Navigation 정책은 [Navigation Single Mode Policy](navigation-single-mode.md)가 각각 담당한다.
 
@@ -67,7 +67,7 @@ Primitive (설계·빌드 시 관리) → Semantic (컴포넌트 참조) → Com
 
 `HMDesignSystem`을 **하나의 Git 저장소**로 관리한다. 저장소 수와 배포물 수는 다르다. 동일 저장소의 변경이라도 컴포넌트·기본 CSS는 패키지 릴리스, 기존 Semantic Token 값은 Theme Publish, Storybook은 내부 검수용 빌드로 각각 처리한다. 개발팀의 서비스 앱은 이 저장소의 소스 파일을 직접 복사하지 않고 배포된 패키지와 Theme API/CDN을 소비한다.
 
-현재 파일 배치는 다음과 같다. Library dist 산출물과 Runtime URL Loader는 구현되어 있다. Registry publish 이력은 테스트 ZIP 검증 범위 밖이며 운영 CDN/API/Publish pipeline은 별도 도입 대상이다.
+현재 파일 배치는 다음과 같다. Library dist 산출물과 Runtime URL Loader는 구현되어 있다. HM 패키지는 npm Registry로 배포하지 않으며 운영 CDN/API/Publish pipeline은 별도 도입 대상이다.
 
 ```text
 HMDesignSystem/
@@ -88,7 +88,7 @@ HMDesignSystem/
 
 ### 5.1 패키지 구성과 Storybook 통합 (구현됨 — 2026-10-02 패키지 분리)
 
-**하나의 Git 저장소 + 두 개의 독립 배포 패키지 + 하나의 통합 Storybook**을 기본으로 한다. 2026-10-02에 npm workspaces(`packages/*`)로 분리했다. `packages/ui`(`@hm-design/ui`)에 Button·Input·Select·Card·Dialog와 Theme(`src/theme/*.css`, `theme.css`, `tailwind.css`)이 있고, `packages/center-graphic`(`@hm-design/center-graphic`)은 ui-viz CENTER Web Reference(제목·정보·노선/공간·시설물)를 이식해 구현했다(기준 문서 `docs/center-graphic/README.md`). 둘은 서로 의존하지 않는다. 루트는 Storybook(`.storybook/`, `src/**/*.stories.tsx`; UI는 `Components`, CENTER는 `Center Graphic` 최상위 그룹)과 Demo(`src/App.tsx`, `src/hm-theme.css`), 컴포넌트 문서(`docs/components/`)를 유지하며 Story와 Demo는 `@hm-design/ui`를 workspace 패키지로 import한다. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 compiled `dist`에서 export한다. `npm run build:packages`가 library 산출물을 생성하며 Registry publish 이력은 테스트 ZIP 검증 범위 밖이다. 소비 앱은 `@import "tailwindcss"; @import "@hm-design/ui/tailwind.css"; @import "@hm-design/ui/theme.css"`를 쓴다. UI dist에는 `fonts/`의 글꼴과 OFL이 포함되며 compiled `theme.css`는 상대 `./fonts/` 경로를 사용한다. Source `packages/ui/src/theme.css`는 `/fonts/NotoSansKR-variable.ttf`를 사용하므로 App/Storybook 개발 서버는 `public/fonts/`를 서빙한다.
+**하나의 Git 저장소 + 두 개의 독립 배포 패키지 + 하나의 통합 Storybook**을 기본으로 한다. 2026-10-02에 npm workspaces(`packages/*`)로 분리했다. `packages/ui`(`@hm-design/ui`)에 Button·Input·Select·Card·Dialog와 Theme(`src/theme/*.css`, `theme.css`, `tailwind.css`)이 있고, `packages/center-graphic`(`@hm-design/center-graphic`)은 ui-viz CENTER Web Reference(제목·정보·노선/공간·시설물)를 이식해 구현했다(기준 문서 `docs/center-graphic/README.md`). 둘은 서로 의존하지 않는다. 루트는 Storybook(`.storybook/`, `src/**/*.stories.tsx`; UI는 `Components`, CENTER는 `Center Graphic` 최상위 그룹)과 Demo(`src/App.tsx`, `src/hm-theme.css`), 컴포넌트 문서(`docs/components/`)를 유지하며 Story와 Demo는 `@hm-design/ui`를 workspace 패키지로 import한다. 두 패키지는 `private: false`이며 ESM JS·타입 선언·CSS를 compiled `dist`에서 export한다. `npm run build:packages`가 library 산출물을 생성하며 HM 패키지는 npm Registry로 배포하지 않고 [Git Submodule + npm Workspace](external-install-submodule.md)로 연결한다. 소비 앱은 `@import "tailwindcss"; @import "@hm-design/ui/tailwind.css"; @import "@hm-design/ui/theme.css"`를 쓴다. UI dist에는 `fonts/`의 글꼴과 OFL이 포함되며 compiled `theme.css`는 상대 `./fonts/` 경로를 사용한다. Source `packages/ui/src/theme.css`는 `/fonts/NotoSansKR-variable.ttf`를 사용하므로 App/Storybook 개발 서버는 `public/fonts/`를 서빙한다.
 
 아래는 목표 구조다.
 
@@ -294,7 +294,7 @@ Layout / Pattern           → 현재 HM 대표 Story / Pattern 문서와 단일
 
 | 단계 | 구축 범위 | 다음 단계 진입 조건 |
 |---|---|---|
-| 현재 구현 | UI/CENTER compiled dist build/export, Component·Pattern, 공개 Runtime 계약/API·URL Loader, Default/External verification Story, Theme-only artifact. Registry publish 이력은 ZIP 검증 범위 밖; 운영 CDN/Publish pipeline은 미구현 | 코드/문서/실제 Storybook 정합성 검증 |
+| 현재 구현 | UI/CENTER compiled dist build/export, Component·Pattern, 공개 Runtime 계약/API·URL Loader, Default/External verification Story, Theme-only artifact. HM 패키지는 Git Submodule + npm Workspace 연결(npm Registry 미사용); 운영 CDN/Publish pipeline은 미구현 | 코드/문서/실제 Storybook 정합성 검증 |
 | MVP | 단일 저장소에서 `@company/ui` 패키징, 기본 CSS, Semantic 계약, Storybook, 로컬 JSON Preview/Loader | 같은 패키지 컴포넌트에서 값 override와 fallback을 실제로 확인 |
 | 운영 기반 | 불변 Theme Registry, 스키마 검증, 버전·호환성, 승인 Publish, API/CDN, 롤백·로그 | 앱 재배포 없이 Theme 값 반영, 실패 시 기본값, 이전 버전 복귀를 확인 |
 | 운영 확장 | 디자인팀 Admin, 권한·감사, 자동 검수·모니터링 | 운영 절차와 담당자가 정해지고 실제 서비스 적용 기록이 남음 |