@hi-man/himan 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-13
+
+### Added
+
+- Added the `github-npm-publish` skill for reusable GitHub Actions npm release workflow guidance.
+- Added `himan resource rename` and top-level `himan rename`, currently marked not recommended, to rename source resources, update metadata/docs, preserve old tags, create a latest-version tag for the new name, and migrate the current project's install targets and lock entry by default.
+- Added `himan source clone` and `himan source sync` for cloning Git sources and syncing latest resource snapshots into another Git source.
+- Added static `analysis` metadata to newly scaffolded skill `himan.yaml` files and a `himan-skill-metadata` skill for generating matching metadata when agents create skills.
+
+## [0.3.5] - 2026-05-12
+
+### Changed
+
+- Changed the CLI version shortcut from `-V` to `-v`; `--version` remains supported.
+- Changed the default install mode to `copy`; pass `--mode link` to install resources as symlinks.
+
 ## [0.3.4] - 2026-05-11
 
 ### Changed

package/README.md

@@ -50,7 +50,7 @@ himan dev rule my-rule
 himan publish rule my-rule --patch
 ```
 
-- **rule / command / skill**：都支持 `create`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`。
+- **rule / command / skill**：都支持 `create`、`rename`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`；其中 `rename` 暂不推荐使用。
 - 安装后项目目标位置（按 `agents`，默认 `cursor`）：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
   - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
@@ -66,7 +66,7 @@ himan publish rule my-rule --patch
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
 - lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
-- 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
+- 安装模式：默认 `--mode copy` 将资源复制到目标 agent 目录；也可用 `--mode link` 使用软链，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
 
 版本以 Git tag 为准，格式：`rule/my-rule@1.0.0`。更多设计见 [docs/mvp](./docs/mvp/README.md)。
@@ -96,15 +96,45 @@ your-himan-source/
 - `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
 - `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
 - `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
-- `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent。
+- `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent；skill 资源可包含 `analysis` 静态分析信息。
 - `content.md` / `SKILL.md`：资源主入口；没有 `himan.yaml` 时，`rule` / `command` 默认使用 `content.md`，`skill` 默认使用 `SKILL.md`。
 
+skill 的 `himan.yaml` 推荐包含静态分析 metadata，便于 hooks、日志和后续分析系统关联 skill 内容成本与依赖：
+
+```yaml
+name: my-skill
+type: skill
+version: 0.1.0
+entry: SKILL.md
+description: Do the skill workflow.
+agents:
+  - codex
+analysis:
+  content:
+    tokenizer: approx-char-v1
+    tokenEstimator: ceil(chars/4)
+    entryTokens: 120
+    packageTokens: 180
+    contentHash: sha256:...
+    measuredAt: "2026-05-13T00:00:00.000Z"
+    measuredBy: codex
+  dependencies:
+    skills: []
+    scripts: []
+    mcpTools: []
+  generation:
+    generatedBy: codex
+    generatedAt: "2026-05-13T00:00:00.000Z"
+```
+
+`analysis` 是静态构建信息，不记录运行时 token 或执行耗时；`himan create skill` 会为新 skill scaffold 生成基础 `analysis`。
+
 可通过 `himan source init-docs` 为当前 default source 生成根目录文档模板；默认只创建缺失文件，`--force` 会覆盖已有 `README.md` / `CHANGELOG.md`，并把当前 source 中已有的 `rule`、`command`、`skill` 整理进 README 资源索引和 CHANGELOG 初始条目；资源引用会优先带上 Git tag 中的最新 semver 版本；对于尚未补齐 `himan.yaml` 的资源，会按默认入口识别，skill 还会读取 `skills/<name>/SKILL.md` front matter。`--dry-run` 可预览结果。有实际文件变更时，命令会提交并 push 到当前 Git source。
 
-`himan create` 和 `himan publish` 会自动维护 source 根目录文档：
+`himan create`、`himan rename` 和 `himan publish` 会自动维护 source 根目录文档：
 
 - `README.md`：只更新 `<!-- himan:resources:start -->` 和 `<!-- himan:resources:end -->` 之间的资源索引；如果没有 marker，会在文件末尾追加一个受控资源索引区。
-- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`publish` 记录 `Changed` / published version。
+- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`rename` / `publish` 记录 `Changed`。
 
 仓库根目录的 `README.md` 和 `CHANGELOG.md` 不会被安装到 agent 目录；agent 只消费被安装的具体资源目录。当前安装实现会 materialize 资源目录本身，因此对 Cursor 这类要求特定单文件格式的 agent，资源目录内应避免放入会干扰识别的额外文件。
 
@@ -136,6 +166,7 @@ your-himan-source/
 | `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
 | `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `rename <type> <old-name> <new-name>` | 暂不推荐使用；重命名当前 default source 中的资源；常用选项：`--dry-run`、`--no-project`、`--json` |
 
 ### 3) project（当前项目）
 
@@ -158,8 +189,8 @@ your-himan-source/
 
 也可使用分组命令（与上面等价）：
 
-- `himan resource list|history|create ...`
-- `himan-resource list|history|create ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan resource list|history|create|rename ...`
+- `himan-resource list|history|create|rename ...`（兼容保留：也可执行 install/dev/uninstall/publish）
 - `himan project list|install|dev|uninstall|publish ...`
 - `himan-project list|install|dev|uninstall|publish ...`
 - `himan agent list|use|current|clear ...`
@@ -169,9 +200,11 @@ your-himan-source/
 
 `publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
 
+`rename` 暂不推荐使用。该命令会移动 source 仓库里的资源目录并更新资源 metadata 名称、README 资源索引和 CHANGELOG。已有发布 tag 不会被改写；若旧资源已有历史版本，rename 会为新名字创建一个指向当前最新版本的 tag。默认会迁移当前项目中对应的安装目标、`.himan/dev` 副本和 lock 条目；传 `--no-project` 时只改 source。对于 skill，命令只自动更新 metadata / front matter 中的精确 `name` 字段，不会自动替换 `SKILL.md` 正文中的旧名称引用。
+
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
-多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
+多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish/rename`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
 
 ## 当前范围
 

package/dist/adapters/git/repo-manager.js

