skillcaddy 0.27.0

package/CHANGELOG.md

@@ -0,0 +1,497 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.27.0] - 2026-10-23
+
+### Added
+- The code root and the library root are now separate concepts (ADR 0012). A clone keeps the library inside the clone exactly as before; every packaged install (`npx`, `npm i -g`, `brew`) keeps the library in `~/.skillcaddy/library`, so reinstalling or upgrading the program never touches installed skills. `SKILLCADDY_ROOT` (already used by `scripts/pull-github.sh`) and `--root` select any other library root; `skillcaddy -a` reports both roots.
+- `lib/roots.js` — the single place that resolves the code root, the library root, and the legacy single-root call shape.
+- `scripts/install.sh` — one-command installer (`curl … | bash`) for the global command, with `--prefix` and `--version` options and a Node.js >= 20 pre-check.
+- `Formula/skillcaddy.rb` — Homebrew formula installing the published npm tarball, plus `scripts/update-homebrew-formula.sh` to refresh its version and checksum after each publish.
+- The package is publishable: `files` restricts the tarball to the runtime (100 files, ~1.4 MB) so the local library is never packaged, `bin` exposes the `skillcaddy` command, and `repository`/`homepage`/`bugs`/`license`/`keywords` are declared.
+- `skills/spec-pipeline/`: three skills implementing the direction-confirmation gap identified in `docs/research/0037`. `spec-direction-gate` (B, rejects rather than advises, records approval in the spec's `## Approval` section), `spec-draft-intake` (F, treats an external draft as untrusted input and reconciles it against the repository), `spec-role-contract` (cross-cutting author/implementer/verifier positions). Design in `docs/research/0037-spec-doc-pipeline-gaps-improvement-plan.md`.
+- `npm run check:specs` — walks `specs/*/TECH.md` and `specs/*/ROLE.md` and exits non-zero when a document fails its gate. Wired into `npm test`. A repository with no `specs/` directory passes; `--strict` inverts that.
+- `npm run enable:spec-pipeline` — recreates the project enablement links for the three skills. They are deliberately absent from the library image (ADR 0011 Decision 4), so this is a once-per-checkout step. Idempotent; `--dry-run`, `--uninstall`, and `--global` are available.
+- CI (`.github/workflows/ci.yml`): `npm ci && npm test` on Node 20 and 22, on pushes to `main` and on pull requests.
+
+### Changed
+- `--root` now selects the library root for every command, including `start`/`stop`/`restart`. Previously Web lifecycle commands rejected a custom root and always used the clone that provided the executable; the Web process still runs that code root, and the resolved library root reaches it through `SKILLCADDY_ROOT`. ADR 0007 is amended accordingly (see `docs/adr/0012-decoupled-code-root-and-library-root.md`).
+- The library image manifest's `producer` object gained an explicit `mode`: `repository` (the library root is a git repository) or `no-repository` (it is a plain directory, with `commit` and `branch` set to `null`). Export no longer refuses to produce an archive when the library root is not a git repository; the repository-state check is skipped with a reported warning instead. Archive format, member list, and `schemaVersion: 1` are unchanged.
+- The bundled `skills/` bucket is scanned from the code root, and its metadata sidecars are stored in the library root, so notes and tags survive a reinstall of the program.
+- `package.json` is no longer `private`. The package is published to the npm registry as `skillcaddy`; this is its first registry release, and `npx skillcaddy` / `npm i -g skillcaddy` work from it.
+
+### Fixed
+- Library image scope-change detection no longer depends on `dev:ino` alone. On Linux, removing and recreating a directory at the same path returns the identical inode, so a scope directory replaced between planning and confirmation passed the stale-plan check undetected. The snapshot now also compares the directory's entry set. macOS increments inodes, which is why this was invisible there.
+- Library image import no longer fails on an NFD-named source under Linux. Staged path names were normalized to NFC *before* the integrity check, and on Linux that rename actually happens (on APFS the NFC spelling already resolves to the same inode, so the name is kept). The directory's plain checksum therefore became the normalized one, matching neither form of the NFD baseline. Verification now runs first and normalization second. ADR 0011 Decision 7 is unchanged — the receiving library still ends up in NFC form. Diagnosis in `docs/research/0038-library-image-nfd-export-failure.md`.
+
+### Notes
+- The 0.26.4 entry below describes the plain-or-normalized tolerance as a fix it shipped. That tolerance has been present since the workflow was first implemented (`2d89f62`), and the v0.26.4 release commit touches no library-image file. It was also not sufficient on Linux, for the ordering reason described above.
+
+## [0.26.4] - 2026-09-21
+
+### Fixed
+- Library image import no longer reports a spurious checksum mismatch for NFD-named sources: the Phase-1 gate fails only when both the plain and the NFC-normalized checksums differ from the baseline, keeping SPEC:127 like-for-like comparison and the ADR 0011 cross-platform promise. *(No library-image change shipped in this release; the tolerance described here has been present since `2d89f62`.)*
+
+## [0.26.3] - 2026-09-21
+
+### Fixed
+- Web manager: the project Agents bulk-clear button now passes an explicit `project` scope instead of the click event, so all selected skills are removed and the confirmation no longer reports `[object PointerEvent]`; `disableAgents` also falls back to `project` for any non-string scope.
+
+## [0.26.2] - 2026-09-09
+
+### Added
+- Web manager: the top bar now links directly to the Skillcaddy GitHub repository beside the version badge, with a compact icon-only layout on narrow screens.
+
+### Fixed
+- Web manager: source-library skill cards now expose the same note-first hover text as Agents and Claude Code enabled cards, falling back to the source description when no note exists.
+
+## [0.26.1] - 2026-09-08
+
+### Added
+- Web manager: Hermes section is now a topbar toggle (off by default), so day-to-day work shows project + Claude Code + global only; opening the switch re-exposes Hermes, the Hermes bulk actions, and the per-skill Hermes enable button.
+- Web manager: library advice (collection/duplicate/setup hints) collapses into an info icon with a count badge in the library panel title; clicking opens a popover with the full list.
+- Web manager: added one shared enabled-skill search across project Agents, Claude Code, global Agents, and Hermes, with per-channel match counts and clear no-match states.
+
+### Changed
+- Web manager: the four enabled scopes now use channel slots: project Agents and Claude Code stay side by side, while global Agents and Hermes each get a full-width slot with an explicit purpose line and bottom-aligned bulk actions.
+- Web manager: Claude Code rows reuse the same source-pill and remove affordance as the agents skills column instead of a separate `.claude-skill` component, so the two project scopes no longer drift visually.
+- Web manager: `claude.css` is now a compatibility placeholder; column and row styles are consolidated in `enabled.css`.
+
+## [0.26.0] - 2026-09-08
+
+### Added
+- Added library image export/import with a self-contained manifest, safe tar unpacking, atomic `0600` archives, resumable source submission, and global/Hermes enablement restoration.
+- Added the fifth `image` acquisition input type, cross-platform fidelity verification, and adversarial unpacking fixtures.
+
+## [0.25.1] - 2026-08-17
+
+### Added
+- Added an independent Hermes enablement scope across the API, CLI, TUI, Web manager, collection flow, and Manager workflow.
+- Added Hermes source-update and Git registry-repair protection for affected links.
+
+### Changed
+- Hermes now accepts `official`, `github`, and `personal` sources while keeping project/global enablement and Claude synchronization independent.
+- Added Hermes state, diagnostics, safe ownership checks, and direct links under `~/.hermes/skills/`.
+
+### Fixed
+- Web startup cleanup now tolerates a child process that exits before its termination signal is delivered.
+
+## [0.25.0] - 2026-08-13
+
+### Changed
+- Refined the Web manager around a compact returning-user status band, persistent error feedback, timed success toasts, clearer busy states, keyboard shortcuts, and visible focus treatment.
+- Replaced abbreviated global action symbols with explicit project/global scope labels while preserving independent controls: a globally enabled skill can still be added to the current project for project setup, Claude synchronization, and project-level precedence.
+- Global collection enable buttons now mirror project buttons by showing enabled progress and retaining the completed success state.
+- Search results now expand matching collections automatically, while source and tag filters keep collections collapsed for easier scanning.
+
+### Fixed
+- Bulk enable and cleanup feedback now reports progress and actionable failures instead of leaving long-running operations visually idle.
+- Archived-skill actions, enabled states, advice severity, and scope actions now expose clearer accessible names and explanations.
+
+## [0.24.1] - 2026-08-12
+
+### Added
+- Added a cron-oriented Git source sync helper that reports unresolved failures through its exit status.
+
+### Changed
+- Registered Git source fetches now retry transient network failures twice, retain sanitized transport diagnostics, and stop contacting additional sources after three consecutive exhausted network failures.
+
+### Fixed
+- Automated cron repair now runs only for source-record collisions, never authorizes breaking repairs implicitly, and reruns the batch only after a repair succeeds.
+- Source-record collisions now remain actionable when a simultaneous fetch failure would otherwise hide the registry mismatch.
+
+## [0.24.0] - 2026-08-12
+
+### Added
+- Added explicit project and global skill enablement across the shared API, CLI, TUI, and Web manager.
+- Added global collection enablement that writes only `~/.agents/skills/` and safely distinguishes links owned by the current Skillcaddy library.
+- Added project/global coexistence, global-link collision protection, and global-link source update and registry repair checks.
+
+### Changed
+- Source update and repair output now reports affected project and global links separately; authorized breaking updates leave affected links in place.
+- Web library actions now separate project controls (`+`, `×`) from global controls (`G+`, `G×`) with a visual divider.
+- Updated the domain model, ADR-0009, Manager skill documentation, README files, and API contracts for scoped enablement.
+
+### Fixed
+- Global collection completion now uses the same green success state as project collection completion.
+
+## [0.23.0] - 2026-08-12
+
+### Added
+- Added TUI option 12 for central-library-only acquisition of complete HTTPS/SSH/SCP Git repositories, public HTTP(S) ZIP archives, and stable direct HTTP(S) `/SKILL.md` files.
+- Added GitHub tree focus handling, required names for Remote file sources, cancellation, idempotency, destination collision, error reporting, and TUI state refresh for source acquisition.
+
+### Changed
+- Aligned the English and Chinese README files, source acquisition implementation plan, ADR-0007/0008, and Manager operations documentation with the new TUI acquisition boundary while keeping Web acquisition out of scope.
+
+## [0.22.0] - 2026-08-07
+
+### Added
+- Added Git source update summaries that distinguish newly added, edited, and deleted skills.
+- Added `--verbose` output for the source CLI and global `skillcaddy -u` command to list affected skill paths.
+
+### Changed
+- Git update summaries now include the old and new commit IDs while remaining transient command output; registry metadata and source content are not polluted with update descriptions.
+
+## [0.21.0] - 2026-08-07
+
+### Added
+- Added an explicit Git source registry repair flow for clean checkouts advanced manually with `git pull`, including fast-forward and current-project link checks.
+- Added ADR-0008 documenting registry-only adoption of externally advanced Git sources.
+
+### Changed
+- Batch Git update output now includes failure categories and reasons, and dirty sources now emit a non-mutating reminder.
+- Dirty Git worktrees remain untouched; repair never pulls, resets, stashes, or overwrites source content.
+
+## [0.20.0] - 2026-08-07
+
+### Added
+- Added a unified clone-backed `skillcaddy` CLI for Web `start`, `stop`, and `restart`, version/help output, safe registered-Git updates with `-u`, and read-only project analysis with `-a`.
+- Added verified Web process ownership and PID lifecycle handling; external services occupying the Web port are never stopped or replaced.
+- Added explicit global CLI/TUI bootstrap commands: `npm run install:cli` / `npm run check:cli`, with `install:tui` / `check:tui` compatibility aliases.
+- Added affected project-link reporting for blocked Git source updates and an explicit `--project` path for the source CLI.
+
+### Changed
+- Made `-a` analysis read-only and made batch Git updates reject a missing current-project context instead of silently skipping link protection.
+- Clarified that `--root` is for source/analysis operations and that Web shutdown fails closed when process ownership cannot be verified.
+- Recorded the clone-backed CLI and local Web lifecycle boundary in ADR-0007 while preserving source-manager and enablement boundaries.
+
+## [0.19.1] - 2026-08-06
+
+### Changed
+- Web 管理器左侧 Agents / Claude Code 已启用列表隐藏路径信息，让列表更紧凑并保留 skill 名称与操作入口。
+
+## [0.19.0] - 2026-07-30
+
+### Changed
+- Centralized Source acquisition behind one shared lifecycle that owns plan retention, re-planning, stale-plan enforcement, installed-state and destination collision checks, publication rollback, result projection, and workspace cleanup.
+- Introduced internal preparation adapter seam for source-specific input parsing, identity selection, content inspection, Source registry projection, and active-content verification.
+- Removed legacy `sourceAdd.js`, `sourceArchiveAdd.js`, `sourceGitAdd.js`, and `sourceRemoteFileAdd.js` modules in favor of the unified acquisition lifecycle.
+
+### Added
+- Added `lib/sourceAcquisition.js` as the core lifecycle orchestrator.
+- Added `lib/sourceAcquisitionAdapter.js` base class and source-specific adapters for Git, Local, Remote Archive, and Remote File inputs.
+- Added `lib/sourceAcquisitionExecution.js` for publication and rollback logic.
+- Added `lib/sourceAcquisitionPolicy.js` for plan fingerprinting, collision checks, and status resolution.
+- Added `test/sourceAcquisitionContract.test.js` covering lifecycle invariants and adapter conformance.
+
+## [0.18.0] - 2026-07-30
+
+### Added
+- Added `POST /api/enable-collection` as the shared execution boundary for Collection enablement.
+
+### Changed
+- Centralized Collection enablement execution behind one shared Web/TUI lifecycle that applies project links, classifies enabled/unchanged/skipped/failed outcomes, and refreshes non-blocking setup reminders without executing setup skills.
+- Reduced Web and TUI adapters to user confirmation and result presentation while preserving partial successes and explicit per-skill failures.
+
+## [0.17.1] - 2026-07-30
+
+### Changed
+- Centralized Local input, Remote Archive, Remote file, single Git, and Git batch Source upgrades behind one shared lifecycle while preserving the established `sourceManager` plans, results, errors, CLI behavior, and Git safety semantics.
+- Removed the remaining legacy Source upgrade path and tightened import boundaries around lifecycle policy, preparation adapters, and the distinct directory and Git publishers.
+
+## [0.17.0] - 2026-07-29
+
+### Added
+- 新增 clone-backed TUI 安装流程：`npm run install:tui` 通过本地 `npm link` 暴露全局 `skillcaddy` 命令，`npm run check:tui` 验证链接仍指向当前原件库 clone；安装前拒绝覆盖由其它 clone 占用的全局 package link。
+
+## [0.16.1] - 2026-07-29
+
+### Fixed
+- TUI 按 Ctrl+C 不再抛出 `AbortError` 堆栈，改为静默退出并输出 `byebye 👋`。
+- TUI 主菜单输入 `q` 退出时同样输出 `byebye 👋`。
+
+## [0.16.0] - 2026-07-29
+
+### Added
+- Web 全局搜索框：在 Library 区域顶部新增搜索输入框，支持按 skill 名称、描述、标签实时过滤。
+- Web 库级状态 tooltip：鼠标悬停在状态 badge（"待配置"/"配置不完整"/"已就绪"）上时显示解释文字。
+- Web 版本展示：库路径后展示 Git commit hash（前 7 位）或 Archive integrity hash（前 12 位），数据来源于 source registry。
+- Web 启用列描述 tooltip：左侧 Agents / Claude Code 已启用列表的每个 skill 条目增加鼠标悬停描述，优先显示中文备注（`note`），无则显示英文描述（`description`）。
+
+### Changed
+- `/api/state` 返回值新增 `sources` 数组，包含每个源的版本信息（Git commit 或 integrity hash）。
+- `renderAgentsSkills` / `renderClaudeStatus` 增加 `skills` 参数用于匹配源 skill 信息。
+
+### Active deprecations
+
+| Legacy feature | Replacement | Deprecated | Runtime support ended | Migration code removed |
+| --- | --- | --- | --- | --- |
+| `<skill-dir>/skillcaddy.json` | `.skillcaddy/metadata/<source>/<relative-path>/skillcaddy.json` | v0.14.0 | v0.15.0 | v0.16.0 |
+
+## [0.15.1] - 2026-07-28
+
+### Added
+- Added managed Remote file sources for stable direct HTTP(S) `/SKILL.md` URLs, including explicit `official/<name>` identities, bounded validation, sanitized reusable origins, SHA-256 integrity, and transactional per-source updates.
+
+### Changed
+- Source discovery now recognizes root `SKILL.md`, bounded `skills/**/SKILL.md` and `skill/**/SKILL.md` layouts, and direct-child `<name>/SKILL.md` layouts while keeping populated `skills/` collections authoritative and excluding support directories.
+
+## [0.15.0] - 2026-07-26
+
+### Added
+- Added a sidecar source registry with stable identities, sanitized provenance, integrity data, physical install paths, and discovered skill paths.
+- Added dry-run adoption for existing Git and Local sources without moving their current directories.
+- Added managed acquisition for local directories, local ZIP files, complete Git repositories, GitHub tree URLs, and public HTTP(S) ZIP files.
+- Added transactional Local and Archive replacement with validation, rollback, download and extraction limits, and current-project link protection.
+- Registered Git source updates now fetch the tracked ref, validate incoming skill paths, advance only by fast-forward, and expose stable `updated`, `current`, `dirty`, `breaking`, and `failed` outcomes.
+- Manager source workflows now infer updates only from registered identities, keep acquisition and enablement separate, and rescan through shared enablement preflight before enabling one explicitly selected acquired skill.
+
+### Changed
+- `npm run pull:github` now delegates to the unified source-management updater instead of maintaining a parallel Git pull implementation.
+- English, Chinese, and Manager documentation now cover the repository-local source commands, migration and recovery, setup boundaries, and deferred first-release capabilities.
+
+### Removed
+- Runtime scanning no longer reads legacy `<skill-dir>/skillcaddy.json` metadata. `npm run migrate:metadata` continues to discover and migrate those files explicitly through v0.15.x.
+
+## [0.14.3] - 2026-07-22
+
+### Fixed
+- Web UI 库级启用按钮现在显示启用数量（如 "2/5"），全部启用时显示绿色背景，更清晰地表达库级启用状态。
+- 单个 skill 启用按钮：已启用状态显示绿色边框 + 绿色文字 + 灰色背景，避免与未启用混淆。
+- 库级启用按钮字体缩小至 13px，确保两位数能正常显示在按钮背景内。
+
+### Changed
+- `skillcaddy-manager` SKILL.md 的 `description` 精简为更短且聚焦的触发词清单（discovery、enable/disable、audits、maintenance、bootstrap、Web/TUI access），降低触发歧义。
+
+## [0.14.2] - 2026-07-20
+
+### Added
+- 新增 tracked collection setup contract：`collection-metadata/<source>/<collection>.json`，声明交互式 setup skill、适用 skills 和项目内就绪产物，不写入第三方 GitHub clone。
+- `/api/state` 新增 `setups`，区分 `missing`、`partial`、`ready`、`invalid`；新增 `collection-setup-required/recommended/invalid` advice。
+- 新增 `POST /api/enable-plan`，为 Web 和 TUI 提供统一库级预检，并在必要时自动把 setup skill 纳入启用计划。
+- 为 `github/mattpocock` 登记首个 setup contract，检测 issue tracker 与 domain docs 配置。
+
+### Changed
+- Web/TUI 库级启用现在会在变更前提示 setup 状态，启用后持续显示“待配置/配置不完整/已就绪”以及明确的 Agent 配置指引。
+- `skillcaddy-manager` 将“已启用”和“已就绪”分开处理；交互式 setup 必须获得用户确认，不会静默执行。
+
+## [0.14.1] - 2026-07-17
+
+### Changed
+- **skillcaddy-manager 重构**：按 writing-great-skills 原则精简结构，引入 Core Loop (`state → route → preflight → act → verify`) 作为 leading concept，信息分层到 `OPERATIONS.md`、`RECOMMENDATION_GUIDE.md`、`METADATA.md`。
+- description 从 107 词压缩到 32 词，删除重复内容（3 处重复的冲突检测逻辑合并为单一引用）。
+- 每个步骤添加明确的 "Complete when" 完成标准。
+- 删除冗余的 `references/README.md` 和 `references/SUMMARY.md`。
+
+## [0.14.0] - 2026-07-14
+
+### Added
+- 新增 `npm run migrate:metadata`：默认仅预检 legacy metadata；确认后使用 `npm run migrate:metadata -- --yes` 写入 sidecar。该命令补充 v0.11.0 的 metadata 存储迁移，并计划在 v0.16.0 删除。
+- `library-duplicate-name` advice 现在返回每个冲突 skill 的稳定建议 alias 和结构化 `enable-with-alias` 动作。
+- TUI skill 详情新增“使用其他名称启用”，将重复名诊断从仅警告扩展为可执行修复，同时不重命名原件库目录。
+
+### Changed
+- `/api/state` 中的 skill 现在返回 `metadataStorage`；检测到 legacy metadata 时会生成带迁移命令的 warning advice。
+
+### Deprecated
+- Legacy `<skill-dir>/skillcaddy.json` 运行时读取已弃用：v0.15.0 将停止 fallback 读取；迁移命令会保留至 v0.15.x，并在 v0.16.0 删除。新写入继续统一使用 sidecar 路径。
+
+## [0.13.1] - 2026-07-13
+
+### Fixed
+- TUI 紧凑表格：当 skill 名过长时正确截断，确保状态标签（可添加/已启用）始终可见。
+- TUI 已启用 skill 列表统一使用紧凑表格样式，与搜索结果保持一致。
+
+## [0.13.0] - 2026-07-13
+
+### Added
+- **TUI 批量生成中文 note**：新增菜单选项 10，交互式流程为仅有英文 `description`、缺少中文 `note` 的 skill 补全中文介绍，支持分批（5/10/全部）处理与跳过。
+- **TUI 库浏览分页**：库详情改为紧凑表格展示，支持 `n`/`p` 翻页、`a` 一键加入该库。
+- 新增 `lib/tuiLayout.js`：TUI 展示排版与紧凑表格格式化（叶子模块，无 store 依赖）。
+- 新增 `skills/skillcaddy-manager/scripts/translate-skill-notes.cjs`：批量中文 note 生成辅助脚本，支持 `list` / `apply`（默认 dry-run，需 `--yes` 才写入），保护已有 note 并校验 manifest 来源。
+- `skills/skillcaddy-manager/SKILL.md` 补充 Batch Chinese Note Generation 用法与规则。
+
+### Changed
+- TUI 中 skill 介绍优先使用 metadata `note`，回退到 `description`，最后回退到路径（`.import-rules.json` 为 `lib/tuiLayout.js` 新增导入规则）。
+- `.import-rules.json` 新增 `lib/tuiLayout.js` 导入规则。
+- README / README_CN 补充 TUI 分页与批量中文 note 说明。
+
+## [0.12.0] - 2026-07-02
+
+### Added
+- **TUI 终端管理器**：`npm run tui -- /path/to/project` 启动交互式终端界面，无需浏览器即可管理 skills。
+  - 查看已启用 skill（Agents + Claude Code 双列展示）
+  - 浏览/搜索 skill 库，支持关键词搜索和来源过滤
+  - 启用 skill 到 Agents 并自动同步 Claude Code
+  - 清理已启用的项目 skill
+  - 同步 Claude Code skills
+  - 编辑 skill metadata（备注、tags、一键加入开关）
+  - 查看项目诊断建议（advice）
+  - 刷新项目状态、切换项目
+  - 更新 GitHub skill 库（调用 `pull-github.sh`）
+- 新增 `scripts/tui.js`：TUI 主入口，实现完整的交互式菜单导航。
+- 新增 `lib/tuiActions.js`：TUI 核心操作逻辑，复用 Web 管理器相同的数据层和动作。
+- 新增 `test/tuiActions.test.js`：TUI 操作逻辑测试覆盖。
+
+### Changed
+- README / README_CN 补充 TUI 启动方式和功能说明。
+- `.import-rules.json` 新增 `lib/tuiActions.js` 导入规则。
+
+## [0.11.0] - 2026-07-01
+
+### Added
+- 新增 `npm run install:manager`：将仓库自带的 `skills/skillcaddy-manager` 以受控软链接安装到 `~/.agents/skills/skillcaddy-manager`，方便 AI Agent 在任意项目中发现 Skillcaddy 管理能力。
+- 新增 `npm run check:manager`：检查全局 `skillcaddy-manager` 是否已安装、是否断链或是否指向其它位置。
+- 新增 `lib/managerInstall.js`：封装 manager skill 安装与检查逻辑。
+
+### Changed
+- **Metadata 存储位置重构**：`skillcaddy.json` 从每个 skill 目录内迁移到集中存储目录 `.skillcaddy/metadata/<source>/<relative-path>/skillcaddy.json`，不再污染上游 SKILL.md，gitignore 更友好。
+- `readSkillMetadata()` 现在优先读取 sidecar metadata，回退到 legacy（skill 目录内）并标记 `metadataStorage: 'legacy'`。
+- `updateSkillMetadata()` 统一写入 sidecar 位置。
+- `lib/sourcePolicy.js` 新增 `resolveAllowedSkillSource()`：返回来源目录与相对路径信息，供 sidecar 路径计算使用。
+- README / README_CN 补充首次安装 `skillcaddy-manager` 的 bootstrap 说明，并明确不会覆盖已有非受控目标。
+
+## [0.10.0] - 2026-06-30
+
+### Added
+- 历史项目列表支持单独移除：每个项目 chip 右侧新增 `×` 删除按钮，hover 时显示移除提示。
+- 项目路径输入框新增 placeholder 示例和字段提示文案"请输入项目路径添加"，引导用户操作。
+
+### Changed
+- 重构项目历史 chip 样式：改用 grid 布局分离路径按钮与删除按钮，增强交互独立性。
+- 删除按钮 hover 状态：深色背景 + 白色图标，视觉反馈更明确。
+- 禁用项目（当前已加载）的路径按钮改为灰色不可点击样式，避免混淆。
+
+## [0.7.0] - 2026-06-29
+
+### Added
+- 新增 `skillcaddy.json` skill 管理元数据：支持为每个 skill 保存人可读 `note` 和 `tags`，不污染上游 `SKILL.md`。
+- `/api/state` 现在会返回每个 skill 的 `note`、`tags`、`autoEnable`、`metadataPath`、`hasMetadata`。
+- 新增 `POST /api/skill-metadata`，用于安全写入 skill 目录内的 `skillcaddy.json`。
+- Web UI 新增 tag tabs 过滤、tag pill 展示、备注展示、内联编辑表单、单 skill 是否参与库级一键加入开关，以及库级一键清理 Agents / Claude Code 已启用 skills。
+- `skillcaddy-manager` 增加 metadata 自动维护规则，指导 Agent 根据 `SKILL.md` 内容生成或更新 `skillcaddy.json`。
+
+### Changed
+- 导入边界规则新增 `lib/sourcePolicy.js` 和 `lib/skillMetadata.js`，复用来源边界检查，避免 metadata 写入绕过 Skillcaddy 来源目录。
+
+## [0.6.0] - 2026-06-29
+
+### Added
+- Web 管理器支持通过 `?projectPath=<encoded-project-path>` 直接打开指定项目，并在切换项目后同步 URL。
+- 项目路径输入区新增本地历史项目记录和"添加项目"入口，方便在多个项目之间切换。
+- Skill 原件库的每个库标题旁新增 `+` 批量启用入口，可一次启用该库内尚未启用且非 archived 的 skills。
+- `skillcaddy-manager` skill 新增"打开 Web 管理器"工作流，指导 Agent 使用 URL 传递项目路径。
+
+### Changed
+- Web 管理器默认固定使用 `http://127.0.0.1:4173`；仅在端口冲突或显式指定时通过 `PORT=<other-port>` 临时覆盖。
+- 首页统计文案统一为 `Agents 启用`、`Claude Code 启用`。
+- 禁用按钮和不可操作控件的鼠标样式改为 `not-allowed`，避免误导成加载状态。
+- README / README_CN 补充固定端口、项目路径 URL 传参、历史项目和批量启用说明。
+
+## [0.5.0] - 2026-06-29
+
+### Added
+- 导入依赖规则系统：`.import-rules.json` 配置 + `scripts/check-imports.js` 检查脚本，强制模块依赖分层
+- 全局技能检测：自动扫描 `~/.agents/skills` 和 `~/.claude/skills`，返回 `global` 数组
+- 技能建议系统：`buildSkillAdvice()` 提供"重复名 / 未启用推荐 / 已启用但来源变化"等管理建议
+- 导入检查测试：`test/check-imports.test.js` 覆盖规则解析、glob 匹配、违规检测
+
+### Changed
+- `npm test` 现在包含导入检查（`npm run lint:imports`），破坏性变更：不合规导入会导致测试失败
+- `lib/skillStore.js`：
+  - `getState()` 返回值新增 `global` 和 `advice` 字段
+  - 新增 `scanGlobalSkills()`：扫描用户级全局技能目录
+  - 新增 `scanSkillLinks(skillsDir)`：提取公共软链接扫描逻辑，供项目级与全局级复用
+  - 新增 `buildSkillAdvice(rootDir, { skills, enabled, global })`：生成管理建议
+- `public/app.js`：适配新的 `global` / `advice` 字段（UI 准备）
+- `skills/skillcaddy-manager/SKILL.md`：增补导入规则、全局技能、建议系统的使用说明
+
+## [0.4.1] - 2026-06-28
+
+### Changed
+- README 双语化
+  - 新增 `README.md`（English，canonical），顶部加 `[English](README.md) · [中文](README_CN.md)` 语言切换
+  - 中文版迁到 `README_CN.md`，顶部同步加语言切换链接
+  - 两份内容 1:1 对应；ASCII 架构图、命令、表格结构保留
+- 新增 "Why Skillcaddy?" / "为什么是 Skillcaddy？" 段（双语）：痛点列表（5 条多项目 / 多 Agent 场景）+ 能力清单（6 条：单一事实来源 / 零项目污染 / 多 Agent 友好 / 独立管理 / 安全默认 / 便于贡献）+ 收尾点题（个人 / 团队 / 作者三类读者）；放置在标题下方、Installation 之前
+
+## [0.4.0] - 2026-06-28
+
+### Added
+- 新源 `skills/`：仓库自带的 skill 视作 `source: 'local'`、`id: 'local/<name>'`，与 `official/github/personal/archived` 一同被扫描
+- 新 skill `skills/skillcaddy-manager/`：教 Agent 如何使用 Skillcaddy 自身
+  - `SKILL.md`：列出 / 启用 / 禁用 / 同步 / 更新 / 健康检查 / 冲突检测的工作流；强制 dry-run 摘要 + 多种确认门（重复名 / 别名占用 / 非 symlink 占用 / GitHub 本地脏 / 动 archived / 删中央原件）
+  - `agents/openai.yaml`：interface 元数据，`allow_implicit_invocation: true`
+- 新工具脚本 `scripts/pull-github.sh` + `npm run pull:github`：批量 fast-forward pull `github/` 下所有仓库，脏工作树跳过，失败汇总退出码
+- 测试新增 `scans repository-provided root skills`：覆盖 `skills/<name>/` 扫描 + 启用路径
+
+### Changed
+- `lib/skillStore.js`：
+  - `ensureSourceFolders` 同时创建 `skills/`
+  - `scanSkills` 增加 `scanRepositorySkills`，先扫仓库自带再扫外部源
+  - `scanSourceFolder(rootDir, sourceFolder, source = sourceFolder)` 增加可选第三参支持自定义 source label（向后兼容：默认仍等于目录名）
+  - `assertInsideSources` 接受 `skills/`，错误信息更新为"来源目录或仓库 skills 目录内"
+
+## [0.3.0] - 2026-06-28
+
+### Added
+- 新模块 `lib/projectPath.js`：集中 `projectPath` 校验
+  - `normalizeProjectPath(value)`：拒绝系统目录（`/`、`/Applications`、`/Library`、`/System`、`/bin`、`/etc`、`/opt`、`/private`、`/sbin`、`/tmp`、`/usr`、`/var`）、用户主目录 `$HOME`、以及 `$HOME` 的祖先目录；`path.resolve` 后返回
+  - `requirePath(value, label)`：从 `claudeStore.js` 抽出的非空 + 类型校验，供 `projectPath.js` 与 `skillStore.js` 复用
+- 新模块 `lib/projectActions.js`：`enableProjectSkill(rootDir, input)` 包装 `enableSkill`，启用后 best-effort 调用 `syncClaudeSkills`，结果合并为 `{ ...enableResult, claudeSync: { ok: true, ... } | { ok: false, error } }`，Claude 同步失败不会抛出
+- 测试新增 `project enable syncs Claude skills best-effort`：覆盖 `enableProjectSkill` 正常路径（claude 同步成功 + agents 启用都生效）
+
+### Changed
+- `lib/claudeStore.js`、`lib/skillStore.js`：所有接受 `projectPath` 的入口（`syncClaudeSkills` / `getClaudeStatus` / `unlinkClaudeSkill` / `getAgentsSkillsDir` / `getClaudeSkillsPath` / `scanEnabledSkills` / `getState`）改为先调用 `normalizeProjectPath`，删除 `claudeStore.js` 内本地 `requirePath`
+- `server.js`：`/api/enable` 路由从 `enableSkill` 切到 `enableProjectSkill`，响应体新增 `claudeSync` 字段（向后兼容，原有字段保留）
+- `public/app.js`：新增 `enableMessage(name, result)`，根据 `claudeSync` 给出三种 UI 文案——默认"已启用 X"；`claudeSync.ok=true` 时"已启用 X，并同步 Claude Code"；`claudeSync.ok=false` 时"已启用 X；Claude Code 自动同步失败：<error>"
+
+### Security
+- `projectPath` 服务端校验前置到 `normalizeProjectPath`，早于任何文件系统操作；不合法路径直接拒绝（防止误把 `/`、`/Users` 等作为目标执行 symlink / readdir）
+
+## [0.2.1] - 2026-06-27
+
+### Fixed
+- Skill 原件库分组标题箭头 `▾` 与文字水平对齐：把 `.chevron` 移进 `<h3>` 内部，h3 改为 flex 容器（`align-items: center` + `gap: 8px`），箭头自身改为 `inline-flex` + `height: 1em`，按字形而非行盒做垂直居中，修复此前箭头视觉上偏低的问题
+- 箭头加 `aria-hidden="true"`，避免屏幕阅读器重复读出
+
+### Changed
+- `app.js`：`groupElement.querySelector('h3')` 改为 `groupElement.querySelector('h3 .title')`，标题文本写入新增的 `.title` span，避免 `textContent` 把箭头字符冲掉
+
+## [0.2.0] - 2026-06-27
+
+### Changed
+- 品牌重命名：标题、`<h1>`、启动日志从 "AI Skills Manager" 改为 "Skillcaddy"
+- `.claude/skills` 不再是 `.agents/skills` 的目录级软链接，改为真实目录 + 每个 skill 一条独立软链接
+  - agents 列禁用某个 skill 不再连带清除 Claude Code 列的同条目（断链显示而非消失）
+  - Claude Code 列清理某个 skill 不再连带影响 agents 列
+  - 旧版 layout（`.claude/skills -> ../.agents/skills`）会在下次 `syncClaudeSkills()` 时自动迁移
+- Claude Code 列卡片去掉"查看"按钮与对应的 SKILL.md 预览面板，操作只剩"清理"
+- 删除顶部"原件 / 已启用 / 可用"汇总栏（信息冗余）
+- agents skill 卡片从 grid 垂直布局改为 flex 横向布局，与 Claude Code 列对齐
+- agents skill 名在是软链接时前缀 `🔗` 图标，按钮文字"禁用"→"清理"
+- 启用 / 清理按钮统一使用 `secondary danger`（白底红字）样式
+- 两列条目按 alias 字母序排序（agents 在 `lib/skillStore.js`；Claude 在 `lib/claudeStore.js`）
+- 启动日志 `Skillcaddy: http://127.0.0.1:4173`
+
+### Added
+- 标题处版本号徽章（`/api/version` 端点 + 启动时缓存 `package.json`）
+- agents 列、Claude Code 列、Skill 原件库面板标题加 `count` 计数徽章
+- `.gitignore` 排除 `.agents/`、`.claude/`（防止本机状态入库）
+- 字体 / 颜色 token 化（`styles.css` 顶部 CSS 变量）
+- 4 个新测试：per-skill 软链接布局、agents/Claude 列表独立性、旧版 layout 自动迁移、两列按字母排序
+
+### Removed
+- Claude Code 状态行（"软链接 /path -> /target · N 个 skill"）——诊断信息泄露路径
+- `/api/read-claude-skill` 端点、`lib/claudeStore.js` 的 `readClaudeSkill`、前端 `readClaudeSkill` 函数、`<section id="claudeSkillContent">` 节点、相关 CSS（`.skill-content` / `.content-head` / `.skill-content pre`）
+- `agentsUi.js` 旧版 grid 布局、`.enabled-head` CSS、text badge `link`/`file`
+
+## [0.1.0] - 2026-06-27
+
+### Added
+- 初始版本
+- 本地 skill 原件库扫描（official / github / personal / archived 四个来源）
+- 按项目软链接启用 skill 到 `.agents/skills/<alias>`
+- 可选同步 Claude Code 入口（创建 `.claude/skills` 指向 `.agents/skills`）
+- 一键启用 / 禁用 agents skills
+- 一键加入 / 清理 Claude Code skills
+- 单个 Claude skill 读取、禁用
+- Web UI（`public/`）展示原件库、已启用列表、Claude skill 状态
+- 基础测试覆盖（`node --test test/*.test.js`）