relayax-cli 0.3.67 → 0.4.12

package/README.md

@@ -1,42 +1,174 @@
-# relay-cli
+# relay
 
-Agent Team Marketplace CLI - 에이전트 팀을 검색하고 설치하세요.
+**The package manager for AI agents.**
+
+Write once, run on any harness. One command install. Built-in usage analytics.
+
+```bash
+npx relayax-cli install @gstack/code-review
+```
+
+```
+ ╭──────────────────────────────────────────────╮
+ │                                              │
+ │   relay — AI agent distribution for humans   │
+ │   and machines.                              │
+ │                                              │
+ │   ✓ installed @gstack/code-review (v2.1.0)   │
+ │   3 skills, 1 agent ready                    │
+ │                                              │
+ ╰──────────────────────────────────────────────╯
+```
+
+---
+
+## Why
+
+AI agents are stuck in silos. You build an agent for Claude Code — it doesn't work on OpenClaw. You share it on GitHub — no one knows it exists. You have no idea if anyone actually uses it.
+
+**Relay fixes this.**
+
+| Problem | Relay |
+|---|---|
+| Agents locked to one harness | Cross-harness compatibility (Claude, OpenClaw, nanoclaw) |
+| No distribution channel | `relay install` — one command, done |
+| Zero feedback from users | Built-in analytics — see which skills get used |
+
+---
 
 ## Quick Start
 
 ```bash
-# 글로벌 설치 없이 바로 사용
-npx relay-cli install @author/team-name
+# Install an agent — no setup required
+npx relayax-cli install @author/agent-name
 
-# 또는 글로벌 설치
-npm install -g relayax-cli
-relay install @author/team-name
+# Or install globally
+npm i -g relayax-cli
+relay install @author/agent-name
 ```
 
+That's it. The agent is ready in your `.relay/agents/` directory, compatible with your harness.
+
+---
+
+## For Agent Builders
+
+```bash
+# Publish your agent to the registry
+relay publish
+
+# See who's using it
+relay status --analytics
+```
+
+Relay tracks skill-level usage out of the box. No extra setup. You'll know exactly which skills land and which don't — so you can ship better agents, faster.
+
+### Package Format
+
+```yaml
+# team.yaml
+name: code-review
+version: 2.1.0
+harness:
+  - claude
+  - openclaw
+  - nanoclaw
+agents:
+  - name: reviewer
+    type: passive
+skills:
+  - name: review-pr
+  - name: security-check
+  - name: style-lint
+```
+
+One spec. Every harness.
+
+---
+
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `relay init` | 초기 설정 (설치 경로, API URL) |
-| `relay search <keyword>` | 팀 검색 |
-| `relay install <name>` | 팀 설치 |
-| `relay list` | 설치된 팀 목록 |
-| `relay uninstall <name>` | 팀 제거 |
+| Command | What it does |
+|---|---|
+| `relay install <name>` | Install an agent |
+| `relay search <keyword>` | Find agents in the registry |
+| `relay publish` | Publish your agent |
+| `relay list` | List installed agents |
+| `relay status` | Check environment + analytics |
+| `relay update` | Update agents to latest |
+| `relay uninstall <name>` | Remove an agent |
+| `relay diff <name>` | See what changed between versions |
 
-## Options
+All output is JSON by default (for AI agents). Add `--pretty` for human-readable format.
 
-- `--pretty` - 사람이 읽기 좋은 포맷으로 출력 (기본: JSON)
-- `--json` - JSON 출력 (기본값, 에이전트 친화적)
+---
 
-## For AI Agents
+## How It Works
+
+```
+                    relay install @team/agent
+                            │
+                 ╭──────────┴──────────╮
+                 │   Relay Registry    │
+                 │  (relay.ax cloud)   │
+                 ╰──────────┬──────────╯
+                            │
+                 ╭──────────┴──────────╮
+                 │  relay agent spec   │
+                 │  (universal format) │
+                 ╰──┬───────┬───────┬──╯
+                    │       │       │
+              ┌─────┴─┐ ┌──┴───┐ ┌─┴──────┐
+              │Claude │ │Open  │ │nano    │
+              │ Code  │ │Claw  │ │claw    │
+              └───────┘ └──────┘ └────────┘
+```
 
-relay CLI는 에이전트가 1차 사용자입니다. 모든 출력은 JSON 기본입니다.
+Relay resolves the right format for your harness automatically. Builders write one spec, users install with one command.
+
+---
+
+## AI-Native
+
+Relay is built for AI agents as first-class users. The CLI outputs structured JSON so agents can search, install, and manage other agents autonomously.
 
 ```bash
-# 에이전트가 팀 검색
-relay search "keyword" | jq '.results[].slug'
+# An agent searching for tools
+relay search "database migration" | jq '.results[].slug'
+
+# An agent installing what it needs
+relay install @tools/db-migrate
+# → {"status":"ok","agent":"db-migrate","skills":["migrate","rollback","seed"]}
+```
 
-# 에이전트가 팀 설치
-relay install @author/team-name
-# → {"status":"ok","team":"Team Name","commands":[...]}
+Relay also ships as an **MCP server**, so any MCP-compatible agent can use it directly:
+
+```bash
+relay mcp
 ```
