diff --git a/PROJECT_MAP.md b/PROJECT_MAP.md
index ee01392..d59ed02 100644
--- a/PROJECT_MAP.md
+++ b/PROJECT_MAP.md
@@ -151,7 +151,7 @@ zio-harness 풀스택 개발 에이전트 팀. 4종 에이전트가 파이프라
 |------|-----|
 | Claude Code 버전 | v2.x 이상 |
 | 필수 환경 변수 | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` |
-| 설치 명령(이 저장소) | `claude plugin marketplace add https://git.zioinfo.co.kr/ythong/harness` → `claude plugin install harness@ythong-harness` |
+| 설치 명령(이 저장소) | `claude plugin marketplace add https://git.zioinfo.co.kr/ythong/harness.git` → `claude plugin install harness@ythong-harness` (⚠️ 비-GitHub git 저장소는 **`.git` 필수** — 없으면 `expected object, received string` 오류) |
 
 ---
 
diff --git a/docs/plugin-guide.md b/docs/plugin-guide.md
index cea46d6..cba4804 100644
--- a/docs/plugin-guide.md
+++ b/docs/plugin-guide.md
@@ -198,15 +198,18 @@ claude plugin list | grep <name>          # 등록 확인
 ## 6. 설치·사용 (사용자 입장)
 
 ```bash
-# 1) 마켓플레이스 추가 (저장소 지정)
-claude plugin marketplace add ythong/harness        # 또는 git URL
+# 1) 마켓플레이스 추가 — git 저장소 URL은 반드시 .git 으로 끝나야 한다
+claude plugin marketplace add https://git.zioinfo.co.kr/ythong/harness.git
 
 # 2) 플러그인 설치
-claude plugin install zio-harness@ythong-harness
+claude plugin install zio-harness@ythong-harness    # 또는 harness / proposal-builder
 
 # 3) 에이전트 팀 플래그 (하네스는 멀티에이전트 API에 의존)
 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 ```
+
+> ⚠️ **`.git` 누락 주의.** 비-GitHub git 저장소(gitea 등)를 `.git` 없이 추가하면 Claude가 git clone 대신 단일 파일 URL로 해석해 저장소 **웹페이지(HTML)**를 가져오고, `Invalid marketplace schema from URL: ... expected object, received string` 오류가 난다. GitHub은 `owner/repo` 단축형도 되지만, 그 외 git 호스트는 **전체 `https://…/repo.git` URL**을 쓴다.
+
 이후 트리거 문장(예: "풀스택 개발 시작")으로 발동합니다. 플래그가 필요한 이유는 [`experimental-dependency.md`](./experimental-dependency.md) 참조.
 
 ---