@storyclaw/talenthub 0.3.7 → 0.3.8

package/README.md

@@ -0,0 +1,273 @@
+# @storyclaw/talenthub
+
+CLI tool to manage StoryClaw AI agents — publish, install, update, and browse the TalentHub marketplace.
+
+[中文文档](#中文文档)
+
+## Install
+
+```bash
+npm install -g @storyclaw/talenthub
+```
+
+## Quick Start
+
+```bash
+# Login
+talenthub login
+
+# Initialize an agent
+talenthub agent init --dir ~/.openclaw/workspace-my-agent
+
+# Publish it
+talenthub agent publish --dir ~/.openclaw/workspace-my-agent
+
+# Browse & install agents
+talenthub agent search
+talenthub agent install <agent-name>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `talenthub login` | Authenticate with StoryClaw |
+| `talenthub logout` | Remove stored credentials |
+| `talenthub agent init` | Initialize a new agent with manifest.json and prompt files |
+| `talenthub agent publish` | Publish a local agent to the registry |
+| `talenthub agent unpublish <name>` | Archive an agent from the registry |
+| `talenthub agent install <name>` | Install an agent and its skills |
+| `talenthub agent update [name]` | Update an agent or all agents (`--all`, `--json`) |
+| `talenthub agent uninstall <name>` | Remove an installed agent |
+| `talenthub agent list` | List installed agents and check for updates |
+| `talenthub agent search [query]` | Browse available agents |
+
+## Agent Structure
+
+A publishable agent directory contains:
+
+| File | Required | Description |
+|------|----------|-------------|
+| `manifest.json` | **Required** | Agent metadata (id, name, category, etc.) |
+| `IDENTITY.md` | Yes | Core identity and personality prompt |
+| `USER.md` | Optional | User-facing instructions |
+| `SOUL.md` | Optional | Deep personality and behavioral guidelines |
+| `AGENTS.md` | Optional | Multi-agent coordination instructions |
+
+### manifest.json
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "emoji": "🤖",
+  "role": "Assistant",
+  "tagline": "A helpful AI assistant",
+  "description": "Longer description of what this agent does.",
+  "category": "productivity",
+  "skills": [],
+  "i18n": {},
+  "minOpenClawVersion": "2026.3.1"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier (lowercase alphanumeric + hyphens) |
+| `name` | string | Human-readable display name |
+| `emoji` | string | Single emoji icon |
+| `role` | string | Short role description |
+| `tagline` | string | One-line summary for search results |
+| `description` | string | Longer description for detail page |
+| `category` | string | One of: `creative`, `finance`, `productivity`, `companion`, `research`, `engineering` |
+| `skills` | string[] | Skill specs (e.g. `https://github.com/owner/repo@skill-name`) |
+| `i18n` | object | Translations keyed by locale (`zh-CN`, `zh-TW`, `ja`). Fill via web interface. |
+| `minOpenClawVersion` | string | Minimum StoryClaw version required |
+| `avatarUrl` | string \| null | Optional avatar image URL |
+
+> **Note:** Version is not in the manifest — it is generated automatically by the server.
+
+### Size Limits
+
+- Each file: **200 KB** max
+- Total across all files: **1 MB** max
+
+## Publishing
+
+```bash
+# From a directory (recommended)
+talenthub agent publish --dir /path/to/agent
+
+# From an installed agent
+talenthub agent publish --name my-agent
+
+# From the current directory
+talenthub agent publish
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dir <path>` | Agent directory with manifest.json and .md files |
+| `--name <name>` | Agent name in openclaw config (resolves workspace dir) |
+| `--id <id>` | Override agent ID from manifest |
+
+## Versioning
+
+Versions are fully server-managed in `YYYY.MM.DD-X` format (e.g. `2026.04.13-1`).
+
+- **New agent** → `YYYY.MM.DD-1`
+- **Core field changes** (skills, USER.md, SOUL.md, AGENTS.md) → version auto-bumps
+- **Metadata-only changes** (emoji, role, tagline, etc.) → version stays the same
+
+Previous versions are automatically saved as snapshots.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `TALENTHUB_URL` | Override registry base URL (default: `https://app.storyclaw.com`) |
+| `TALENTHUB_REGISTRY` | Alias for `TALENTHUB_URL` |
+
+## Docs
+
+- [Publishing Guide (English)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.md)
+- [Publishing Guide (中文)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.zh-CN.md)
+
+## License
+
+MIT
+
+---
+
+## 中文文档
+
+StoryClaw AI Agent 管理工具 — 发布、安装、更新和浏览 TalentHub 市场。
+
+[English](#storyclawtalenthub)
+
+### 安装
+
+```bash
+npm install -g @storyclaw/talenthub
+```
+
+### 快速开始
+
+```bash
+# 登录
+talenthub login
+
+# 初始化 Agent
+talenthub agent init --dir ~/.openclaw/workspace-my-agent
+
+# 发布
+talenthub agent publish --dir ~/.openclaw/workspace-my-agent
+
+# 浏览和安装
+talenthub agent search
+talenthub agent install <agent-name>
+```
+
+### 命令列表
+
+| 命令 | 说明 |
+|------|------|
+| `talenthub login` | 登录 StoryClaw |
+| `talenthub logout` | 退出登录 |
+| `talenthub agent init` | 初始化新 Agent（生成 manifest.json 和提示词文件） |
+| `talenthub agent publish` | 发布 Agent 到注册中心 |
+| `talenthub agent unpublish <name>` | 下架 Agent |
+| `talenthub agent install <name>` | 安装 Agent 及其技能 |
+| `talenthub agent update [name]` | 更新 Agent（`--all` 更新全部，`--json` 结构化输出） |
+| `talenthub agent uninstall <name>` | 卸载 Agent |
+| `talenthub agent list` | 列出已安装的 Agent |
+| `talenthub agent search [query]` | 搜索可用 Agent |
+
+### Agent 目录结构
+
+| 文件 | 是否必须 | 说明 |
+|------|----------|------|
+| `manifest.json` | **必须** | Agent 元数据（ID、名称、分类等） |
+| `IDENTITY.md` | 必须 | 核心身份和人设提示词 |
+| `USER.md` | 可选 | 面向用户的使用说明 |
+| `SOUL.md` | 可选 | 深层性格和行为准则 |
+| `AGENTS.md` | 可选 | 多 Agent 协作指令 |
+
+### manifest.json
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "emoji": "🤖",
+  "role": "Assistant",
+  "tagline": "一句话描述你的 Agent",
+  "description": "更详细的介绍。",
+  "category": "productivity",
+  "skills": [],
+  "i18n": {},
+  "minOpenClawVersion": "2026.3.1"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 唯一标识符，小写字母加连字符 |
+| `name` | string | 显示名称 |
+| `emoji` | string | 一个 emoji 图标 |
+| `role` | string | 角色简述 |
+| `tagline` | string | 一行摘要 |
+| `description` | string | 详细描述 |
+| `category` | string | `creative`、`finance`、`productivity`、`companion`、`research`、`engineering` |
+| `skills` | string[] | 技能包列表（如 `https://github.com/owner/repo@skill-name`） |
+| `i18n` | object | 按语言代码存放翻译（`zh-CN`、`zh-TW`、`ja`），可通过网页界面填写 |
+| `minOpenClawVersion` | string | 最低 StoryClaw 版本 |
+| `avatarUrl` | string \| null | 头像 URL（可选） |
+
+> **注意：** manifest 中没有 `version` 字段，版本由服务器自动生成。
+
+### 发布
+
+```bash
+# 从目录发布（推荐）
+talenthub agent publish --dir /path/to/agent
+
+# 从已安装的 Agent 发布
+talenthub agent publish --name my-agent
+
+# 从当前目录发布
+talenthub agent publish
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--dir <path>` | Agent 目录 |
+| `--name <name>` | openclaw 配置中的 Agent 名称 |
+| `--id <id>` | 覆盖 manifest 中的 Agent ID |
+
+### 版本管理
+
+版本完全由服务器管理，格式为 `YYYY.MM.DD-X`（如 `2026.04.13-1`）。
+
+- **新 Agent** → `YYYY.MM.DD-1`
+- **核心字段变更**（skills、USER.md、SOUL.md、AGENTS.md）→ 版本自动递增
+- **仅元数据变更**（emoji、role、tagline 等）→ 版本不变
+
+每次版本递增时自动保存上一版本快照。
+
+### 文件大小限制
+
+- 单个文件：最大 **200 KB**
+- 所有文件总计：最大 **1 MB**
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `TALENTHUB_URL` | 覆盖注册中心地址（默认：`https://app.storyclaw.com`） |
+| `TALENTHUB_REGISTRY` | `TALENTHUB_URL` 的别名 |
+
+### 详细文档
+
+- [发布指南（中文）](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.zh-CN.md)
+- [Publishing Guide (English)](https://github.com/storyclaw-official/talenthub/blob/main/docs/publishing-guide.md)

package/dist/cli.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 // try IPv4 first to avoid EHOSTUNREACH delays on every fetch.
 dns.setDefaultResultOrder("ipv4first");
 import { Command } from "commander";
+import { agentInit } from "./commands/agent-init.js";
 import { agentInstall } from "./commands/agent-install.js";
 import { agentList } from "./commands/agent-list.js";
 import { agentPublish } from "./commands/agent-publish.js";
@@ -30,6 +31,11 @@ program
     .action(login);
 program.command("logout").description("Remove stored credentials").action(logout);
 const agent = program.command("agent").description("Agent management commands");
+agent
+    .command("init")
+    .description("Initialize a new agent with manifest.json and prompt files")
+    .option("-d, --dir <path>", "Target directory (defaults to current directory)")
+    .action(agentInit);
 agent
     .command("install <name>")
     .description("Install an agent and its skills")
@@ -41,6 +47,7 @@ agent
     .command("update [name]")
     .description("Update an agent or all agents")
     .option("-a, --all", "Update all installed agents")
+    .option("--json", "Output structured JSONL progress for machine consumption", false)
     .action(agentUpdate);
 agent
     .command("uninstall <name>")
@@ -56,9 +63,11 @@ agent
     .description("Browse available agents")
     .action(agentSearch);
 agent
-    .command("publish <name>")
+    .command("publish")
     .description("Publish a local agent to the registry")
-    .option("-d, --dir <path>", "Agent directory containing manifest.json and .md files")
+    .option("-d, --dir <path>", "Agent directory containing manifest.json and .md files (defaults to current directory)")
+    .option("-n, --name <name>", "Agent name in openclaw config (used to resolve workspace dir)")
+    .option("--id <id>", "Override agent ID from manifest")
     .action(agentPublish);
 agent
     .command("unpublish <name>")

package/dist/commands/agent-init.d.ts

@@ -0,0 +1,3 @@
+export declare function agentInit(opts?: {
+    dir?: string;
+}): Promise<void>;

package/dist/commands/agent-init.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/**
+ * Parse IDENTITY.md to extract Name and Emoji fields.
+ *
+ * Expected format:
+ *   - **Name:** Aria
+ *   - **Emoji:** 🎭
+ */
+function parseIdentityMd(dir) {
+    const filePath = path.join(dir, "IDENTITY.md");
+    if (!fs.existsSync(filePath))
+        return {};
+    const content = fs.readFileSync(filePath, "utf-8");
+    const result = {};
+    const nameMatch = content.match(/\*\*Name:\*\*\s*(.+)/i);
+    if (nameMatch) {
+        // Take first part before | or — (e.g. "AI Assistant | AI 助理" → "AI Assistant")
+        result.name = nameMatch[1].split(/\s*[|—]\s*/)[0].trim();
+    }
+    const emojiMatch = content.match(/\*\*Emoji:\*\*\s*(.+)/i);
+    if (emojiMatch) {
+        const val = emojiMatch[1].trim();
+        // Skip if it says "none" or similar
+        if (val && !/^none/i.test(val)) {
+            result.emoji = val;
+        }
+    }
+    return result;
+}
+const VALID_CATEGORIES = ["creative", "finance", "productivity", "companion", "research", "engineering"];
+export async function agentInit(opts = {}) {
+    const dir = path.resolve(opts.dir || ".");
+    const manifestPath = path.join(dir, "manifest.json");
+    if (fs.existsSync(manifestPath)) {
+        console.error(`manifest.json already exists in ${dir}`);
+        process.exit(1);
+    }
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Derive defaults from directory name and IDENTITY.md
+    // Agent dirs are typically "workspace-xxx" — extract "xxx" as the id
+    const baseName = path.basename(dir);
+    const dirName = (baseName.startsWith("workspace-") ? baseName.slice("workspace-".length) : baseName)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-");
+    const identity = parseIdentityMd(dir);
+    // --- ID ---
+    const defaultId = /^[a-z0-9-]+$/.test(dirName) ? dirName : "";
+    const idInput = await prompt(defaultId ? `Agent ID [${defaultId}]: ` : "Agent ID (lowercase alphanumeric + hyphens): ");
+    const id = idInput || defaultId;
+    if (!id || !/^[a-z0-9-]+$/.test(id)) {
+        console.error("Invalid agent ID. Must be lowercase alphanumeric + hyphens only.");
+        process.exit(1);
+    }
+    // --- Name ---
+    const defaultName = identity.name || "";
+    const nameInput = await prompt(defaultName ? `Agent name [${defaultName}]: ` : "Agent name: ");
+    const name = nameInput || defaultName;
+    if (!name) {
+        console.error("Agent name is required.");
+        process.exit(1);
+    }
+    // --- Emoji ---
+    const defaultEmoji = identity.emoji || "";
+    const emojiInput = await prompt(defaultEmoji ? `Emoji [${defaultEmoji}]: ` : "Emoji (optional): ");
+    const emoji = emojiInput || defaultEmoji;
+    // --- Category ---
+    const category = await prompt(`Category (${VALID_CATEGORIES.join(", ")}) [productivity]: `);
+    const finalCategory = category || "productivity";
+    if (!VALID_CATEGORIES.includes(finalCategory)) {
+        console.error(`Invalid category. Must be one of: ${VALID_CATEGORIES.join(", ")}`);
+        process.exit(1);
+    }
+    const role = await prompt("Role (optional): ");
+    const tagline = await prompt("Tagline (optional): ");
+    const manifest = {
+        id,
+        name,
+        category: finalCategory,
+        ...(emoji && { emoji }),
+        ...(role && { role }),
+        ...(tagline && { tagline }),
+        description: "",
+        skills: [],
+        i18n: {},
+    };
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`\n✓ Created ${manifestPath}`);
+    // Create placeholder prompt files if they don't exist
+    for (const file of ["IDENTITY.md", "USER.md", "SOUL.md", "AGENTS.md"]) {
+        const filePath = path.join(dir, file);
+        if (!fs.existsSync(filePath)) {
+            fs.writeFileSync(filePath, `# ${file.replace(".md", "")}\n`);
+        }
+    }
+    console.log("✓ Created prompt files (IDENTITY.md, USER.md, SOUL.md, AGENTS.md)");
+    console.log(`\nNext: edit the prompt files, then run "talenthub agent publish ${id} --dir ${dir}"`);
+}

package/dist/commands/agent-publish.d.ts

@@ -1,3 +1,5 @@
-export declare function agentPublish(name: string, opts?: {
+export declare function agentPublish(opts?: {
     dir?: string;
+    name?: string;
+    id?: string;
 }): Promise<void>;

package/dist/commands/agent-publish.js

@@ -1,19 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import readline from "node:readline";
 import { readAuth, getRegistryBaseUrl } from "../lib/auth.js";
 import { findAgentEntry, readConfig } from "../lib/config.js";
 import { fetchRetry } from "../lib/fetch.js";
 import { resolveWorkspaceDir } from "../lib/paths.js";
-function prompt(question) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
-        });
-    });
-}
 const MAX_FILE_SIZE = 200 * 1024;
 const MAX_TOTAL_SIZE = 1024 * 1024;
 function readAgentDir(dir) {
@@ -21,15 +11,19 @@ function readAgentDir(dir) {
         console.error(`Directory not found: ${dir}`);
         process.exit(1);
     }
-    let manifest = {};
     const manifestPath = path.join(dir, "manifest.json");
-    if (fs.existsSync(manifestPath)) {
-        try {
-            manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-        }
-        catch {
-            console.warn("Warning: could not parse manifest.json.");
-        }
+    if (!fs.existsSync(manifestPath)) {
+        console.error(`manifest.json not found in ${dir}`);
+        console.error("Create a manifest.json with at least: { \"id\": \"...\", \"name\": \"...\", \"category\": \"...\" }");
+        process.exit(1);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    }
+    catch {
+        console.error("Failed to parse manifest.json.");
+        process.exit(1);
     }
     const files = {};
     let totalSize = 0;
@@ -52,7 +46,7 @@ function readAgentDir(dir) {
     }
     return { manifest, files };
 }
-export async function agentPublish(name, opts = {}) {
+export async function agentPublish(opts = {}) {
     const auth = readAuth();
     if (!auth) {
         console.error("Not logged in. Run \"talenthub login\" first.");
@@ -60,42 +54,45 @@ export async function agentPublish(name, opts = {}) {
     }
     let manifest;
     let files;
-    let fallbackName = name;
-    let fallbackModel = "claude-sonnet-4-5";
-    let fallbackSkills = [];
     if (opts.dir) {
         const agentDir = path.resolve(opts.dir);
         ({ manifest, files } = readAgentDir(agentDir));
     }
-    else {
+    else if (opts.name) {
         const cfg = readConfig();
-        const entry = findAgentEntry(cfg, name);
+        const entry = findAgentEntry(cfg, opts.name);
         if (!entry) {
-            console.error(`Agent "${name}" not found in openclaw config.`);
-            console.error("Use --dir to publish from an agent directory, or install the agent first.");
+            console.error(`Agent "${opts.name}" not found in openclaw config.`);
+            console.error("Use --dir to publish from an agent directory.");
             process.exit(1);
         }
-        fallbackName = entry.name || name;
-        fallbackModel = entry.model || fallbackModel;
-        fallbackSkills = entry.skills || [];
-        const wsDir = resolveWorkspaceDir(name);
+        const wsDir = resolveWorkspaceDir(opts.name);
         ({ manifest, files } = readAgentDir(wsDir));
     }
-    const agentId = manifest.id || name;
-    const currentVersion = manifest.version || "0.1.0";
-    const version = await prompt(`Version [${currentVersion}]: `);
-    const finalVersion = version || currentVersion;
+    else {
+        // Default to current directory
+        ;
+        ({ manifest, files } = readAgentDir(path.resolve(".")));
+    }
+    const agentId = opts.id || manifest.id;
+    if (!agentId) {
+        console.error("No agent ID found. Set \"id\" in manifest.json or use --id.");
+        process.exit(1);
+    }
+    const agentName = manifest.name;
+    if (!agentName) {
+        console.error("No agent name found. Set \"name\" in manifest.json.");
+        process.exit(1);
+    }
     const payload = {
         id: agentId,
-        version: finalVersion,
-        name: manifest.name || fallbackName,
+        name: agentName,
         emoji: manifest.emoji || "",
         role: manifest.role || "",
         tagline: manifest.tagline || "",
         description: manifest.description || "",
         category: manifest.category || "productivity",
-        model: manifest.model || fallbackModel,
-        skills: manifest.skills || fallbackSkills,
+        skills: manifest.skills || [],
         identity_prompt: files["IDENTITY.md"] || "",
         user_prompt: files["USER.md"] || "",
         soul_prompt: files["SOUL.md"] || "",
@@ -103,11 +100,9 @@ export async function agentPublish(name, opts = {}) {
         min_openclaw_version: manifest.minOpenClawVersion || null,
         avatar_url: manifest.avatarUrl || null,
         is_public: true,
-        ...(manifest.i18n && typeof manifest.i18n === "object"
-            ? { i18n: manifest.i18n }
-            : {}),
+        i18n: manifest.i18n && typeof manifest.i18n === "object" ? manifest.i18n : {},
     };
-    console.log(`\nPublishing ${payload.emoji || ""} ${payload.name} v${finalVersion}...`);
+    console.log(`\nPublishing ${payload.emoji || ""} ${payload.name}...`);
     const base = getRegistryBaseUrl();
     const url = `${base}/api/talenthub/registry/publish`;
     const res = await fetchRetry(url, {

package/dist/commands/agent-uninstall.js

@@ -43,7 +43,6 @@ export async function agentUninstall(name, options) {
     console.log(`Removed agent "${name}"` +
         (removedBindings > 0 ? ` (${removedBindings} binding(s) cleaned)` : "") +
         ".");
-    console.log("Restart the OpenClaw gateway to apply changes.");
 }
 function removeAgentFromConfig(cfg, agentId) {
     const result = removeAgent(cfg, agentId);

package/dist/commands/agent-update.d.ts

@@ -1,3 +1,4 @@
 export declare function agentUpdate(name?: string, options?: {
     all?: boolean;
+    json?: boolean;
 }): Promise<void>;

package/dist/commands/agent-update.js

@@ -6,9 +6,22 @@ import { fetchManifest } from "../lib/registry.js";
 import { resolveWorkspaceDir } from "../lib/paths.js";
 import { markInstalled, readState } from "../lib/state.js";
 import { checkUpdates } from "../lib/update-check.js";
-async function updateAgent(agentId) {
+function jsonl(obj) {
+    process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+const WEIGHT = { manifest: 10, skillsStart: 10, skillsEnd: 80, files: 90, config: 100 };
+async function updateAgent(agentId, json) {
+    const log = json ? () => { } : console.log.bind(console);
     const manifest = await fetchManifest(agentId);
     const wsDir = resolveWorkspaceDir(agentId);
+    if (json)
+        jsonl({
+            event: "start",
+            agentId: manifest.id, name: manifest.name, emoji: manifest.emoji,
+            version: manifest.version, skillCount: manifest.skills.length,
+        });
+    if (json)
+        jsonl({ event: "progress", phase: "manifest", percent: WEIGHT.manifest });
     // Backup workspace
     const backupDir = `${wsDir}.bak`;
     if (fs.existsSync(wsDir)) {
@@ -19,6 +32,7 @@ async function updateAgent(agentId) {
     }
     fs.mkdirSync(wsDir, { recursive: true });
     // Write agent files from the registry response
+    log("  Writing agent files...");
     if (manifest.files) {
         for (const [filename, content] of Object.entries(manifest.files)) {
             if (content) {
@@ -26,13 +40,36 @@ async function updateAgent(agentId) {
             }
         }
     }
-    // Install any new skills and re-sync symlinks for all
-    if (manifest.skills.length > 0) {
-        installAllSkills(manifest.skills, wsDir);
+    if (json)
+        jsonl({ event: "progress", phase: "files", percent: WEIGHT.files });
+    // Install any new skills (existing skills are skipped)
+    let installed = 0;
+    let failed = 0;
+    let skipped = 0;
+    const warnings = [];
+    const skillTotal = manifest.skills.length;
+    if (skillTotal > 0) {
+        log("  Installing new skills...");
+        const skillWeight = WEIGHT.skillsEnd - WEIGHT.skillsStart;
+        const result = installAllSkills(manifest.skills, wsDir, json ? (evt) => {
+            const percent = WEIGHT.skillsStart + Math.round((evt.current / evt.total) * skillWeight);
+            jsonl({
+                event: "progress", phase: "skills", percent,
+                detail: evt.name, current: evt.current, total: evt.total, status: evt.status,
+            });
+            if (evt.status === "failed") {
+                warnings.push(`${evt.name}: ${evt.error ?? "install failed"}`);
+            }
+        } : undefined, json);
+        installed = result.installed;
+        failed = result.failed;
+        skipped = result.skipped;
+    }
+    else {
+        if (json)
+            jsonl({ event: "progress", phase: "skills", percent: WEIGHT.skillsEnd });
     }
     // Update config
-    // Write workspace path instead of skills — the gateway discovers skills
-    // from <workspace>/skills/ symlinks that were created during skill install.
     const cfg = readConfig();
     const updatedCfg = addOrUpdateAgent(cfg, {
         id: manifest.id,
@@ -41,35 +78,51 @@ async function updateAgent(agentId) {
     });
     writeConfig(updatedCfg);
     markInstalled(manifest.id, manifest.version);
+    if (json)
+        jsonl({ event: "progress", phase: "config", percent: WEIGHT.config });
+    if (json) {
+        jsonl({ event: "done", agentId, success: true, version: manifest.version, installed, skipped, failed, warnings });
+    }
     return true;
 }
 export async function agentUpdate(name, options) {
+    const json = options?.json === true;
+    const log = json ? () => { } : console.log.bind(console);
     if (options?.all || !name) {
         const updates = await checkUpdates();
         if (updates.length === 0) {
-            console.log("All agents are up to date.");
+            if (json)
+                jsonl({ event: "done", success: true, updated: 0 });
+            else
+                log("All agents are up to date.");
             return;
         }
         // Update shared skills first
-        console.log("Updating shared skills...");
+        log("Updating shared skills...");
         updateAllSkills();
-        console.log(`\nFound ${updates.length} update(s):\n`);
+        log(`\nFound ${updates.length} update(s):\n`);
         for (const u of updates) {
-            console.log(`  Updating ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);
-            await updateAgent(u.agentId);
-            console.log(`  ✓ ${u.name} updated to ${u.latestVersion}`);
+            log(`  Updating ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);
+            await updateAgent(u.agentId, json);
+            log(`  ✓ ${u.name} updated to ${u.latestVersion}`);
         }
-        console.log("\nAll done.");
+        if (json)
+            jsonl({ event: "done", success: true, updated: updates.length });
+        else
+            log("\nAll done.");
         return;
     }
     const state = readState();
     if (!state.agents[name]) {
-        console.error(`Agent "${name}" is not installed. Use "talenthub agent install ${name}" first.`);
+        if (json)
+            jsonl({ event: "error", message: `Agent "${name}" is not installed` });
+        else
+            console.error(`Agent "${name}" is not installed. Use "talenthub agent install ${name}" first.`);
         process.exit(1);
     }
-    console.log("Updating shared skills...");
+    log("Updating shared skills...");
     updateAllSkills();
-    console.log(`Updating agent "${name}"...`);
-    await updateAgent(name);
-    console.log(`✓ Agent "${name}" updated. All done.`);
+    log(`Updating agent "${name}"...`);
+    await updateAgent(name, json);
+    log(`✓ Agent "${name}" updated. All done.`);
 }

package/dist/lib/update-check.js

@@ -1,5 +1,6 @@
 import { fetchCatalog } from "./registry.js";
 import { readState, writeState } from "./state.js";
+import { isOlderVersion } from "./version.js";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 export async function getCatalogCached() {
     const state = readState();
@@ -21,7 +22,7 @@ export async function checkUpdates() {
         const remote = catalog.agents[agentId];
         if (!remote)
             continue;
-        if (remote.version !== installed.version) {
+        if (isOlderVersion(installed.version, remote.version)) {
             updates.push({
                 agentId,
                 currentVersion: installed.version,

package/dist/lib/version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Agent version utilities.
+ *
+ * Format: YYYY.MM.DD-X
+ *   - YYYY: 4-digit year
+ *   - MM:   2-digit zero-padded month (01-12)
+ *   - DD:   2-digit zero-padded day (01-31)
+ *   - X:    positive integer counter (1, 2, 3, ...)
+ */
+/**
+ * Compare two version strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ *
+ * Falls back to string comparison if either version doesn't match the
+ * YYYY.MM.DD-X format (for backwards compatibility with old versions).
+ */
+export declare function compareVersions(a: string, b: string): -1 | 0 | 1;
+/**
+ * Check if version `a` is older than version `b`.
+ */
+export declare function isOlderVersion(a: string, b: string): boolean;

package/dist/lib/version.js

@@ -0,0 +1,53 @@
+/**
+ * Agent version utilities.
+ *
+ * Format: YYYY.MM.DD-X
+ *   - YYYY: 4-digit year
+ *   - MM:   2-digit zero-padded month (01-12)
+ *   - DD:   2-digit zero-padded day (01-31)
+ *   - X:    positive integer counter (1, 2, 3, ...)
+ */
+const VERSION_RE = /^(\d{4})\.(\d{2})\.(\d{2})-(\d+)$/;
+function parseVersion(v) {
+    const m = VERSION_RE.exec(v);
+    if (!m)
+        return null;
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    const counter = Number(m[4]);
+    if (month < 1 || month > 12 || day < 1 || day > 31 || counter < 1)
+        return null;
+    return { year: Number(m[1]), month, day, counter };
+}
+/**
+ * Compare two version strings.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ *
+ * Falls back to string comparison if either version doesn't match the
+ * YYYY.MM.DD-X format (for backwards compatibility with old versions).
+ */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    // If both parse, compare structurally
+    if (pa && pb) {
+        const fields = ["year", "month", "day", "counter"];
+        for (const field of fields) {
+            if (pa[field] < pb[field])
+                return -1;
+            if (pa[field] > pb[field])
+                return 1;
+        }
+        return 0;
+    }
+    // Fallback: string comparison (handles old "2026.3.16" style versions)
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+/**
+ * Check if version `a` is older than version `b`.
+ */
+export function isOlderVersion(a, b) {
+    return compareVersions(a, b) === -1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storyclaw/talenthub",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "CLI tool to manage StoryClaw AI agents",
   "type": "module",
   "bin": {