@hi-man/himan 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-14
+
+### Added
+
+- Added `himan resource archive` and `himan resource restore` for moving source resources into `archive/<plural>/<name>`, listing archived resources, and explicitly installing archived history with `--include-archived`.
+- Added the `himan-resource-manage` skill for creating, editing, validating, and publishing Himan resources from project agent folders.
+
+### Changed
+
+- Changed `himan doctor` to warn when a project lock references resources archived in its recorded source.
+
+## [0.4.1] - 2026-05-14
+
+### Added
+
+- Added `himan doctor` to check local Node/Git availability, Himan home state, current source scanning, effective agents, project lock state, and installed targets.
+
+### Changed
+
+- Changed `create` and `dev` to use current project agent target directories for resource authoring, while `publish` now logs stages and can install the published version either into the current project or globally.
+- Changed `himan init` to support quick-start setup with optional `--agent`, `--install type/name[@version],...`, `--mode`, and `--json`.
+
 ## [0.4.0] - 2026-05-13
 
 ### Added

package/README.md

@@ -41,15 +41,21 @@ pnpm dlx @hi-man/himan --help
 以下示例假设你已有一个可访问的 himan Git source 仓库，仓库中存在 `my-rule` 的资源版本 tag，并且你拥有发布所需的 Git push 权限。
 
 ```bash
-himan init https://github.com/your-org/your-himan-registry.git
-himan list rule
-himan agent use codex
-himan install rule my-rule
+himan init https://github.com/your-org/your-himan-registry.git \
+  --agent codex \
+  --install rule/my-rule
+himan doctor
+himan create skill my-skill
+# 编辑并验证项目下 .agents/skills/my-skill/
+himan publish skill my-skill --patch
 himan dev rule my-rule
-# 编辑项目下 .himan/dev/rule/my-rule/
+# 直接编辑项目下 .agents/rules/my-rule/；若只存在全局安装，dev 会先复制到当前项目
 himan publish rule my-rule --patch
 ```
 
+- `init` 的 `--agent` 会写入当前项目默认 agent；`--install` 可一次选择要安装的资源，格式为 `type/name[@version]`，多个资源用逗号分隔，例如 `rule/my-rule,skill/my-skill@1.0.0`。
+- 也可以只执行 `himan init <git_url>` 跳过 agent 和资源安装，后续再用 `himan agent use ...`、`himan list ...`、`himan install ...` 单独配置。
+- `himan doctor` 会检查本机 Node/Git、Himan home、当前 source、资源扫描、默认 agent、lock 和已安装目标。
 - **rule / command / skill**：都支持 `create`、`rename`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`；其中 `rename` 暂不推荐使用。
 - 安装后项目目标位置（按 `agents`，默认 `cursor`）：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
@@ -61,10 +67,11 @@ himan publish rule my-rule --patch
   - `claude-code` -> `~/.claude/{rules|commands|skills}/<name>`
   - `codex` -> `~/.agents/{rules|commands|skills}/<name>`
   - `openclaw` -> `~/.openclaw/{rules|commands|skills}/<name>`
-- 开发态目录：
-  - `rule` -> `.himan/dev/rule/<name>`
-  - `command` -> `.himan/dev/command/<name>`
-  - `skill` -> `.himan/dev/skill/<name>`
+- 创建与开发态目录默认就是当前项目的 agent 目标目录；例如 Codex：
+  - `rule` -> `.agents/rules/<name>`
+  - `command` -> `.agents/commands/<name>`
+  - `skill` -> `.agents/skills/<name>`
+  `dev` 修改项目内资源时不再创建 `.himan/dev`，只在资源仅存在于用户级全局目录时复制到当前项目对应 agent 目录。
 - lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
 - 安装模式：默认 `--mode copy` 将资源复制到目标 agent 目录；也可用 `--mode link` 使用软链，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
@@ -91,11 +98,19 @@ your-himan-source/
     my-skill/
       himan.yaml
       SKILL.md
+  archive/
+    rules/
+      old-rule/
+        himan.yaml
+        content.md
+    commands/
+    skills/
 ```
 
 - `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
 - `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
 - `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
+- `archive/rules/`、`archive/commands/`、`archive/skills/`：归档资源目录；默认列表、文档索引和 source sync 不把它们视为 active 资源。
 - `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent；skill 资源可包含 `analysis` 静态分析信息。
 - `content.md` / `SKILL.md`：资源主入口；没有 `himan.yaml` 时，`rule` / `command` 默认使用 `content.md`，`skill` 默认使用 `SKILL.md`。
 
