@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.3

package/CONTRIBUTING.md

@@ -9,3 +9,25 @@ Skill installs must not overwrite existing directories. Local removal must reval
 The supported Harness cohort lives in `compatibility.json`. Keep all development packages on that exact cohort and document source/tag evidence before broadening support. Do not copy historical support ranges from another plugin.
 
 Commit regenerated `lib/` with source changes because Git installations consume it. Release metadata, compatibility, English/Chinese installation commands and release notes must agree. Follow `docs/RELEASE.md`; a passing test suite is not evidence that publication or real desktop acceptance happened.
+
+## CLI and local source installation
+
+For CLI users and local development, install a specific published version:
+
+```sh
+dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.3
+```
+
+Replace `desktop` with the target profile. To test a local source build:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm pack --pack-destination artifacts
+dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.3.tgz
+```
+
+Fully quit and reopen the target Harness instance after a CLI install. Advanced configuration is documented in [CONFIGURATION.md](./docs/CONFIGURATION.md).
+
+## Curated catalogue
+
+The marketplace home list comes from `catalog/curation.json` (editorial: which skills, category, Chinese summary, picks) and its generated snapshot `src/catalog/skills.json`. To add or remove a skill, edit the curation, run `node scripts/catalog-refresh.mjs`, review the entries it reports as dropped, then `pnpm build`. Selection and security rules are in `docs/CATALOG.md`.

package/README.md

@@ -3,118 +3,68 @@
 </p>
 
 <p align="center">
-  <img src="./assets/readme/hero-zh.png" width="100%" alt="Skills Hub：发现技能，装进你的工作流。3D 技能文档汇入蓝色收纳座的概念插画。">
+  <img src="./assets/readme/hero-zh.png" width="100%" alt="Skills Hub：发现技能，装进你的工作流。">
 </p>
 
 <p align="center">
   <strong>DeepSeek Harness 的技能市场与本机技能管理器</strong><br>
-  浏览 ClawHub 与 SkillHub，读懂 SKILL.md，再安装到你的 Harness。
+  浏览 ClawHub 与 SkillHub，找到适合你的技能。
 </p>
 
 <p align="center">
-  <a href="#快速开始">快速开始</a> · <a href="./docs/COMPATIBILITY.md">兼容性</a> · <a href="./docs/RELEASE.md">发布指南</a> · <a href="./LICENSE">MIT</a>
+  <a href="#快速开始">快速开始</a> · <a href="./docs/COMPATIBILITY.md">兼容性</a> · <a href="./LICENSE">MIT</a>
 </p>
 
-## 技能发现和本机管理，在同一个面板里
+## 在 Harness 里发现、安装和管理技能
 
-**Skills Hub** 把两个技能市场与本机用户技能放进 Harness 侧栏。无需在网站、下载目录和技能文件夹之间来回切换：搜索、查看文档、确认安装，再到「已安装技能」里统一管理。
+搜索 ClawHub 和 SkillHub 中的技能，阅读使用说明，再安装到 Harness。市场安装的技能和本机已有技能，都可以在「已安装技能」中查看和管理。
+
+当前版本：**0.0.3**。首页改为 398 个精选技能、13 个分类，详情页重新设计，并能说明技能安装后会做什么。[更新说明](./release-notes/v0.0.3.md)
 
 <p align="center">
-  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub 在 DeepSeek Harness 中的实际界面：技能卡片、搜索与筛选、来源健康状态，以及已安装技能入口。">
+  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub 技能市场：分类、搜索、筛选和精选技能卡片。">
 </p>
 
-*实际 Harness 0.2.0-rc.2 界面；市场内容随上游更新。顶部 3D Hero 为概念插画。*
-
-| 你要做的事 | Skills Hub 怎么帮你 |
+| 功能 | 说明 |
 | --- | --- |
-| **找一个技能** | 聚合 ClawHub 与 SkillHub，支持搜索和筛选；向下滚动自动加载更多。 |
-| **先看清，再安装** | 渲染 Markdown、表格和代码块，预览包内文件与上游安全报告；列表和详情都有骨架屏。 |
-| **整理已安装技能** | 搜索市场安装和本机用户技能，查看来源、实际路径与正文，再确认卸载。 |
+| **精选清单** | 398 个 ClawHub 与 SkillHub 热门技能，按 13 个分类整理，随插件发布，打开即看。 |
+| **实时搜索** | 输入关键词即搜索两个市场的全部技能，同名技能按作者区分。 |
+| **安装前预览** | 阅读说明和文件，查看上游安全扫描，以及技能会执行的命令、读取的密钥和访问的网络。 |
+| **管理已安装技能** | 搜索本机技能，查看来源与安装位置，确认后卸载。 |
+| **本地缓存** | 缓存已浏览的分页、详情和文件预览，重启后继续使用。 |
 
 ## 快速开始
 
-**插件 `0.0.1` · 宿主 `0.2.0-rc.2`**。面向 DeepSeek Harness 0.2.0 桌面端产品线；其他宿主版本尚未验证。[查看验收范围 →](./docs/COMPATIBILITY.md)
-
-在运行桌面端的 profile 中安装：
-
-```sh
-dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.1
-```
+适用于 **DeepSeek Harness 0.2.0-rc.2**。[兼容版本](./docs/COMPATIBILITY.md)
 
-完全退出并重新打开 Harness，在侧栏点击 **技能市场**。使用其他 profile 时，把 `desktop` 替换成对应名称。
+打开 **DeepSeek Harness 桌面端 → 插件 → 添加插件**，粘贴以下任意一种内容：
 
-1. **浏览**：搜索关键词，或按来源、安全状态筛选。
-2. **预览**：打开技能，阅读概览和文件内容。
-3. **安装**：核对来源并确认；在「已安装技能」中查看、搜索或卸载。
+**GitHub 仓库地址（推荐）**
 
-> 包名必须带 `@nanmicoder/`。npm 上不带 scope 的 `dsh-skills-hub` 属于其他作者。
-
-<details>
-<summary><strong>从源码安装</strong></summary>
-
-需要 Node.js `^22.19.0 || >=24` 和 pnpm `10.33.0`。
-
-```sh
-pnpm install --frozen-lockfile
-pnpm pack --pack-destination artifacts
-dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.1.tgz
+```text
+https://github.com/NanmiCoder/dsh-skills-hub
 ```
 