@@ -1,7 +1,9 @@
 import { promises as fs } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { simpleGit } from "simple-git";
 import { HimanError, errorCodes } from "../../utils/errors.js";
+const MANAGED_TAG_PATTERNS = ["rule/*@*", "command/*@*", "skill/*@*"];
 export class RepoManager {
     async cloneOrFetch(repo, targetDir) {
         const gitDir = path.join(targetDir, ".git");
@@ -61,6 +63,124 @@ export class RepoManager {
         await this.pushCurrentBranch(git, branch);
         return true;
     }
+    async cloneManagedSourceRefs(sourceRepoDir, targetRepo, options = {}) {
+        const sourceGit = simpleGit(sourceRepoDir);
+        await sourceGit.fetch(["--tags", "--prune"]);
+        const branch = options.branch ?? (await this.getCurrentBranch(sourceGit));
+        const sourceBranchRef = await this.resolveSourceBranchRef(sourceGit, branch);
+        const targetBranch = options.targetBranch ?? branch;
+        const targetRefs = await this.listRemoteRefs(targetRepo);
+        if (targetRefs.length > 0) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, "Target source repository is not empty.", { targetRepo, refs: targetRefs.map((item) => item.ref) });
+        }
+        const tags = await this.listManagedResourceTags(sourceRepoDir);
+        if (options.dryRun) {
+            return {
+                branch,
+                targetBranch,
+                tags,
+                dryRun: true,
+                pushed: false,
+            };
+        }
+        const refspecs = [
+            `${sourceBranchRef}:refs/heads/${targetBranch}`,
+            ...tags.map((tag) => `refs/tags/${tag}:refs/tags/${tag}`),
+        ];
+        await sourceGit.raw(["push", "--atomic", targetRepo, ...refspecs]);
+        return {
+            branch,
+            targetBranch,
+            tags,
+            dryRun: false,
+            pushed: true,
+        };
+    }
+    async syncLatestSourceSnapshot(sourceRepoDir, targetRepo, resources, options = {}) {
+        if (resources.length === 0) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, "No versioned resources found to sync.");
+        }
+        const targetBranch = options.targetBranch ?? "main";
+        const targetRefs = await this.listRemoteRefs(targetRepo);
+        const existingTagRefs = new Set(targetRefs
+            .filter((item) => item.ref.startsWith("refs/tags/"))
+            .map((item) => item.ref.slice("refs/tags/".length)));
+        const targetDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-sync-"));
+        const snapshotsDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-snapshots-"));
+        try {
+            const targetGit = await this.prepareTargetWorktree(targetRepo, targetDir, targetBranch, targetRefs);
+            const results = [];
+            for (const resource of resources) {
+                const sourceSnapshotDir = path.join(snapshotsDir, resource.type, resource.name);
+                await this.materializeSourceResourceSnapshot(sourceRepoDir, resource, sourceSnapshotDir);
+                if (existingTagRefs.has(resource.tag)) {
+                    await this.ensureExistingTagMatchesResource(targetDir, resource, sourceSnapshotDir);
+                    results.push({
+                        type: resource.type,
+                        name: resource.name,
+                        version: resource.version,
+                        tag: resource.tag,
+                        action: "skipped",
+                    });
+                }
+                else {
+                    results.push({
+                        type: resource.type,
+                        name: resource.name,
+                        version: resource.version,
+                        tag: resource.tag,
+                        action: "created",
+                    });
+                }
+                if (!options.dryRun) {
+                    const targetResourceDir = path.join(targetDir, this.getResourcePath(resource));
+                    await fs.rm(targetResourceDir, { recursive: true, force: true });
+                    await fs.mkdir(path.dirname(targetResourceDir), { recursive: true });
+                    await fs.cp(sourceSnapshotDir, targetResourceDir, { recursive: true });
+                }
+            }
+            if (options.dryRun) {
+                return {
+                    targetBranch,
+                    resources: results,
+                    dryRun: true,
+                    committed: false,
+                    pushed: false,
+                };
+            }
+            const changedPaths = [
+                ...new Set(resources.map((resource) => `${resource.type}s`)),
+            ];
+            const committed = await this.commitChanges(targetGit, "sync latest himan source resources", changedPaths, false);
+            const createdTags = results
+                .filter((result) => result.action === "created")
+                .map((result) => result.tag);
+            for (const tag of createdTags) {
+                await targetGit.addTag(tag);
+            }
+            const shouldPush = committed || createdTags.length > 0;
+            if (shouldPush) {
+                await targetGit.raw([
+                    "push",
+                    "--atomic",
+                    "origin",
+                    `${targetBranch}:refs/heads/${targetBranch}`,
+                    ...createdTags.map((tag) => `refs/tags/${tag}:refs/tags/${tag}`),
+                ]);
+            }
+            return {
+                targetBranch,
+                resources: results,
+                dryRun: false,
+                committed,
+                pushed: shouldPush,
+            };
+        }
+        finally {
+            await fs.rm(targetDir, { recursive: true, force: true });
+            await fs.rm(snapshotsDir, { recursive: true, force: true });
+        }
+    }
     async commitChanges(git, message, paths, requireChanges) {
         const pathspecs = paths.length > 0 ? paths : ["."];
         await git.add(pathspecs);
@@ -80,6 +200,132 @@ export class RepoManager {
         await git.commit(message, pathspecs);
         return true;
     }
+    async prepareTargetWorktree(targetRepo, targetDir, targetBranch, targetRefs) {
+        const hasTargetBranch = targetRefs.some((item) => item.ref === `refs/heads/${targetBranch}`);
+        if (hasTargetBranch) {
+            await simpleGit().clone(targetRepo, targetDir, ["--branch", targetBranch]);
+            const git = simpleGit(targetDir);
+            await git.fetch(["--tags", "--prune"]);
+            return git;
+        }
+        const git = simpleGit(targetDir);
+        await git.raw(["init", `--initial-branch=${targetBranch}`]);
+        await git.addRemote("origin", targetRepo);
+        if (targetRefs.some((item) => item.ref.startsWith("refs/tags/"))) {
+            await git.raw(["fetch", "origin", "+refs/tags/*:refs/tags/*"]);
+        }
+        return git;
+    }
+    async materializeSourceResourceSnapshot(sourceRepoDir, resource, targetDir) {
+        if (resource.sourceRef) {
+            await this.archiveResource(sourceRepoDir, resource.sourceRef, this.getResourcePath(resource), targetDir);
+            return;
+        }
+        if (!resource.sourcePath) {
+            throw new HimanError(errorCodes.VERSION_NOT_FOUND, `Version source not found for ${resource.type}/${resource.name}@${resource.version}.`);
+        }
+        await fs.rm(targetDir, { recursive: true, force: true });
+        await fs.mkdir(path.dirname(targetDir), { recursive: true });
+        await fs.cp(resource.sourcePath, targetDir, { recursive: true });
+    }
+    async ensureExistingTagMatchesResource(targetRepoDir, resource, sourceSnapshotDir) {
+        const previousDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-source-tag-"));
+        try {
+            await this.archiveResource(targetRepoDir, resource.tag, this.getResourcePath(resource), previousDir);
+            const [sourceSnapshot, previousSnapshot] = await Promise.all([
+                this.readDirectorySnapshot(sourceSnapshotDir),
+                this.readDirectorySnapshot(previousDir),
+            ]);
+            if (!this.snapshotsEqual(sourceSnapshot, previousSnapshot)) {
+                throw new HimanError(errorCodes.RESOURCE_EXISTS, `Target tag already exists with different content: ${resource.tag}`);
+            }
+        }
+        finally {
+            await fs.rm(previousDir, { recursive: true, force: true });
+        }
+    }
+    async listManagedResourceTags(repoDir) {
+        const tags = new Set();
+        for (const pattern of MANAGED_TAG_PATTERNS) {
+            for (const tag of await this.listTags(repoDir, pattern)) {
+                tags.add(tag);
+            }
+        }
+        return [...tags].sort((a, b) => a.localeCompare(b));
+    }
+    async listRemoteRefs(repo) {
+        const output = await simpleGit().raw(["ls-remote", "--heads", "--tags", repo]);
+        return output
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const [hash, ref] = line.split(/\s+/);
+            return { hash, ref };
+        })
+            .filter((item) => item.hash && item.ref && !item.ref.endsWith("^{}"));
+    }
+    async getCurrentBranch(git) {
+        const branch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+        if (!branch || branch === "HEAD") {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Source repository is not on a named branch.");
+        }
+        return branch;
+    }
+    async resolveSourceBranchRef(git, branch) {
+        if (await this.hasGitRef(git, `refs/heads/${branch}`)) {
+            return branch;
+        }
+        const remoteRef = `refs/remotes/origin/${branch}`;
+        if (await this.hasGitRef(git, remoteRef)) {
+            return remoteRef;
+        }
+        throw new HimanError(errorCodes.INVALID_INPUT, `Source branch not found: ${branch}`);
+    }
+    async hasGitRef(git, ref) {
+        try {
+            await git.raw(["rev-parse", "--verify", ref]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async readDirectorySnapshot(targetDir) {
+        const files = await this.listFiles(targetDir);
+        const snapshot = new Map();
+        for (const file of files) {
+            const relative = path.relative(targetDir, file).split(path.sep).join("/");
+            snapshot.set(relative, await fs.readFile(file, "utf8"));
+        }
+        return snapshot;
+    }
+    async listFiles(targetDir) {
+        const entries = await fs.readdir(targetDir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const fullPath = path.join(targetDir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await this.listFiles(fullPath)));
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+        return files.sort((a, b) => a.localeCompare(b));
+    }
+    snapshotsEqual(a, b) {
+        if (a.size !== b.size)
+            return false;
+        for (const [file, content] of a) {
+            if (b.get(file) !== content)
+                return false;
+        }
+        return true;
+    }
+    getResourcePath(resource) {
+        return `${resource.type}s/${resource.name}`;
+    }
     async pushCurrentBranch(git, branch) {
         const currentBranch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
         const targetBranch = branch ?? currentBranch;

package/dist/adapters/resource/resource-analysis.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+const TOKENIZER = "approx-char-v1";
+const TOKEN_ESTIMATOR = "ceil(chars/4)";
+export function buildResourceAnalysisMetadata(input) {
+    const measuredAt = input.measuredAt ?? new Date();
+    const packageFiles = input.packageFiles?.length
+        ? input.packageFiles
+        : [{ path: input.entry, content: input.entryContent }];
+    return {
+        content: {
+            tokenizer: TOKENIZER,
+            tokenEstimator: TOKEN_ESTIMATOR,
+            entryTokens: estimateTokens(input.entryContent),
+            packageTokens: estimateTokens(packageFiles.map((file) => file.content).join("\n")),
+            contentHash: hashPackageFiles(packageFiles),
+            measuredAt: measuredAt.toISOString(),
+            measuredBy: input.measuredBy,
+        },
+        dependencies: {
+            skills: [],
+            scripts: [],
+            mcpTools: [],
+        },
+        generation: {
+            generatedBy: input.generatedBy,
+            generatedAt: measuredAt.toISOString(),
+        },
+    };
+}
+function estimateTokens(content) {
+    return Math.ceil(content.length / 4);
+}
+function hashPackageFiles(files) {
+    const hash = createHash("sha256");
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+        hash.update(file.path);
+        hash.update("\0");
+        hash.update(file.content);
+        hash.update("\0");
+    }
+    return `sha256:${hash.digest("hex")}`;
+}

package/dist/adapters/source/git-source-adapter.js

@@ -1,5 +1,6 @@
 import { RepoManager } from "../git/repo-manager.js";
 import { ResourceScanner } from "../resource/resource-scanner.js";
+import { buildResourceAnalysisMetadata } from "../resource/resource-analysis.js";
 import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
@@ -85,19 +86,13 @@ export class GitSourceAdapter {
         if (resourceExists && !options.force) {
             throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
         }
+        const entryContent = this.getDefaultContent(type, name);
         const files = [path.join(resourceDir, "himan.yaml"), path.join(resourceDir, entry)];
         if (!options.dryRun) {
             await fs.rm(resourceDir, { recursive: true, force: true });
             await fs.mkdir(resourceDir, { recursive: true });
-            await fs.writeFile(path.join(resourceDir, "himan.yaml"), YAML.stringify({
-                name,
-                type,
-                version: "0.1.0",
-                entry,
-                description: options.description ?? `${type} resource ${name}`,
-                agents,
-            }), "utf8");
-            await fs.writeFile(path.join(resourceDir, entry), this.getDefaultContent(type, name), "utf8");
+            await fs.writeFile(path.join(resourceDir, "himan.yaml"), YAML.stringify(this.buildCreateResourceMetadata(type, name, entry, entryContent, options.description ?? `${type} resource ${name}`, agents)), "utf8");
+            await fs.writeFile(path.join(resourceDir, entry), entryContent, "utf8");
             await this.maintainSourceDocs(repoDir, {
                 section: resourceExists ? "Changed" : "Added",
                 line: resourceExists
@@ -113,6 +108,73 @@ export class GitSourceAdapter {
             dryRun: Boolean(options.dryRun),
         };
     }
+    async rename(type, oldName, newName, options = {}) {
+        const repoDir = this.getRepoDir();
+        const typeDir = this.getTypeDir(type);
+        const previousResourceDir = path.join(repoDir, typeDir, oldName);
+        const resourceDir = path.join(repoDir, typeDir, newName);
+        if (!(await this.exists(previousResourceDir))) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${oldName}`);
+        }
+        await this.ensureRenameTargetAvailable(repoDir, type, newName, resourceDir);
+        const history = await this.history(type, oldName);
+        const latestVersion = history[0]?.version;
+        const tag = latestVersion ? `${type}/${newName}@${latestVersion}` : undefined;
+        if (options.dryRun) {
+            return {
+                type,
+                oldName,
+                newName,
+                previousResourceDir,
+                resourceDir,
+                latestVersion,
+                tag,
+                committed: false,
+                dryRun: true,
+            };
+        }
+        await fs.mkdir(path.dirname(resourceDir), { recursive: true });
+        await fs.rename(previousResourceDir, resourceDir);
+        await this.updateRenamedResourceMetadata(resourceDir, type, oldName, newName);
+        const versionOverrides = latestVersion
+            ? new Map([[this.getResourceVersionOverrideKey(type, newName), latestVersion]])
+            : new Map();
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Changed",
+            line: `- Renamed \`${type}/${oldName}\` to \`${type}/${newName}\`.`,
+        }, versionOverrides);
+        const changedPaths = [
+            path.relative(repoDir, previousResourceDir),
+            path.relative(repoDir, resourceDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ];
+        if (tag) {
+            await this.repoManager.commitTagAndPush(repoDir, `rename ${type}/${oldName} to ${type}/${newName}`, tag, undefined, changedPaths);
+            return {
+                type,
+                oldName,
+                newName,
+                previousResourceDir,
+                resourceDir,
+                latestVersion,
+                tag,
+                committed: true,
+                dryRun: false,
+            };
+        }
+        const committed = await this.repoManager.commitAndPush(repoDir, `rename ${type}/${oldName} to ${type}/${newName}`, undefined, changedPaths);
+        return {
+            type,
+            oldName,
+            newName,
+            previousResourceDir,
+            resourceDir,
+            latestVersion,
+            tag,
+            committed,
+            dryRun: false,
+        };
+    }
     async initDocs(options = {}) {
         const repoDir = this.getRepoDir();
         const files = [
@@ -147,6 +209,13 @@ export class GitSourceAdapter {
             committed,
         };
     }
+    async cloneTo(targetRepo, options = {}) {
+        return this.repoManager.cloneManagedSourceRefs(this.getRepoDir(), targetRepo, options);
+    }
+    async syncLatestTo(targetRepo, options = {}) {
+        const resources = await this.collectLatestVersionedResources();
+        return this.repoManager.syncLatestSourceSnapshot(this.getRepoDir(), targetRepo, resources, options);
+    }
     getRepoDir() {
         if (!this.sourceConfig?.repoDir) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Git source is not initialized.");
@@ -171,6 +240,65 @@ export class GitSourceAdapter {
             return false;
         }
     }
+    async ensureRenameTargetAvailable(repoDir, type, newName, resourceDir) {
+        if (await this.exists(resourceDir)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${newName}`);
+        }
+        const [resources, history] = await Promise.all([
+            this.scanner.scanByType(repoDir, type),
+            this.history(type, newName),
+        ]);
+        if (resources.some((resource) => resource.name === newName) || history.length > 0) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${newName}`);
+        }
+    }
+    async updateRenamedResourceMetadata(resourceDir, type, oldName, newName) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (await this.exists(yamlPath)) {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            let parsed;
+            try {
+                parsed = YAML.parse(raw);
+            }
+            catch (error) {
+                throw this.invalidResourceMetadata(type, oldName, "himan.yaml is not valid YAML.", { yamlPath, reason: error instanceof Error ? error.message : String(error) });
+            }
+            if (!this.isRecord(parsed)) {
+                throw this.invalidResourceMetadata(type, oldName, "himan.yaml must be an object.", { yamlPath });
+            }
+            await fs.writeFile(yamlPath, YAML.stringify({
+                ...parsed,
+                name: newName,
+            }), "utf8");
+            return;
+        }
+        if (type !== "skill")
+            return;
+        await this.updateSkillFrontMatterName(path.join(resourceDir, this.getDefaultEntry(type)), oldName, newName);
+    }
+    async updateSkillFrontMatterName(skillPath, oldName, newName) {
+        if (!(await this.exists(skillPath)))
+            return;
+        const raw = await fs.readFile(skillPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+        if (!match)
+            return;
+        let parsed;
+        try {
+            parsed = YAML.parse(match[1]);
+        }
+        catch {
+            return;
+        }
+        if (!this.isRecord(parsed) || parsed.name !== oldName)
+            return;
+        const frontMatter = YAML.stringify({
+            ...parsed,
+            name: newName,
+        }).trimEnd();
+        const updated = `---\n${frontMatter}\n---\n${raw.slice(match[0].length)}`;
+        await fs.writeFile(skillPath, updated, "utf8");
+    }
     async validatePublishResource(type, name, resourceDir) {
         const yamlPath = path.join(resourceDir, "himan.yaml");
         if (!(await this.exists(yamlPath))) {
@@ -406,6 +534,25 @@ export class GitSourceAdapter {
         }
         return `# ${name}\n\nDescribe skill workflow here.\n`;
     }
+    buildCreateResourceMetadata(type, name, entry, entryContent, description, agents) {
+        const metadata = {
+            name,
+            type,
+            version: "0.1.0",
+            entry,
+            description,
+            agents,
+        };
+        if (type === "skill") {
+            metadata.analysis = buildResourceAnalysisMetadata({
+                entry,
+                entryContent,
+                measuredBy: "himan",
+                generatedBy: "himan",
+            });
+        }
+        return metadata;
+    }
     async buildReadmeContent(repoDir, versionOverrides = new Map()) {
         const resourceLines = await this.buildResourceIndex(repoDir, versionOverrides);
         const repo = this.sourceConfig?.repo ?? "<git_url>";
@@ -666,6 +813,38 @@ export class GitSourceAdapter {
             return undefined;
         }
     }
+    async collectLatestVersionedResources() {
+        const repoDir = this.getRepoDir();
+        const resources = [];
+        for (const type of RESOURCE_TYPES) {
+            const scanned = await this.scanner.scanByType(repoDir, type);
+            for (const resource of scanned) {
+                const history = await this.history(type, resource.name);
+                const latest = history[0];
+                const metadataVersion = await this.readResourceVersion(repoDir, type, resource.name);
+                const version = latest?.version ?? metadataVersion;
+                if (!version || !semver.valid(version)) {
+                    throw new HimanError(errorCodes.VERSION_NOT_FOUND, `Latest version not found for ${type}/${resource.name}.`);
+                }
+                resources.push({
+                    type,
+                    name: resource.name,
+                    version,
+                    tag: `${type}/${resource.name}@${version}`,
+                    sourceRef: latest ? latest.raw : undefined,
+                    sourcePath: latest
+                        ? undefined
+                        : path.join(repoDir, this.getTypeDir(type), resource.name),
+                });
+            }
+        }
+        return resources.sort((a, b) => {
+            const typeOrder = RESOURCE_TYPES.indexOf(a.type) - RESOURCE_TYPES.indexOf(b.type);
+            if (typeOrder !== 0)
+                return typeOrder;
+            return a.name.localeCompare(b.name);
+        });
+    }
     async getResourceRef(repoDir, type, name, versionOverrides = new Map()) {
         const version = versionOverrides.get(this.getResourceVersionOverrideKey(type, name)) ??
             (await this.readLatestTaggedResourceVersion(repoDir, type, name)) ??

package/dist/adapters/source/registry-source-adapter.js

@@ -18,6 +18,9 @@ export class RegistrySourceAdapter {
     async create(_type, _name, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async rename(_type, _oldName, _newName, _options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
     async initDocs(_options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }

package/dist/cli/builders.js

@@ -60,10 +60,11 @@ function appendCommandGroupsHelp(program) {
     program.addHelpText("after", `
 Command groups:
   source   Data source management (git now, registry reserved)
-           init, source init, source add, source use, source list, source init-docs
+           init, source init, source add, source use, source list,
+           source init-docs, source clone, source sync
   resource Source resource discovery and metadata
-           list, list --installed, history, create,
-           resource list, resource history, resource create
+           list, list --installed, history, create, rename (not recommended yet),
+           resource list, resource history, resource create, resource rename
   project  Resource usage lifecycle in current project or user-level agent dirs
            list, install, dev, uninstall, publish,
            project list, project install, project dev, project uninstall, project publish

package/dist/cli/resource-commands.js

@@ -91,6 +91,29 @@ export function registerResourceCommands(command, services) {
             process.stdout.write(`Created ${result.type}/${result.name} at ${result.resourceDir}${result.dryRun ? " (dry-run)" : ""}\n`);
         });
     });
+    command
+        .command("rename")
+        .argument("<type>", "resource type")
+        .argument("<old-name>", "current resource name")
+        .argument("<new-name>", "new resource name")
+        .option("--dry-run", "show rename result without writing")
+        .option("--no-project", "do not migrate current project install targets or lock")
+        .option("--json", "output json format")
+        .description("Rename resource in current default source (not recommended yet)")
+        .action(async (type, oldName, newName, options) => {
+        await runAction(async () => {
+            const resourceType = ensureResourceType(type);
+            const result = await services.rename(resourceType, oldName, newName, process.cwd(), {
+                dryRun: options.dryRun,
+                migrateProject: options.project,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Renamed ${result.type}/${result.oldName} to ${result.type}/${result.newName}${result.dryRun ? " (dry-run)" : ""}\n`);
+        });
+    });
 }
 async function writeInstalledList(services, type, agents, json) {
     if (!type) {

package/dist/cli/shared.js

@@ -12,7 +12,7 @@ export function createBaseProgram(name, description) {
             // Parse/usage errors are unified by writeCliError().
         },
     });
-    program.name(name).description(description).version(PACKAGE_VERSION);
+    program.name(name).description(description).version(PACKAGE_VERSION, "-v, --version");
     return program;
 }
 export async function runAction(action) {

package/dist/cli/source-commands.js

@@ -35,6 +35,80 @@ export function registerSourceCommands(command, services, options) {
             process.stdout.write(`Using source: ${result.name}\n`);
         });
     });
+    command
+        .command("clone")
+        .argument("<from>", "source name or git repository URL")
+        .argument("<to>", "target source name or git repository URL")
+        .option("--branch <branch>", "source branch to clone")
+        .option("--target-branch <branch>", "target branch name")
+        .option("--add-source <name>", "add the target git repo as a named source after clone")
+        .option("--use", "switch default source to the target source after clone")
+        .option("--dry-run", "show refs without pushing")
+        .option("--json", "output json format")
+        .description("Clone a git source into an empty target git repository")
+        .action(async (from, to, options) => {
+        await runAction(async () => {
+            const result = await services.cloneSource(from, to, {
+                branch: options.branch,
+                targetBranch: options.targetBranch,
+                addSource: options.addSource,
+                use: options.use,
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Source clone ${result.dryRun ? "dry-run" : "completed"}: ${result.source.name ?? result.source.repo} -> ${result.target.name ?? result.target.repo}\n`);
+            process.stdout.write(`- branch ${result.branch} -> ${result.targetBranch}\n`);
+            process.stdout.write(`- resource tags: ${result.tags.length}\n`);
+            if (result.addedSource) {
+                process.stdout.write(`- added source: ${result.addedSource}\n`);
+            }
+            if (result.usedSource) {
+                process.stdout.write(`- using source: ${result.usedSource}\n`);
+            }
+        });
+    });
+    command
+        .command("sync")
+        .argument("<from>", "source name or git repository URL")
+        .argument("<to>", "target source name or git repository URL")
+        .option("--target-branch <branch>", "target branch name", "main")
+        .option("--add-source <name>", "add the target git repo as a named source after sync")
+        .option("--use", "switch default source to the target source after sync")
+        .option("--dry-run", "show resources without pushing")
+        .option("--json", "output json format")
+        .description("Sync latest source resource snapshots into a target git repository")
+        .action(async (from, to, options) => {
+        await runAction(async () => {
+            const result = await services.syncSource(from, to, {
+                targetBranch: options.targetBranch,
+                addSource: options.addSource,
+                use: options.use,
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            const created = result.resources.filter((resource) => resource.action === "created").length;
+            const skipped = result.resources.length - created;
+            process.stdout.write(`Source sync ${result.dryRun ? "dry-run" : "completed"}: ${result.source.name ?? result.source.repo} -> ${result.target.name ?? result.target.repo}\n`);
+            process.stdout.write(`- target branch: ${result.targetBranch}\n`);
+            process.stdout.write(`- resources: ${result.resources.length}\n`);
+            process.stdout.write(`- tags created: ${created}\n`);
+            if (skipped > 0) {
+                process.stdout.write(`- tags skipped: ${skipped}\n`);
+            }
+            if (result.addedSource) {
+                process.stdout.write(`- added source: ${result.addedSource}\n`);
+            }
+            if (result.usedSource) {
+                process.stdout.write(`- using source: ${result.usedSource}\n`);
+            }
+        });
+    });
     command
         .command("list")
         .option("--json", "output json format")

package/dist/domain/source-transfer.js

@@ -0,0 +1 @@
+export {};

package/dist/services/index.js

@@ -43,9 +43,7 @@ export class ServiceFactory {
         };
     }
     async addSource(name, type, repo) {
-        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
-            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid source name: ${name}`);
-        }
+        this.validateSourceName(name);
         await this.stateStore.ensureBaseDirs();
         const sourceConfig = this.buildSourceConfig(type, repo);
         const source = this.createSource(type);
@@ -105,6 +103,47 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.initDocs(options);
     }
+    async cloneSource(from, to, options = {}) {
+        await this.stateStore.ensureBaseDirs();
+        this.validateSourceTransferOptions(to, options);
+        const sourceEndpoint = await this.resolveGitSourceEndpoint(from);
+        const targetEndpoint = await this.resolveGitSourceEndpoint(to);
+        this.validateSourceTransferUseTarget(targetEndpoint, options);
+        this.ensureDifferentGitSources(sourceEndpoint, targetEndpoint);
+        const source = await this.loadGitSourceFromEndpoint(sourceEndpoint);
+        const result = await source.cloneTo(targetEndpoint.repo, {
+            branch: options.branch,
+            targetBranch: options.targetBranch,
+            dryRun: options.dryRun,
+        });
+        const configUpdates = await this.applySourceTransferConfigUpdates(targetEndpoint, options);
+        return {
+            source: sourceEndpoint,
+            target: targetEndpoint,
+            ...result,
+            ...configUpdates,
+        };
+    }
+    async syncSource(from, to, options = {}) {
+        await this.stateStore.ensureBaseDirs();
+        this.validateSourceTransferOptions(to, options);
+        const sourceEndpoint = await this.resolveGitSourceEndpoint(from);
+        const targetEndpoint = await this.resolveGitSourceEndpoint(to);
+        this.validateSourceTransferUseTarget(targetEndpoint, options);
+        this.ensureDifferentGitSources(sourceEndpoint, targetEndpoint);
+        const source = await this.loadGitSourceFromEndpoint(sourceEndpoint);
+        const result = await source.syncLatestTo(targetEndpoint.repo, {
+            targetBranch: options.targetBranch,
+            dryRun: options.dryRun,
+        });
+        const configUpdates = await this.applySourceTransferConfigUpdates(targetEndpoint, options);
+        return {
+            source: sourceEndpoint,
+            target: targetEndpoint,
+            ...result,
+            ...configUpdates,
+        };
+    }
     async setAgents(agents, scope, projectDir) {
         const normalized = normalizeAgents(agents);
         if (scope === "project") {
@@ -183,11 +222,11 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.history(type, name);
     }
-    async install(type, name, version, projectDir, agents, mode = "link") {
+    async install(type, name, version, projectDir, agents, mode = "copy") {
         const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
         return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
     }
-    async installGlobal(type, name, version, projectDir, agents, mode = "link") {
+    async installGlobal(type, name, version, projectDir, agents, mode = "copy") {
         const source = await this.loadSourceFromConfig();
         return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
     }
@@ -274,6 +313,31 @@ export class ServiceFactory {
             dryRun: options.dryRun,
         });
     }
+    async rename(type, oldName, newName, projectDir, options = {}) {
+        this.validateRenameInput(type, oldName, newName);
+        const source = await this.loadSourceFromConfig();
+        const shouldMigrateProject = options.migrateProject !== false && !options.dryRun;
+        const locked = shouldMigrateProject
+            ? await this.getLockedResource(projectDir, type, oldName)
+            : undefined;
+        const installInfo = shouldMigrateProject
+            ? await this.tryResolveInstalledResource(projectDir, type, oldName)
+            : undefined;
+        const hasDevPath = shouldMigrateProject &&
+            (await this.exists(this.getProjectDevPath(projectDir, type, oldName)));
+        if (shouldMigrateProject && (locked || installInfo || hasDevPath)) {
+            await this.ensureRenamedProjectResourceAvailable(projectDir, type, oldName, newName, locked, installInfo);
+        }
+        const result = await source.rename(type, oldName, newName, {
+            dryRun: options.dryRun,
+        });
+        const projectMigrated = shouldMigrateProject &&
+            (await this.migrateRenamedProjectResource(source, type, oldName, newName, projectDir, result, locked, installInfo));
+        return {
+            ...result,
+            projectMigrated,
+        };
+    }
     async installFromLock(projectDir, agents, mode) {
         const { lock, state } = await this.lockStore.loadWithState(projectDir);
         if (state === "missing") {
@@ -331,6 +395,76 @@ export class ServiceFactory {
     async loadSourceFromConfig() {
         return (await this.loadSourceWithInfoFromConfig()).source;
     }
+    async resolveGitSourceEndpoint(ref) {
+        const config = await this.stateStore.loadConfig();
+        const configured = config?.sources?.items[ref];
+        if (configured) {
+            if (configured.type !== "git" || !configured.repo) {
+                throw new HimanError(errorCodes.INVALID_INPUT, `Source is not a git source: ${ref}`);
+            }
+            return {
+                name: ref,
+                repo: configured.repo,
+                repoId: configured.repoId ?? toRepoId(configured.repo),
+            };
+        }
+        if (!ref.trim()) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Git repo is required.");
+        }
+        return {
+            repo: ref,
+            repoId: toRepoId(ref),
+        };
+    }
+    async loadGitSourceFromEndpoint(endpoint) {
+        const sourceConfig = this.buildSourceConfig("git", endpoint.repo, endpoint.repoId);
+        const source = new GitSourceAdapter();
+        await source.init(sourceConfig);
+        return source;
+    }
+    validateSourceTransferOptions(targetRef, options) {
+        if (options.addSource) {
+            this.validateSourceName(options.addSource);
+        }
+        if (!options.use || options.addSource) {
+            return;
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(targetRef)) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "`--use` requires the target to be a configured source name or `--add-source <name>`.");
+        }
+    }
+    validateSourceTransferUseTarget(target, options) {
+        if (options.use && !options.addSource && !target.name) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "`--use` requires the target to be a configured source name or `--add-source <name>`.");
+        }
+    }
+    ensureDifferentGitSources(source, target) {
+        if (source.repo === target.repo) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Source and target repositories must be different.");
+        }
+    }
+    async applySourceTransferConfigUpdates(target, options) {
+        if (options.dryRun)
+            return {};
+        let addedSource;
+        if (options.addSource) {
+            await this.addSource(options.addSource, "git", target.repo);
+            addedSource = options.addSource;
+        }
+        const sourceToUse = options.use ? options.addSource ?? target.name : undefined;
+        if (sourceToUse) {
+            await this.useSource(sourceToUse);
+        }
+        return {
+            addedSource,
+            usedSource: sourceToUse,
+        };
+    }
+    validateSourceName(name) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid source name: ${name}`);
+        }
+    }
     async loadSourceWithInfoFromConfig() {
         const { name, source: stateSource } = await this.getCurrentSourceState();
         const sourceInfo = this.toLockSourceInfo(stateSource, name);
@@ -391,6 +525,75 @@ export class ServiceFactory {
             return undefined;
         return lock.resources.find((item) => item.type === type && item.name === name);
     }
+    async ensureRenamedProjectResourceAvailable(projectDir, type, oldName, newName, locked, installInfo) {
+        const lockedNewName = await this.getLockedResource(projectDir, type, newName);
+        if (lockedNewName) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Installed resource already exists: ${type}/${newName}`);
+        }
+        const newDevPath = this.getProjectDevPath(projectDir, type, newName);
+        if (await this.exists(newDevPath)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Development resource already exists: ${type}/${newName}`);
+        }
+        const agents = locked?.agents?.length
+            ? normalizeAgents(locked.agents)
+            : installInfo?.agents;
+        if (!agents?.length)
+            return;
+        for (const linkPath of getProjectResourcePaths(projectDir, type, newName, agents)) {
+            if (await this.exists(linkPath)) {
+                throw new HimanError(errorCodes.RESOURCE_EXISTS, `Installed resource already exists: ${type}/${newName}`);
+            }
+        }
+    }
+    async migrateRenamedProjectResource(source, type, oldName, newName, projectDir, result, locked, installInfo) {
+        const oldDevPath = this.getProjectDevPath(projectDir, type, oldName);
+        const newDevPath = this.getProjectDevPath(projectDir, type, newName);
+        const hasDevPath = await this.exists(oldDevPath);
+        if (!locked && !installInfo && !hasDevPath) {
+            return false;
+        }
+        let sourcePath;
+        if (hasDevPath) {
+            await fs.mkdir(path.dirname(newDevPath), { recursive: true });
+            await fs.rename(oldDevPath, newDevPath);
+            await this.updateRenamedResourceMetadata(newDevPath, type, oldName, newName);
+            sourcePath = newDevPath;
+        }
+        else if (result.latestVersion) {
+            const storePath = this.getStorePath(type, newName, result.latestVersion);
+            if (!(await this.exists(storePath))) {
+                await source.pull(type, newName, result.latestVersion, storePath);
+            }
+            sourcePath = storePath;
+        }
+        else if (installInfo) {
+            sourcePath = installInfo.installedPath;
+        }
+        else {
+            sourcePath = result.resourceDir;
+        }
+        const agents = locked?.agents?.length
+            ? normalizeAgents(locked.agents)
+            : installInfo?.agents ?? normalizeAgents();
+        const mode = installInfo?.mode ?? this.resolveInstallMode(locked?.mode);
+        const oldLinkPaths = installInfo?.linkPaths ?? getProjectResourcePaths(projectDir, type, oldName, agents);
+        const newLinkPaths = getProjectResourcePaths(projectDir, type, newName, agents);
+        for (const linkPath of newLinkPaths) {
+            await this.materializeResource(sourcePath, linkPath, mode);
+        }
+        for (const linkPath of oldLinkPaths) {
+            await fs.rm(linkPath, { recursive: true, force: true });
+        }
+        if (locked) {
+            await this.lockStore.renameResource(projectDir, {
+                type,
+                oldName,
+                newName,
+                version: result.latestVersion ?? locked.version,
+            });
+        }
+        return true;
+    }
     buildSourceConfig(type, repo, repoId) {
         if (type === "registry") {
             return { type };
@@ -431,7 +634,7 @@ export class ServiceFactory {
         await fs.symlink(sourcePath, targetPath, "dir");
     }
     resolveInstallMode(mode) {
-        return mode === "copy" ? "copy" : "link";
+        return mode === "link" ? "link" : "copy";
     }
     async resolveInstalledResource(projectDir, type, name) {
         const locked = await this.getLockedResource(projectDir, type, name);
@@ -546,6 +749,48 @@ export class ServiceFactory {
                 this.readStringArrayMetadata(metadata, "targets"),
         };
     }
+    async updateRenamedResourceMetadata(resourceDir, type, oldName, newName) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (await this.exists(yamlPath)) {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            const parsed = YAML.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return;
+            }
+            await fs.writeFile(yamlPath, YAML.stringify({
+                ...parsed,
+                name: newName,
+            }), "utf8");
+            return;
+        }
+        if (type !== "skill")
+            return;
+        const entryPath = path.join(resourceDir, this.getDefaultEntry(type));
+        if (!(await this.exists(entryPath)))
+            return;
+        const raw = await fs.readFile(entryPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+        if (!match)
+            return;
+        let parsed;
+        try {
+            parsed = YAML.parse(match[1]);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed) ||
+            parsed.name !== oldName) {
+            return;
+        }
+        const frontMatter = YAML.stringify({
+            ...parsed,
+            name: newName,
+        }).trimEnd();
+        await fs.writeFile(entryPath, `---\n${frontMatter}\n---\n${raw.slice(match[0].length)}`, "utf8");
+    }
     async readFrontMatter(filePath) {
         const raw = await fs.readFile(filePath, "utf8");
         const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw.trimStart());
@@ -623,4 +868,15 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.TEMPLATE_NOT_FOUND, `Template not found: ${options.template}`);
         }
     }
+    validateRenameInput(type, oldName, newName) {
+        if (!["rule", "command", "skill"].includes(type)) {
+            throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for rename: ${type}`);
+        }
+        if (oldName === newName) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Old and new resource names must be different.");
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(newName)) {
+            throw new HimanError(errorCodes.INVALID_RESOURCE_NAME, `Invalid resource name: ${newName}. Use kebab-case only.`);
+        }
+    }
 }