@@ -131,10 +146,12 @@ 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 rename` 和 `himan publish` 会自动维护 source 根目录文档：
+`himan create` 默认在当前项目 agent 目标目录创建资源脚手架，供用户直接验证；`himan publish` 会把项目目录中的资源同步回当前 default source，并自动维护 source 根目录文档：
 
 - `README.md`：只更新 `<!-- himan:resources:start -->` 和 `<!-- himan:resources:end -->` 之间的资源索引；如果没有 marker，会在文件末尾追加一个受控资源索引区。
-- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`rename` / `publish` 记录 `Changed`。
+- `CHANGELOG.md`：`publish` 向 `[Unreleased]` 下追加 `Changed` / published version 条目。
+
+`himan rename` 也会维护 source 根目录文档：更新 README 资源索引，并向 CHANGELOG 的 `[Unreleased]` 追加 `Changed` 条目。
 
 仓库根目录的 `README.md` 和 `CHANGELOG.md` 不会被安装到 agent 目录；agent 只消费被安装的具体资源目录。当前安装实现会 materialize 资源目录本身，因此对 Cursor 这类要求特定单文件格式的 agent，资源目录内应避免放入会干扰识别的额外文件。
 
@@ -144,11 +161,13 @@ analysis:
 
 | 命令                          | 说明                                             |
 | ----------------------------- | ------------------------------------------------ |
-| `init <git_url>`              | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json` |
+| `init <git_url> [--agent a,b] [--install type/name[@version],...] [--mode link\|copy] [--json]` | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json`；可同时写当前项目默认 agent 并安装选定资源 |
 | `source add <name> <git_url>` | 添加命名 Git 源                                    |
 | `source use <name>`           | 切换默认源                                          |
 | `source list [--json]`        | 查看已配置源（标记当前 default）                     |
 | `source init-docs [--force] [--dry-run] [--json]` | 为当前 default source 生成仓库级 README/CHANGELOG |
+| `source clone <from> <to> [--branch b] [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将 Git source 分支和 himan 管理的资源 tag 复制到空目标 Git 仓库 |
+| `source sync <from> <to> [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将最新资源快照同步到目标 Git 仓库并创建对应最新 tag |
 | `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
 
 等价独立命令：
@@ -158,14 +177,18 @@ analysis:
 - `himan-source use <name>`
 - `himan-source list [--json]`
 - `himan-source init-docs [--force] [--dry-run] [--json]`
+- `himan-source clone <from> <to> [...]`
+- `himan-source sync <from> <to> [...]`
 
 ### 2) resource（资源）
 
 | 命令                             | 说明                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
+| `list [type] [--agent a,b] [--brief] [--installed] [--archived] [--include-archived] [--json]` | 默认列出当前 default source 的 active 资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源；`--archived` 只看归档资源，`--include-archived` 同时展示 active 和归档资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
-| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `create <type> <name>`           | 在当前项目 agent 目录创建脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `archive <type> <name>`          | 将当前 default source 中的资源移动到 `archive/<plural>/<name>`；常用选项：`--reason`、`--dry-run`、`--json` |
+| `restore <type> <name>`          | 将归档资源恢复回 active 类型目录；常用选项：`--dry-run`、`--json` |
 | `rename <type> <old-name> <new-name>` | 暂不推荐使用；重命名当前 default source 中的资源；常用选项：`--dry-run`、`--no-project`、`--json` |
 
 ### 3) project（当前项目）
@@ -173,10 +196,10 @@ analysis:
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
 | `list [type] [--agent a,b] [--json]` | 查看当前项目 `himan.lock` 中记录的已安装资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示 |
-| `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式 |
-| `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
+| `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy] [--include-archived]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式；归档资源必须显式传 `--include-archived` 才能按历史版本安装 |
+| `dev <type> <name>`               | 切换到开发态；项目资源原地编辑，全局资源先复制到当前项目目标目录 |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
-| `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
+| `publish <type> <name> [--global]` | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个）；发布后默认安装到当前项目并更新 lock，`--global` 安装到用户级目录 |
 
 ### 4) agent（默认 Agent）
 
@@ -187,21 +210,30 @@ analysis:
 | `agent current [--json]` | 查看当前项目、全局和最终生效的默认 agent |
 | `agent clear [--project\|--global] [--json]` | 清除当前项目或全局默认 agent；默认 `--project` |
 
+### 5) doctor（可用性检查）
+
+| 命令 | 说明 |
+|------|------|
+| `doctor [--json]` | 检查 Node/Git、Himan home、当前 source、资源扫描、默认 agent、项目 lock、归档资源引用和已安装目标；存在 error 时以非零状态退出 |
+
 也可使用分组命令（与上面等价）：
 
-- `himan resource list|history|create|rename ...`
-- `himan-resource list|history|create|rename ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan resource list|history|create|archive|restore|rename ...`
+- `himan-resource list|history|create|archive|restore|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 ...`
+- `himan doctor ...`
 
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
-若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用当前项目已有安装位置，找不到时再从用户级全局安装位置复制到当前项目。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
 
-`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>` 开发目录。
+`publish` 会展示 prepare、resolve-version、publish-source、sync-store、install、cleanup、done 等阶段日志。发布源优先使用旧版 `.himan/dev` 目录，其次使用当前项目 agent 目标目录，最后回退到 source 仓库对应资源目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装；默认安装到当前项目并更新 `himan.lock`，传 `--global` 时安装到用户级目录且不写当前项目 lock。
 
 `rename` 暂不推荐使用。该命令会移动 source 仓库里的资源目录并更新资源 metadata 名称、README 资源索引和 CHANGELOG。已有发布 tag 不会被改写；若旧资源已有历史版本，rename 会为新名字创建一个指向当前最新版本的 tag。默认会迁移当前项目中对应的安装目标、`.himan/dev` 副本和 lock 条目；传 `--no-project` 时只改 source。对于 skill，命令只自动更新 metadata / front matter 中的精确 `name` 字段，不会自动替换 `SKILL.md` 正文中的旧名称引用。
 
+`archive` 是 source 级软下线操作：它把资源目录移动到 `archive/<plural>/<name>`，从默认 `list`、source README 资源索引和 `source sync` 的 active 快照中移除，并在 `CHANGELOG.md` 记录归档事件；已有 Git tag、本地 store、项目安装目录和 `himan.lock` 不会被删除。直接安装归档资源会返回 `E_RESOURCE_ARCHIVED`，需要显式加 `--include-archived`；无参数 `himan install` 仍会按 lock 恢复已记录的归档资源。`doctor` 会对 lock 中引用归档资源的项目给出 warning。`restore` 会把资源从 archive 目录移回 active 类型目录。
+
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
 多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish/rename`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。

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

@@ -5,8 +5,10 @@ export class ResourceScanner {
     async scanRules(repoDir) {
         return this.scanByType(repoDir, "rule");
     }
-    async scanByType(repoDir, type) {
-        const baseDir = path.join(repoDir, this.getTypeDir(type));
+    async scanByType(repoDir, type, options = {}) {
+        const baseDir = options.archived
+            ? path.join(repoDir, "archive", this.getTypeDir(type))
+            : path.join(repoDir, this.getTypeDir(type));
         const hasBaseDir = await this.exists(baseDir);
         if (!hasBaseDir)
             return [];
@@ -32,16 +34,23 @@ export class ResourceScanner {
                     agents: Array.isArray(parsed.agents)
                         ? (parsed.agents ?? [])
                         : (parsed.targets ?? []),
+                    ...(options.archived
+                        ? {
+                            archived: true,
+                            archivedAt: this.readStringMetadata(parsed, "archivedAt"),
+                            archiveReason: this.readStringMetadata(parsed, "archiveReason"),
+                        }
+                        : {}),
                 });
                 continue;
             }
-            const inferred = await this.inferResourceMeta(path.join(baseDir, resourceDir.name), resourceDir.name, type);
+            const inferred = await this.inferResourceMeta(path.join(baseDir, resourceDir.name), resourceDir.name, type, options);
             if (inferred)
                 result.push(inferred);
         }
         return result;
     }
-    async inferResourceMeta(resourceDir, dirName, type) {
+    async inferResourceMeta(resourceDir, dirName, type, options) {
         const entry = this.getDefaultEntry(type);
         const entryPath = path.join(resourceDir, entry);
         if (!(await this.exists(entryPath)))
@@ -55,6 +64,7 @@ export class ResourceScanner {
             agents: this.readStringArrayMetadata(metadata, "agents") ??
                 this.readStringArrayMetadata(metadata, "targets") ??
                 [],
+            ...(options.archived ? { archived: true } : {}),
         };
     }
     async readSkillFrontMatter(skillPath) {

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

@@ -24,19 +24,31 @@ export class GitSourceAdapter {
         this.sourceConfig = sourceConfig;
         await this.repoManager.cloneOrFetch(sourceConfig.repo, sourceConfig.repoDir);
     }
-    async list(type) {
+    async list(type, options = {}) {
         const repoDir = this.getRepoDir();
+        if (options.archived) {
+            return this.scanner.scanByType(repoDir, type, { archived: true });
+        }
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
         const metadataHash = await this.getResourceMetadataHash(baseDir, type);
         const cached = await this.indexStore.get(repoId, type);
+        let active;
         if (cached && cached.metadataHash === metadataHash) {
-            return cached.resources;
+            active = cached.resources;
+        }
+        else {
+            active = await this.scanner.scanByType(repoDir, type);
+            await this.indexStore.upsert(repoId, type, metadataHash, active);
+        }
+        if (!options.includeArchived) {
+            return active;
         }
-        const scanned = await this.scanner.scanByType(repoDir, type);
-        await this.indexStore.upsert(repoId, type, metadataHash, scanned);
-        return scanned;
+        const archived = await this.scanner.scanByType(repoDir, type, {
+            archived: true,
+        });
+        return [...active, ...archived].sort((a, b) => a.name.localeCompare(b.name));
     }
     async history(type, name) {
         const tags = await this.repoManager.listTags(this.getRepoDir(), `${type}/${name}@*`);
@@ -46,6 +58,9 @@ export class GitSourceAdapter {
             .sort((a, b) => semver.rcompare(a.version, b.version));
         return versions;
     }
+    async isArchived(type, name) {
+        return this.exists(path.join(this.getRepoDir(), "archive", this.getTypeDir(type), name));
+    }
     async pull(type, name, version, targetDir) {
         const tag = `${type}/${name}@${version}`;
         await this.repoManager.archiveResource(this.getRepoDir(), tag, `${type}s/${name}`, targetDir);
@@ -175,6 +190,101 @@ export class GitSourceAdapter {
             dryRun: false,
         };
     }
+    async archive(type, name, options = {}) {
+        const repoDir = this.getRepoDir();
+        const typeDir = this.getTypeDir(type);
+        const previousResourceDir = path.join(repoDir, typeDir, name);
+        const archiveDir = path.join(repoDir, "archive", typeDir, name);
+        const archiveReason = this.normalizeArchiveReason(options.reason);
+        const archivedAt = new Date().toISOString();
+        if (!(await this.exists(previousResourceDir))) {
+            if (await this.exists(archiveDir)) {
+                throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource already archived: ${type}/${name}`);
+            }
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
+        }
+        if (await this.exists(archiveDir)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Archived resource already exists: ${type}/${name}`);
+        }
+        if (options.dryRun) {
+            return {
+                type,
+                name,
+                previousResourceDir,
+                archiveDir,
+                archivedAt,
+                archiveReason,
+                committed: false,
+                dryRun: true,
+            };
+        }
+        await this.markArchivedResourceMetadata(previousResourceDir, type, name, archivedAt, archiveReason);
+        await fs.mkdir(path.dirname(archiveDir), { recursive: true });
+        await fs.rename(previousResourceDir, archiveDir);
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Deprecated",
+            line: archiveReason
+                ? `- Archived \`${type}/${name}\`: ${archiveReason}.`
+                : `- Archived \`${type}/${name}\`.`,
+        });
+        const committed = await this.repoManager.commitAndPush(repoDir, `archive ${type}/${name}`, undefined, [
+            path.relative(repoDir, previousResourceDir),
+            path.relative(repoDir, archiveDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
+        return {
+            type,
+            name,
+            previousResourceDir,
+            archiveDir,
+            archivedAt,
+            archiveReason,
+            committed,
+            dryRun: false,
+        };
+    }
+    async restore(type, name, options = {}) {
+        const repoDir = this.getRepoDir();
+        const typeDir = this.getTypeDir(type);
+        const previousArchiveDir = path.join(repoDir, "archive", typeDir, name);
+        const resourceDir = path.join(repoDir, typeDir, name);
+        if (!(await this.exists(previousArchiveDir))) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Archived resource not found: ${type}/${name}`);
+        }
+        if (await this.exists(resourceDir)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
+        }
+        if (options.dryRun) {
+            return {
+                type,
+                name,
+                previousArchiveDir,
+                resourceDir,
+                committed: false,
+                dryRun: true,
+            };
+        }
+        await this.clearArchivedResourceMetadata(previousArchiveDir, type, name);
+        await fs.mkdir(path.dirname(resourceDir), { recursive: true });
+        await fs.rename(previousArchiveDir, resourceDir);
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Changed",
+            line: `- Restored \`${type}/${name}\` from archive.`,
+        });
+        const committed = await this.repoManager.commitAndPush(repoDir, `restore ${type}/${name}`, undefined, [
+            path.relative(repoDir, previousArchiveDir),
+            path.relative(repoDir, resourceDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
+        return {
+            type,
+            name,
+            previousArchiveDir,
+            resourceDir,
+            committed,
+            dryRun: false,
+        };
+    }
     async initDocs(options = {}) {
         const repoDir = this.getRepoDir();
         const files = [
@@ -299,6 +409,44 @@ export class GitSourceAdapter {
         const updated = `---\n${frontMatter}\n---\n${raw.slice(match[0].length)}`;
         await fs.writeFile(skillPath, updated, "utf8");
     }
+    normalizeArchiveReason(reason) {
+        const trimmed = reason?.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    async markArchivedResourceMetadata(resourceDir, type, name, archivedAt, archiveReason) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath)))
+            return;
+        const parsed = await this.readResourceYamlObject(yamlPath, type, name);
+        await fs.writeFile(yamlPath, YAML.stringify({
+            ...parsed,
+            archived: true,
+            archivedAt,
+            ...(archiveReason ? { archiveReason } : {}),
+        }), "utf8");
+    }
+    async clearArchivedResourceMetadata(resourceDir, type, name) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath)))
+            return;
+        const parsed = await this.readResourceYamlObject(yamlPath, type, name);
+        const { archived: _archived, archivedAt: _archivedAt, archiveReason: _archiveReason, ...rest } = parsed;
+        await fs.writeFile(yamlPath, YAML.stringify(rest), "utf8");
+    }
+    async readResourceYamlObject(yamlPath, type, name) {
+        const raw = await fs.readFile(yamlPath, "utf8");
+        let parsed;
+        try {
+            parsed = YAML.parse(raw);
+        }
+        catch (error) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml is not valid YAML.", { yamlPath, reason: error instanceof Error ? error.message : String(error) });
+        }
+        if (!this.isRecord(parsed)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml must be an object.", { yamlPath });
+        }
+        return parsed;
+    }
     async validatePublishResource(type, name, resourceDir) {
         const yamlPath = path.join(resourceDir, "himan.yaml");
         if (!(await this.exists(yamlPath))) {
@@ -785,7 +933,12 @@ export class GitSourceAdapter {
         return found === -1 ? lines.length : found;
     }
     findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, section) {
-        const sectionOrder = ["Added", "Changed"];
+        const sectionOrder = [
+            "Added",
+            "Changed",
+            "Deprecated",
+            "Removed",
+        ];
         const sectionRank = sectionOrder.indexOf(section);
         for (let index = unreleasedIndex + 1; index < blockEnd; index += 1) {
             const line = lines[index].trim();

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

@@ -3,12 +3,15 @@ export class RegistrySourceAdapter {
     async init(_sourceConfig) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
-    async list(_type) {
+    async list(_type, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
     async history(_type, _name) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async isArchived(_type, _name) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
     async pull(_type, _name, _version, _targetDir) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
@@ -21,6 +24,12 @@ export class RegistrySourceAdapter {
     async rename(_type, _oldName, _newName, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async archive(_type, _name, _options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
+    async restore(_type, _name, _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

@@ -1,5 +1,6 @@
 import { ServiceFactory } from "../services/index.js";
 import { registerAgentCommands } from "./agent-commands.js";
+import { registerDoctorCommand } from "./doctor-command.js";
 import { registerProjectCommands } from "./project-commands.js";
 import { registerResourceCommands } from "./resource-commands.js";
 import { registerInitCommand, registerSourceCommands } from "./source-commands.js";
@@ -9,6 +10,7 @@ export function buildCli() {
     const services = new ServiceFactory();
     appendCommandGroupsHelp(program);
     registerInitCommand(program, services);
+    registerDoctorCommand(program, services);
     const sourceCmd = program.command("source").description("Manage source repositories");
     registerSourceCommands(sourceCmd, services, { includeInit: true });
     const resourceCmd = program
@@ -63,12 +65,16 @@ Command groups:
            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, rename (not recommended yet),
-           resource list, resource history, resource create, resource rename
+           list, list --archived, list --installed, history, create,
+           archive, restore, rename (not recommended yet),
+           resource list, resource history, resource create,
+           resource archive, resource restore, resource rename
   project  Resource usage lifecycle in current project or user-level agent dirs
-           list, install, dev, uninstall, publish,
+           list, install, install --include-archived, dev, uninstall, publish,
            project list, project install, project dev, project uninstall, project publish
   agent    Default agent configuration
            agent list, agent use, agent current, agent clear
+  doctor   Runtime and project health checks
+           doctor
 `);
 }

package/dist/cli/doctor-command.js

@@ -0,0 +1,30 @@
+import { runAction } from "./shared.js";
+export function registerDoctorCommand(command, services) {
+    command
+        .command("doctor")
+        .option("--json", "output json format")
+        .description("Check Himan runtime and project health")
+        .action(async (options) => {
+        await runAction(async () => {
+            const result = await services.doctor(process.cwd());
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                writeDoctorResult(result);
+            }
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+function writeDoctorResult(result) {
+    process.stdout.write("Himan doctor\n");
+    for (const check of result.checks) {
+        process.stdout.write(`${formatCheckStatus(check)} ${check.name}: ${check.message}\n`);
+    }
+}
+function formatCheckStatus(check) {
+    return `[${check.status}]`;
+}

package/dist/cli/project-commands.js

@@ -39,12 +39,16 @@ export function registerProjectCommands(command, services, options = {}) {
         .option("--agent <list>", "install target agents, comma separated")
         .option("--mode <mode>", "install mode: link or copy")
         .option("--global", "install into user-level agent directories")
+        .option("--include-archived", "allow installing an archived resource explicitly")
         .description("Install resource, or install from himan.lock")
         .action(async (type, nameVersion, options) => {
         await runAction(async () => {
             const agents = parseAgents(options.agent);
             const mode = parseInstallMode(options.mode);
             if (!type && !nameVersion) {
+                if (options.includeArchived) {
+                    throw new HimanError(errorCodes.CLI_USAGE, "--include-archived only applies to single-resource install.");
+                }
                 if (options.global) {
                     throw new HimanError(errorCodes.CLI_USAGE, "Global install requires a resource:\n"
                         + "  - himan install <type> <name[@version]> --global [--mode link|copy]");
@@ -68,8 +72,8 @@ export function registerProjectCommands(command, services, options = {}) {
             const resourceType = ensureResourceType(type);
             const { name, version } = parseNameVersion(nameVersion);
             const result = options.global
-                ? await services.installGlobal(resourceType, name, version, process.cwd(), agents, mode)
-                : await services.install(resourceType, name, version, process.cwd(), agents, mode);
+                ? await services.installGlobal(resourceType, name, version, process.cwd(), agents, mode, { includeArchived: options.includeArchived })
+                : await services.install(resourceType, name, version, process.cwd(), agents, mode, { includeArchived: options.includeArchived });
             process.stdout.write(`Installed ${options.global ? "global " : ""}${result.type}/${result.name}@${result.version}\n`);
         });
     });
@@ -82,7 +86,11 @@ export function registerProjectCommands(command, services, options = {}) {
         await runAction(async () => {
             const resourceType = ensureResourceType(type);
             const result = await services.dev(resourceType, name, process.cwd());
-            process.stdout.write(`Switched ${result.type}/${result.name} to dev mode: ${result.devPath}\n`);
+            if (result.sourceScope === "global") {
+                process.stdout.write(`Copied global ${result.type}/${result.name} into current project: ${result.devPath}\n`);
+                return;
+            }
+            process.stdout.write(`Editing ${result.type}/${result.name} in place: ${result.devPath}\n`);
         });
     });
     command
@@ -104,13 +112,23 @@ export function registerProjectCommands(command, services, options = {}) {
         .option("--patch", "patch release")
         .option("--minor", "minor release")
         .option("--major", "major release")
+        .option("--global", "install the published version into user-level agent directories")
         .description("Publish resource (default: --patch)")
         .action(async (type, name, options) => {
         await runAction(async () => {
             const resourceType = ensureResourceType(type);
             const releaseType = resolveReleaseType(options);
-            const result = await services.publish(resourceType, name, releaseType, process.cwd());
-            process.stdout.write(`Published ${result.type}/${result.name}@${result.version}\n`);
+            const installScope = options.global ? "global" : "project";
+            process.stdout.write(options.global
+                ? "Published resource will be installed globally; current project lock will not be updated.\n"
+                : "Published resource will be installed into the current project and recorded in himan.lock. Use --global to install globally instead.\n");
+            const result = await services.publish(resourceType, name, releaseType, process.cwd(), {
+                installScope,
+                onProgress: (progress) => {
+                    process.stdout.write(`[publish:${progress.stage}] ${progress.message}\n`);
+                },
+            });
+            process.stdout.write(`Published ${result.type}/${result.name}@${result.version} and installed ${result.installScope === "global" ? "globally" : "into current project"}\n`);
         });
     });
 }