+
+---
+
+## Open Core
+
+The CLI and agent spec are open source (MIT). Build agents, publish them, self-host your own registry — no vendor lock-in.
+
+[relay.ax](https://relayax.com) provides the hosted registry with:
+- Private agent hosting
+- Organization management & access control
+- Usage analytics dashboard
+- Enterprise SSO & audit logs
+
+---
+
+## Community
+
+- [25+ production agents](https://relayax.com) ready to install
+- [Builder docs](https://relayax.com/docs) for creating your own
+- [Discord](#) for help and discussion
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://relayax.com">RelayAX</a></sub>
+</p>

package/dist/commands/create.js

@@ -143,7 +143,14 @@ function registerCreate(program) {
                 });
             }
         }
-        // 3. .relay/relay.yaml 생성
+        // 3. recommended_scope 자동 추천
+        //    rules/ 존재 or 프레임워크 태그 → local, 그 외 → global
+        const frameworkTags = ['nextjs', 'react', 'vue', 'angular', 'svelte', 'nuxt', 'remix', 'astro', 'django', 'rails', 'laravel', 'spring', 'express', 'fastapi', 'flask'];
+        const hasRules = fs_1.default.existsSync(path_1.default.join(projectPath, '.relay', 'rules'))
+            || fs_1.default.existsSync(path_1.default.join(projectPath, 'rules'));
+        const hasFrameworkTag = tags.some((t) => frameworkTags.includes(t.toLowerCase()));
+        const recommendedScope = (hasRules || hasFrameworkTag) ? 'local' : 'global';
+        // 4. .relay/relay.yaml 생성
         fs_1.default.mkdirSync(relayDir, { recursive: true });
         const yamlData = {
             name,
@@ -151,6 +158,7 @@ function registerCreate(program) {
             description,
             version: '1.0.0',
             type: 'hybrid',
+            recommended_scope: recommendedScope,
             tags,
             visibility,
             contents: [],
@@ -187,6 +195,7 @@ function registerCreate(program) {
                 status: 'ok',
                 name,
                 slug: slug,
+                recommended_scope: recommendedScope,
                 relay_yaml: 'created',
                 directories: createdDirs,
                 local_commands: localResults,
@@ -194,8 +203,11 @@ function registerCreate(program) {
             }));
         }
         else {
+            const scopeLabel = recommendedScope === 'global' ? '\x1b[32m글로벌\x1b[0m' : '\x1b[33m로컬\x1b[0m';
+            const scopeReason = hasRules ? 'rules/ 감지' : hasFrameworkTag ? '프레임워크 태그 감지' : '범용 에이전트';
             console.log(`\n\x1b[32m✓ ${name} 에이전트 프로젝트 생성 완료\x1b[0m\n`);
             console.log(`  .relay/relay.yaml 생성됨`);
+            console.log(`  recommended_scope: ${scopeLabel} (${scopeReason})`);
             if (createdDirs.length > 0) {
                 console.log(`  디렉토리 생성: ${createdDirs.join(', ')}`);
             }

package/dist/commands/diff.js

@@ -1,9 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDiff = registerDiff;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
 const api_js_1 = require("../lib/api.js");
 const slug_js_1 = require("../lib/slug.js");
-const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 function registerDiff(program) {
     program
         .command('diff <slug> <v1> <v2>')
@@ -13,6 +19,7 @@ function registerDiff(program) {
         try {
             const resolved = await (0, slug_js_1.resolveSlug)(slugInput);
             const versions = await (0, api_js_1.fetchAgentVersions)(resolved.full);
+            const info = await (0, api_js_1.fetchAgentInfo)(resolved.full);
             const ver1 = versions.find((v) => v.version === v1);
             const ver2 = versions.find((v) => v.version === v2);
             if (!ver1 || !ver2) {
@@ -21,19 +28,36 @@ function registerDiff(program) {
             if (!json) {
                 console.log(`\n\x1b[1m${resolved.full}\x1b[0m v${v1} ↔ v${v2} 비교 중...\n`);
             }
-            // Download both versions to temp dirs
-            const tempDir1 = (0, storage_js_1.makeTempDir)();
-            const tempDir2 = (0, storage_js_1.makeTempDir)();
-            try {
-                // Get download URLs for both versions via registry API
-                // For now, we use the current version's package_url as fallback
-                // The registry API returns the latest version; for specific versions,
-                // we'd need a version-specific endpoint
-                const info = await (0, api_js_1.fetchAgentInfo)(resolved.full);
-                if (!info.package_url) {
-                    throw new Error('패키지 URL을 가져올 수 없습니다');
+            // Use git diff if git_url is available
+            if (info.git_url) {
+                (0, git_operations_js_1.checkGitInstalled)();
+                const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'relay-diff-'));
+                try {
+                    (0, git_operations_js_1.gitClone)(info.git_url, tempDir);
+                    const diffOutput = (0, git_operations_js_1.gitDiff)(tempDir, `v${v1}`, `v${v2}`);
+                    if (json) {
+                        console.log(JSON.stringify({
+                            slug: resolved.full,
+                            v1: { version: v1, created_at: ver1.created_at, changelog: ver1.changelog },
+                            v2: { version: v2, created_at: ver2.created_at, changelog: ver2.changelog },
+                            diff: diffOutput,
+                        }));
+                    }
+                    else {
+                        if (diffOutput.trim()) {
+                            console.log(diffOutput);
+                        }
+                        else {
+                            console.log('  변경 사항이 없습니다.');
+                        }
+                    }
                 }
-                // Since version-specific download isn't available yet, show versions info
+                finally {
+                    fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+                }
+            }
+            else {
+                // Fallback: show version info only (no git URL available)
                 if (json) {
                     console.log(JSON.stringify({
                         slug: resolved.full,
@@ -50,13 +74,9 @@ function registerDiff(program) {
                     if (ver2.changelog)
                         console.log(`    ${ver2.changelog}`);
                     console.log();
-                    console.log(`\x1b[33m  버전별 패키지 다운로드 비교는 추후 지원 예정입니다.\x1b[0m`);
+                    console.log(`\x1b[33m  git 기반 diff는 새로 배포된 에이전트에서만 지원됩니다.\x1b[0m`);
                 }
             }
-            finally {
-                (0, storage_js_1.removeTempDir)(tempDir1);
-                (0, storage_js_1.removeTempDir)(tempDir2);
-            }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/commands/export.d.ts

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

package/dist/commands/export.js

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExport = registerExport;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const manifest_generator_js_1 = require("../lib/manifest-generator.js");
+const paths_js_1 = require("../lib/paths.js");
+function registerExport(program) {
+    program
+        .command('export <platform>')
+        .description('로컬에서 플랫폼 네이티브 매니페스트를 생성합니다')
+        .option('--out <dir>', '출력 디렉토리 (기본: .relay/export/<platform>/)')
+        .option('--project <dir>', '프로젝트 루트 경로')
+        .action(async (platform, opts) => {
+        const json = program.opts().json ?? false;
+        const projectPath = (0, paths_js_1.resolveProjectPath)(opts.project);
+        const relayDir = path_1.default.join(projectPath, '.relay');
+        const relayYamlPath = path_1.default.join(relayDir, 'relay.yaml');
+        // Check relay.yaml exists
+        if (!fs_1.default.existsSync(relayYamlPath)) {
+            const msg = 'relay.yaml not found';
+            if (json) {
+                console.error(JSON.stringify({ error: 'NOT_FOUND', message: msg }));
+            }
+            else {
+                console.error(`\x1b[31m${msg}\x1b[0m`);
+                console.error('  relay.yaml이 있는 에이전트 디렉토리에서 실행하세요.');
+            }
+            process.exit(1);
+        }
+        // Validate platform
+        const validPlatforms = [...manifest_generator_js_1.SUPPORTED_PLATFORMS, 'all'];
+        if (!validPlatforms.includes(platform)) {
+            const msg = `지원하지 않는 플랫폼: ${platform}`;
+            if (json) {
+                console.error(JSON.stringify({ error: 'INVALID_PLATFORM', message: msg, supported: manifest_generator_js_1.SUPPORTED_PLATFORMS }));
+            }
+            else {
+                console.error(`\x1b[31m${msg}\x1b[0m`);
+                console.error(`  지원 플랫폼: ${manifest_generator_js_1.SUPPORTED_PLATFORMS.join(', ')}, all`);
+            }
+            process.exit(1);
+        }
+        // Parse relay.yaml
+        const yamlContent = fs_1.default.readFileSync(relayYamlPath, 'utf-8');
+        const raw = js_yaml_1.default.load(yamlContent) ?? {};
+        const manifestYaml = {
+            name: String(raw.name ?? ''),
+            slug: String(raw.slug ?? ''),
+            description: String(raw.description ?? ''),
+            version: String(raw.version ?? '1.0.0'),
+            source: raw.source ? String(raw.source) : undefined,
+            org_slug: raw.org_slug ? String(raw.org_slug) : undefined,
+            platforms: platform === 'all' ? undefined : [platform],
+        };
+        // Generate manifests
+        const files = (0, manifest_generator_js_1.generateManifests)(manifestYaml, relayDir);
+        if (files.length === 0) {
+            if (json) {
+                console.log(JSON.stringify({ status: 'empty', message: '생성할 매니페스트가 없습니다.' }));
+            }
+            else {
+                console.log('생성할 매니페스트가 없습니다.');
+            }
+            return;
+        }
+        // Determine output directory
+        const outDir = opts.out
+            ? path_1.default.resolve(opts.out)
+            : path_1.default.join(relayDir, 'export', platform);
+        fs_1.default.mkdirSync(outDir, { recursive: true });
+        // Write files
+        const written = [];
+        for (const file of files) {
+            const filePath = path_1.default.join(outDir, file.relativePath);
+            fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+            fs_1.default.writeFileSync(filePath, file.content);
+            written.push(file.relativePath);
+        }
+        if (json) {
+            console.log(JSON.stringify({ status: 'ok', platform, output_dir: outDir, files: written }));
+        }
+        else {
+            console.log(`\n\x1b[32m✓ 매니페스트 생성 완료\x1b[0m  (${platform})`);
+            console.log(`  출력: \x1b[36m${outDir}\x1b[0m\n`);
+            for (const f of written) {
+                console.log(`  \x1b[90m•\x1b[0m ${f}`);
+            }
+            // Platform-specific usage hints
+            console.log('');
+            if (platform === 'claude-code' || platform === 'all') {
+                console.log('  \x1b[90mClaude Code:\x1b[0m /plugin marketplace add <marketplace.json URL>');
+            }
+            if (platform === 'codex' || platform === 'all') {
+                console.log('  \x1b[90mCodex:\x1b[0m .codex-plugin/plugin.json을 Codex에 등록하세요');
+            }
+            if (platform === 'antigravity' || platform === 'all') {
+                console.log('  \x1b[90mAntigravity:\x1b[0m .agent/skills/를 프로젝트에 복사하세요');
+            }
+        }
+    });
+}

package/dist/commands/install.js

@@ -9,6 +9,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const api_js_1 = require("../lib/api.js");
 const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 const config_js_1 = require("../lib/config.js");
 const slug_js_1 = require("../lib/slug.js");
 const preamble_js_1 = require("../lib/preamble.js");
@@ -212,11 +213,10 @@ function registerInstall(program) {
                 throw new Error('에이전트 정보를 가져오지 못했습니다.');
             // Re-bind as non-optional so TypeScript tracks the narrowing through nested scopes
             let resolvedAgent = agent;
-            // Scope 자동결정: --global/--local 플래그 > agent_type 기반
+            // Scope 자동결정: --global/--local 플래그 > recommended_scope > agent_type 기반
             const scope = _opts.global ? 'global'
                 : _opts.local ? 'local'
-                    : resolvedAgent.type === 'passive' ? 'local'
-                        : 'global';
+                    : resolvedAgent.recommended_scope ?? (resolvedAgent.type === 'passive' ? 'local' : 'global');
             const agentDir = scope === 'global'
                 ? path_1.default.join(os_1.default.homedir(), '.relay', 'agents', parsed.owner, parsed.name)
                 : path_1.default.join(projectPath, '.relay', 'agents', parsed.owner, parsed.name);
@@ -240,31 +240,39 @@ function registerInstall(program) {
                     process.exit(1);
                 }
             }
-            // 3. Download package (retry once if signed URL expired)
-            let tarPath;
-            try {
-                tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
+            // 3. Download package: prefer git clone, fallback to tar.gz
+            const requestedVersion = versionMatch ? versionMatch[2] : undefined;
+            if (resolvedAgent.git_url) {
+                // Git clone path
+                (0, git_operations_js_1.checkGitInstalled)();
+                const gitUrl = (0, git_operations_js_1.buildGitUrl)(resolvedAgent.git_url, { code: _opts.code });
+                await (0, storage_js_1.clonePackage)(gitUrl, agentDir, requestedVersion);
             }
-            catch (dlErr) {
-                const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
-                if (dlMsg.includes('403') || dlMsg.includes('expired')) {
-                    // Signed URL expired — re-fetch agent info for new URL and retry
-                    if (!json) {
-                        console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
-                    }
-                    resolvedAgent = await (0, api_js_1.fetchAgentInfo)(slug);
+            else {
+                // Legacy tar.gz path (retry once if signed URL expired)
+                let tarPath;
+                try {
                     tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
                 }
-                else {
-                    throw dlErr;
+                catch (dlErr) {
+                    const dlMsg = dlErr instanceof Error ? dlErr.message : String(dlErr);
+                    if (dlMsg.includes('403') || dlMsg.includes('expired')) {
+                        if (!json) {
+                            console.error('\x1b[33m⚙ 다운로드 URL 만료, 재시도 중...\x1b[0m');
+                        }
+                        resolvedAgent = await (0, api_js_1.fetchAgentInfo)(slug);
+                        tarPath = await (0, storage_js_1.downloadPackage)(resolvedAgent.package_url, tempDir);
+                    }
+                    else {
+                        throw dlErr;
+                    }
                 }
+                if (fs_1.default.existsSync(agentDir)) {
+                    fs_1.default.rmSync(agentDir, { recursive: true, force: true });
+                }
+                fs_1.default.mkdirSync(agentDir, { recursive: true });
+                await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             }
-            // 4. Extract to .relay/agents/<slug>/
-            if (fs_1.default.existsSync(agentDir)) {
-                fs_1.default.rmSync(agentDir, { recursive: true, force: true });
-            }
-            fs_1.default.mkdirSync(agentDir, { recursive: true });
-            await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             // 4.5. Inject preamble (update check) into SKILL.md and commands
             (0, preamble_js_1.injectPreambleToAgent)(agentDir, slug);
             // 5. Deploy symlinks to detected AI tool directories

package/dist/commands/publish.js

@@ -17,6 +17,8 @@ const version_check_js_1 = require("../lib/version-check.js");
 const paths_js_1 = require("../lib/paths.js");
 const error_report_js_1 = require("../lib/error-report.js");
 const step_tracker_js_1 = require("../lib/step-tracker.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
+const manifest_generator_js_1 = require("../lib/manifest-generator.js");
 // GUIDE_INSTRUCTION removed — share text now uses npx install command directly
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const cliPkg = require('../../package.json');
@@ -50,6 +52,7 @@ function parseRelayYaml(content) {
         type,
         source: raw.source ? String(raw.source) : undefined,
         org_slug: raw.org_slug ? String(raw.org_slug) : undefined,
+        platforms: Array.isArray(raw.platforms) ? raw.platforms.map((p) => String(p)) : undefined,
     };
 }
 function detectCommands(agentDir) {
@@ -696,6 +699,46 @@ function registerPublish(program) {
         const entrySlug = config.slug.startsWith('@') ? config.slug.slice(1) : config.slug;
         const entryFileName = entrySlug.replace('/', '-') + '.md';
         fs_1.default.writeFileSync(path_1.default.join(commandsDir, entryFileName), entryContent);
+        // Check git is available
+        try {
+            (0, git_operations_js_1.checkGitInstalled)();
+        }
+        catch (gitErr) {
+            const gitMsg = gitErr instanceof Error ? gitErr.message : String(gitErr);
+            (0, error_report_js_1.reportCliError)('publish', 'GIT_NOT_FOUND', gitMsg);
+            if (json) {
+                console.error(JSON.stringify({ error: 'GIT_NOT_FOUND', message: gitMsg }));
+            }
+            else {
+                console.error(`\x1b[31m${gitMsg}\x1b[0m`);
+            }
+            process.exit(1);
+        }
+        // Generate platform manifests (after preamble/command, before git commit)
+        const manifestYaml = {
+            name: config.name,
+            slug: config.slug,
+            description: config.description,
+            version: config.version,
+            source: config.source,
+            org_slug: config.org_slug ?? selectedOrgSlug,
+            platforms: config.platforms,
+        };
+        const manifestFiles = (0, manifest_generator_js_1.generateManifests)(manifestYaml, relayDir);
+        for (const mf of manifestFiles) {
+            const mfPath = path_1.default.join(relayDir, mf.relativePath);
+            fs_1.default.mkdirSync(path_1.default.dirname(mfPath), { recursive: true });
+            fs_1.default.writeFileSync(mfPath, mf.content);
+        }
+        const generatedPlatforms = [...new Set(manifestFiles.map((f) => {
+                if (f.relativePath.startsWith('.claude-plugin/') || f.relativePath === 'marketplace.json')
+                    return 'claude-code';
+                if (f.relativePath.startsWith('.codex-plugin/'))
+                    return 'codex';
+                if (f.relativePath.startsWith('.agent/'))
+                    return 'antigravity';
+                return 'unknown';
+            }))];
         let tarPath = null;
         try {
             tarPath = await createTarball(relayDir);
@@ -703,6 +746,29 @@ function registerPublish(program) {
                 console.error(`업로드 중...`);
             }
             const result = await publishToApi(token, tarPath, metadata);
+            // Git push: commit and push to git server (non-fatal if git server unavailable)
+            try {
+                const gitUrl = result.git_url;
+                if (gitUrl) {
+                    if (!json) {
+                        console.error('git 저장소에 푸시 중...');
+                    }
+                    const isFirstPublish = !result.is_update;
+                    if (isFirstPublish) {
+                        await (0, git_operations_js_1.gitPublishInit)(relayDir, gitUrl, config.version);
+                    }
+                    else {
+                        await (0, git_operations_js_1.gitPublishUpdate)(relayDir, gitUrl, config.version);
+                    }
+                }
+            }
+            catch (gitPushErr) {
+                // Git push failure is non-fatal — tar.gz upload already succeeded
+                if (!json) {
+                    const gpMsg = gitPushErr instanceof Error ? gitPushErr.message : String(gitPushErr);
+                    console.error(`\x1b[33m⚠ git push 실패 (배포는 완료됨): ${gpMsg}\x1b[0m`);
+                }
+            }
             // Update entry command preamble with scoped slug from server (non-fatal)
             try {
                 if (result.slug && result.slug !== config.slug) {
@@ -724,6 +790,17 @@ function registerPublish(program) {
                 console.log(`\n\x1b[32m✓ ${config.name} 배포 완료\x1b[0m  v${result.version}`);
                 console.log(`  슬러그: \x1b[36m${result.slug}\x1b[0m`);
                 console.log(`  URL:    \x1b[36m${result.url}\x1b[0m`);
+                // Show generated platform manifests
+                if (generatedPlatforms.length > 0) {
+                    console.log(`\n  \x1b[90m플랫폼 매니페스트:\x1b[0m ${generatedPlatforms.join(', ')}`);
+                }
+                // Show Claude Code plugin install command if claude-code manifest was generated
+                if (generatedPlatforms.includes('claude-code')) {
+                    const pluginSlug = result.slug.startsWith('@') ? result.slug.slice(1) : result.slug;
+                    const pluginUrl = `${config_js_1.API_URL}/api/registry/@${pluginSlug}/plugin`;
+                    console.log(`\n  \x1b[90mClaude Code 플러그인:\x1b[0m`);
+                    console.log(`  \x1b[36m/plugin marketplace add ${pluginUrl}\x1b[0m`);
+                }
                 // Show shareable onboarding guide as a plain copyable block
                 if (isTTY) {
                     const detailSlug = result.slug.startsWith('@') ? result.slug.slice(1) : result.slug;

package/dist/commands/update.js

@@ -9,6 +9,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const api_js_1 = require("../lib/api.js");
 const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 const installer_js_1 = require("../lib/installer.js");
 const config_js_1 = require("../lib/config.js");
 const slug_js_1 = require("../lib/slug.js");
@@ -76,13 +77,30 @@ function registerUpdate(program) {
             const agentDir = currentScope === 'global'
                 ? path_1.default.join(os_1.default.homedir(), '.relay', 'agents', owner, name)
                 : path_1.default.join(projectPath, '.relay', 'agents', owner, name);
-            // Download & extract
-            const tarPath = await (0, storage_js_1.downloadPackage)(agent.package_url, tempDir);
-            if (fs_1.default.existsSync(agentDir)) {
-                fs_1.default.rmSync(agentDir, { recursive: true, force: true });
+            // Download & extract: prefer git, fallback to tar.gz
+            if (agent.git_url && fs_1.default.existsSync(path_1.default.join(agentDir, '.git'))) {
+                // Existing git clone — fetch + checkout latest tag
+                (0, git_operations_js_1.checkGitInstalled)();
+                (0, git_operations_js_1.gitFetch)(agentDir);
+                const latestTag = (0, git_operations_js_1.gitLatestTag)(agentDir);
+                if (latestTag) {
+                    (0, git_operations_js_1.gitCheckout)(agentDir, latestTag);
+                }
+            }
+            else if (agent.git_url) {
+                // No existing clone — fresh git clone
+                (0, git_operations_js_1.checkGitInstalled)();
+                await (0, storage_js_1.clonePackage)(agent.git_url, agentDir);
+            }
+            else {
+                // Legacy tar.gz path
+                const tarPath = await (0, storage_js_1.downloadPackage)(agent.package_url, tempDir);
+                if (fs_1.default.existsSync(agentDir)) {
+                    fs_1.default.rmSync(agentDir, { recursive: true, force: true });
+                }
+                fs_1.default.mkdirSync(agentDir, { recursive: true });
+                await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             }
-            fs_1.default.mkdirSync(agentDir, { recursive: true });
-            await (0, storage_js_1.extractPackage)(tarPath, agentDir);
             // Inject preamble
             (0, preamble_js_1.injectPreambleToAgent)(agentDir, slug);
             // Deploy symlinks (always — handles migration from legacy deployed_files)

package/dist/index.js

@@ -24,6 +24,7 @@ const access_js_1 = require("./commands/access.js");
 const grant_js_1 = require("./commands/grant.js");
 const versions_js_1 = require("./commands/versions.js");
 const diff_js_1 = require("./commands/diff.js");
+const export_js_1 = require("./commands/export.js");
 const feedback_js_1 = require("./commands/feedback.js");
 const server_js_1 = require("./mcp/server.js");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
@@ -56,6 +57,7 @@ program
 (0, grant_js_1.registerGrant)(program);
 (0, versions_js_1.registerVersions)(program);
 (0, diff_js_1.registerDiff)(program);
+(0, export_js_1.registerExport)(program);
 (0, feedback_js_1.registerFeedback)(program);
 program
     .command('mcp')

package/dist/lib/git-operations.d.ts

@@ -0,0 +1,38 @@
+export declare function checkGitInstalled(): void;
+export declare function gitInit(dir: string): void;
+export declare function gitClone(url: string, destDir: string, opts?: {
+    depth?: number;
+}): void;
+export declare function gitAdd(dir: string, files?: string): void;
+export declare function gitCommit(dir: string, message: string): void;
+export declare function gitTag(dir: string, tag: string): void;
+export declare function gitPush(dir: string, remote: string, refspec?: string): void;
+export declare function gitFetch(dir: string): void;
+export declare function gitCheckout(dir: string, ref: string): void;
+export declare function gitDiff(dir: string, from: string, to: string): string;
+export declare function gitLatestTag(dir: string): string | null;
+/**
+ * Build an authenticated git URL.
+ * For public repos: https://git.relayax.com/@owner/agent.git
+ * For gated/private: https://TOKEN:x@git.relayax.com/@owner/agent.git
+ */
+export declare function buildGitUrl(baseUrl: string, auth?: {
+    token?: string;
+    code?: string;
+}): string;
+/**
+ * First-time publish: init → add → commit → tag → push
+ */
+export declare function gitPublishInit(sourceDir: string, remoteUrl: string, version: string): Promise<void>;
+/**
+ * Re-publish: clone → replace files → commit → tag → push
+ */
+export declare function gitPublishUpdate(sourceDir: string, remoteUrl: string, version: string): Promise<void>;
+/**
+ * Install: git clone to destination, optionally checkout a specific version.
+ */
+export declare function gitInstall(gitUrl: string, destDir: string, version?: string): Promise<void>;
+/**
+ * Update: fetch latest then checkout the newest tag.
+ */
+export declare function gitUpdate(destDir: string): Promise<string | null>;

package/dist/lib/git-operations.js

@@ -0,0 +1,168 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkGitInstalled = checkGitInstalled;
+exports.gitInit = gitInit;
+exports.gitClone = gitClone;
+exports.gitAdd = gitAdd;
+exports.gitCommit = gitCommit;
+exports.gitTag = gitTag;
+exports.gitPush = gitPush;
+exports.gitFetch = gitFetch;
+exports.gitCheckout = gitCheckout;
+exports.gitDiff = gitDiff;
+exports.gitLatestTag = gitLatestTag;
+exports.buildGitUrl = buildGitUrl;
+exports.gitPublishInit = gitPublishInit;
+exports.gitPublishUpdate = gitPublishUpdate;
+exports.gitInstall = gitInstall;
+exports.gitUpdate = gitUpdate;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+// ─── Git Binary Check ───
+function checkGitInstalled() {
+    try {
+        (0, child_process_1.execFileSync)('git', ['--version'], { stdio: 'pipe' });
+    }
+    catch {
+        throw new Error('git이 설치되어 있지 않습니다.\n' +
+            '  macOS: xcode-select --install\n' +
+            '  Ubuntu/Debian: sudo apt install git\n' +
+            '  Windows: https://git-scm.com/download/win');
+    }
+}
+// ─── Core Git Operations ───
+function gitInit(dir) {
+    (0, child_process_1.execFileSync)('git', ['init'], { cwd: dir, stdio: 'pipe' });
+}
+function gitClone(url, destDir, opts) {
+    const args = ['clone'];
+    if (opts?.depth) {
+        args.push('--depth', String(opts.depth));
+    }
+    args.push(url, destDir);
+    (0, child_process_1.execFileSync)('git', args, { stdio: 'pipe' });
+}
+function gitAdd(dir, files = '.') {
+    (0, child_process_1.execFileSync)('git', ['add', files], { cwd: dir, stdio: 'pipe' });
+}
+function gitCommit(dir, message) {
+    // Configure committer for the temp repo
+    (0, child_process_1.execFileSync)('git', ['config', 'user.email', 'relay@relayax.com'], { cwd: dir, stdio: 'pipe' });
+    (0, child_process_1.execFileSync)('git', ['config', 'user.name', 'Relay CLI'], { cwd: dir, stdio: 'pipe' });
+    (0, child_process_1.execFileSync)('git', ['commit', '-m', message], { cwd: dir, stdio: 'pipe' });
+}
+function gitTag(dir, tag) {
+    (0, child_process_1.execFileSync)('git', ['tag', tag], { cwd: dir, stdio: 'pipe' });
+}
+function gitPush(dir, remote, refspec) {
+    const args = ['push', remote];
+    if (refspec)
+        args.push(refspec);
+    args.push('--tags');
+    (0, child_process_1.execFileSync)('git', args, { cwd: dir, stdio: 'pipe' });
+}
+function gitFetch(dir) {
+    (0, child_process_1.execFileSync)('git', ['fetch', '--tags'], { cwd: dir, stdio: 'pipe' });
+}
+function gitCheckout(dir, ref) {
+    (0, child_process_1.execFileSync)('git', ['checkout', ref], { cwd: dir, stdio: 'pipe' });
+}
+function gitDiff(dir, from, to) {
+    return (0, child_process_1.execFileSync)('git', ['diff', `${from}..${to}`], {
+        cwd: dir,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+}
+function gitLatestTag(dir) {
+    try {
+        const result = (0, child_process_1.execFileSync)('git', ['describe', '--tags', '--abbrev=0'], {
+            cwd: dir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return result || null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── High-level Operations ───
+/**
+ * Build an authenticated git URL.
+ * For public repos: https://git.relayax.com/@owner/agent.git
+ * For gated/private: https://TOKEN:x@git.relayax.com/@owner/agent.git
+ */
+function buildGitUrl(baseUrl, auth) {
+    if (!auth?.token && !auth?.code)
+        return baseUrl;
+    const url = new URL(baseUrl);
+    const credential = auth.token ?? auth.code ?? '';
+    url.username = credential;
+    url.password = 'x';
+    return url.toString();
+}
+/**
+ * First-time publish: init → add → commit → tag → push
+ */
+async function gitPublishInit(sourceDir, remoteUrl, version) {
+    gitInit(sourceDir);
+    gitAdd(sourceDir);
+    gitCommit(sourceDir, `v${version}`);
+    gitTag(sourceDir, `v${version}`);
+    gitPush(sourceDir, remoteUrl, 'HEAD:main');
+}
+/**
+ * Re-publish: clone → replace files → commit → tag → push
+ */
+async function gitPublishUpdate(sourceDir, remoteUrl, version) {
+    const tempCloneDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'relay-git-'));
+    try {
+        // Clone existing repo
+        gitClone(remoteUrl, tempCloneDir);
+        // Copy .git directory to source dir
+        const gitDir = path_1.default.join(tempCloneDir, '.git');
+        const destGitDir = path_1.default.join(sourceDir, '.git');
+        fs_1.default.cpSync(gitDir, destGitDir, { recursive: true });
+        // Add all files (including new/changed, removing deleted)
+        gitAdd(sourceDir);
+        gitCommit(sourceDir, `v${version}`);
+        gitTag(sourceDir, `v${version}`);
+        gitPush(sourceDir, 'origin');
+    }
+    finally {
+        fs_1.default.rmSync(tempCloneDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Install: git clone to destination, optionally checkout a specific version.
+ */
+async function gitInstall(gitUrl, destDir, version) {
+    // Remove existing directory if present
+    if (fs_1.default.existsSync(destDir)) {
+        fs_1.default.rmSync(destDir, { recursive: true, force: true });
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(destDir), { recursive: true });
+    gitClone(gitUrl, destDir, { depth: 1 });
+    if (version) {
+        // Fetch all tags then checkout the specific version
+        gitFetch(destDir);
+        gitCheckout(destDir, `v${version}`);
+    }
+}
+/**
+ * Update: fetch latest then checkout the newest tag.
+ */
+async function gitUpdate(destDir) {
+    gitFetch(destDir);
+    const latestTag = gitLatestTag(destDir);
+    if (latestTag) {
+        gitCheckout(destDir, latestTag);
+    }
+    return latestTag;
+}

package/dist/lib/guide.js

@@ -29,16 +29,25 @@ function generateGuide(config, commands, requires) {
     const scopedSlug = config.slug.startsWith('@') ? config.slug : `@${config.slug}`;
     const installCmd = `npx relayax-cli install ${scopedSlug}`;
     const requiresSummary = requires ? buildRequiresSummary(requires) : '';
+    const slugPart = scopedSlug.startsWith('@') ? scopedSlug.slice(1) : scopedSlug;
+    const pluginUrl = `https://www.relayax.com/api/registry/${slugPart}/plugin`;
     return `# ${config.name}
 
 > ${config.description}
 
 ## 설치
 
+### CLI
 \`\`\`bash
 ${installCmd}
 \`\`\`
 
+### Claude Code Plugin
+\`\`\`
+/plugin marketplace add ${pluginUrl}
+/plugin install ${config.slug.split('/').pop() ?? config.slug}
+\`\`\`
+
 ${commands.length > 0 ? `## 포함된 커맨드
 
 ${commands.map((cmd) => `- \`/${cmd.name}\`: ${cmd.description}`).join('\n')}

package/dist/lib/manifest-generator.d.ts

@@ -0,0 +1,20 @@
+export interface GeneratedFile {
+    relativePath: string;
+    content: string;
+}
+export interface ManifestRelayYaml {
+    name: string;
+    slug: string;
+    description: string;
+    version: string;
+    source?: string;
+    org_slug?: string;
+    platforms?: string[];
+}
+export declare const SUPPORTED_PLATFORMS: readonly ["claude-code", "codex", "antigravity"];
+export type Platform = typeof SUPPORTED_PLATFORMS[number];
+/**
+ * Generate platform-native manifests from relay.yaml metadata.
+ * Used by both `relay publish` and `relay export`.
+ */
+export declare function generateManifests(yaml: ManifestRelayYaml, agentDir: string): GeneratedFile[];

package/dist/lib/manifest-generator.js

@@ -0,0 +1,144 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PLATFORMS = void 0;
+exports.generateManifests = generateManifests;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.SUPPORTED_PLATFORMS = ['claude-code', 'codex', 'antigravity'];
+// ─── Claude Code Generator ───
+function generateClaudeCodeManifest(yaml, agentDir) {
+    const files = [];
+    // .claude-plugin/plugin.json
+    const pluginJson = {
+        name: yaml.slug.replace(/^@/, ''),
+        description: yaml.description,
+        version: yaml.version,
+    };
+    if (yaml.source) {
+        pluginJson.repository = yaml.source;
+    }
+    if (yaml.org_slug) {
+        pluginJson.author = { name: yaml.org_slug };
+    }
+    files.push({
+        relativePath: '.claude-plugin/plugin.json',
+        content: JSON.stringify(pluginJson, null, 2),
+    });
+    // marketplace.json (self-contained marketplace with single plugin entry)
+    const slug = yaml.slug.startsWith('@') ? yaml.slug.slice(1) : yaml.slug;
+    const parts = slug.split('/');
+    const owner = parts[0] ?? slug;
+    const pluginName = parts[1] ?? slug;
+    const marketplaceJson = {
+        name: `@${slug}`,
+        owner: { name: owner },
+        plugins: [
+            {
+                name: pluginName,
+                source: {
+                    source: 'url',
+                    url: './',
+                },
+                version: yaml.version,
+            },
+        ],
+    };
+    files.push({
+        relativePath: 'marketplace.json',
+        content: JSON.stringify(marketplaceJson, null, 2),
+    });
+    return files;
+}
+// ─── Codex Generator ───
+function generateCodexManifest(yaml, agentDir) {
+    const pluginJson = {
+        name: yaml.slug.replace(/^@/, ''),
+        description: yaml.description,
+        version: yaml.version,
+    };
+    // Check if skills/ directory exists
+    const skillsDir = path_1.default.join(agentDir, 'skills');
+    if (fs_1.default.existsSync(skillsDir)) {
+        pluginJson.skills = './skills/';
+    }
+    return [
+        {
+            relativePath: '.codex-plugin/plugin.json',
+            content: JSON.stringify(pluginJson, null, 2),
+        },
+    ];
+}
+// ─── Antigravity Generator ───
+function generateAntigravityManifest(yaml, agentDir) {
+    // Antigravity uses .agent/skills/ structure
+    // Only generate if skills/ directory exists
+    const skillsDir = path_1.default.join(agentDir, 'skills');
+    if (!fs_1.default.existsSync(skillsDir)) {
+        return [];
+    }
+    // Map skills/ to .agent/skills/ — no content changes, just path mapping
+    const files = [];
+    const skillEntries = fs_1.default.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of skillEntries) {
+        if (entry.isDirectory()) {
+            const skillMd = path_1.default.join(skillsDir, entry.name, 'SKILL.md');
+            if (fs_1.default.existsSync(skillMd)) {
+                const content = fs_1.default.readFileSync(skillMd, 'utf-8');
+                files.push({
+                    relativePath: `.agent/skills/${entry.name}/SKILL.md`,
+                    content,
+                });
+            }
+        }
+    }
+    return files;
+}
+// ─── Platform Registry ───
+const GENERATORS = {
+    'claude-code': generateClaudeCodeManifest,
+    'codex': generateCodexManifest,
+    'antigravity': generateAntigravityManifest,
+};
+// ─── Public API ───
+/**
+ * Generate platform-native manifests from relay.yaml metadata.
+ * Used by both `relay publish` and `relay export`.
+ */
+function generateManifests(yaml, agentDir) {
+    const platforms = resolvePlatforms(yaml.platforms);
+    const files = [];
+    for (const platform of platforms) {
+        const generator = GENERATORS[platform];
+        if (generator) {
+            try {
+                files.push(...generator(yaml, agentDir));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`\x1b[33m⚠ ${platform} 매니페스트 생성 실패: ${msg}\x1b[0m`);
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Resolve platforms list: filter valid platforms, warn on invalid ones.
+ */
+function resolvePlatforms(platforms) {
+    if (!platforms || platforms.length === 0) {
+        return [...exports.SUPPORTED_PLATFORMS];
+    }
+    const valid = [];
+    for (const p of platforms) {
+        if (exports.SUPPORTED_PLATFORMS.includes(p)) {
+            valid.push(p);
+        }
+        else {
+            console.error(`\x1b[33m⚠ 지원하지 않는 플랫폼: ${p} (지원: ${exports.SUPPORTED_PLATFORMS.join(', ')})\x1b[0m`);
+        }
+    }
+    return valid;
+}

package/dist/lib/storage.d.ts

@@ -2,3 +2,8 @@ export declare function downloadPackage(url: string, destDir: string): Promise<s
 export declare function extractPackage(tarPath: string, destDir: string): Promise<void>;
 export declare function makeTempDir(): string;
 export declare function removeTempDir(dir: string): void;
+/**
+ * Clone an agent from git URL to destination directory.
+ * Replaces downloadPackage() + extractPackage() for git-based agents.
+ */
+export declare function clonePackage(gitUrl: string, destDir: string, version?: string): Promise<void>;

package/dist/lib/storage.js

@@ -7,6 +7,7 @@ exports.downloadPackage = downloadPackage;
 exports.extractPackage = extractPackage;
 exports.makeTempDir = makeTempDir;
 exports.removeTempDir = removeTempDir;
+exports.clonePackage = clonePackage;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -14,6 +15,7 @@ const fs_2 = require("fs");
 const promises_1 = require("stream/promises");
 const stream_1 = require("stream");
 const tar_1 = require("tar");
+const git_operations_js_1 = require("./git-operations.js");
 async function downloadPackage(url, destDir) {
     const res = await fetch(url);
     if (!res.ok) {
@@ -41,3 +43,10 @@ function makeTempDir() {
 function removeTempDir(dir) {
     fs_1.default.rmSync(dir, { recursive: true, force: true });
 }
+/**
+ * Clone an agent from git URL to destination directory.
+ * Replaces downloadPackage() + extractPackage() for git-based agents.
+ */
+async function clonePackage(gitUrl, destDir, version) {
+    await (0, git_operations_js_1.gitInstall)(gitUrl, destDir, version);
+}

package/dist/mcp/server.js

@@ -12,6 +12,7 @@ const config_js_1 = require("../lib/config.js");
 const api_js_1 = require("../lib/api.js");
 const slug_js_1 = require("../lib/slug.js");
 const storage_js_1 = require("../lib/storage.js");
+const git_operations_js_1 = require("../lib/git-operations.js");
 const ai_tools_js_1 = require("../lib/ai-tools.js");
 const preamble_js_1 = require("../lib/preamble.js");
 const installer_js_1 = require("../lib/installer.js");
@@ -124,38 +125,56 @@ function createMcpServer() {
             }
             const tempDir = (0, storage_js_1.makeTempDir)();
             try {
-                const tarPath = await (0, storage_js_1.downloadPackage)(agent.package_url, tempDir);
                 const agentDir = path_1.default.join(projectPath, '.relay', 'agents', parsed.owner, parsed.name);
-                if (fs_1.default.existsSync(agentDir))
-                    fs_1.default.rmSync(agentDir, { recursive: true, force: true });
-                fs_1.default.mkdirSync(agentDir, { recursive: true });
-                await (0, storage_js_1.extractPackage)(tarPath, agentDir);
+                if (agent.git_url) {
+                    // Git clone path
+                    (0, git_operations_js_1.checkGitInstalled)();
+                    await (0, storage_js_1.clonePackage)(agent.git_url, agentDir);
+                }
+                else {
+                    // Legacy tar.gz path
+                    const tarPath = await (0, storage_js_1.downloadPackage)(agent.package_url, tempDir);
+                    if (fs_1.default.existsSync(agentDir))
+                        fs_1.default.rmSync(agentDir, { recursive: true, force: true });
+                    fs_1.default.mkdirSync(agentDir, { recursive: true });
+                    await (0, storage_js_1.extractPackage)(tarPath, agentDir);
+                }
                 (0, preamble_js_1.injectPreambleToAgent)(agentDir, fullSlug);
                 const installed = (0, config_js_1.loadInstalled)();
                 installed[fullSlug] = { agent_id: agent.id, version: agent.version, installed_at: new Date().toISOString(), files: [agentDir] };
                 (0, config_js_1.saveInstalled)(installed);
                 await (0, api_js_1.reportInstall)(agent.id, fullSlug, agent.version);
                 (0, api_js_1.sendUsagePing)(agent.id, fullSlug, agent.version);
-                // relay.yaml에서 tags, requires 읽기 (scope 판단용)
+                // relay.yaml에서 tags, requires, recommended_scope 읽기
                 let agentTags = [];
                 let agentRequires = null;
                 let hasRules = false;
+                let recommendedScope;
                 try {
                     const relayYamlPath = path_1.default.join(agentDir, 'relay.yaml');
                     if (fs_1.default.existsSync(relayYamlPath)) {
                         const cfg = js_yaml_1.default.load(fs_1.default.readFileSync(relayYamlPath, 'utf-8'));
                         agentTags = cfg.tags ?? [];
                         agentRequires = cfg.requires ?? null;
+                        if (cfg.recommended_scope === 'global' || cfg.recommended_scope === 'local') {
+                            recommendedScope = cfg.recommended_scope;
+                        }
                     }
                     hasRules = fs_1.default.existsSync(path_1.default.join(agentDir, 'rules')) && fs_1.default.readdirSync(path_1.default.join(agentDir, 'rules')).length > 0;
                 }
                 catch { /* non-critical */ }
+                // recommended_scope가 relay.yaml에 없으면 휴리스틱으로 추론
+                if (!recommendedScope) {
+                    const frameworkTags = ['nextjs', 'react', 'vue', 'angular', 'svelte', 'nuxt', 'remix', 'astro', 'django', 'rails', 'laravel', 'spring', 'express', 'fastapi', 'flask'];
+                    recommendedScope = (hasRules || agentTags.some((t) => frameworkTags.includes(t.toLowerCase()))) ? 'local' : 'global';
+                }
                 const cliUpdate = await getCliUpdateWarning();
                 return { content: [jsonTextWithUpdate({
                             status: 'ok', agent: agent.name, slug: fullSlug, version: agent.version,
                             description: agent.description ?? '', tags: agentTags, requires: agentRequires, has_rules: hasRules,
+                            recommended_scope: recommendedScope,
                             files: countFiles(agentDir), install_path: agentDir,
-                            scope_hint: '설치 후 에이전트 성격에 따라 글로벌/로컬 배치를 사용자에게 물어보세요. tags에 특정 프레임워크가 있거나 rules/가 있으면 로컬 추천, 범용이면 글로벌 추천.',
+                            scope_hint: `이 에이전트의 권장 배치 범위는 "${recommendedScope}"입니다. 사용자에게 확인 후 relay deploy --scope ${recommendedScope}로 배치하세요.`,
                         }, cliUpdate)] };
             }
             finally {

package/dist/types.d.ts

@@ -32,11 +32,14 @@ export interface AgentRegistryInfo {
     description?: string;
     version: string;
     package_url: string;
+    git_url?: string;
     commands: {
         name: string;
         description: string;
     }[];
     type?: 'command' | 'passive' | 'hybrid';
+    /** 에이전트 제작자가 권장하는 배치 범위 */
+    recommended_scope?: 'global' | 'local';
     agent_details?: {
         name: string;
         description: string;

package/package.json

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