@nanmicoder/dsh-skills-hub 0.0.1

package/AGENTS.md

@@ -0,0 +1,9 @@
+# Skills Hub development
+
+Read `CONTRIBUTING.md`, `docs/COMPATIBILITY.md` and `docs/RELEASE.md` for implementation and release work. The current package name is `@nanmicoder/dsh-skills-hub`; the unscoped npm name belongs to another project. The plugin's first release is 0.0.1; Harness versions are tracked separately.
+
+Use the pinned pnpm version and lockfile, keep Harness development dependencies on one exact cohort, and run `pnpm pack:check` before delivery. Regenerate and retain `lib/` for Git installs. Avoid absolute local paths in committed metadata or runtime bundles. Never claim an untested host version is supported.
+
+For interactive browser automation, use the `ego-browser` skill from Ego Lite. Do not use another browser-control skill unless explicitly requested or Ego Lite is unavailable.
+
+Publication is separate from preparing a release: do not publish, push tags, change repository visibility or edit a user's active profile unless the user authorized those actions. Existing authorization takes precedence over generic workflow prompts. Use isolated profiles and disposable skills for tests.

package/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+Use Node.js `^22.19.0 || >=24` and the pnpm version pinned in `package.json`. Keep one lockfile. Run `pnpm install --frozen-lockfile`, then `pnpm pack:check` before submitting a change.
+
+Separate host code (`src/`) from browser code (`src/client/`). Client value imports from Harness must be platform module-table entries; type-only imports are fine. Use CSS Modules and `--dsw-*` theme variables. Keep loading, empty, failure, retry and disabled states accessible, and respect reduced motion.
+
+Skill installs must not overwrite existing directories. Local removal must revalidate its root and target and require an explicit confirmation; never trust a path supplied by the browser. Cover filesystem traversal, symlinks, conflicts and provider failures with meaningful tests. Follow the contracts in `docs/CONTRACT.md` and update them when APIs change.
+
+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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NanmiCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+<p align="right">
+  <strong>简体中文</strong> · <a href="./README_EN.md">English</a>
+</p>
+
+<p align="center">
+  <img src="./assets/readme/hero-zh.png" width="100%" alt="Skills Hub：发现技能，装进你的工作流。3D 技能文档汇入蓝色收纳座的概念插画。">
+</p>
+
+<p align="center">
+  <strong>DeepSeek Harness 的技能市场与本机技能管理器</strong><br>
+  浏览 ClawHub 与 SkillHub，读懂 SKILL.md，再安装到你的 Harness。
+</p>
+
+<p align="center">
+  <a href="#快速开始">快速开始</a> · <a href="./docs/COMPATIBILITY.md">兼容性</a> · <a href="./docs/RELEASE.md">发布指南</a> · <a href="./LICENSE">MIT</a>
+</p>
+
+## 技能发现和本机管理，在同一个面板里
+
+**Skills Hub** 把两个技能市场与本机用户技能放进 Harness 侧栏。无需在网站、下载目录和技能文件夹之间来回切换：搜索、查看文档、确认安装，再到「已安装技能」里统一管理。
+
+<p align="center">
+  <img src="./assets/readme/marketplace.png" width="100%" alt="Skills Hub 在 DeepSeek Harness 中的实际界面：技能卡片、搜索与筛选、来源健康状态，以及已安装技能入口。">
+</p>
+
+*实际 Harness 0.2.0-rc.2 界面；市场内容随上游更新。顶部 3D Hero 为概念插画。*
+
+| 你要做的事 | Skills Hub 怎么帮你 |
+| --- | --- |
+| **找一个技能** | 聚合 ClawHub 与 SkillHub，支持搜索和筛选；向下滚动自动加载更多。 |
+| **先看清，再安装** | 渲染 Markdown、表格和代码块，预览包内文件与上游安全报告；列表和详情都有骨架屏。 |
+| **整理已安装技能** | 搜索市场安装和本机用户技能，查看来源、实际路径与正文，再确认卸载。 |
+
+## 快速开始
+
+**插件 `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
+```
+
+完全退出并重新打开 Harness，在侧栏点击 **技能市场**。使用其他 profile 时，把 `desktop` 替换成对应名称。
+
+1. **浏览**：搜索关键词，或按来源、安全状态筛选。
+2. **预览**：打开技能，阅读概览和文件内容。
+3. **安装**：核对来源并确认；在「已安装技能」中查看、搜索或卸载。
+
+> 包名必须带 `@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
+```
+
+同样需要完全重启 Harness。构建产物随源码保留，打包前会重新构建和检查。
+
+</details>
+
+## 已安装管理，路径清楚，操作明确
+
+列表覆盖配置的安装目录、`$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
+```
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `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)。
+
+</details>
+
+## 开发与发布
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check       # 类型、构建、回归测试与版本检查
+pnpm pack:check  # 另检查 npm 包内容及运行时依赖闭包
+```
+
+[贡献指南](./CONTRIBUTING.md) · [维护规范](./AGENTS.md) · [兼容性与验收](./docs/COMPATIBILITY.md) · [0.0.1 发布流程](./docs/RELEASE.md)
+
+MIT 许可证。详见 [LICENSE](./LICENSE)。