-同样需要完全重启 Harness。构建产物随源码保留，打包前会重新构建和检查。
-
-</details>
+**或 npm 包名**
 
-## 已安装管理，路径清楚，操作明确
-
-列表覆盖配置的安装目录、`$DSH_HOME/skills` 与共享 agents 用户技能目录。目录式技能、平铺 Markdown 和符号链接都能识别；同名但不同路径的技能分别展示。
-
-- **确认后卸载**：展示将要删除的实际位置。
-- **链接只删链接**：保留它指向的原始技能文件。
-- **管理用户技能**：项目级和内置技能不在这个主机级列表中。
-
-安装过程不执行技能脚本，也不会覆盖已有目录。技能可能指示 agent 后续运行第三方代码；安全标签来自上游报告，不代表独立审计。请在安装前查看内容和发布者。
-
-<details>
-<summary><strong>配置与移除插件</strong></summary>
-
-默认配置即可使用。高级配置写在插件行中：
-
-```yaml
-- id: skills-hub
-  name: '@nanmicoder/dsh-skills-hub'
-  config:
-    allowUninstall: false
-    timeoutMs: 30000
+```text
+@nanmicoder/dsh-skills-hub@0.0.3
 ```
 
-| 配置项 | 默认值 | 说明 |
-| --- | --- | --- |
-| `skillsRoot` | `null` | 安装目录；默认是 Harness 用户技能目录。 |
-| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API 地址。 |
-| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API 地址。 |
-| `timeoutMs` | `15000` | 单次上游请求超时，单位毫秒。 |
-| `requestRetries` | `1` | 网络及服务器错误重试次数。 |
-| `allowUninstall` | `true` | 是否允许在面板卸载技能。 |
-| `pageSize` | `24` | 市场分页大小。 |
-
-移除插件本身：
+点击 **安装 → 立即启用**，然后从侧栏进入 **技能市场**。
 
-```sh
-dsh plugin --profile desktop remove @nanmicoder/dsh-skills-hub
-```
+## 使用
 
-这不会删除已安装的技能。文件扫描范围与接口见[实现约定](./docs/CONTRACT.md)。
+1. **查找**：按分类浏览精选清单，或输入关键词搜索全部技能。
+2. **预览**：打开技能，查看说明和文件内容。
+3. **安装与管理**：确认安装后，到「已安装技能」中查看或卸载。
 
-</details>
+技能由第三方社区作者发布；Skills Hub 是社区插件，并非 DeepSeek 官方出品。精选清单只做整理推荐，不构成安全担保，安装前请查看安全报告与 SKILL.md。
 
-## 开发与发布
+## 已安装技能
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check       # 类型、构建、回归测试与版本检查
-pnpm pack:check  # 另检查 npm 包内容及运行时依赖闭包
-```
+在「已安装技能」中，可以统一查看和卸载市场安装及本机已有的用户技能。项目内技能和 Harness 内置技能不在此列表中。
 
-[贡献指南](./CONTRIBUTING.md) · [维护规范](./AGENTS.md) · [兼容性与验收](./docs/COMPATIBILITY.md) · [0.0.1 发布流程](./docs/RELEASE.md)
+卸载前会显示具体位置，供你确认。若只想移除 Skills Hub 插件，在桌面端 **插件** 页面打开 **@nanmicoder/dsh-skills-hub**，点击 **卸载**；已安装的技能会保留。
 