package/dist/state/project-lock-store.js

@@ -73,4 +73,23 @@ export class ProjectLockStore {
         lock.updatedAt = new Date().toISOString();
         await fs.writeFile(this.getLockPath(projectDir), JSON.stringify(lock, null, 2), "utf8");
     }
+    async renameResource(projectDir, resource) {
+        const lock = await this.load(projectDir);
+        if (!lock)
+            return;
+        const found = lock.resources.find((item) => item.type === resource.type && item.name === resource.oldName);
+        if (!found)
+            return;
+        const now = new Date().toISOString();
+        found.name = resource.newName;
+        found.version = resource.version ?? found.version;
+        found.updatedAt = now;
+        lock.updatedAt = now;
+        lock.resources.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type.localeCompare(b.type);
+            return a.name.localeCompare(b.name);
+        });
+        await fs.writeFile(this.getLockPath(projectDir), JSON.stringify(lock, null, 2), "utf8");
+    }
 }

package/docs/development.md

@@ -13,7 +13,7 @@
 ```bash
 pnpm install
 pnpm run build
-pnpm run dev -- --help
+pnpm cli --help
 node dist/bin/himan.js --help
 ```
 
@@ -28,6 +28,7 @@ pnpm test
 | 命令 | 作用 |
 |------|------|
 | `pnpm run clean` | 删除 `dist/` |
