relayax-cli 0.2.38 → 0.2.40

package/dist/commands/access.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerAccess(program: Command): void;

package/dist/commands/access.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAccess = registerAccess;
+const commander_1 = require("commander");
+const config_js_1 = require("../lib/config.js");
+async function claimAccess(slug, code) {
+    const token = await (0, config_js_1.getValidToken)();
+    if (!token) {
+        throw new Error('LOGIN_REQUIRED');
+    }
+    const res = await fetch(`${config_js_1.API_URL}/api/teams/${slug}/claim-access`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ code }),
+        signal: AbortSignal.timeout(10000),
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok) {
+        const errCode = body.error ?? String(res.status);
+        switch (errCode) {
+            case 'INVALID_LINK':
+                throw new Error('초대 링크가 유효하지 않거나 만료되었습니다.');
+            case 'NOT_FOUND':
+                throw new Error('팀을 찾을 수 없습니다.');
+            case 'UNAUTHORIZED':
+                throw new Error('LOGIN_REQUIRED');
+            default:
+                throw new Error(body.message ?? `접근 권한 요청 실패 (${res.status})`);
+        }
+    }
+    return body;
+}
+function registerAccess(program) {
+    program
+        .command('access <slug>')
+        .description('초대 코드로 팀에 접근 권한을 얻고 바로 설치합니다')
+        .requiredOption('--code <code>', '팀 초대 코드')
+        .action(async (slug, opts) => {
+        const json = program.opts().json ?? false;
+        try {
+            const result = await claimAccess(slug, opts.code);
+            if (!result.success || !result.team) {
+                throw new Error('서버 응답이 올바르지 않습니다.');
+            }
+            const teamSlug = result.team.slug;
+            if (json) {
+                console.log(JSON.stringify({ status: 'ok', team: result.team }));
+            }
+            else {
+                console.log(`\x1b[32m접근 권한이 부여되었습니다: ${result.team.name}\x1b[0m`);
+                console.log(`\x1b[33m팀을 설치합니다: relay install ${teamSlug}\x1b[0m\n`);
+            }
+            // Automatically install the team
+            const { registerInstall } = await import('./install.js');
+            const subProgram = new commander_1.Command();
+            subProgram.option('--json', '구조화된 JSON 출력');
+            if (json)
+                subProgram.setOptionValue('json', true);
+            registerInstall(subProgram);
+            await subProgram.parseAsync(['node', 'relay', 'install', teamSlug]);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message === 'LOGIN_REQUIRED') {
+                if (json) {
+                    console.error(JSON.stringify({
+                        error: 'LOGIN_REQUIRED',
+                        message: '로그인이 필요합니다. relay login을 먼저 실행하세요.',
+                        fix: 'relay login 실행 후 재시도하세요.',
+                    }));
+                }
+                else {
+                    console.error('\x1b[31m오류: 로그인이 필요합니다.\x1b[0m');
+                    console.error('  relay login을 먼저 실행하세요.');
+                }
+                process.exit(1);
+            }
+            if (json) {
+                console.error(JSON.stringify({ error: 'ACCESS_FAILED', message, fix: '접근 링크 코드를 확인하거나 팀 제작자에게 문의하세요.' }));
+            }
+            else {
+                console.error(`\x1b[31m오류: ${message}\x1b[0m`);
+            }
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/create.js

@@ -24,7 +24,10 @@ function registerCreate(program) {
     program
         .command('create <name>')
         .description('새 에이전트 팀 프로젝트를 생성합니다')
-        .action(async (name) => {
+        .option('--description <desc>', '팀 설명')
+        .option('--tags <tags>', '태그 (쉼표 구분)')
+        .option('--visibility <visibility>', '공개 범위 (public, gated, private)')
+        .action(async (name, opts) => {
         const json = program.opts().json ?? false;
         const projectPath = process.cwd();
         const relayDir = path_1.default.join(projectPath, '.relay');
@@ -33,7 +36,7 @@ function registerCreate(program) {
         // 1. .relay/relay.yaml 이미 존재하면 에러
         if (fs_1.default.existsSync(relayYamlPath)) {
             if (json) {
-                console.error(JSON.stringify({ error: 'ALREADY_EXISTS', message: '.relay/relay.yaml이 이미 존재합니다.' }));
+                console.error(JSON.stringify({ error: 'ALREADY_EXISTS', message: '.relay/relay.yaml이 이미 존재합니다.', fix: '기존 .relay/relay.yaml을 확인하세요. 새로 시작하려면 삭제 후 재시도.' }));
             }
             else {
                 console.error('.relay/relay.yaml이 이미 존재합니다. 기존 팀 프로젝트에서는 `relay init`을 사용하세요.');
@@ -42,28 +45,73 @@ function registerCreate(program) {
         }
         // 2. 메타데이터 수집
         const defaultSlug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
-        let description = '';
-        let tags = [];
-        let visibility = 'public';
-        if (isTTY) {
+        let description = opts.description ?? '';
+        let tags = opts.tags ? opts.tags.split(',').map((t) => t.trim()).filter(Boolean) : [];
+        let visibility = opts.visibility ?? 'public';
+        if (json) {
+            // --json 모드: 필수 값 부족 시 에러 반환 (프롬프트 없음)
+            if (!opts.description) {
+                console.error(JSON.stringify({
+                    error: 'MISSING_FIELD',
+                    message: '팀 설명이 필요합니다.',
+                    fix: `relay create ${name} --description <설명> --json`,
+                    field: 'description',
+                }));
+                process.exit(1);
+            }
+            if (!opts.visibility) {
+                console.error(JSON.stringify({
+                    error: 'MISSING_VISIBILITY',
+                    message: '공개 범위를 선택하세요.',
+                    fix: `relay create ${name} --description "${description}" --visibility <visibility> --json`,
+                    options: [
+                        { value: 'public', label: '공개 — 누구나 설치' },
+                        { value: 'gated', label: '링크 공유 — 접근 링크가 있는 사람만' },
+                        { value: 'private', label: '비공개 — Space 멤버만' },
+                    ],
+                }));
+                process.exit(1);
+            }
+            if (!['public', 'gated', 'private'].includes(opts.visibility)) {
+                console.error(JSON.stringify({
+                    error: 'INVALID_FIELD',
+                    message: `유효하지 않은 visibility 값: ${opts.visibility}`,
+                    fix: `visibility는 public, gated, private 중 하나여야 합니다.`,
+                    options: [
+                        { value: 'public', label: '공개' },
+                        { value: 'gated', label: '링크 공유' },
+                        { value: 'private', label: '비공개' },
+                    ],
+                }));
+                process.exit(1);
+            }
+        }
+        else if (isTTY) {
             const { input: promptInput, select: promptSelect } = await import('@inquirer/prompts');
             console.log(`\n  \x1b[33m⚡\x1b[0m \x1b[1mrelay create\x1b[0m — 새 팀 프로젝트\n`);
-            description = await promptInput({
-                message: '팀 설명:',
-                validate: (v) => v.trim().length > 0 ? true : '설명을 입력해주세요.',
-            });
-            const tagsRaw = await promptInput({
-                message: '태그 (쉼표로 구분, 선택):',
-                default: '',
-            });
-            tags = tagsRaw.split(',').map((t) => t.trim()).filter(Boolean);
-            visibility = await promptSelect({
-                message: '공개 범위:',
-                choices: [
-                    { name: '공개', value: 'public' },
-                    { name: '비공개 (Space 멤버만)', value: 'private' },
-                ],
-            });
+            if (!description) {
+                description = await promptInput({
+                    message: '팀 설명:',
+                    validate: (v) => v.trim().length > 0 ? true : '설명을 입력해주세요.',
+                });
+            }
+            if (!opts.tags) {
+                const tagsRaw = await promptInput({
+                    message: '태그 (쉼표로 구분, 선택):',
+                    default: '',
+                });
+                tags = tagsRaw.split(',').map((t) => t.trim()).filter(Boolean);
+            }
+            if (!opts.visibility) {
+                visibility = await promptSelect({
+                    message: '공개 범위:',
+                    choices: [
+                        { name: '공개', value: 'public' },
+                        { name: '링크 공유 (접근 링크 필요)', value: 'gated' },
+                        { name: '비공개 (Space 멤버만)', value: 'private' },
+                    ],
+                });
+            }
         }
         // 3. .relay/relay.yaml 생성
         fs_1.default.mkdirSync(relayDir, { recursive: true });

package/dist/commands/follow.js

@@ -15,7 +15,7 @@ function registerFollow(program) {
         if (!token) {
             const msg = '로그인이 필요합니다. `relay login`을 먼저 실행하세요.';
             if (json) {
-                console.log(JSON.stringify({ error: 'NO_TOKEN', message: msg }));
+                console.log(JSON.stringify({ error: 'NO_TOKEN', message: msg, fix: 'relay login 실행 후 재시도하세요.' }));
             }
             else {
                 console.error(msg);
@@ -34,7 +34,7 @@ function registerFollow(program) {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             if (json) {
-                console.log(JSON.stringify({ error: 'FOLLOW_FAILED', message }));
+                console.log(JSON.stringify({ error: 'FOLLOW_FAILED', message, fix: 'username을 확인하거나 잠시 후 재시도하세요.' }));
             }
             else {
                 console.error(`팔로우 실패: ${message}`);

package/dist/commands/init.js

@@ -121,16 +121,31 @@ function registerInit(program) {
     program
         .command('init')
         .description('에이전트 CLI에 relay 슬래시 커맨드를 설치합니다')
-        .option('--tools <tools>', '설치할 에이전트 CLI 지정 (all 또는 쉼표 구분)')
+        .option('--tools <tools>', '설치할 에이전트 CLI 지정 (쉼표 구분)')
+        .option('--all', '감지된 모든 에이전트 CLI에 설치')
         .option('--auto', '대화형 프롬프트 없이 자동으로 모든 감지된 CLI에 설치')
         .action(async (opts) => {
         const json = program.opts().json ?? false;
-        // auto mode: --auto flag, --json flag, or stdin is not a TTY
-        const autoMode = opts.auto === true || json || !process.stdin.isTTY;
+        // auto mode: --auto flag, --all flag, or stdin is not a TTY (but NOT --json alone)
+        const autoMode = opts.auto === true || opts.all === true || !process.stdin.isTTY;
         const projectPath = process.cwd();
         const detected = (0, ai_tools_js_1.detectAgentCLIs)(projectPath);
         const detectedIds = new Set(detected.map((t) => t.value));
         const isBuilder = isTeamProject(projectPath);
+        // ── 0. --json 모드에서 --tools/--all 없으면 MISSING_TOOLS 에러 ──
+        if (json && !opts.tools && !opts.all && !opts.auto) {
+            const detectedOptions = detected.map((t) => ({ value: t.value, label: t.name }));
+            if (detectedOptions.length === 0) {
+                detectedOptions.push(...ai_tools_js_1.AI_TOOLS.slice(0, 5).map((t) => ({ value: t.value, label: t.name })));
+            }
+            console.error(JSON.stringify({
+                error: 'MISSING_TOOLS',
+                message: '설치할 에이전트 CLI를 선택하세요.',
+                fix: `relay init --tools <도구1,도구2> --json 또는 relay init --all --json`,
+                options: detectedOptions,
+            }));
+            process.exit(1);
+        }
         // ── 1. 글로벌 User 커맨드 설치 ──
         let globalStatus = 'already';
         let globalTools = [];

package/dist/commands/install.js

@@ -15,18 +15,21 @@ const preamble_js_1 = require("../lib/preamble.js");
 const join_js_1 = require("./join.js");
 const init_js_1 = require("./init.js");
 /**
- * slugInput이 "@spaces/{spaceSlug}/{teamSlug}" 형식이면 파싱해 반환.
+ * slugInput이 "@spaces/{spaceSlug}/{teamSlug}" 또는 "@{spaceSlug}/{teamSlug}" 형식이면 파싱해 반환.
  * 아니면 null.
  */
 function parseSpaceTarget(slugInput) {
-    const m = slugInput.match(/^@spaces\/([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
-    if (!m)
-        return null;
-    return {
-        spaceSlug: m[1],
-        rawTeamSlug: m[2],
-        teamSlug: `@${m[1]}/${m[2]}`,
-    };
+    // @spaces/{spaceSlug}/{teamSlug} 형식 (기존)
+    const m1 = slugInput.match(/^@spaces\/([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
+    if (m1) {
+        return { spaceSlug: m1[1], rawTeamSlug: m1[2], teamSlug: `@${m1[1]}/${m1[2]}` };
+    }
+    // @{spaceSlug}/{teamSlug} 형식 (신규)
+    const m2 = slugInput.match(/^@([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)$/);
+    if (m2) {
+        return { spaceSlug: m2[1], rawTeamSlug: m2[2], teamSlug: `@${m2[1]}/${m2[2]}` };
+    }
+    return null;
 }
 function registerInstall(program) {
     program
@@ -69,20 +72,29 @@ function registerInstall(program) {
             let team;
             let slug;
             let parsed;
+            // Whether the spaceTarget was matched via the ambiguous @{slug}/{team} pattern
+            // (i.e. NOT the explicit @spaces/... prefix). Used for 404 fallback below.
+            const isAmbiguousSpaceTarget = spaceTarget !== null && !slugInput.startsWith('@spaces/');
             if (spaceTarget) {
                 // Space 팀: POST /api/spaces/{spaceSlug}/teams/{teamSlug}/install
                 // This verifies membership, increments install count, and returns metadata.
+                let usedSpacePath = true;
                 try {
                     team = await (0, api_js_1.installSpaceTeam)(spaceTarget.spaceSlug, spaceTarget.rawTeamSlug);
                 }
                 catch (fetchErr) {
                     const fetchMsg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
-                    if (fetchMsg.includes('403')) {
+                    if (fetchMsg.includes('404') && isAmbiguousSpaceTarget) {
+                        // Space not found — @{owner}/{team} is actually a normal registry slug, fall back
+                        usedSpacePath = false;
+                    }
+                    else if (fetchMsg.includes('403')) {
                         if (json) {
                             console.error(JSON.stringify({
                                 error: 'SPACE_ONLY',
                                 message: '이 팀은 Space 멤버만 설치 가능합니다.',
                                 spaceSlug: spaceTarget.spaceSlug,
+                                fix: `relay join ${spaceTarget.spaceSlug} --code <초대코드>로 Space에 가입한 후 재시도하세요.`,
                             }));
                         }
                         else {
@@ -91,11 +103,22 @@ function registerInstall(program) {
                         }
                         process.exit(1);
                     }
-                    throw fetchErr;
+                    else {
+                        throw fetchErr;
+                    }
+                }
+                if (!usedSpacePath) {
+                    // Fallback: treat as normal registry install
+                    parsed = await (0, slug_js_1.resolveSlug)(slugInput);
+                    slug = parsed.full;
+                    team = await (0, api_js_1.fetchTeamInfo)(slug);
+                }
+                else {
+                    // slug from server is "@spaces/{spaceSlug}/{teamSlug}" — derive local path parts
+                    // team is guaranteed assigned by installSpaceTeam above (usedSpacePath === true)
+                    parsed = { owner: spaceTarget.spaceSlug, name: spaceTarget.rawTeamSlug, full: team.slug };
+                    slug = team.slug;
                 }
-                // slug from server is "@spaces/{spaceSlug}/{teamSlug}" — derive local path parts
-                parsed = { owner: spaceTarget.spaceSlug, name: spaceTarget.rawTeamSlug, full: team.slug };
-                slug = team.slug;
             }
             else {
                 // Normal registry install
@@ -107,15 +130,44 @@ function registerInstall(program) {
                 catch (fetchErr) {
                     const fetchMsg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
                     if (fetchMsg.includes('403')) {
-                        // Parse join_policy and membership_status from error body if available
+                        // Parse error body for join_policy, membership_status, visibility, purchase_info
                         let joinPolicy;
                         let membershipStatus;
+                        let errorVisibility;
+                        let purchaseInfo;
                         try {
                             const errBody = JSON.parse(fetchMsg.replace(/^.*?(\{)/, '{'));
                             joinPolicy = typeof errBody.join_policy === 'string' ? errBody.join_policy : undefined;
                             membershipStatus = typeof errBody.membership_status === 'string' ? errBody.membership_status : undefined;
+                            errorVisibility = typeof errBody.visibility === 'string' ? errBody.visibility : undefined;
+                            if (errBody.purchase_info && typeof errBody.purchase_info === 'object') {
+                                purchaseInfo = errBody.purchase_info;
+                            }
                         }
                         catch { /* ignore parse errors */ }
+                        // Gated team: show purchase info + relay access hint
+                        if (errorVisibility === 'gated' || purchaseInfo) {
+                            if (json) {
+                                console.error(JSON.stringify({
+                                    error: 'GATED_ACCESS_REQUIRED',
+                                    message: '이 팀은 접근 권한이 필요합니다.',
+                                    slug,
+                                    purchase_info: purchaseInfo ?? null,
+                                    fix: '접근 링크 코드가 있으면: relay access <slug> --code <코드>',
+                                }));
+                            }
+                            else {
+                                console.error('\x1b[31m🔒 이 팀은 접근 권한이 필요합니다.\x1b[0m');
+                                if (purchaseInfo?.message) {
+                                    console.error(`\n  \x1b[36m${purchaseInfo.message}\x1b[0m`);
+                                }
+                                if (purchaseInfo?.url) {
+                                    console.error(`  \x1b[36m${purchaseInfo.url}\x1b[0m`);
+                                }
+                                console.error(`\n\x1b[33m접근 링크 코드가 있으면: relay access ${slugInput} --code <코드>\x1b[0m`);
+                            }
+                            process.exit(1);
+                        }
                         if (joinPolicy === 'auto') {
                             // Auto-join the Space then retry install
                             if (!json) {
@@ -132,7 +184,7 @@ function registerInstall(program) {
                             catch (joinErr) {
                                 const joinMsg = joinErr instanceof Error ? joinErr.message : String(joinErr);
                                 if (json) {
-                                    console.error(JSON.stringify({ error: 'JOIN_FAILED', message: joinMsg, slug }));
+                                    console.error(JSON.stringify({ error: 'JOIN_FAILED', message: joinMsg, slug, fix: 'Space slug와 초대 코드를 확인 후 재시도하세요.' }));
                                 }
                                 else {
                                     console.error(`\x1b[31mSpace 가입 실패: ${joinMsg}\x1b[0m`);
@@ -145,9 +197,10 @@ function registerInstall(program) {
                             if (json) {
                                 console.error(JSON.stringify({
                                     error: 'APPROVAL_REQUIRED',
-                                    message: `가입 신청이 필요합니다. \`relay join @${spaceSlug}\`로 가입하세요.`,
+                                    message: `가입 신청이 필요합니다.`,
                                     slug,
                                     spaceSlug,
+                                    fix: `relay join @${spaceSlug} --code <초대코드>로 Space에 가입한 후 재시도하세요. 초대 코드는 Space 관리자에게 요청하세요.`,
                                 }));
                             }
                             else {
@@ -162,6 +215,7 @@ function registerInstall(program) {
                                     error: 'NO_ACCESS',
                                     message: '이 팀에 대한 접근 권한이 없습니다.',
                                     slug,
+                                    fix: '이 팀의 접근 링크 코드가 있으면 `relay access ' + slugInput + ' --code <코드>`로 접근 권한을 얻으세요. 없으면 팀 제작자에게 문의하세요.',
                                 }));
                             }
                             else {
@@ -175,6 +229,7 @@ function registerInstall(program) {
                                     error: 'SPACE_ONLY',
                                     message: '이 팀은 Space 멤버만 설치 가능합니다.',
                                     slug,
+                                    fix: 'Space 관리자에게 초대 코드를 요청한 후 `relay join <space-slug> --code <코드>`로 가입하세요.',
                                 }));
                             }
                             else {
@@ -189,6 +244,8 @@ function registerInstall(program) {
                     }
                 }
             }
+            if (!team)
+                throw new Error('팀 정보를 가져오지 못했습니다.');
             const teamDir = path_1.default.join(projectPath, '.relay', 'teams', parsed.owner, parsed.name);
             // 2. Visibility check + auto-login
             const visibility = team.visibility ?? 'public';
@@ -210,6 +267,7 @@ function registerInstall(program) {
                                 visibility,
                                 slug,
                                 message: '이 팀은 로그인이 필요합니다. relay login을 먼저 실행하세요.',
+                                fix: 'relay login 실행 후 재시도하세요.',
                             }));
                         }
                         else {
@@ -219,8 +277,30 @@ function registerInstall(program) {
                     }
                 }
             }
-            // 3. Download package
-            const tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+            // 3. Download package (retry once if signed URL expired)
+            let tarPath;
+            try {
+                tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+            }
+            catch (dlErr) {
+                const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
+                if (dlMsg.includes('403') || dlMsg.includes('expired')) {
+                    // Signed URL expired — re-fetch team info for new URL and retry
+                    if (!json) {
+                        console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
+                    }
+                    if (spaceTarget) {
+                        team = await (0, api_js_1.installSpaceTeam)(spaceTarget.spaceSlug, spaceTarget.rawTeamSlug);
+                    }
+                    else {
+                        team = await (0, api_js_1.fetchTeamInfo)(slug);
+                    }
+                    tarPath = await (0, storage_js_1.downloadPackage)(team.package_url, tempDir);
+                }
+                else {
+                    throw dlErr;
+                }
+            }
             // 4. Extract to .relay/teams/<slug>/
             if (fs_1.default.existsSync(teamDir)) {
                 fs_1.default.rmSync(teamDir, { recursive: true, force: true });
@@ -326,7 +406,7 @@ function registerInstall(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(JSON.stringify({ error: 'INSTALL_FAILED', message }));
+            console.error(JSON.stringify({ error: 'INSTALL_FAILED', message, fix: message }));
             process.exit(1);
         }
         finally {

package/dist/commands/join.js

@@ -57,7 +57,7 @@ function registerJoin(program) {
                 console.error('\x1b[33m⚠ relay init이 실행되지 않았습니다. 먼저 relay init을 실행하세요.\x1b[0m');
             }
             else {
-                console.error(JSON.stringify({ error: 'NOT_INITIALIZED', message: 'relay init을 먼저 실행하세요.' }));
+                console.error(JSON.stringify({ error: 'NOT_INITIALIZED', message: 'relay init을 먼저 실행하세요.', fix: 'relay init 실행하세요.' }));
             }
             process.exit(1);
         }
@@ -92,7 +92,8 @@ function registerJoin(program) {
                                 const desc = t.description ? `  \x1b[90m— ${t.description}\x1b[0m` : '';
                                 console.log(`  \x1b[36m•\x1b[0m \x1b[1m${t.slug}\x1b[0m${desc}`);
                             }
-                            console.log(`\n\x1b[33m💡 설치: relay install @spaces/${slug}/<팀슬러그>\x1b[0m`);
+                            console.log(`\n\x1b[33m💡 전체 설치: relay install @spaces/${slug}/<팀슬러그>\x1b[0m`);
+                            console.log(`\x1b[33m💡 가이드 URL 공유: https://relayax.com/api/spaces/${slug}/guide.md\x1b[0m`);
                         }
                     }
                 }
@@ -117,6 +118,7 @@ function registerJoin(program) {
                     console.error(JSON.stringify({
                         error: 'LOGIN_REQUIRED',
                         message: '로그인이 필요합니다. relay login 을 먼저 실행하세요.',
+                        fix: 'relay login 실행 후 재시도하세요.',
                     }));
                 }
                 else {
@@ -126,7 +128,7 @@ function registerJoin(program) {
                 process.exit(1);
             }
             if (json) {
-                console.error(JSON.stringify({ error: 'JOIN_FAILED', message }));
+                console.error(JSON.stringify({ error: 'JOIN_FAILED', message, fix: 'Space slug와 초대 코드를 확인 후 재시도하세요.' }));
             }
             else {
                 console.error(`\x1b[31m오류: ${message}\x1b[0m`);

package/dist/commands/list.js

@@ -29,7 +29,7 @@ function registerList(program) {
             const token = await (0, config_js_1.getValidToken)();
             if (!token) {
                 if (json) {
-                    console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.' }));
+                    console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.', fix: 'relay login 실행 후 재시도하세요.' }));
                 }
                 else {
                     console.error('\x1b[31m오류: 로그인이 필요합니다.\x1b[0m');
@@ -59,7 +59,7 @@ function registerList(program) {
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
                 if (json) {
-                    console.error(JSON.stringify({ error: 'FETCH_FAILED', message }));
+                    console.error(JSON.stringify({ error: 'FETCH_FAILED', message, fix: '네트워크 연결을 확인하거나 잠시 후 재시도하세요.' }));
                 }
                 else {
                     console.error(`\x1b[31m오류: ${message}\x1b[0m`);

package/dist/commands/login.js

@@ -148,7 +148,7 @@ function registerLogin(program) {
             catch (err) {
                 const msg = err instanceof Error ? err.message : '로그인 실패';
                 if (json) {
-                    console.error(JSON.stringify({ error: 'LOGIN_FAILED', message: msg }));
+                    console.error(JSON.stringify({ error: 'LOGIN_FAILED', message: msg, fix: '브라우저에서 로그인을 완료하고 relay login을 재시도하세요.' }));
                 }
                 else {
                     console.error(`\x1b[31m오류: ${msg}\x1b[0m`);

package/dist/commands/publish.js

@@ -24,8 +24,9 @@ function parseRelayYaml(content) {
     const requires = raw.requires;
     const rawVisibility = String(raw.visibility ?? '');
     const visibility = rawVisibility === 'private' ? 'private'
-        : rawVisibility === 'public' ? 'public'
-            : undefined;
+        : rawVisibility === 'gated' ? 'gated'
+            : rawVisibility === 'public' ? 'public'
+                : undefined;
     const rawType = String(raw.type ?? '');
     const type = rawType === 'command' ? 'command'
         : rawType === 'passive' ? 'passive'
@@ -281,6 +282,8 @@ function registerPublish(program) {
         .command('publish')
         .description('현재 팀 패키지를 Space에 배포합니다 (relay.yaml 필요)')
         .option('--token <token>', '인증 토큰')
+        .option('--space <slug>', '배포할 Space 지정')
+        .option('--version <version>', '배포 버전 지정 (relay.yaml 업데이트)')
         .action(async (opts) => {
         const json = program.opts().json ?? false;
         const teamDir = process.cwd();
@@ -317,6 +320,7 @@ function registerPublish(program) {
                 console.error(JSON.stringify({
                     error: 'NOT_INITIALIZED',
                     message: '.relay/relay.yaml이 없습니다. 먼저 `relay create`를 실행하세요.',
+                    fix: 'relay create 또는 .relay/relay.yaml을 생성하세요.',
                 }));
                 process.exit(1);
             }
@@ -345,12 +349,16 @@ function registerPublish(program) {
             const visibility = await promptSelect({
                 message: '공개 범위:',
                 choices: [
-                    { name: '공개', value: 'public' },
-                    { name: '비공개 (Space 멤버만)', value: 'private' },
+                    { name: '공개 — 누구나 설치', value: 'public' },
+                    { name: '링크 공유 — 접근 링크가 있는 사람만 설치', value: 'gated' },
+                    { name: '비공개 — Space 멤버만', value: 'private' },
                 ],
             });
             console.error('\n\x1b[2m💡 프로필에 연락처를 설정하면 설치 시 명함이 전달됩니다: www.relayax.com/dashboard/profile\x1b[0m');
-            if (visibility === 'private') {
+            if (visibility === 'gated') {
+                console.error('\x1b[2m💡 링크 공유 팀은 웹 대시보드에서 접근 링크와 구매 안내를 설정하세요: www.relayax.com/dashboard\x1b[0m');
+            }
+            else if (visibility === 'private') {
                 console.error('\x1b[2m💡 비공개 팀은 Space를 통해 멤버를 관리하세요: www.relayax.com/dashboard/teams\x1b[0m');
             }
             console.error('');
@@ -377,11 +385,18 @@ function registerPublish(program) {
             console.error(JSON.stringify({
                 error: 'INVALID_CONFIG',
                 message: 'relay.yaml에 name, slug, description이 필요합니다.',
+                fix: 'relay.yaml에 name, slug, description을 확인하세요.',
             }));
             process.exit(1);
         }
-        // Version bump suggestion for republishing
-        if (isTTY) {
+        // Version bump: --version flag takes priority
+        if (opts.version) {
+            config.version = opts.version;
+            const yamlData = js_yaml_1.default.load(fs_1.default.readFileSync(relayYamlPath, 'utf-8'));
+            yamlData.version = opts.version;
+            fs_1.default.writeFileSync(relayYamlPath, js_yaml_1.default.dump(yamlData, { lineWidth: 120 }), 'utf-8');
+        }
+        else if (isTTY) {
             const { select: promptVersion } = await import('@inquirer/prompts');
             const [major, minor, patch] = config.version.split('.').map(Number);
             const bumpPatch = `${major}.${minor}.${patch + 1}`;
@@ -415,6 +430,7 @@ function registerPublish(program) {
             console.error(JSON.stringify({
                 error: 'EMPTY_PACKAGE',
                 message: '.relay/ 안에 skills/, agents/, rules/, commands/ 중 하나 이상에 파일이 있어야 합니다.',
+                fix: '.relay/ 안에 skills/, agents/, rules/, commands/ 중 하나에 파일을 추가하세요.',
             }));
             process.exit(1);
         }
@@ -424,71 +440,110 @@ function registerPublish(program) {
             console.error(JSON.stringify({
                 error: 'NO_TOKEN',
                 message: '인증이 필요합니다. `relay login`을 먼저 실행하세요.',
+                fix: 'relay login 실행 후 재시도하세요.',
             }));
             process.exit(1);
         }
         // Fetch user's Spaces and select publish target
         let selectedSpaceId;
-        let selectedSpaceIsPersonal = true;
+        let selectedSpaceSlug;
+        let selectedJoinPolicy;
         try {
             const { fetchMySpaces } = await import('./spaces.js');
             const spaces = await fetchMySpaces(token);
-            const personalSpace = spaces.find((s) => s.is_personal);
-            const teamSpaces = spaces.filter((s) => !s.is_personal);
-            if (isTTY) {
+            // --space flag: resolve Space by slug
+            if (opts.space) {
+                const matched = spaces.find((s) => s.slug === opts.space);
+                if (matched) {
+                    selectedSpaceId = matched.id;
+                    selectedSpaceSlug = matched.slug;
+                    selectedJoinPolicy = matched.join_policy;
+                }
+                else {
+                    if (json) {
+                        console.error(JSON.stringify({
+                            error: 'INVALID_SPACE',
+                            message: `Space '${opts.space}'를 찾을 수 없습니다.`,
+                            fix: `사용 가능한 Space: ${spaces.map((s) => s.slug).join(', ')}`,
+                            options: spaces.map((s) => ({ value: s.slug, label: `${s.name} (${s.slug})` })),
+                        }));
+                    }
+                    else {
+                        console.error(`Space '${opts.space}'를 찾을 수 없습니다.`);
+                    }
+                    process.exit(1);
+                }
+            }
+            else if (isTTY) {
                 if (spaces.length === 0) {
                     // No spaces at all — publish without space_id
                     console.error('\x1b[33m⚠ 소속 Space가 없습니다. 개인 계정으로 배포합니다.\x1b[0m\n');
                 }
-                else if (spaces.length === 1 && personalSpace) {
-                    // Only personal Space — auto-select
-                    selectedSpaceId = personalSpace.id;
-                    selectedSpaceIsPersonal = true;
-                    console.error(`\x1b[2m  Space: 개인 스페이스 (${personalSpace.slug})\x1b[0m\n`);
+                else if (spaces.length === 1) {
+                    // Only one Space — auto-select regardless of type
+                    selectedSpaceId = spaces[0].id;
+                    selectedSpaceSlug = spaces[0].slug;
+                    selectedJoinPolicy = spaces[0].join_policy;
+                    console.error(`\x1b[2m  Space: ${spaces[0].name} (${spaces[0].slug})\x1b[0m\n`);
                 }
                 else {
                     // Multiple spaces — prompt user
                     const { select: selectSpace } = await import('@inquirer/prompts');
-                    const spaceChoices = [
-                        ...(personalSpace ? [{ name: `개인 스페이스 (${personalSpace.slug})`, value: personalSpace.id, isPersonal: true }] : []),
-                        ...teamSpaces.map((s) => ({ name: `${s.name} (${s.slug})`, value: s.id, isPersonal: false })),
-                    ];
+                    const spaceChoices = spaces.map((s) => ({
+                        name: `${s.name} (${s.slug})`,
+                        value: s.id,
+                        slug: s.slug,
+                        join_policy: s.join_policy,
+                    }));
                     const chosenId = await selectSpace({
                         message: '어떤 Space에 배포할까요?',
                         choices: spaceChoices.map((c) => ({ name: c.name, value: c.value })),
                     });
                     const chosen = spaceChoices.find((c) => c.value === chosenId);
                     selectedSpaceId = chosenId;
-                    selectedSpaceIsPersonal = chosen?.isPersonal ?? false;
+                    selectedSpaceSlug = chosen?.slug;
+                    selectedJoinPolicy = chosen?.join_policy;
                     const chosenLabel = chosen?.name ?? chosenId;
                     console.error(`  → Space: ${chosenLabel}\n`);
                 }
             }
-            else if (personalSpace) {
-                selectedSpaceId = personalSpace.id;
-                selectedSpaceIsPersonal = true;
+            else if (spaces.length > 1 && json) {
+                // --json 모드 + 여러 Space: 에이전트가 선택할 수 있도록 에러 반환
+                console.error(JSON.stringify({
+                    error: 'MISSING_SPACE',
+                    message: '배포할 Space를 선택하세요.',
+                    fix: `relay publish --space <slug> --json`,
+                    options: spaces.map((s) => ({ value: s.slug, label: `${s.name} (${s.slug})` })),
+                }));
+                process.exit(1);
+            }
+            else if (spaces.length > 0) {
+                selectedSpaceId = spaces[0].id;
+                selectedSpaceSlug = spaces[0].slug;
+                selectedJoinPolicy = spaces[0].join_policy;
             }
         }
         catch {
             // Space 조회 실패 시 무시하고 계속 진행
         }
-        // Visibility default based on Space type: personal → public, team Space → private
-        const defaultVisibility = selectedSpaceIsPersonal ? 'public' : 'private';
-        const defaultVisLabel = defaultVisibility === 'public'
-            ? '공개 (개인 Space 기본값)'
-            : '비공개 (팀 Space 기본값)';
+        // Visibility default based on join_policy: approval → private, otherwise → public
+        const defaultVisibility = selectedJoinPolicy === 'approval' ? 'private' : 'public';
         // Visibility validation: must be explicitly set
         if (!config.visibility) {
             if (isTTY) {
                 const { select: promptSelect } = await import('@inquirer/prompts');
-                console.error(`\n\x1b[33m⚠ relay.yaml에 visibility가 설정되지 않았습니다.\x1b[0m  (기본값: ${defaultVisLabel})`);
+                console.error(`\n\x1b[33m⚠ relay.yaml에 visibility가 설정되지 않았습니다.\x1b[0m  (기본값: ${defaultVisibility === 'public' ? '공개' : '비공개'})`);
                 config.visibility = await promptSelect({
                     message: '공개 범위를 선택하세요:',
                     choices: [
                         {
-                            name: `공개 — Space에 누구나 검색·설치${defaultVisibility === 'public' ? '  ✓ 추천' : ''}`,
+                            name: `공개 — 누구나 설치${defaultVisibility === 'public' ? '  ✓ 추천' : ''}`,
                             value: 'public',
                         },
+                        {
+                            name: '링크 공유 — 접근 링크가 있는 사람만 설치',
+                            value: 'gated',
+                        },
                         {
                             name: `비공개 — Space 멤버만 접근${defaultVisibility === 'private' ? '  ✓ 추천' : ''}`,
                             value: 'private',
@@ -505,7 +560,13 @@ function registerPublish(program) {
             else {
                 console.error(JSON.stringify({
                     error: 'MISSING_VISIBILITY',
-                    message: 'relay.yaml에 visibility (public 또는 private)를 설정해주세요.',
+                    message: 'relay.yaml에 visibility를 설정해주세요.',
+                    options: [
+                        { value: 'public', label: '공개 — 누구나 설치' },
+                        { value: 'gated', label: '링크 공유 — 접근 링크가 있는 사람만 설치' },
+                        { value: 'private', label: '비공개 — Space 멤버만 접근' },
+                    ],
+                    fix: 'relay.yaml의 visibility 필드를 위 옵션 중 하나로 설정하세요.',
                 }));
                 process.exit(1);
             }
@@ -513,23 +574,36 @@ function registerPublish(program) {
         // Confirm visibility before publish (재배포 시 변경 기회 제공)
         if (isTTY) {
             const { select: promptConfirmVis } = await import('@inquirer/prompts');
-            const visLabel = config.visibility === 'public'
-                ? `\x1b[32m공개\x1b[0m (Space에 누구나 검색·설치)${defaultVisibility === 'public' ? '  ✓ 추천' : ''}`
-                : `\x1b[33m비공개\x1b[0m (Space 멤버만 접근)${defaultVisibility === 'private' ? '  ✓ 추천' : ''}`;
-            const visAction = await promptConfirmVis({
-                message: `공개 범위: ${config.visibility === 'public' ? '공개' : '비공개'} — 유지할까요?`,
+            const visLabelMap = {
+                public: '공개',
+                gated: '링크공유',
+                private: '비공개',
+            };
+            const currentVisLabel = visLabelMap[config.visibility ?? 'public'] ?? config.visibility;
+            const newVisibility = await promptConfirmVis({
+                message: `공개 범위: ${currentVisLabel} — 유지하거나 변경하세요`,
                 choices: [
-                    { name: `유지 — ${visLabel}`, value: 'keep' },
-                    { name: '변경', value: 'change' },
+                    {
+                        name: `공개 — 누구나 설치${defaultVisibility === 'public' ? '  ✓ 추천' : ''}`,
+                        value: 'public',
+                    },
+                    {
+                        name: '링크공유 — 접근 링크가 있는 사람만 설치',
+                        value: 'gated',
+                    },
+                    {
+                        name: `비공개 — Space 멤버만 접근${defaultVisibility === 'private' ? '  ✓ 추천' : ''}`,
+                        value: 'private',
+                    },
                 ],
+                default: config.visibility ?? defaultVisibility,
             });
-            if (visAction === 'change') {
-                config.visibility = config.visibility === 'public' ? 'private' : 'public';
+            if (newVisibility !== config.visibility) {
+                config.visibility = newVisibility;
                 const yamlData = js_yaml_1.default.load(fs_1.default.readFileSync(relayYamlPath, 'utf-8'));
                 yamlData.visibility = config.visibility;
                 fs_1.default.writeFileSync(relayYamlPath, js_yaml_1.default.dump(yamlData, { lineWidth: 120 }), 'utf-8');
-                const newLabel = config.visibility === 'public' ? '공개' : '비공개';
-                console.error(`  → relay.yaml에 visibility: ${config.visibility} 저장됨 (${newLabel})\n`);
+                console.error(`  → relay.yaml에 visibility: ${config.visibility} 저장됨 (${visLabelMap[config.visibility]})\n`);
             }
         }
         // Profile hint
@@ -564,6 +638,7 @@ function registerPublish(program) {
             agent_details: detectedAgents,
             skill_details: detectedSkills,
             ...(selectedSpaceId ? { space_id: selectedSpaceId } : {}),
+            ...(selectedSpaceSlug ? { space_slug: selectedSpaceSlug } : {}),
         };
         if (!json) {
             console.error(`패키지 생성 중... (${config.name} v${config.version})`);
@@ -636,34 +711,22 @@ function registerPublish(program) {
                 }
                 // Show shareable onboarding guide as a plain copyable block
                 if (isTTY) {
-                    const guideLines = [
-                        'npm install -g relayax-cli',
-                        'relay login',
-                        `relay install ${result.slug}`,
-                    ];
-                    // Type-based usage hint
-                    const teamType = config.type ?? 'hybrid';
-                    if (teamType === 'passive') {
-                        guideLines.push('', '# 설치하면 자동 적용됩니다');
-                    }
-                    else if (detectedCommands.length > 0) {
-                        const usageCmd = teamType === 'hybrid'
-                            ? `# 자동 적용 + /${detectedCommands[0].name} 으로 추가 기능`
-                            : `# 사용법: /${detectedCommands[0].name}`;
-                        guideLines.push('', usageCmd);
-                    }
+                    const detailSlug = result.slug.startsWith('@') ? result.slug.slice(1) : result.slug;
+                    const guideUrl = `https://relayax.com/api/registry/${detailSlug}/guide.md`;
                     console.log(`\n  \x1b[90m주변인에게 공유하세요:\x1b[0m\n`);
                     console.log('```');
-                    guideLines.forEach((line) => console.log(line));
+                    console.log('아래 가이드를 읽고 그대로 따라해줘:');
+                    console.log(guideUrl);
                     console.log('```');
-                    const detailSlug = result.slug.startsWith('@') ? result.slug.slice(1) : result.slug;
+                    console.log(`\n  \x1b[90mCLI 설치된 사용자용 (짧은 버전):\x1b[0m`);
+                    console.log(`  /relay:relay-install ${result.slug}`);
                     console.log(`\n  \x1b[90m상세페이지: \x1b[36mrelayax.com/@${detailSlug}\x1b[0m`);
                 }
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(JSON.stringify({ error: 'PUBLISH_FAILED', message }));
+            console.error(JSON.stringify({ error: 'PUBLISH_FAILED', message, fix: message }));
             process.exit(1);
         }
         finally {

package/dist/commands/search.js

@@ -48,7 +48,7 @@ function registerSearch(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(JSON.stringify({ error: 'SEARCH_FAILED', message }));
+            console.error(JSON.stringify({ error: 'SEARCH_FAILED', message, fix: '검색어를 변경하거나 잠시 후 재시도하세요.' }));
             process.exit(1);
         }
     });

package/dist/commands/spaces.d.ts

@@ -4,7 +4,8 @@ export interface SpaceInfo {
     slug: string;
     name: string;
     description: string | null;
-    is_personal: boolean;
+    space_type?: string;
+    join_policy?: string;
     role: string;
 }
 export declare function fetchMySpaces(token: string): Promise<SpaceInfo[]>;

package/dist/commands/spaces.js

@@ -22,7 +22,7 @@ function registerSpaces(program) {
         const token = await (0, config_js_1.getValidToken)();
         if (!token) {
             if (json) {
-                console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.' }));
+                console.error(JSON.stringify({ error: 'LOGIN_REQUIRED', message: '로그인이 필요합니다. relay login을 먼저 실행하세요.', fix: 'relay login 실행 후 재시도하세요.' }));
             }
             else {
                 console.error('\x1b[31m오류: 로그인이 필요합니다.\x1b[0m');
@@ -36,29 +36,21 @@ function registerSpaces(program) {
                 console.log(JSON.stringify({ spaces }));
                 return;
             }
-            const personal = spaces.find((s) => s.is_personal);
-            const others = spaces.filter((s) => !s.is_personal);
-            if (personal) {
-                console.log(`\n\x1b[90m개인 스페이스:\x1b[0m`);
-                console.log(`  \x1b[36m${personal.slug}\x1b[0m  \x1b[1m${personal.name}\x1b[0m`);
+            if (spaces.length === 0) {
+                console.log('\nSpace가 없습니다.');
+                console.log('\x1b[33m💡 Space를 만들려면: www.relayax.com/spaces/new\x1b[0m');
             }
-            if (others.length > 0) {
-                console.log(`\n\x1b[1m내 Space\x1b[0m (${others.length}개):\n`);
-                for (const s of others) {
+            else {
+                console.log(`\n\x1b[1m내 Space\x1b[0m (${spaces.length}개):\n`);
+                for (const s of spaces) {
                     const role = s.role === 'owner' ? '\x1b[33m소유자\x1b[0m'
-                        : s.role === 'admin' ? '\x1b[36m관리자\x1b[0m'
+                        : s.role === 'builder' ? '\x1b[36m빌더\x1b[0m'
                             : '\x1b[90m멤버\x1b[0m';
                     const desc = s.description
                         ? `  \x1b[90m${s.description.length > 40 ? s.description.slice(0, 40) + '...' : s.description}\x1b[0m`
                         : '';
                     console.log(`  \x1b[36m${s.slug}\x1b[0m  \x1b[1m${s.name}\x1b[0m  ${role}${desc}`);
                 }
-            }
-            if (!personal && others.length === 0) {
-                console.log('\nSpace가 없습니다.');
-                console.log('\x1b[33m💡 Space를 만들려면: www.relayax.com/spaces/new\x1b[0m');
-            }
-            if (others.length > 0) {
                 console.log(`\n\x1b[33m💡 Space 팀 목록: relay list --space <slug>\x1b[0m`);
                 console.log(`\x1b[33m💡 비공개 배포: relay.yaml에 visibility: private 설정 후 relay publish\x1b[0m`);
             }
@@ -66,7 +58,7 @@ function registerSpaces(program) {
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             if (json) {
-                console.error(JSON.stringify({ error: 'FETCH_FAILED', message }));
+                console.error(JSON.stringify({ error: 'FETCH_FAILED', message, fix: '네트워크 연결을 확인하거나 잠시 후 재시도하세요.' }));
             }
             else {
                 console.error(`\x1b[31m오류: ${message}\x1b[0m`);

package/dist/commands/update.js

@@ -133,7 +133,7 @@ function registerUpdate(program) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.error(JSON.stringify({ error: 'UPDATE_FAILED', message }));
+            console.error(JSON.stringify({ error: 'UPDATE_FAILED', message, fix: 'npm update -g relayax-cli로 수동 업데이트하세요.' }));
             process.exit(1);
         }
         finally {

package/dist/index.js

@@ -20,6 +20,7 @@ const join_js_1 = require("./commands/join.js");
 const spaces_js_1 = require("./commands/spaces.js");
 const deploy_record_js_1 = require("./commands/deploy-record.js");
 const ping_js_1 = require("./commands/ping.js");
+const access_js_1 = require("./commands/access.js");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
 const program = new commander_1.Command();
@@ -46,4 +47,5 @@ program
 (0, spaces_js_1.registerSpaces)(program);
 (0, deploy_record_js_1.registerDeployRecord)(program);
 (0, ping_js_1.registerPing)(program);
+(0, access_js_1.registerAccess)(program);
 program.parse();

package/dist/lib/command-adapter.js

@@ -57,13 +57,46 @@ function getGlobalCommandPathForTool(skillsDir, commandId) {
 function formatCommandFile(content) {
     return `---\ndescription: ${content.description}\n---\n\n${content.body}\n`;
 }
-// ─── Login JIT 공통 안내 ───
-const LOGIN_JIT_GUIDE = `
-### 인증 오류 처리
-- 커맨드 실행 결과에 \`LOGIN_REQUIRED\` 에러가 포함되면:
-  1. \`relay login\` 실행 (timeout 300초)
-     - 브라우저가 자동으로 열리고, 사용자가 로그인을 완료하면 토큰이 자동 저장됩니다.
-  2. 완료 후 \`relay status --json\`으로 로그인 성공을 확인하고, 원래 커맨드를 재실행합니다.`;
+// ─── 에러 처리 가이드 (결정적 실행 + 비결정적 조율) ───
+const ERROR_HANDLING_GUIDE = `
+### 에러 처리 가이드
+
+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\` 필드의 메시지를 사용자에게 전달하고, 필요하면 다음 행동을 제안합니다.`;
 // ─── 명함 표시 포맷 ───
 const BUSINESS_CARD_FORMAT = `
 ### 빌더 명함 표시
@@ -128,7 +161,7 @@ slug가 직접 주어지면 (\`/relay-install @alice/doc-writer\`) 이 단계를
 
 **AskUserQuestion 호출:**
 - question: "어디서 팀을 찾을까요?"
-- options: Space가 있으면 \`["<space1_name> (개인)", "<space2_name>", ...]\`, 없으면 이 단계를 건너뛰고 바로 내 Space 탐색으로 진행
+- options: Space가 있으면 \`["<space1_name>", "<space2_name>", ...]\`, 없으면 이 단계를 건너뛰고 바로 내 Space 탐색으로 진행
 
 **응답 처리:**
 - Space 이름 선택 → 1-2. Space 팀 탐색으로 진행
@@ -177,13 +210,24 @@ slug가 직접 주어지면 (\`/relay-install @alice/doc-writer\`) 이 단계를
 
 #### 2-1. 패키지 다운로드
 \`relay install <@space/team> --json\` 명령어를 실행합니다.
-- 공개 팀: \`relay install <@space/team> --json\`
-- Space 팀 (비공개): \`relay install @<space-slug>/<team-slug> --json\`
+- 공개 팀 (public): \`relay install <@space/team> --json\`
+- 링크 공유 팀 (gated): \`relay install <slug> --json\`
+  - 접근 권한이 없으면 CLI가 **purchase_info** (구매 안내 메시지 + URL)를 표시합니다.
+  - 접근 링크 코드가 있으면: \`relay access <slug> --code <code>\` 로 접근 부여 + 자동 설치를 한번에 수행합니다.
+  - Space 멤버이면 접근 확인 없이 바로 설치됩니다.
+- Space 팀 (비공개/private): \`relay install @<space-slug>/<team-slug> --json\`
   - Space 가입이 필요하면: \`relay join <space-slug> --code <invite-code>\` 를 먼저 실행합니다.
   - 또는 \`--join-code <code>\`로 가입+설치를 한번에 할 수 있습니다.
 - CLI가 init과 login을 자동으로 처리합니다 (사용자가 별도 실행할 필요 없음).
 - JSON 출력에서 \`install_path\` (패키지 경로)를 확인합니다.
 
+**gated 팀 접근 거부 처리:**
+- CLI가 403 + \`GATED_ACCESS_REQUIRED\` 에러를 반환하면:
+  1. purchase_info의 message와 url을 사용자에게 표시합니다.
+  2. "접근 링크 코드가 있으신가요?"라고 물어봅니다.
+  3. 코드가 있으면 \`relay access <slug> --code <code>\`를 실행합니다.
+  4. 코드가 없으면 purchase_info의 url로 구매 안내합니다.
+
 #### 2-2. 배치 범위 선택 (추천 포함)
 
 팀의 성격을 분석하여 글로벌/로컬 중 적합한 쪽을 추천합니다.
@@ -283,7 +327,7 @@ requires 섹션이 없거나 비어있으면 이 단계를 건너뜁니다.
 \`\`\`
 ⚠️  필수 요구사항이 충족되지 않았습니다. 팀 기능이 제한될 수 있습니다.
 \`\`\`
-${LOGIN_JIT_GUIDE}
+${ERROR_HANDLING_GUIDE}
 
 ### Step 3. 완료 & 팔로우 제안
 
@@ -308,18 +352,12 @@ ${BUSINESS_CARD_FORMAT}
 \`\`\`
 주변인에게 공유하세요:
 
-npm install -g relayax-cli
-relay login
-relay install {slug}
-
-상세페이지: relayax.com/@{owner}/{team}
+아래 가이드를 읽고 그대로 따라해줘:
+https://relayax.com/api/registry/{owner}/{slug}/guide.md
 \`\`\`
 
-- \`{slug}\`가 \`@owner/team\` 형식이면 상세페이지는 \`relayax.com/@{owner}/{team}\`으로 치환합니다.
-
-- type 기반 사용법도 포함:
-  - command/hybrid: \`# 사용법: /{첫번째 커맨드}\`
-  - passive: \`# 설치하면 자동 적용됩니다\`
+- \`{slug}\`가 \`@owner/team\` 형식이면 \`{owner}\`과 \`{slug}\`를 분리하여 URL을 구성합니다.
+- CLI가 이미 설치된 사용자를 위한 짧은 버전도 함께 표시합니다: \`/relay:relay-install {slug}\`
 
 #### 3-4. 사용 제안
 - "바로 사용해볼까요?" 제안
@@ -333,8 +371,8 @@ relay install {slug}
 
 ### 인터랙티브 모드 (/relay-install)
 → relay spaces --json 실행
-→ AskUserQuestion: "어디서 팀을 찾을까요?" → ["개인 Space (alice)", "Acme Corp"]
-→ "개인 Space" 선택 → "어떤 팀을 찾고 계세요?"
+→ AskUserQuestion: "어디서 팀을 찾을까요?" → ["Alice's Space (alice)", "Acme Corp"]
+→ "Alice's Space" 선택 → "어떤 팀을 찾고 계세요?"
 → relay search "문서" 실행 → 결과 리스트 표시
 → AskUserQuestion: "어떤 팀을 설치할까요?" → ["1", "2", "3", "다시 검색"]
 → "1" 선택 (@alice/doc-writer)
@@ -401,7 +439,6 @@ relay install {slug}
       "slug": "my-space",
       "name": "내 스페이스",
       "description": "설명",
-      "is_personal": false,
       "role": "owner"
     }
   ]
@@ -409,9 +446,8 @@ relay install {slug}
 \`\`\`
 
 **표시:**
-- \`is_personal: true\` → 개인 스페이스로 분류
-- \`role\`: owner → 소유자, admin → 관리자, member → 멤버
-${LOGIN_JIT_GUIDE}
+- \`role\`: owner → 소유자, builder → 빌더, member → 멤버
+${ERROR_HANDLING_GUIDE}
 - Spaces 조회 실패해도 설치된 팀 목록은 정상 표시합니다 (로컬 데이터).
 
 ### 3. Space 팀 목록 (옵션)
@@ -542,14 +578,14 @@ relay.yaml의 \`visibility\` 설정을 확인합니다.
 #### 신규 배포 (visibility 미설정)
 
 **AskUserQuestion 호출:**
-- question: "어디에 배포할까요?"
-- options: \`["공개 (Space 공개)", "비공개 (Space 전용)"]\`
+- question: "공개 범위를 선택하세요"
+- options: \`["공개 — 누구나 설치", "링크 공유 — 접근 링크가 있는 사람만 설치", "비공개 — Space 멤버만"]\`
 
 **응답 처리:**
 - "공개" → relay.yaml에 \`visibility: public\` 저장
+- "링크 공유" → relay.yaml에 \`visibility: gated\` 저장. 배포 후 웹 대시보드(/dashboard)에서 접근 링크를 생성하고 구매 안내를 설정할 수 있다고 안내.
 - "비공개" → \`relay spaces --json\` 실행 후 Space 목록 표시
-  - \`is_personal: true\`인 개인 Space는 **제외**합니다. 비공개 배포는 팀 Space에만 가능합니다.
-  - 팀 Space가 0개이면: "비공개 배포하려면 팀 Space가 필요합니다. www.relayax.com/spaces 에서 Space를 생성하세요."라고 안내하고 중단합니다.
+  - Space가 0개이면: "비공개 배포하려면 Space가 필요합니다. www.relayax.com/spaces 에서 Space를 생성하세요."라고 안내하고 중단합니다.
 
   **AskUserQuestion 호출 (Space가 1개여도 반드시 호출):**
   - question: "어떤 Space에 배포할까요?"
@@ -563,7 +599,7 @@ relay.yaml의 \`visibility\` 설정을 확인합니다.
 현재 설정을 확인합니다:
 
 **AskUserQuestion 호출:**
-- question: 공개일 때 "현재 **공개** 설정입니다. Space에 공개됩니다. 유지할까요?", 비공개일 때 "현재 **비공개** 설정입니다 (Space: {name}). 유지할까요?"
+- question: 공개일 때 "현재 **공개** 설정입니다. 유지할까요?", 링크공유일 때 "현재 **링크 공유** 설정입니다. 접근 링크가 있는 사람만 설치 가능합니다. 유지할까요?", 비공개일 때 "현재 **비공개** 설정입니다 (Space: {name}). 유지할까요?"
 - options: \`["유지", "변경"]\`
 
 "변경" → 신규 배포와 동일한 플로우
@@ -677,13 +713,13 @@ requires: env 2개, cli 1개
 - 출력에 코드블록이 없으면 아래 형태로 직접 생성합니다:
 
 \\\`\\\`\\\`
-npm install -g relayax-cli
-relay login
-relay install <slug>
+아래 가이드를 읽고 그대로 따라해줘:
+https://relayax.com/api/registry/{owner}/{slug}/guide.md
 \\\`\\\`\\\`
 
-- \`<slug>\`는 배포된 팀의 실제 슬러그로 치환합니다.
-- "이 블록을 팀원에게 공유하면 바로 설치할 수 있습니다"라고 안내합니다.
+- \`{owner}\`과 \`{slug}\`는 배포된 팀의 실제 슬러그에서 추출합니다 (\`@owner/slug\` → \`owner\`, \`slug\`).
+- "이 블록을 팀원에게 공유하면 Claude가 환경 체크부터 설치까지 자동으로 해줍니다"라고 안내합니다.
+- CLI가 이미 설치된 사용자를 위한 짧은 버전도 함께 표시: \`/relay:relay-install <slug>\`
 ${BUSINESS_CARD_FORMAT}
 
 ## 예시
@@ -699,7 +735,8 @@ ${BUSINESS_CARD_FORMAT}
 → AskUserQuestion: "이대로 배포할까요?" → ["배포", "취소"]
 → "배포" → relay publish 실행
 → "배포 완료! URL: https://relayax.com/@my-space/my-team"
-→ 온보딩 가이드 코드블록 표시`,
+→ 온보딩 가이드 코드블록 표시
+${ERROR_HANDLING_GUIDE}`,
     },
 ];
 // ─── Builder Commands (로컬 설치) ───

package/dist/types.d.ts

@@ -51,7 +51,7 @@ export interface TeamRegistryInfo {
     tags?: string[];
     install_count?: number;
     requires?: Record<string, unknown>;
-    visibility?: "public" | "private";
+    visibility?: "public" | "gated" | "private";
     welcome?: string | null;
     contact?: Record<string, string> | null;
     author?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relayax-cli",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "RelayAX Agent Team Marketplace CLI - Install and manage agent teams",
   "main": "dist/index.js",
   "bin": {