-MIT 许可证。详见 [LICENSE](./LICENSE)。
+[反馈问题](https://github.com/NanmiCoder/dsh-skills-hub/issues) · [高级配置](./docs/CONFIGURATION.md) · [参与开发](./CONTRIBUTING.md) · [MIT 许可证](./LICENSE)

package/README_EN.md

@@ -3,118 +3,68 @@
 </p>
 
 <p align="center">
-  <img src="./assets/readme/hero-en.png" width="100%" alt="Skills Hub for DeepSeek Harness. Your skills. One place. A conceptual 3D library of skill documents in a blue dock.">
+  <img src="./assets/readme/hero-en.png" width="100%" alt="Skills Hub for DeepSeek Harness. Your skills. One place.">
 </p>
 
 <p align="center">
   <strong>A skill marketplace and local skill manager for DeepSeek Harness</strong><br>
-  Browse ClawHub and SkillHub, read SKILL.md, then install into Harness.
+  Browse ClawHub and SkillHub to find the skills you need.
 </p>
 
 <p align="center">
-  <a href="#quick-start">Quick start</a> · <a href="./docs/COMPATIBILITY.md">Compatibility</a> · <a href="./docs/RELEASE.md">Release guide</a> · <a href="./LICENSE">MIT</a>
+  <a href="#quick-start">Quick start</a> · <a href="./docs/COMPATIBILITY.md">Compatibility</a> · <a href="./LICENSE">MIT</a>
 </p>
 
-## Discovery and local management, in one panel
+## Discover, install and manage skills in Harness
 
-**Skills Hub** brings two marketplaces and your local user skills into the Harness sidebar. Search, inspect the instructions, confirm an installation, and manage it from the **Installed** view.
+Search ClawHub and SkillHub, read a skill’s instructions, and install it into Harness. Manage marketplace installations and existing local skills together in **Installed**.
+
+Current version: **0.0.3**. The home page now opens on 398 curated skills in 13 categories, with a redesigned detail page that explains what a skill will do once installed. [Release notes](./release-notes/v0.0.3.md)
 
 <p align="center">
-  <img src="./assets/readme/marketplace.png" width="100%" alt="Actual Skills Hub panel in DeepSeek Harness: skill cards, search, filters, source health and the installed-skills entry.">
+  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub marketplace with categories, search, filters and curated skill cards.">
 </p>
 
-*Actual Harness 0.2.0-rc.2 interface, shown in Chinese. Catalogue content changes upstream. The 3D hero is a conceptual illustration.*
-
-| What you want to do | How Skills Hub helps |
+| Feature | What it does |
 | --- | --- |
-| **Find a skill** | Search and filter ClawHub and SkillHub together. More results load as you scroll. |
-| **Inspect before installing** | Read Markdown, tables and code blocks; preview package files and upstream security reports. List and detail skeletons make loading visible. |
-| **Manage installed skills** | Search marketplace installations and local user skills, inspect their source, path and instructions, then confirm removal. |
+| **Curated catalogue** | 398 popular ClawHub and SkillHub skills in 13 categories, shipped with the plugin and shown instantly. |
+| **Live search** | Type a keyword to search every skill on both marketplaces; same-name skills are told apart by author. |
+| **Preview before installing** | Read instructions and files, check upstream scans, and see the commands, secrets and network hosts a skill uses. |
+| **Manage installed skills** | Search local skills, inspect their source and installation path, and confirm removal. |
+| **Local cache** | Reuse browsed pages, details and file previews across desktop restarts. |
 
 ## Quick start
 
-**Plugin `0.0.1` · Harness `0.2.0-rc.2`.** Targets the DeepSeek Harness 0.2.0 desktop release line; other host versions have not been validated. [See acceptance scope →](./docs/COMPATIBILITY.md)
-
-Install into your desktop profile:
-
-```sh
-dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.1
-```
+Supports **DeepSeek Harness 0.2.0-rc.2**. [Compatible versions](./docs/COMPATIBILITY.md)
 
-Fully quit and reopen Harness, then choose **Skills Hub** in the sidebar. Replace `desktop` with your profile name if needed.
+Open **DeepSeek Harness desktop → Plugins → Add plugin** and paste either of the following:
 
-1. **Browse**: search a keyword or filter by source and security status.
-2. **Preview**: open a skill and read its overview and files.
-3. **Install**: confirm its source; use **Installed** to inspect, search or remove it later.
+**GitHub repository URL (recommended)**
 
-> Keep the `@nanmicoder/` scope. The unscoped npm package `dsh-skills-hub` belongs to another author.
-
-<details>
-<summary><strong>Install from source</strong></summary>
-
-Requires Node.js `^22.19.0 || >=24` and pnpm `10.33.0`.
-
-```sh
-pnpm install --frozen-lockfile
-pnpm pack --pack-destination artifacts
-dsh plugin --profile desktop add ./artifacts/nanmicoder-dsh-skills-hub-0.0.1.tgz
+```text
+https://github.com/NanmiCoder/dsh-skills-hub
 ```
 
-Restart Harness afterward. Build artifacts are committed with source and rebuilt and checked before packing.
-
-</details>
+**Or the npm package name**
 
-## Local management with explicit paths
-
-The list covers the configured installation root, `$DSH_HOME/skills` and the shared agents user skills directory. It discovers directory-based skills, flat Markdown files and symlinks. Skills with the same name at different paths remain separate entries.
-
-- **Confirm removals** after checking the exact location.
-- **Unlink linked skills** without deleting their original files.
-- **Manage user skills**; project-specific and bundled skills are outside this host-level list.
-
-Installation does not execute skill scripts or overwrite existing directories. Skills may instruct an agent to run third-party code later. Security labels are upstream reports, not independent audits; review the contents and publisher before installing.
-
-<details>
-<summary><strong>Configuration and plugin removal</strong></summary>
-
-Defaults work out of the box. Advanced settings belong in the plugin row:
-
-```yaml
-- id: skills-hub
-  name: '@nanmicoder/dsh-skills-hub'
-  config:
-    allowUninstall: false
-    timeoutMs: 30000
+```text
+@nanmicoder/dsh-skills-hub@0.0.3
 ```
 
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `skillsRoot` | `null` | Installation root; defaults to Harness's user skills directory. |
-| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API origin. |
-| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API origin. |
-| `timeoutMs` | `15000` | Per-request upstream timeout in milliseconds. |
-| `requestRetries` | `1` | Retries for network and server failures. |
-| `allowUninstall` | `true` | Allow skill removal from the panel. |
-| `pageSize` | `24` | Marketplace page size. |
-
-Remove the plugin itself:
+Click **Install → Enable now**, then open **Skills Hub** from the sidebar.
 
-```sh
-dsh plugin --profile desktop remove @nanmicoder/dsh-skills-hub
-```
+## Use
 
-This does not delete installed skills. See the [implementation contract](./docs/CONTRACT.md) for discovery scope and APIs.
+1. **Find**: browse the curated catalogue by category, or enter a keyword to search every skill.
+2. **Preview**: open a skill to read its instructions and inspect its files.
+3. **Install and manage**: confirm installation, then find or remove it in **Installed**.
 
-</details>
+Skills are published by third-party community authors. Skills Hub is a community plugin, not a DeepSeek product. The curated list is a recommendation, not a security guarantee; check the security report and SKILL.md before installing.
 
-## Develop and release
+## Installed skills
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check       # types, build, regression tests and release metadata
-pnpm pack:check  # also inspect package contents and runtime import closure
-```
+Use **Installed** to view and remove marketplace installations and existing local user skills. Project-specific skills and skills bundled with Harness are not included.
 
-[Contributing](./CONTRIBUTING.md) · [Maintenance rules](./AGENTS.md) · [Compatibility and acceptance](./docs/COMPATIBILITY.md) · [0.0.1 release guide](./docs/RELEASE.md)
+The removal dialog shows the exact location for you to confirm. To remove Skills Hub itself, open **@nanmicoder/dsh-skills-hub** on the desktop **Plugins** page and click **Uninstall**. Your installed skills will remain.
 
-MIT. See [LICENSE](./LICENSE).
+[Report an issue](https://github.com/NanmiCoder/dsh-skills-hub/issues) · [Advanced configuration](./docs/CONFIGURATION.md) · [Contribute](./CONTRIBUTING.md) · [MIT license](./LICENSE)

package/README_ZH.md

@@ -2,4 +2,6 @@
 
 中文文档已成为仓库默认首页，请查看 [README.md](./README.md)。
 
+当前版本：**0.0.3**。[更新说明](./release-notes/v0.0.3.md)
+
 [English documentation](./README_EN.md)

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "pluginVersion": "0.0.1",
+  "pluginVersion": "0.0.3",
   "recommendedHost": "0.2.0-rc.2",
   "hostTag": "dsh-v0.2.0-rc.2",
   "hostCommit": "639ed015397290b3745d163aafe02ffee4aa3f84",

package/docs/CATALOG.md

@@ -0,0 +1,39 @@
+# Curated catalogue
+
+The marketplace home list is a curated catalogue of a few hundred skills, not the upstream registries' full feeds. ClawHub holds ~81k skills and SkillHub ~110k native ones; a reader cannot choose from that, and the long tail is dominated by near-duplicates, copies and abandoned experiments.
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `catalog/curation.json` | Editorial source: categories, and for each skill its `source`, `slug`, `owner`, `category`, `featured`, Chinese `summary`, `tags`, and `allowSuspicious` when applicable. Edited by hand. |
+| `src/catalog/skills.json` | Snapshot generated from the curation plus upstream metadata (name, stats, version, icon, license, security verdict). Shipped in `lib/` and served as the home list. |
+| `scripts/catalog-refresh.mjs` | Regenerates the snapshot. `--check` reports without writing. |
+
+Run `node scripts/catalog-refresh.mjs`, review the dropped entries it prints, then rebuild (`pnpm build`) so `lib/catalog/skills.json` follows.
+
+## What is served from where
+
+- **List, categories, catalogue search:** the snapshot. No upstream request; the source bar shows the snapshot's `generatedAt` as the fetch time.
+- **Detail, files, install:** the owning registry, through the regular cache. Catalogue entries pin the ClawHub owner, because ClawHub slugs are not unique and the registry's first match for a popular slug is often a later copy by another author.
+- **"Search all markets":** an explicit live search across both registries (`scope=market`). Results are labelled as not curated.
+
+SkillHub's mirrors of ClawHub skills are not used for ClawHub entries: the mirror pipeline stopped on 2026-07-23, roughly one in ten mirrored skills lags its ClawHub version, and mirror files differ from the original (`skill-card.md` dropped, `_meta.json` added).
+
+## Selection policy
+
+Candidates were the top 1,500 ClawHub skills by downloads and the top 600 SkillHub native skills, reviewed per category for usefulness, popularity and distinctness (one or two per job, not five wrappers of the same API). Excluded:
+
+- skills only meaningful inside OpenClaw/Clawdbot (gateway hooks, OpenClaw configuration, Clawdbot channels);
+- paid versions, crypto trading or anything moving money automatically, fake engagement or mass account automation, adult content;
+- SkillHub slugs that resolve to a different owner than the curated one (SkillHub's detail route is slug-only);
+- ambiguous ClawHub slugs whose remaining owners are low-download copies (`summarize`, `find-skills`, `agent-browser`, `tavily-search`).
+
+## Security policy
+
+- ClawHub: the moderation verdict and the latest version's scan (VirusTotal, skillspector, LLM review). SkillHub: the vendor security reports.
+- `malicious` or blocked: never listed.
+- `suspicious`: listed only when the curation entry carries `allowSuspicious` with the reason, and shipped as `flagged` with that reason in `securityNote`. This is reserved for widely recommended skills whose finding is about disclosure or permission scope, not hidden behaviour. Skills that upload local content, update their own code from a remote source, or expose credentials are not exempted.
+- A refresh re-checks every entry; a newly suspicious skill without `allowSuspicious` drops out of the snapshot.
+
+A clean verdict is upstream's, not ours. Installing still shows the source and verdict, and installation never executes skill scripts.

package/docs/COMPATIBILITY.md

@@ -29,3 +29,49 @@ Ego Lite drove the actual host UI. Slow fixture upstream responses made the load
 `pnpm pack:check` passed 44 tests without failures or skips, including live provider list/detail/file/install/uninstall, request-origin fencing, local removal policy, duplicate paths, symlink preservation, bounded file reads, Markdown rendering and controller concurrency. A final clean build and tarball closure check followed the visual/style fixes. npm publication dry-run and registry name/version preflight succeeded. No package was published, Git tag created, repository visibility changed or active user profile modified. Local npm authentication was absent (`npm whoami`: `ENEEDAUTH`); publication requires an authorized login or the documented CI secret.
 
 Local-only logs and screenshots are kept in the ignored `artifacts/` directory. CI covers Node 22.19 and 24; those CI jobs and a native desktop launch were not run in this local acceptance.
+
+## Installed-skill detail revision — 2026-09-30
+
+The local skill detail moved from the primitive's 380px modal to a full-panel page on the shared detail shell. Re-verified on the same cohort (`@deepseek-ai/dsh@0.2.0-rc.2` from npm, macOS arm64 / Node 26.7.0) with an isolated `DSH_HOME`/`DSH_AGENTS_HOME`, a disposable Web profile and a tarball install of this revision; the user's real profile was not touched.
+
+The run covered: the installed inventory (six rows), a search query surviving the round trip to the detail and back (with focus returned to the row that was opened), the market-installed skill's page (provenance badge, path line, 4-file inventory, rendered GFM table, collapsed YAML metadata, rail facts, "view in marketplace" opening the provider-backed page), a hand-placed skill (market rows absent rather than zero, no marketplace link), a symlink entry (linked badge), the Files tab with per-file preview switching, and removal from the detail page — confirmation showing the exact path, then row and directory both gone. Focus lands on the heading when the page opens; there is no horizontal overflow at 760px; light and dark themes were both inspected; the console stayed clean.
+
+One defect was found and fixed by this run: the uninstall confirmation was rendered only in the list branch, so the detail page's removal button did nothing.
+
+Deviation from the procedure above: Ego Lite's browser skill was not available to this session, so the drive used headless Chromium (Playwright 1.60.0) instead. Screenshots are in `artifacts/local-detail-acceptance/`; the results are recorded as observed, not inferred from fixture tests.
+
+## Markdown file preview revision — 2026-09-30
+
+The Files tab now renders markdown (frontmatter split into the structured metadata panel, body through the bundled GFM renderer) and keeps the exact bytes behind a preview/source switch. Verified with **ego-browser 0.5.1.13** against an isolated profile on the same host cohort, driving the real UI: an installed skill (`skillhub:anti-fraud`, 4 files) and a market skill (`clawhub:skill-vetter`, 2 files, live upstream).
+
+Recorded results — installed skill, Files tab: preview showed 1 table, 4 headings, 6 list items and 1 code block with the metadata panel and no literal `**`; the source view showed 67 line-number spans, the raw `name: anti-fraud` header and the literal `**先定级，再开口**`. Selecting another file returned to the rendered form. Market skill, Files tab: preview showed 12 headings, 15 list items, 5 code blocks and 1 table, again with no literal `**`; source showed 278 line-number spans and the raw `name: skill-vetter` header. Screenshots are in `artifacts/markdown-preview-verify/`.
+
+This run used the Ego Lite browser as the project procedure requires; the earlier Playwright deviation applied only to the revision above.
+
+## Provenance and look-ahead revision — 2026-09-30
+
+Cache answers now carry the moment they were read from upstream instead of being restamped with the current clock, a reader-requested refresh (`refresh=1`) reaches upstream, the panel prints the snapshot age, and the next catalogue page is fetched one screen before it is needed. Verified in an isolated profile on the same cohort, driving the real UI and the plugin's own endpoints.
+
+Recorded results: two identical list reads returned `fromCache: false` then `fromCache: true` **with the same `fetchedAt`**; `refresh=1` returned `fromCache: false` with a newer timestamp while `forcedRefreshes` and `upstreamRequests` advanced by one each; `refresh=maybe` was rejected with 400; the status bar rendered `ClawHub 正常 快照 刚刚`; a fresh page with no scrolling issued **0** cursor requests; scrolling to within 708px of the container's end (sentinel still 639px below the fold) issued cursor requests immediately, which is the look-ahead — measured with a viewport-rooted observer reporting "not intersecting" for the same sentinel, confirming the container root is required. Screenshots are in `artifacts/p0-p1-verify/`.
+
+## Persistent cache regression — 2026-09-30
+
+The previous cache lived only in the host process's `Map`; the provenance revision above did not persist it across exits. The host now stores snapshots under its Harness home and defaults to a one-hour TTL (`cacheTtlMinutes` can change it).
+
+Automated regression uses the compiled plugin in separate Node HTTP host processes with a minimal Cordis context, isolated `DSH_HOME`/`DSH_AGENTS_HOME` and fixture upstreams. After reading three cursor pages, a search, both providers' details and both file previews, the test kills the host with `SIGKILL` and boots a new process against the same temporary home. Every repeated read is served without additional upstream requests; original `fetchedAt` values survive, and a skill installed while the host was stopped is annotated from the new filesystem scan. Further restarts verify refreshed snapshots, expiry, stale list/detail fallback during upstream failure, and isolation when provider URLs change. Unit coverage includes corrupt records, failed disk writes, concurrent atomic publication, count limits and a shorter configured TTL. Install-time manifest reads reject upstream failure even when a snapshot exists.
+
+Adversarial review also covered the actual HTTP install entry point (a withdrawn manifest is rejected despite a fresh disk snapshot), first-response installation annotations without an `/installed` warmup, browser revalidation and per-page provenance, configuration changes during asynchronous cache reads and multi-step installation, snapshot integrity, oversized replacement invalidation, and abandoned temporary writes. Regression tests cover each behavior.
+
+The automated evidence above is process-restart coverage rather than a full native acceptance run. Separately, the user authorized installation into the active desktop: a locally packed build was installed using the desktop's bundled package manager while it was stopped, then DeepSeek Harness **0.2.0-rc.2** was relaunched. The actual market loaded 24 entries from each source and wrote two list snapshots with a 60-minute lifetime. This smoke check does not claim a native restart-after-warm acceptance of every cached path. The supported Harness cohort remains unchanged.
+
+### Curated catalogue, owner pinning and detail redesign
+
+The home list now comes from the shipped curated catalogue, ClawHub reads are pinned to the card's author, and the market detail page follows the redesign (header with stats, overview/files/security/changelog tabs, rule-based "what this skill does" and "when it triggers", redesigned install confirmation). Verified with **ego-browser** against the published `@deepseek-ai/dsh@0.2.0-rc.2` runtime (all 278 Harness packages on the same cohort) in a disposable Web profile with temporary `DSH_HOME`/`DSH_AGENTS_HOME`, macOS arm64 / Node 26.7.0, from a tarball of this revision; the user's real profile and desktop app were not touched.
+
+Recorded results: the home list rendered the 13 catalogue categories with counts and editor's picks dealt across categories, with no upstream list request. A flagged ClawHub skill (`self-improving-agent`) showed the suspicious scan chip, per-scanner reports including the LLM review text, the bundled `CHANGELOG.md` entry point, and an install dialog whose confirm button stayed disabled until the acknowledgement was checked. A SkillHub skill (`libai`) showed a passed scan, its catalogue category and sub-category tags. At a 720px panel the side rail moved below the document with no horizontal overflow; dark mode followed the host tokens. Installing `clawhub:weather` through the dialog wrote `"owner": "steipete"` to the sidecar and switched the page to installed; uninstalling removed the directory. `pnpm pack:check` passed 96 tests. Screenshots are kept locally in `artifacts/catalog-redesign-verify/`.
+
+The catalogue home and the installed inventory were then brought onto the same visual system (white top band over a grey canvas of 14px-radius cards, shared chips, mono counts, black primary actions), and both detail pages now share one `SkillDetailShell`. Re-verified the same way: the home shows the catalogue total and list date instead of live source health, which appears only for an explicit all-markets search (28 live results for `pdf`, with per-source status); installing from a card switched it to installed; the installed list and its detail rendered in the shared layout; a 720px panel had no horizontal overflow and dark mode followed the host tokens. `pnpm pack:check` passed 96 tests.
+
+## 0.0.3 release preparation — 2026-10-02
+
+The 0.0.3 release commit changes only version metadata, documentation and the README screenshot on top of the revisions recorded above. The README marketplace screenshot was retaken with ego-browser from the packed 0.0.3 tarball in an isolated Web profile (same `@deepseek-ai/dsh@0.2.0-rc.2` cohort, temporary `DSH_HOME`/`DSH_AGENTS_HOME`). It shows the curated home and the community-plugin disclaimer. `pnpm pack:check` was rerun on the release commit. No package was published and no tag was pushed.

package/docs/CONFIGURATION.md

@@ -0,0 +1,38 @@
+# 高级配置
+
+日常使用可直接在桌面端安装和管理插件，无需修改配置。以下内容供需要自定义安装目录、数据源或移除权限的用户参考。
+
+配置写在插件行中：
+
+```yaml
+- id: skills-hub
+  name: '@nanmicoder/dsh-skills-hub'
+  config:
+    allowUninstall: false
+    timeoutMs: 30000
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `skillsRoot` | `null` | 安装目录；默认是 Harness 用户技能目录。 |
+| `clawhubBaseUrl` | `https://clawhub.ai` | ClawHub API 地址。 |
+| `skillhubBaseUrl` | `https://api.skillhub.cn` | SkillHub API 地址。 |
+| `timeoutMs` | `15000` | 单次上游请求超时，单位毫秒。 |
+| `requestRetries` | `1` | 网络及服务器错误重试次数。 |
+| `allowUninstall` | `true` | 是否允许在面板卸载技能。 |
+| `pageSize` | `24` | 市场分页大小。 |
+| `cacheTtlMinutes` | `60` | 列表分页、搜索、技能详情及文件预览的本地缓存有效期，单位分钟，范围 1–1440。 |
+
+## 市场缓存
+
+浏览过的市场分页、详情及文件预览会自动保存到 `$DSH_HOME/cache/skills-hub/v1`（未设置 `DSH_HOME` 时为 `~/.dsh/cache/skills-hub/v1`），退出并重启 Harness 后仍可复用。默认从上游获取成功时起保留 1 小时，再次浏览不会延长有效期；超过有效期会重新请求上游。面板中的列表或详情手动刷新会立即重新拉取并替换对应快照；文件预览按自身有效期读取。重开详情时可先显示上一份快照，随后向本地 Host 核对有效期和当前安装状态，缓存有效时不会请求上游。
+
+缓存按数据源地址、查询条件、分页游标和分页大小区分，不受技能安装目录影响。安装状态仍根据当前本地文件计算。安装技能时会重新读取上游清单，失败时不会使用缓存清单继续安装。
+
+磁盘最多保留 500 条快照、64 MiB，旧快照优先清理。过期的列表和详情仅在上游失败时用于浏览兜底，最多保留 7 天；缓存损坏或无法写入时，市场仍可通过内存缓存和上游请求工作。
+
+## 技能发现范围
+
+列表覆盖配置的安装目录、`$DSH_HOME/skills` 与共享 agents 用户技能目录。支持目录式技能、平铺 Markdown 和符号链接；同名但不同路径的技能分别展示。删除符号链接时仅移除链接，保留目标文件。项目级与内置技能不在此列表中。
+
+接口和路径校验规则见[实现约定](./CONTRACT.md)。

package/docs/CONTRACT.md

@@ -1,10 +1,10 @@
-# Skills Hub 0.0.1 implementation contract
+# Skills Hub 0.0.3 implementation contract
 
 This document describes the shipped code, not a migration plan. The TypeScript models in `src/market/types.ts`, `src/skills/installed.ts` and `src/client/api.ts` define the detailed wire shapes. Update this document with API changes.
 
 ## 1. Package and host
 
-The package is `@nanmicoder/dsh-skills-hub`, version `0.0.1`. Its supported host package cohort is exactly `0.2.0-rc.2`; the desktop release line is 0.2.0. The exact upstream tag and commit are recorded in `compatibility.json` and [COMPATIBILITY.md](COMPATIBILITY.md).
+The package is `@nanmicoder/dsh-skills-hub`, version `0.0.3`. Its supported host package cohort is exactly `0.2.0-rc.2`; the desktop release line is 0.2.0. The exact upstream tag and commit are recorded in `compatibility.json` and [COMPATIBILITY.md](COMPATIBILITY.md).
 
 `cordis.patch.yml` inserts one row (`id: skills-hub`) named after the scoped package. `lib/index.js` is the host entry. `lib/client.js` is the browser factory registered with `window.__ModuleLoader__.load` under that same package name. The plugin adds a global sidebar panel and does not replace built-in components or require an agent session.
 
@@ -14,7 +14,7 @@ The host performs provider requests and filesystem operations. It binds the avai
 
 The browser only calls same-origin `/api/skills-hub/*` endpoints, with same-origin credentials. Shared market imports in browser code are type-only. Browser runtime externals must belong to the Harness platform module table; host services and Node modules must not enter the browser bundle.
 
-`react-markdown` and `remark-gfm` are development dependencies compiled into the browser artifact. Rendering supports headings, tables, task lists and fenced code without relying on an optional host renderer. Raw HTML is skipped; dangerous URL protocols are filtered by the renderer, and external links use `noopener noreferrer`.
+`react-markdown` and `remark-gfm` are development dependencies compiled into the browser artifact. Rendering supports headings, tables, task lists and fenced code without relying on an optional host renderer. Raw HTML is skipped; dangerous URL protocols are filtered by the renderer, and external links use `noopener noreferrer`. `src/client/skill-markdown.ts` splits a document's YAML frontmatter from its body with a small subset parser compiled into the same bundle (scalars, inline/block sequences, `|`/`>` block scalars, one level of nested mapping kept as raw YAML): no YAML dependency enters the browser program, and the metadata block is rendered as structure instead of reaching the renderer, where its closing `---` would turn the whole block into a setext heading.
 
 The bundler explicitly selects the browser platform even though its output is a CommonJS factory. Both build-time import checks and manifest checks guard this boundary. CSS Modules use `--dsw-*` theme tokens and relative source IDs for portable output.
 
@@ -47,19 +47,27 @@ An `InstalledSkillRecord` has:
 
 Duplicate names/market IDs in separate roots remain separate rows with separate keys. Local endpoints accept keys, never arbitrary client-supplied paths. They freshly scan the allowed roots to resolve the entry. Removal renames the selected entry to a hidden temporary sibling before deletion; removing a link preserves its target. A flat file removal preserves its sibling files.
 
+A local detail read resolves the entry, reads its `SKILL.md`/flat document (2 MiB bound) and inventories the entry's own files: relative POSIX paths with size and detected language, dot-entries (including the provenance sidecar) excluded, at most 500 rows, symlinked files never followed. The document's frontmatter is returned verbatim as YAML text — the structured panel of a market detail is fed by upstream JSON that a hand-written skill does not have. A file read takes the same key plus a relative path: the path is validated (no absolute paths, no `..`, no empty segment), resolved inside the entry's real path, and rejected when a symlink would leave it, so the endpoint is never an arbitrary-file reader. A flat entry exposes only itself, never its siblings in the same root. Truncation at 300 KiB is reported, not thrown.
+
 Market installation uses staging and atomic publication, rejects directory conflicts, validates file paths and hashes when supplied, and writes a `.skills-hub.json` sidecar. The market-ID uninstall endpoint requires valid matching provenance; the explicit local-management endpoint can remove unmanaged entries after the UI confirmation. Both honor `allowUninstall`.
 
 After mutations the plugin refreshes its installed lookup. Harness's filesystem watcher handles skill catalog invalidation; the plugin does not forge filesystem observation events. Reading the catalog is best-effort and does not replace that watcher.
 
 ## 4. Marketplace models and limits
 
-Providers normalize ClawHub and SkillHub into `NormalizedSkill`. A market ID is `clawhub:<slug>` or `skillhub:<slug>`. The model includes name/summary/author, statistics, tags, version, security status and installation state. SkillHub mirrors may be deduplicated into their ClawHub originals.
+Providers normalize ClawHub and SkillHub into `NormalizedSkill`. A market ID is `clawhub:<slug>` or `skillhub:<slug>`. The model includes name/summary/author, statistics, tags, category, version, security status and installation state. SkillHub mirrors may be deduplicated into their ClawHub originals.
+
+The home list is the curated catalogue (`docs/CATALOG.md`): a snapshot shipped in `lib/catalog/skills.json`, listed, categorised and searched locally with no upstream request. Its categories are the catalogue's own. Opening, previewing and installing a catalogue skill still read the owning registry; catalogue entries pin the ClawHub owner so an ambiguous slug resolves to the curated skill, and the detail overlays the catalogue's category, pick flag and Chinese summary on the live record. Live upstream listing and search remain available as the explicit `market` scope.
 
 `NormalizedSkillDetail` adds Markdown `description`, optional frontmatter/license, `files` and `totalSize`. File metadata includes relative path, byte size, language, optional hash/content type and `tooBig`. File previews include `content`, `size`, `language` and `truncated`.
 
 Source status is `ok`, `degraded`, `failed` or `cached`, with optional fetch time/cache/error metadata. Provider failures remain visible independently; an unavailable source must not silently look like an empty marketplace.
 
-Current market limits are 5 MiB per file, 20 MiB total and 200 files per install. Market previews truncate after 300 KiB. ClawHub search results are capped at 50 because that search endpoint does not paginate. Local installed Markdown previews are limited to 2 MiB and reject oversized content.
+Upstream list pages (including each cursor), search pages, normalized details with their file inventory, and file previews are cached in memory and persisted under `$DSH_HOME/cache/skills-hub/v1` (default `~/.dsh/cache/skills-hub/v1`). Writes use a temporary file and atomic rename, and complete before the response returns. Restarted hosts read snapshots lazily, checking a versioned SHA-256 digest of the key, timestamps and payload before using them. Keys include the source's configured base URL as well as all payload-affecting request parameters; each operation captures its provider configuration and cache instance so a profile reload cannot mix them. Local install annotations are computed after reading the cache, and HTTP reads wait for the initial local inventory scan.
+
+All snapshots default to a 60-minute TTL, configurable through `cacheTtlMinutes` (1–1440). `storedAt` and `expiresAt` survive restart; a hit does not extend them, and reducing the configured TTL also limits existing snapshots. Browser display copies revalidate through the Host on each detail opening or file selection; each list card retains its own page's provenance for installation confirmation. Expired list/detail snapshots may be served on upstream errors for at most seven days. Actual install-time manifest reads bypass both fresh cache hits and stale fallback. Persisted snapshots are capped at 500 entries / 64 MiB, evict older writes first, and reject entries larger than 5 MiB while invalidating any older snapshot at that key. Writes also reclaim abandoned plugin temporary files older than one hour, leaving recent files alone for concurrent publishers. Unsupported/corrupt records or filesystem failures fall back to ordinary upstream reads and memory storage; the host logs a filesystem/parse failure once per activation.
+
+Current market limits are 5 MiB per file, 20 MiB total and 200 files per install. Market previews truncate after 300 KiB. ClawHub search results are capped at 50 because that search endpoint does not paginate. Local installed Markdown previews are limited to 2 MiB and reject oversized content; a single local file preview truncates after 300 KiB, matching the market preview policy.
 
 ## 5. HTTP and browser behavior
 
@@ -76,22 +84,37 @@ All paths below are relative to `/api/skills-hub`.
 | Method | Path / input | Success body |
 | --- | --- | --- |
 | GET | `/status` | `{ sources }` keyed by market source. |
-| GET | `/skills?q=&source=&security=&installed=&cursor=&limit=` | `{ items, nextCursor, sources }`. |
-| GET | `/skills/:source/:slug` | `{ skill, sourceStatus }`. |
-| GET | `/skills/:source/:slug/file?path=…` | `{ file }`. |
-| POST | `/install`, JSON `{ id }` | `{ ok: true, installedPath, skill }`. |
+| GET | `/stats` | `{ stats }` cache counters: `hits`, `misses`, `staleServed`, `upstreamRequests`, `forcedRefreshes`. |
+| GET | `/categories` | `{ items: MarketCategory[], status }`: catalogue categories with their skill counts; `status.fetchedAt` is the snapshot time. |
+| GET | `/skills?q=&scope=&category=&source=&security=&installed=&cursor=&limit=&refresh=` | `{ items, nextCursor, sources }`. |
+| GET | `/skills/:source/:slug?refresh=&owner=` | `{ skill, sourceStatus }`. |
+| GET | `/skills/:source/:slug/file?path=…&owner=` | `{ file }`. |
+| POST | `/install`, JSON `{ id, owner? }` | `{ ok: true, installedPath, skill }`. |
 | POST | `/uninstall`, JSON `{ id }` | `{ ok: true, removedPath, skill }`; market-managed installation only. |
 | GET | `/installed` | `{ items: InstalledSkillRecord[] }`; no provider request. |
-| GET | `/installed/detail?key=…` | `{ item, markdown }`; reads the selected local copy. |
+| GET | `/installed/detail?key=…` | `{ item, markdown, frontmatter, files }`; reads the selected local copy, its raw YAML header and its own file inventory. |
+| GET | `/installed/file?key=…&path=…` | `{ file }` with `content`, `size`, `language`, `truncated`; the path must resolve inside the selected entry. |
 | POST | `/installed/uninstall`, JSON `{ key }` | `{ ok: true, removedPath, item }`; exact discovered entry. |
 
-List `source` is `all`, `clawhub` or `skillhub`. `security` is `all`, `verified`, `benign`, `unknown` or `flagged`. `installed` is `all`, `installed` or `installable`; this filters the remote catalog and is distinct from the independent Installed view. `limit` is 1–100, defaulting to configured `pageSize`. Cursors are opaque and `null` means exhausted.
+`refresh` is `1`/`true` or `0`/`false` (absent means false); any other value is a `BAD_REQUEST`, because a refresh the Host cannot honour would let the panel present a cached answer as a fresh one. A refresh skips fresh cache entries for that request and rewrites them with what upstream returned.
+
+ClawHub slugs are shared across authors, so `clawhub:<slug>` does not name one skill. `owner` (`[A-Za-z0-9][A-Za-z0-9_.-]{0,63}`; malformed is `BAD_REQUEST`) pins detail, file and install reads to the author of the card the reader opened; the panel sends it for every ClawHub card, list items carry it in `author.handle`, and the install sidecar records it so the installed view reopens the same skill. Without one, the Host uses the catalogue's pinned owner, then an owner it resolved earlier, and only then resolves a 409 `AMBIGUOUS_SKILL_SLUG` to the most-downloaded candidate — never the registry's first-listed match, which for popular slugs is routinely a later copy. Detail and file cache keys include the owner. An install whose detail resolves to a different author than requested is refused. A live search page shows one card per slug; a SkillHub mirror folds into a ClawHub original only when both name the same author.
+
+List `scope` is `catalog` (default) or `market`. With `catalog`, every filter runs on the snapshot before pagination and `sources` carry the snapshot time with `fromCache: true`; `refresh` has nothing to re-read. With `market`, the list is the live merged upstream feed described above and `category` is ignored. `category` is absent, `all`, or a category key (`[a-z0-9][a-z0-9-]{0,63}`). List `source` is `all`, `clawhub` or `skillhub`. `security` is `all`, `verified`, `benign`, `unknown` or `flagged`. `installed` is `all`, `installed` or `installable`; this filters the remote catalog and is distinct from the independent Installed view. `limit` is 1–100, defaulting to configured `pageSize`. Cursors are opaque and `null` means exhausted.
 
 ### 5.3 Interaction contract
 
 The marketplace shows skeleton cards on initial loading and a detail skeleton immediately after opening a card. An intersection observer inside the actual list scroll area loads the next page as the sentinel approaches view. It preserves loaded cards, deduplicates results and avoids concurrent duplicate loads. Pagination failures expose retry without discarding existing results.
 
-Search/filter changes cancel superseded requests, reset pagination and reject stale responses. Installed management has its own loading, empty, error, search and refresh states. Its local detail reads the exact selected entry, and removal requires a confirmation showing its path; symlink removals explain that the target is preserved. Successful mutations update the displayed list and installed state. Buttons expose disabled/pending state during mutations.
+A category bar above the filters shows the catalogue categories. A catalogue search offers to repeat the query across all markets (`scope=market`, labelled as not curated); clearing the query returns to the catalogue. Search/filter/category changes cancel superseded requests, reset pagination and reject stale responses. Installed management has its own loading, empty, error, search and refresh states. Its local detail reads the exact selected entry, and removal requires a confirmation showing its path; symlink removals explain that the target is preserved. Successful mutations update the displayed list and installed state. Buttons expose disabled/pending state during mutations.
+
+Both detail pages are full-panel views built on one shell (`SkillDetailShell`): the list is replaced, focus moves to the heading, and a back control returns to it. The market page keeps its tab and selected file in `MarketState`; the local page keeps them in its own state and never unmounts the inventory list, so the query and rows survive the round trip. The local page shows only what the filesystem proves — path, provenance, size, installed time, layout, the rendered SKILL.md and its own files — and omits market-only rows (author, downloads, security reports) rather than showing zeros. A skill with valid market provenance also offers "view in marketplace", which switches to the market section and opens its provider-backed page: upstream facts stay upstream, and the local page stays readable offline.
+
+Provenance is part of every answer. `sourceStatus.fetchedAt` is the moment the payload was *read from upstream* — a cache hit keeps the original timestamp instead of restamping it with the current clock — and `fromCache` says whether the answer came from a stored copy. The panel prints that age next to each source and, when a detail is a snapshot, offers the one action that reaches upstream (`refresh=1`). Installing never relies on a snapshot: the manifest is re-read with `refresh` semantics before the files are fetched and hash-verified, so a cached security verdict or file list can never authorize an install.
+
+The catalogue fetches the next page about one screen before the reader reaches the end of the list, and only after the reader has scrolled at least once: opening the panel and leaving must not cost a page nobody looked at. The request count is unchanged — the same page is fetched either way — it simply happens while the reader is still scrolling, so arriving at the sentinel finds data instead of starting a request. The look-ahead observer must be rooted at the list's own scroll container: the catalogue scrolls inside the host dock, and a viewport-rooted observer is clipped by that dock, which makes `rootMargin` a no-op there.
+
+Inside the Files tab, a markdown document opens rendered — frontmatter as structured metadata, body through the same GFM renderer — because SKILL.md is prose meant to be read. Installing remains a trust decision, so a preview/source switch keeps the exact bytes (line numbers, and a copy button pointed at what is on disk) one click away; selecting another file returns to the rendered form. Every other language is source-only, since a toggle there would promise a rendering that does not exist.
 
 ## 6. Configuration