package/README_EN.md

@@ -0,0 +1,120 @@
+<p align="right">
+  <a href="./README.md">简体中文</a> · <strong>English</strong>
+</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.">
+</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.
+</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>
+</p>
+
+## Discovery and local management, in one panel
+
+**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.
+
+<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.">
+</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 |
+| --- | --- |
+| **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. |
+
+## 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
+```
+
+Fully quit and reopen Harness, then choose **Skills Hub** in the sidebar. Replace `desktop` with your profile name if needed.
+
+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.
+
+> 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
+```
+
+Restart Harness afterward. Build artifacts are committed with source and rebuilt and checked before packing.
+
+</details>
+
+## 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
+```
+
+| 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:
+
+```sh
+dsh plugin --profile desktop remove @nanmicoder/dsh-skills-hub
+```
+
+This does not delete installed skills. See the [implementation contract](./docs/CONTRACT.md) for discovery scope and APIs.
+
+</details>
+
+## Develop and release
+
+```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
+```
+
+[Contributing](./CONTRIBUTING.md) · [Maintenance rules](./AGENTS.md) · [Compatibility and acceptance](./docs/COMPATIBILITY.md) · [0.0.1 release guide](./docs/RELEASE.md)
+
+MIT. See [LICENSE](./LICENSE).

package/README_ZH.md

@@ -0,0 +1,5 @@
+# Skills Hub · 简体中文
+
+中文文档已成为仓库默认首页，请查看 [README.md](./README.md)。
+
+[English documentation](./README_EN.md)

package/compatibility.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "pluginVersion": "0.0.1",
+  "recommendedHost": "0.2.0-rc.2",
+  "hostTag": "dsh-v0.2.0-rc.2",
+  "hostCommit": "639ed015397290b3745d163aafe02ffee4aa3f84",
+  "desktopReleaseLine": "0.2.0",
+  "previewTag": "next",
+  "supportedHosts": ["0.2.0-rc.2"]
+}

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Add only our own plugin row. This layer does not replace any official DSH
+# component: the profile keeps every bundle it already had.
+- insert:
+    - id: skills-hub
+      name: "@nanmicoder/dsh-skills-hub"

package/docs/COMPATIBILITY.md

@@ -0,0 +1,31 @@
+# Harness compatibility
+
+The build and peer dependency baseline is **`0.2.0-rc.2`** for every `@deepseek-ai/dsh-*` package. The source reference is tag `dsh-v0.2.0-rc.2`, commit `639ed015397290b3745d163aafe02ffee4aa3f84` in `deepseek-ai/deepseek-harness`. These are the precise package coordinates behind the requested desktop 0.2.0 release line; an untagged future `0.2.0` package is not silently covered.
+
+The referenced packages were confirmed on npm. A clean install resolves one cohort, with `autoInstallPeers: false`; missing host peers used by development packages are explicitly provided at the same version. No local workspace overrides or private filesystem paths are needed.
+
+The plugin uses the host's Cordis service lifecycle, lazy `webServer` binding, connection request gate, user/configured skill roots, web-client slot registration, layout services and the browser module-loader factory protocol. It does not replace official profile components. The patch inserts a single row named `@nanmicoder/dsh-skills-hub`. The browser bundle registers that same package ID and externalizes only platform modules. Markdown processing is bundled, so it does not depend on an optional host Markdown renderer service.
+
+## Acceptance procedure
+
+Use the exact source tag or installed desktop cohort, a temporary `DSH_HOME`, an isolated profile and disposable skills. Do not change the user's real profile for acceptance.
+
+1. Build and pack the plugin. Install the tarball into the isolated profile.
+2. Dump the resolved profile and confirm the scoped plugin row.
+3. Cold-boot the host; confirm no pending plugin service and the advertised `lib/client.js` bundle returns successfully.
+4. Open Skills Hub in the actual host browser. Confirm module registration, DOM mount, and absence of page errors.
+5. Verify initial skeleton, detail skeleton, rendered Markdown and automatic next-page loading. Test an empty list and source failure/retry.
+6. Install a disposable market skill. Confirm its files and the Installed row; uninstall and confirm removal. Add a temporary local skill under a configured root, refresh and remove it through the local confirmation path.
+7. Check light/dark layout and keyboard-accessible controls. Record actual results separately from automated fixture coverage.
+
+`pnpm pack:check` covers static typing, source and manifest contracts, regression tests, clean build, release metadata and tarball import closure. It does not by itself certify a running desktop session or upstream network availability. Future host cohorts must repeat this acceptance before widening peer ranges.
+
+## 0.0.1 acceptance record — 2026-09-30
+
+Validation used the published npm `@deepseek-ai/dsh@0.2.0-rc.2` runtime with every Harness dependency overridden to the same cohort, on macOS arm64 / Node 26.7.0. The plugin was installed from its npm tarball into a disposable Web profile, with isolated `DSH_HOME` and `DSH_AGENTS_HOME`. The complete published host started without startup warnings. The earlier source-checkout trial lacked unrelated built host packages and is not the compatibility evidence.
+
+Ego Lite drove the actual host UI. Slow fixture upstream responses made the loading states observable: eight initial card skeletons, the detail skeleton, and automatic growth from 24 to 48 cards after a wheel scroll. Headings, a GFM table and fenced code rendered as DOM; injected HTML scripts did not execute and no `javascript:` links remained. A fixture skill was installed through the confirmation dialog and appeared in Installed. A local skill preview rendered its body without YAML frontmatter. Both entries were removed through confirmation dialogs and their filesystem entries disappeared. Light and dark themes were inspected; the layout had no horizontal viewport overflow. This verifies the shared Web client and host plugin protocol, not a native desktop installer or OS-specific shell integration.
+
+`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.