+| `pnpm cli <subcommand>` | 从源码运行主 CLI |
 | `pnpm run build` | 清理并编译 TypeScript 到 `dist/` |
 | `pnpm run typecheck` | 运行 TypeScript 类型检查，不输出文件 |
 | `pnpm test` | 运行 Vitest 一次 |

package/docs/mvp/README.md

@@ -43,7 +43,7 @@
 - 也支持 `himan install`（无参数）按 `himan.lock` 批量复现安装。
 - 未指定版本则安装该资源最新 tag 对应版本。
 - 若本地 store 中已有该版本缓存，则复用、不重新从 Git 导出；否则导出到 store。
-- 在项目下按安装模式创建目标（默认 `--mode link` 软链；`--mode copy` 复制）。
+- 在项目下按安装模式创建目标（默认 `--mode copy` 复制；`--mode link` 软链）。
 - 目标路径由 agent 和资源类型共同决定：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
   - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
@@ -91,7 +91,7 @@
 - **领域**：资源类型、版本、路径约定
 - **适配**：Git 实现 + Registry 预留；扫描与解析元数据；版本计算；配置与全局路径
 
-**原则：** store 按版本目录追加、不覆盖已有缓存；开发目录与项目安装目标分离；项目侧默认以软链引用资源，也支持复制。
+**原则：** store 按版本目录追加、不覆盖已有缓存；开发目录与项目安装目标分离；项目侧默认复制资源，也支持软链引用。
 
 ### 3.2 目录与数据
 

package/docs/mvp/impl.md

@@ -44,7 +44,7 @@
 - 命令层接受 `rule|command|skill`
 - 无版本则取该资源历史中的最新 semver
 - 若本地 store 已有该版本目录则不再从 Git 导出；否则从对应 tag 导出资源树到 store
-- 在项目中按 agent 和资源类型创建/更新安装目标，例如 `cursor -> .cursor/{rules|commands|skills}`、`codex -> .agents/{rules|commands|skills}`；默认软链到 store 中该版本，也可通过 `--mode copy` 复制内容
+- 在项目中按 agent 和资源类型创建/更新安装目标，例如 `cursor -> .cursor/{rules|commands|skills}`、`codex -> .agents/{rules|commands|skills}`；默认复制 store 中该版本，也可通过 `--mode link` 软链引用
 
 ### 2.5 `dev <type> <name>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Prompt and agent asset management CLI",
   "keywords": [
     "ai",
@@ -51,7 +51,7 @@
     "clean": "rm -rf dist",
     "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/bin/himan.ts",
+    "cli": "tsx src/bin/himan.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",