relayax-cli 0.2.41 → 0.3.42

package/dist/lib/version-check.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkCliVersion = checkCliVersion;
-exports.checkTeamVersion = checkTeamVersion;
-exports.checkAllTeams = checkAllTeams;
+exports.checkAgentVersion = checkAgentVersion;
+exports.checkAllAgents = checkAllAgents;
 const config_js_1 = require("./config.js");
 const api_js_1 = require("./api.js");
 const update_cache_js_1 = require("./update-cache.js");
@@ -28,7 +28,7 @@ async function checkCliVersion(force) {
     }
     return null;
 }
-async function checkTeamVersion(slug, force) {
+async function checkAgentVersion(slug, force) {
     if ((0, update_cache_js_1.isCacheValid)(slug, force))
         return null;
     try {
@@ -40,20 +40,20 @@ async function checkTeamVersion(slug, force) {
         if (entry.type === 'system') {
             return null;
         }
-        const team = await (0, api_js_1.fetchTeamInfo)(slug);
+        const agent = await (0, api_js_1.fetchAgentInfo)(slug);
         (0, update_cache_js_1.updateCacheTimestamp)(slug);
         // Fire-and-forget usage ping (only when cache expired = actual API call happened)
-        const teamId = entry.team_id ?? team.id;
-        if (teamId) {
-            (0, api_js_1.sendUsagePing)(teamId, slug, entry.version);
+        const agentId = entry.agent_id ?? agent.id;
+        if (agentId) {
+            (0, api_js_1.sendUsagePing)(agentId, slug, entry.version);
         }
-        if (team.version !== entry.version) {
+        if (agent.version !== entry.version) {
             return {
-                type: 'team',
+                type: 'agent',
                 slug,
                 current: entry.version,
-                latest: team.version,
-                author: team.author?.username,
+                latest: agent.version,
+                author: agent.author?.username,
             };
         }
     }
@@ -62,12 +62,12 @@ async function checkTeamVersion(slug, force) {
     }
     return null;
 }
-async function checkAllTeams(force) {
+async function checkAllAgents(force) {
     const installed = (0, config_js_1.loadInstalled)();
     const slugs = Object.keys(installed);
     const results = [];
     for (const slug of slugs) {
-        const result = await checkTeamVersion(slug, force);
+        const result = await checkAgentVersion(slug, force);
         if (result)
             results.push(result);
     }

package/dist/prompts/_business-card.md

@@ -0,0 +1,41 @@
+### 빌더 명함 표시
+JSON 결과의 `author`, `welcome` 필드를 사용하여 명함을 표시합니다.
+불릿 리스트(- 또는 *)로 나열하지 마세요. 반드시 인용 블록(>) 안에 넣어야 합니다.
+
+**JSON 결과에서 사용할 필드:**
+- `author.display_name` 또는 `author.username` → 명함 제목
+- `welcome` → 환영 메시지 (💬)
+- `author.contact_links` → 연락처 배열 (`[{type, label, value}]`)
+- `author.username` → 프로필 링크 (👤)
+
+**예시 (이 형태를 그대로 따르세요):**
+
+JSON 결과 예시:
+```json
+{
+  "author": { "username": "alice", "display_name": "Alice Kim", "contact_links": [
+    {"type": "email", "label": "이메일", "value": "alice@example.com"},
+    {"type": "website", "label": "블로그", "value": "https://alice.dev"},
+    {"type": "kakao", "label": "카카오", "value": "https://open.kakao.com/o/abc123"}
+  ]},
+  "welcome": "안녕하세요!\n에이전트 빌더 Alice입니다.\n설치해주셔서 감사합니다."
+}
+```
+
+출력:
+
+> **🪪 Alice Kim의 명함**
+>
+> 💬 "안녕하세요!
+> 에이전트 빌더 Alice입니다.
+> 설치해주셔서 감사합니다."
+>
+> 📧 alice@example.com
+> 🔗 블로그: alice.dev
+> 💬 카카오: open.kakao.com/o/abc123
+> 👤 relayax.com/@alice
+
+- `welcome`이 없으면 💬 줄을 생략합니다.
+- 연락처의 type에 맞는 이모지: 📧 email, 💬 kakao, 🐦 x, 💼 linkedin, 💻 github, 🔗 website/custom
+- 연락처가 여러 개면 각각 한 줄씩 표시합니다.
+- `author`가 null이면 명함 블록 전체를 생략합니다.

package/dist/prompts/_error-handling.md

@@ -0,0 +1,38 @@
+### 에러 처리 가이드
+
+CLI 명령 실행 후 JSON 에러가 반환되면 아래 기준에 따라 처리합니다.
+**원칙: "되돌릴 수 없는 영향이 있는가?"로 판단합니다.**
+
+#### 1. 자동 해결 (사용자에게 물어보지 않음)
+되돌릴 수 있고, 부작용 없는 에러:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `LOGIN_REQUIRED` / `NO_TOKEN` | `relay login` 실행 (timeout 300초, 브라우저 자동 열림) → 성공 후 원래 명령 재시도 |
+| `NOT_INITIALIZED` | `relay init --all --json` 실행 → 원래 명령 재시도 |
+| `FETCH_FAILED` | 3초 대기 후 원래 명령 재시도 (최대 2회). 2회 실패 시 사용자에게 안내 |
+
+#### 2. 사용자에게 선택지 제시 (AskUserQuestion)
+`options` 필드가 있는 에러:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `MISSING_VISIBILITY` | options의 label을 선택지로 AskUserQuestion 호출 |
+| `MISSING_FIELD` | fix 안내 + 사용자에게 값 입력 요청 |
+| `MISSING_TOOLS` | options의 감지된 도구 목록을 선택지로 AskUserQuestion 호출 |
+| `MISSING_SPACE` | options의 Space 목록을 선택지로 AskUserQuestion 호출 |
+
+사용자가 선택하면, 선택된 값을 CLI 플래그에 반영하여 명령을 재호출합니다.
+
+#### 3. 사용자에게 안내 (되돌릴 수 없는 에러)
+구매, 접근 권한, 보안 관련:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `GATED_ACCESS_REQUIRED` | purchase_info의 message/url 표시 → "접근 코드가 있으신가요?" AskUserQuestion |
+| `SPACE_ONLY` | Space 가입 필요 안내 → "초대 코드가 있으신가요?" AskUserQuestion |
+| `APPROVAL_REQUIRED` | 승인 대기 안내 |
+| `NO_ACCESS` | 접근 방법 안내 |
+
+#### 4. 그 외 에러
+`fix` 필드의 메시지를 사용자에게 전달하고, 필요하면 다음 행동을 제안합니다.

package/dist/prompts/_requirements-check.md

@@ -0,0 +1,59 @@
+### Requirements 체크리스트 (필수 — 항목이 있으면 반드시 수행)
+
+`relay.yaml`의 `requires` 섹션을 읽고, **각 항목을 하나씩 확인하여 체크리스트로 표시**합니다.
+requires 섹션이 없거나 비어있으면 이 단계를 건너뜁니다.
+
+**출력 형식** (반드시 이 형식으로 사용자에게 보여줍니다):
+```
+📋 Requirements 확인
+
+[runtime]
+  ✅ Node.js >=18 — v20.11.0 확인됨
+  ❌ Python >=3.10 — v3.8.5 (업그레이드 필요)
+
+[cli]
+  ✅ playwright — 설치됨
+  ❌ ffmpeg — 미설치 → 설치 명령: brew install ffmpeg
+
+[npm]
+  ✅ sharp — 설치됨
+  ❌ puppeteer — 미설치 → 설치 중...
+
+[env]
+  ✅ OPENAI_API_KEY — 설정됨
+  ❌ SLACK_WEBHOOK_URL (선택) — 미설정. 알림 전송에 필요
+
+[mcp]
+  ⚙️  supabase — MCP 서버 설정 필요 (아래 안내 참고)
+
+[agents]
+  ✅ @alice/doc-writer — 이미 설치됨
+  📦 @bob/utils — 미설치 → 설치 중...
+```
+
+**처리 규칙 (각 카테고리별):**
+
+1. **runtime**: `node --version`, `python3 --version`으로 확인. 버전 미달이면 ❌ 표시 후 업그레이드 안내.
+2. **cli**: `which <name>`으로 확인.
+   - 설치됨 → ✅
+   - 미설치 + `install` 필드 있음 → 사용자에게 설치할지 물어본 후 실행
+   - 미설치 + `install` 필드 없음 → ❌ 표시 후 수동 설치 안내
+3. **npm**: `npm list <package> 2>/dev/null`으로 확인.
+   - 설치됨 → ✅
+   - 미설치 + required → `npm install <package>` 실행
+   - 미설치 + optional → ❌ 표시 후 안내만
+4. **env**: `echo $<NAME>`으로 확인.
+   - 설정됨 → ✅
+   - 미설정 + required → ❌ 표시 후 `description`과 함께 설정 방법 안내
+   - 미설정 + optional → ⚠️ 표시 후 용도 안내
+5. **mcp**: MCP 서버 설정이 필요한 경우 ⚙️ 표시 후 설정 방법을 상세히 안내.
+   - `config` 필드가 있으면 settings.json에 추가할 JSON 블록을 보여줍니다.
+   - `env` 필드가 있으면 필요한 환경변수도 함께 안내합니다.
+6. **agents**: `relay list --json`으로 설치 여부 확인.
+   - 설치됨 → ✅
+   - 미설치 → `relay install <@author/agent> --json` 실행하여 재귀 설치
+
+**중요**: 모든 required 항목이 ❌인 경우, 체크리스트 끝에 경고를 표시합니다:
+```
+⚠️  필수 요구사항이 충족되지 않았습니다. 에이전트 기능이 제한될 수 있습니다.
+```

package/dist/prompts/_setup-cli.md

@@ -0,0 +1,19 @@
+## Step 1. Relay CLI 설치
+
+relay CLI가 설치되어 있지 않다면:
+
+```bash
+npm install -g relayax-cli
+```
+
+Node.js가 없는 경우:
+- macOS: `brew install node`
+- Windows: `winget install OpenJS.NodeJS.LTS`
+- Linux: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash && source ~/.bashrc && nvm install --lts`
+
+npm 권한 오류 시:
+```bash
+mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
+npm install -g relayax-cli
+```

package/dist/prompts/_setup-login.md

@@ -0,0 +1,7 @@
+## Step 2. 로그인
+
+```bash
+relay login
+```
+
+브라우저가 열리면 GitHub 또는 카카오 계정으로 로그인하세요.

package/dist/prompts/_setup-org.md

@@ -0,0 +1,27 @@
+## Organization 생성
+
+먼저 Organization이 있는지 확인합니다:
+
+```bash
+relay orgs list --json
+```
+
+Organization이 없으면 새로 생성합니다:
+
+```bash
+relay orgs create "조직 이름"
+```
+
+생성 후 접근 코드를 만들어 멤버를 초대할 수 있습니다:
+
+```bash
+relay grant create --org <org-slug>
+```
+
+접근 코드를 받은 멤버는 아래 명령으로 Organization에 가입합니다:
+
+```bash
+relay grant use --code <접근코드>
+```
+
+또는 웹에서 직접 관리할 수도 있습니다: relayax.com/orgs

package/dist/prompts/business-card.md

@@ -0,0 +1,41 @@
+### 빌더 명함 표시
+JSON 결과의 `author`, `welcome` 필드를 사용하여 명함을 표시합니다.
+불릿 리스트(- 또는 *)로 나열하지 마세요. 반드시 인용 블록(>) 안에 넣어야 합니다.
+
+**JSON 결과에서 사용할 필드:**
+- `author.display_name` 또는 `author.username` → 명함 제목
+- `welcome` → 환영 메시지 (💬)
+- `author.contact_links` → 연락처 배열 (`[{type, label, value}]`)
+- `author.username` → 프로필 링크 (👤)
+
+**예시 (이 형태를 그대로 따르세요):**
+
+JSON 결과 예시:
+```json
+{
+  "author": { "username": "alice", "display_name": "Alice Kim", "contact_links": [
+    {"type": "email", "label": "이메일", "value": "alice@example.com"},
+    {"type": "website", "label": "블로그", "value": "https://alice.dev"},
+    {"type": "kakao", "label": "카카오", "value": "https://open.kakao.com/o/abc123"}
+  ]},
+  "welcome": "안녕하세요!\n에이전트 빌더 Alice입니다.\n설치해주셔서 감사합니다."
+}
+```
+
+출력:
+
+> **🪪 Alice Kim의 명함**
+>
+> 💬 "안녕하세요!
+> 에이전트 빌더 Alice입니다.
+> 설치해주셔서 감사합니다."
+>
+> 📧 alice@example.com
+> 🔗 블로그: alice.dev
+> 💬 카카오: open.kakao.com/o/abc123
+> 👤 relayax.com/@alice
+
+- `welcome`이 없으면 💬 줄을 생략합니다.
+- 연락처의 type에 맞는 이모지: 📧 email, 💬 kakao, 🐦 x, 💼 linkedin, 💻 github, 🔗 website/custom
+- 연락처가 여러 개면 각각 한 줄씩 표시합니다.
+- `author`가 null이면 명함 블록 전체를 생략합니다.

package/dist/prompts/error-handling.md

@@ -0,0 +1,38 @@
+### 에러 처리 가이드
+
+CLI 명령 실행 후 JSON 에러가 반환되면 아래 기준에 따라 처리합니다.
+**원칙: "되돌릴 수 없는 영향이 있는가?"로 판단합니다.**
+
+#### 1. 자동 해결 (사용자에게 물어보지 않음)
+되돌릴 수 있고, 부작용 없는 에러:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `LOGIN_REQUIRED` / `NO_TOKEN` | `relay login` 실행 (timeout 300초, 브라우저 자동 열림) → 성공 후 원래 명령 재시도 |
+| `NOT_INITIALIZED` | `relay init --all --json` 실행 → 원래 명령 재시도 |
+| `FETCH_FAILED` | 3초 대기 후 원래 명령 재시도 (최대 2회). 2회 실패 시 사용자에게 안내 |
+
+#### 2. 사용자에게 선택지 제시 (AskUserQuestion)
+`options` 필드가 있는 에러:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `MISSING_VISIBILITY` | options의 label을 선택지로 AskUserQuestion 호출 |
+| `MISSING_FIELD` | fix 안내 + 사용자에게 값 입력 요청 |
+| `MISSING_TOOLS` | options의 감지된 도구 목록을 선택지로 AskUserQuestion 호출 |
+| `MISSING_SPACE` | options의 Space 목록을 선택지로 AskUserQuestion 호출 |
+
+사용자가 선택하면, 선택된 값을 CLI 플래그에 반영하여 명령을 재호출합니다.
+
+#### 3. 사용자에게 안내 (되돌릴 수 없는 에러)
+구매, 접근 권한, 보안 관련:
+
+| 에러 코드 | 행동 |
+|-----------|------|
+| `GATED_ACCESS_REQUIRED` | purchase_info의 message/url 표시 → "접근 코드가 있으신가요?" AskUserQuestion |
+| `SPACE_ONLY` | Space 가입 필요 안내 → "초대 코드가 있으신가요?" AskUserQuestion |
+| `APPROVAL_REQUIRED` | 승인 대기 안내 |
+| `NO_ACCESS` | 접근 방법 안내 |
+
+#### 4. 그 외 에러
+`fix` 필드의 메시지를 사용자에게 전달하고, 필요하면 다음 행동을 제안합니다.

package/dist/prompts/index.d.ts

@@ -0,0 +1,7 @@
+export declare const REQUIREMENTS_CHECK: string;
+export declare const ERROR_HANDLING_GUIDE: string;
+export declare const BUSINESS_CARD_FORMAT: string;
+export declare const SETUP_CLI: string;
+export declare const SETUP_LOGIN: string;
+export declare const INSTALL_PROMPT: string;
+export declare const PUBLISH_PROMPT: string;

package/dist/prompts/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLISH_PROMPT = exports.INSTALL_PROMPT = exports.SETUP_LOGIN = exports.SETUP_CLI = exports.BUSINESS_CARD_FORMAT = exports.ERROR_HANDLING_GUIDE = exports.REQUIREMENTS_CHECK = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readPrompt(filename) {
+    return fs_1.default.readFileSync(path_1.default.join(__dirname, filename), 'utf-8').trim();
+}
+function interpolate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+}
+// ─── 공유 조각 ───
+exports.REQUIREMENTS_CHECK = readPrompt('_requirements-check.md');
+exports.ERROR_HANDLING_GUIDE = readPrompt('_error-handling.md');
+exports.BUSINESS_CARD_FORMAT = readPrompt('_business-card.md');
+exports.SETUP_CLI = readPrompt('_setup-cli.md');
+exports.SETUP_LOGIN = readPrompt('_setup-login.md');
+const fragments = {
+    REQUIREMENTS_CHECK: exports.REQUIREMENTS_CHECK,
+    ERROR_HANDLING_GUIDE: exports.ERROR_HANDLING_GUIDE,
+    BUSINESS_CARD_FORMAT: exports.BUSINESS_CARD_FORMAT,
+};
+// ─── 전체 프롬프트 (조각 합성 완료) ───
+exports.INSTALL_PROMPT = interpolate(readPrompt('install.md'), fragments);
+exports.PUBLISH_PROMPT = interpolate(readPrompt('publish.md'), fragments);

package/dist/prompts/install.md

@@ -0,0 +1,187 @@
+요청된 에이전트를 relay에서 다운로드하고, 현재 에이전트 환경에 맞게 구성합니다.
+인자 없이 호출하면 인터랙티브 탐색 모드로 진입합니다.
+
+## 인터랙션 플로우
+
+이 커맨드는 3단계 인터랙션으로 진행됩니다. 각 단계에서 반드시 AskUserQuestion 도구를 사용하세요.
+
+### Step 1. Organization 선택 & 에이전트 탐색 (slug가 없을 때만)
+
+slug가 직접 주어지면 (`/relay-install @alice/doc-writer`) 이 단계를 건너뛰고 Step 2로 갑니다.
+
+#### 1-1. Organization 선택
+`relay orgs list --json` 을 실행하여 사용자의 Organization 목록을 가져옵니다.
+
+**AskUserQuestion 호출:**
+- question: "어디서 에이전트를 찾을까요?"
+- options: Organization이 있으면 `["<org1_name>", "<org2_name>", ...]`, 없으면 이 단계를 건너뛰고 바로 공개 에이전트 탐색으로 진행
+
+**응답 처리:**
+- Organization 이름 선택 → 1-2. Org 에이전트 탐색으로 진행
+
+#### 1-2. Org 에이전트 탐색
+선택된 Organization에서 에이전트를 검색합니다.
+`relay search <keyword>` 명령어를 실행합니다 (필요하면 여러 키워드로 반복).
+또는 `relay list --org <org-slug> --json`으로 전체 목록을 가져옵니다.
+
+검색 결과를 번호 리스트로 보여줍니다:
+
+```
+검색 결과 (3개)
+
+1. @alice/doc-writer — 기술 문서 자동화
+   /write-doc, /api-doc
+
+2. @bob/code-reviewer — PR 리뷰 자동화
+   /review, /suggest
+
+3. @carol/test-gen — 테스트 코드 생성
+   /gen-test, /coverage
+```
+
+**AskUserQuestion 호출:**
+- question: "어떤 에이전트를 설치할까요?"
+- options: `["1", "2", "3", "다시 검색", "돌아가기"]`
+
+"다시 검색" → 새 키워드로 1-2 반복
+"돌아가기" → 1-1로 돌아감
+번호 선택 → 해당 에이전트의 slug로 설치 진행
+
+#### 1-3. Org 에이전트 목록 (전체 보기)
+`relay list --org <org-slug> --json` 을 실행합니다.
+
+에이전트 목록을 번호 리스트로 보여줍니다 (1-2와 동일 형식).
+
+**AskUserQuestion 호출:**
+- question: "어떤 에이전트를 설치할까요?"
+- options: `["1", "2", ..., "돌아가기"]`
+
+"돌아가기" → 1-1로 돌아감
+번호 선택 → 해당 에이전트의 slug로 설치 진행
+
+### Step 2. 설치 & 배치 범위 선택
+
+#### 2-1. 패키지 다운로드
+`relay install <@org/agent> --json` 명령어를 실행합니다.
+- 공개 에이전트 (public): `relay install <@org/agent> --json`
+- 링크 공유 에이전트 (private): `relay install <slug> --json`
+  - 접근 권한이 없으면 CLI가 **purchase_info** (구매 안내 메시지 + URL)를 표시합니다.
+  - 접근 링크 코드가 있으면: `relay access <slug> --code <code>` 로 접근 부여 + 자동 설치를 한번에 수행합니다.
+  - Org 멤버이면 접근 확인 없이 바로 설치됩니다.
+- Org 전용 에이전트 (internal): `relay install @<org-slug>/<agent-slug> --json`
+  - Org 가입이 필요하면: `relay join <org-slug> --code <invite-code>` 를 먼저 실행합니다.
+  - 또는 `--join-code <code>`로 가입+설치를 한번에 할 수 있습니다.
+- CLI가 init과 login을 자동으로 처리합니다 (사용자가 별도 실행할 필요 없음).
+- JSON 출력에서 `install_path` (패키지 경로)를 확인합니다.
+
+**private 에이전트 접근 거부 처리:**
+- CLI가 403 + `GATED_ACCESS_REQUIRED` 에러를 반환하면:
+  1. purchase_info의 message와 url을 사용자에게 표시합니다.
+  2. "접근 링크 코드가 있으신가요?"라고 물어봅니다.
+  3. 코드가 있으면 `relay access <slug> --code <code>`를 실행합니다.
+  4. 코드가 없으면 purchase_info의 url로 구매 안내합니다.
+
+#### 2-2. 배치 범위 선택 (추천 포함)
+
+에이전트의 성격을 분석하여 글로벌/로컬 중 적합한 쪽을 추천합니다.
+
+**추천 로직:**
+- **글로벌 추천** — 범용 유틸리티 에이전트: 코드 리뷰, 문서 생성, 테스트, 번역 등 프로젝트에 무관하게 사용하는 도구성 에이전트
+- **로컬 추천** — 프로젝트 특화 에이전트: 특정 프레임워크/스택 전용, 프로젝트별 워크플로우, 팀 내부 컨벤션에 의존하는 에이전트
+
+판단 기준 (다운로드된 패키지의 relay.yaml과 콘텐츠를 분석):
+1. `tags`에 특정 프레임워크/스택 키워드가 있으면 (nextjs, supabase, react 등) → 로컬 추천
+2. `requires`에 프로젝트 종속 의존성이 있으면 (npm 패키지, 특정 파일 구조) → 로컬 추천
+3. rules/ 파일이 있으면 (프로젝트 컨벤션 주입) → 로컬 추천
+4. 범용 키워드 (utility, review, docs, testing 등) → 글로벌 추천
+5. 판단이 어려우면 → 글로벌 추천 (기본값)
+
+**AskUserQuestion 호출:**
+- question: "{추천 이유}. {추천}에 설치할까요?"
+- options: `["글로벌 (모든 프로젝트) ✓ 추천", "로컬 (이 프로젝트만)"]` 또는 `["글로벌 (모든 프로젝트)", "로컬 (이 프로젝트만) ✓ 추천"]`
+
+예시:
+- "범용 코드 리뷰 도구입니다. 글로벌에 설치할까요?" → `["글로벌 (모든 프로젝트) ✓ 추천", "로컬 (이 프로젝트만)"]`
+- "Next.js + Supabase 전용 에이전트입니다. 이 프로젝트에 설치할까요?" → `["글로벌 (모든 프로젝트)", "로컬 (이 프로젝트만) ✓ 추천"]`
+
+**응답 처리:**
+- "글로벌" → `~/.claude/`에 배치
+- "로컬" → 현재 프로젝트 `.claude/`에 배치
+
+#### 2-3. 에이전트 환경에 맞게 배치
+다운로드된 패키지(`install_path`)에서 파일을 읽고 선택된 범위에 배치합니다:
+- 글로벌: `<install_path>/commands/` → `~/.claude/commands/`에 복사, skills/ 동일
+- 로컬: `<install_path>/commands/` → `.claude/commands/`에 복사, skills/ 동일
+- agents/, rules/ 파일도 같은 방식으로 배치합니다.
+- **충돌 확인**: 같은 이름의 파일이 이미 있으면 사용자에게 덮어쓸지 물어봅니다.
+
+#### 2-4. 배치 정보 기록 (필수)
+배치 완료 후 반드시 `relay deploy-record`를 실행합니다:
+```
+relay deploy-record <slug> --scope <global|local> --files <배치된_파일1> <배치된_파일2> ...
+```
+
+{{REQUIREMENTS_CHECK}}
+{{ERROR_HANDLING_GUIDE}}
+
+### Step 3. 완료 & 팔로우 제안
+
+#### 3-1. 완료 안내
+- 배치된 파일과 활성화된 커맨드 목록을 보여줍니다.
+{{BUSINESS_CARD_FORMAT}}
+
+#### 3-2. 팔로우 제안 (필수 — 이 단계를 절대 건너뛰지 마세요)
+명함 표시 직후, 빌더의 username이 JSON 결과에 있으면 **반드시** AskUserQuestion 도구를 호출하세요.
+
+**AskUserQuestion 호출:**
+- question: `@{username}을 팔로우할까요? 새 버전 알림을 받을 수 있습니다.`
+- options: `["팔로우", "건너뛰기"]`
+
+**응답 처리:**
+- "팔로우" → `relay follow @{username}` 실행. 로그인이 안 되어 있으면 `relay login` 먼저 실행 후 재시도.
+- "건너뛰기" → 다음 단계로 진행
+
+#### 3-3. 공유 가이드 (필수 — 설치 완료 시 반드시 표시)
+설치 완료 후 아래 공유용 설치 가이드를 표시합니다. 복사 가능한 코드 블록으로 보여줍니다.
+
+```
+주변인에게 공유하세요:
+
+아래 가이드를 읽고 그대로 따라해줘:
+https://relayax.com/api/registry/{owner}/{slug}/guide.md
+```
+
+- `{slug}`가 `@owner/agent` 형식이면 `{owner}`과 `{slug}`를 분리하여 URL을 구성합니다.
+- CLI가 이미 설치된 사용자를 위한 짧은 버전도 함께 표시합니다: `/relay:relay-install {slug}`
+
+#### 3-4. 사용 제안
+- "바로 사용해볼까요?" 제안
+
+#### 3-5. 업데이트 확인
+- `relay check-update` 명령어를 실행합니다.
+- CLI 업데이트가 있으면 안내합니다: "relay v{new} available. Run: npm update -g relayax-cli"
+- 다른 에이전트 업데이트가 있으면 안내합니다.
+
+## 예시
+
+### 인터랙티브 모드 (/relay-install)
+→ relay orgs list --json 실행
+→ AskUserQuestion: "어디서 에이전트를 찾을까요?" → ["Alice's Org (alice)", "Acme Corp"]
+→ "Alice's Org" 선택 → "어떤 에이전트를 찾고 계세요?"
+→ relay search "문서" 실행 → 결과 리스트 표시
+→ AskUserQuestion: "어떤 에이전트를 설치할까요?" → ["1", "2", "3", "다시 검색"]
+→ "1" 선택 (@alice/doc-writer)
+→ AskUserQuestion: "어디에 설치할까요?" → ["글로벌 (모든 프로젝트)", "로컬 (이 프로젝트만)"]
+→ "글로벌" 선택
+→ 설치 + 배치 + deploy-record
+→ 명함 표시
+→ AskUserQuestion: "@alice을 팔로우할까요?" → ["팔로우", "건너뛰기"]
+→ "✓ 설치 완료! /write-doc를 사용해볼까요?"
+
+### 다이렉트 모드 (/relay-install @alice/doc-writer)
+→ relay install @alice/doc-writer --json 실행 (Step 1 건너뜀)
+→ AskUserQuestion: "어디에 설치할까요?" → ["글로벌 (모든 프로젝트)", "로컬 (이 프로젝트만)"]
+→ 설치 + 배치 + deploy-record
+→ 명함 표시
+→ AskUserQuestion: "@alice을 팔로우할까요?" → ["팔로우", "건너뛰기"]
+→ "✓ 설치 완료! /write-doc를 사용해볼까요?"