package/docs/CONTRACT.md

@@ -0,0 +1,125 @@
+# Skills Hub 0.0.1 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).
+
+`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.
+
+## 2. Host/browser boundary
+
+The host performs provider requests and filesystem operations. It binds the available `webServer`/`httpServer` lazily, scopes route disposal to Cordis effects, and resolves the connection request gate for each request so late service activation is respected. Headless profiles may load the plugin without mounting a web surface.
+
+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`.
+
+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.
+
+## 3. Filesystem scope and installed identities
+
+The installation root is `skillsRoot` when configured, otherwise `$DSH_HOME/skills` (default Harness home: `~/.dsh`). Discovery scans, in order:
+
+1. The installation root.
+2. `$DSH_HOME/skills`.
+3. `$DSH_AGENTS_HOME/skills`, defaulting to `~/.agents/skills`.
+
+Duplicate roots collapse. Tilde prefixes are expanded and configured relative paths resolve against the host working directory. Session/project `.dsh/skills` and `.agents/skills` roots are deliberately excluded because this panel has no session working directory. This is a user-root inventory, not an enumeration of every skill a particular session or plugin provider might expose.
+
+Discovery recognizes directory bundles containing `SKILL.md`, flat Markdown skill files and valid symlink entries. It reads names/descriptions from bounded frontmatter and measures files with traversal limits. The Installed view is populated from this filesystem scan independently of market availability; it does not invent market entries for local skills.
+
+An `InstalledSkillRecord` has:
+
+| Field | Meaning |
+| --- | --- |
+| `key` | Opaque 64-character hexadecimal identity for the exact filesystem entry; use this for local management. |
+| `id` | Market `source:slug` when a valid provenance sidecar exists; otherwise a local identity. Not unique across duplicate installations. |
+| `source` | `clawhub`, `skillhub` or `local`. |
+| `slug`, `name`, `dirName` | Logical skill and display identity. |
+| `dirPath` | Absolute path of the bundle directory, flat file or symlink entry, shown before removal. |
+| `linked` | Entry is a symlink; removal unlinks it, never its target. |
+| `managed` | Valid `.skills-hub.json` marketplace provenance was discovered. |
+| `removable` | Whether UI removal is allowed; the list reflects `allowUninstall`. The server independently enforces that switch. |
+| `bytes`, `fileCount` | Bounded scan statistics. |
+| `version`, `summary`, `installedAt` | Optional metadata. |
+
+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.
+
+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.
+
+`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.
+
+## 5. HTTP and browser behavior
+
+### 5.1 Transport and validation
+
+One host prefix route serves the endpoints below. Responses are JSON with `Cache-Control: no-store`. Failures use `{ "error": { "code": "…", "message": "…" } }` and an appropriate non-2xx status. Methods, route depth, IDs, enum filters, body sizes and paths are validated. The connection gate can reject requests with 401/403.
+
+The browser surfaces transport failures as `NETWORK_ERROR`; invalid successful JSON becomes `MARKET_UPSTREAM_BAD_RESPONSE`. Aborted superseded reads are control flow and must not appear as user-visible errors.
+
+### 5.2 Endpoints
+
+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 }`. |
+| 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. |
+| 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.
+
+### 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.
+
+## 6. Configuration
+
+`src/config.ts` is the configuration source of truth. Defaults:
+
+| Key | Default |
+| --- | --- |
+| `skillsRoot` | `null` |
+| `clawhubBaseUrl` | `https://clawhub.ai` |
+| `skillhubBaseUrl` | `https://api.skillhub.cn` |
+| `timeoutMs` | `15000` |
+| `requestRetries` | `1` |
+| `allowUninstall` | `true` |
+| `pageSize` | `24` |
+
+Timeout is at least 1000 ms, retries are nonnegative, and page size is 1–100. The uninstall switch covers market and local removal. Installation does not execute skill scripts; reviewing and later following third-party instructions remains a separate trust decision.
+
+## 7. Build, verification and release
+
+Use the `packageManager` version in `package.json` and the single pnpm lockfile. All development `@deepseek-ai/dsh-*` packages use the exact supported cohort.
+
+- `pnpm typecheck`: host and client TypeScript programs.
+- `pnpm build`: clean `lib/`, compile both programs and bundle the client.
+- `pnpm verify`: manifest checks and regression tests, including filesystem and HTTP behavior.
+- `pnpm verify:release`: package, release note and compatibility metadata coherence.
+- `pnpm check`: typecheck, build, verify and release metadata.
+- `pnpm pack:check`: complete check plus npm tarball export/runtime-import closure and leak checks.
+
+`prepack` and `prepublishOnly` run the complete check. Git retains generated `lib/`; npm includes the browser bundle and declarations while excluding intermediate `lib/client/` JavaScript. The registry preflight refuses collisions, existing versions and backwards stable releases. CI and publication workflow details live in [RELEASE.md](RELEASE.md).
+
+Automated tests are distinct from exact-host/browser acceptance. The supported cohort, evidence and remaining scope belong in [COMPATIBILITY.md](COMPATIBILITY.md); widening peer ranges requires renewed host verification.

package/docs/RELEASE.md

@@ -0,0 +1,24 @@
+# Release 0.0.1
+
+Package: `@nanmicoder/dsh-skills-hub`. Repository: `NanmiCoder/dsh-skills-hub`. Tag: `v0.0.1`. npm channel: `latest`. This is an initial plugin release, independent of the host's `0.2.0-rc.2` version.
+
+## Before making the repository public
+
+1. Run `pnpm install --frozen-lockfile` and `pnpm pack:check` on the intended release commit.
+2. Perform the exact-host acceptance described in [COMPATIBILITY.md](COMPATIBILITY.md), including a browser mount and real install/uninstall in a temporary skills root. Record the host tag, plugin commit, commands and results; fixture tests alone do not prove host acceptance.
+3. Review `git diff`, generated `lib/`, package contents and release notes. Commit source and build artifacts together. Never include credentials, profiles or acceptance-home contents.
+4. Confirm npm account permission for the `@nanmicoder` scope. The unscoped name is owned by someone else. Changing GitHub visibility alone does not grant npm permissions.
+
+## GitHub Actions publication
+
+Publication runs online in `.github/workflows/release.yml`, matching the AgentTeams release model. Push `v0.0.1` to trigger it, or dispatch the workflow with an explicit version. Both Node 22.19 and 24 must pass validation. The Node 24 job uploads the built tarball and SHA-256 checksum; the publication job verifies and publishes that exact artifact using npm 11.19.0. It does not rebuild during publication. A GitHub Release is published only after npm succeeds.
+
+Configure npm Trusted Publishing for GitHub owner `NanmiCoder`, repository `dsh-skills-hub`, workflow `release.yml`, environment `npm`, allowing direct publication. OIDC uses `id-token: write`; routine releases need no local npm login and no stored npm token. The existing AgentTeams trust binding is package-specific and does not authorize this new package.
+
+For a brand-new package, npm requires an initial publication before its trusted publisher can be configured. If initial publication uses a short-lived granular token, place it only in this repository's `npm` environment as `NPM_TOKEN`, publish through the same Action, then remove/revoke the bootstrap token after configuring OIDC. Never commit or print credentials. npm may require browser-based security-key verification for these account operations.
+
+Before tagging, commit all source and generated artifacts, confirm the version and release notes, and ensure the working tree is clean. Registry preflight rejects duplicate versions, repository collisions and backwards movement of `latest`. Do not move a published tag. The exact-commit bypass supported by the standalone preflight utility is not used by the online publication workflow.
+
+## After publication / recovery
+
+Install `@nanmicoder/dsh-skills-hub@0.0.1` into an isolated profile and repeat the smoke flow. Compare the downloaded package and expected version before announcing availability. If a release is faulty, publish a new fixed version or deprecate the faulty version with a clear message; do not rewrite published Git tags or assume deleting a GitHub Release retracts npm. Preserve user skills when removing or replacing the plugin.