dsh-agent-plugins-market 0.6.1 → 0.7.0

package/README.md

@@ -1,237 +1,217 @@
-# dsh-agent-plugins-market — Claude Code plugin marketplaces for DeepSeek Harness
-
-English | [简体中文](README.zh.md) | [Docs website](https://sivan757.github.io/dsh-agent-plugins-market/)
-
-> **Bring the Claude Code / Codex / Cursor plugin-marketplace ecosystem into DeepSeek Harness (DSH): install and inject agent plugins — skills, MCP servers, hooks and slash commands — from git marketplace repos, with a market page right inside the Web GUI.**
-
-**dsh-agent-plugins-market is the standard way to run Claude Code, Codex, Cursor and Kimi plugin marketplaces inside DeepSeek Harness — zero conversion, zero file copying.**
-
-![npm](https://img.shields.io/npm/v/dsh-agent-plugins-market) ![npm downloads](https://img.shields.io/npm/dm/dsh-agent-plugins-market) ![License](https://img.shields.io/github/license/Sivan757/dsh-agent-plugins-market) ![GitHub stars](https://img.shields.io/github/stars/Sivan757/dsh-agent-plugins-market)
-
-![Agent Plugins Market screenshot](docs/screenshot.png)
-
-![Suite detail (skills / MCP / commands preview)](docs/screenshot-detail.png)
-
-## Why?
-
-DeepSeek Harness is a powerful agent harness — but its plugin ecosystem doesn't yet have the breadth of the **Claude Code plugin marketplace** world. There are hundreds of ready-made plugin marketplaces on GitHub (Claude Code `.claude-plugin/marketplace.json`, Codex `.codex-plugin`, Cursor, Kimi, agent-plugins.org v1.0.0 portable suites) full of skills, MCP servers, hooks and slash commands.
-
-`dsh-agent-plugins-market` is the bridge: **add any git marketplace repo as a source, install its suites, and their skills / MCP servers / hooks / commands are injected into your DSH sessions at runtime** — no manual file copying, no conversion needed. Claude Code-authored skills work verbatim (`${CLAUDE_PLUGIN_ROOT}` is substituted automatically).
+<img src="docs-site/public/favicon.svg" alt="" width="48" height="48" />
+
+# dsh-agent-plugins-market
+
+**A plugin marketplace and agent capability workspace for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness).**
+
+Reuse supported content from Claude Code, Codex, Cursor, Kimi and other recognized layouts, and manage your own skills, commands, agent personas, MCP services and LSP servers in the DSH Web GUI.
+
+If this plugin is useful to you, a ⭐ on [GitHub](https://github.com/Sivan757/dsh-agent-plugins-market) is appreciated.
+
+English | [简体中文](README.zh.md) | [Documentation](https://sivan757.github.io/dsh-agent-plugins-market/) | [npm](https://www.npmjs.com/package/dsh-agent-plugins-market)
+
+[![npm version](https://img.shields.io/npm/v/dsh-agent-plugins-market)](https://www.npmjs.com/package/dsh-agent-plugins-market) [![License](https://img.shields.io/github/license/Sivan757/dsh-agent-plugins-market)](LICENSE)
+
+[Quick start](#quick-start) · [Everyday use](#everyday-use) · [Compatibility](#compatibility-and-boundaries) · [FAQ](#faq)
+
+## Pages
+
+<table>
+  <tr>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/market.png" alt="Market" width="100%" /><br />
+      <b>Market</b><br />Add sources, preview suites, install and enable.
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/skills.png" alt="Skills" width="100%" /><br />
+      <b>Skills</b><br />Browse skills and author your own.
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/commands.png" alt="Commands" width="100%" /><br />
+      <b>Commands</b><br />Manage prompt templates invoked as /name.
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/personas.png" alt="Agent personas" width="100%" /><br />
+      <b>Agent personas</b><br />Roles with an exact provider, model and effort.
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/mcp.png" alt="MCP services" width="100%" /><br />
+      <b>MCP services</b><br />Credentials, authorization and connection status.
+    </td>
+    <td align="center" width="33%">
+      <img src="docs/screenshots/lsp.png" alt="LSP servers" width="100%" /><br />
+      <b>LSP servers</b><br />Language server configuration and runtime status.
+    </td>
+  </tr>
+</table>
+
+## What you can do
+
+- **Ten suite layouts.** Claude Code, Codex, Cursor, Kimi Code, ZCode, Qoder CLI, GitHub Copilot CLI, Universal `.plugin/`, [agent-plugins](https://agent-plugins.org) and manifest-less skill collections.
+- **Sources.** Add a Git repository, a local directory or an archive (`.zip` / `.tar.gz` / `.tgz` / `.tar`); adopt a checkout you cloned yourself; refresh on demand; delete a managed checkout when you remove its source.
+- **Downloads that fit your network.** Pick a download region — default `auto` follows the interface language, or choose global / China mainland — and the plugin routes `github.com` clones through the matching mirror. A proxy and per-invocation tuning live in the host config.
+- **Runtime surfaces.** Enabled suites inject into sessions: skills into the catalog and slash menu, commands as `/name`, agent personas into the subagent catalog, MCP tools with an `mcp__` prefix, hooks onto host lifecycle events, and language servers through the `lsp` tool.
+- **MCP.** A built-in bridge runs stdio, Streamable HTTP with OAuth and legacy SSE without a host MCP client. `${VAR}` references resolve from the host credential store or the launch environment; per-server overrides disable or patch a declaration without editing the source; an optional host-client compatibility mode is available. Tools register as `mcp__<suite>__<server>__<tool>`.
+- **LSP.** Self-provisioned: installing the plugin is the whole setup, and the `lsp` tool mounts only while a language server is wanted. The server executable itself must be on `PATH`. Upgrading from a release that asked you to expose LSP from your profile? A profile that still carries that hand-added layer reports a seam conflict; the LSP panel names the file and removes the layer for you, keeping a backup.
+- **Agent personas and delegation.** Role cards save an exact provider, model and reasoning effort; they appear in the session catalog and run through `subagent_run`, which starts a durable background child and returns its id immediately.
+- **Project dimension.** Skills, agents, commands, MCP servers and hooks are read from the project's own directories with no install step.
+- **Your own resources.** Author skills, commands and agent personas as Markdown under `~/.agents/`, then edit them or disable them without deleting the files.
+- **Background source updates.** Optionally refresh every configured source on a timer; off by default.
+- **Web workspace.** Six tabs — Market, Skills, Commands, Agent personas, MCP services and LSP servers — each with search, filters and a grid/list toggle, plus status panels with diagnostics, credential editing, and an install confirmation that warns before executable third-party content is enabled.
+- **Bilingual interface and feedback.** Workspace strings and injected prompts follow the host language. With feedback enabled, the model can file a `report_market_issue` report through the `gh` CLI or a GitHub token; with neither, it opens a prefilled GitHub issue page and hands you the complete issue text.
 
 ## Quick start
 
-> Requires DeepSeek Harness ≥ 0.1.0-rc.6 with a Web profile.
+Install into your profile, replacing `<name>` with its name:
 
 ```sh
-# install into a dsh profile (npm registry, recommended)
 dsh plugin --profile <name> add dsh-agent-plugins-market
-
-# or via pnpm inside the profile
-pnpm add dsh-agent-plugins-market
-```
-
-Restart dsh, open **Settings → Agent Plugins Market**, add a marketplace repo as a source (e.g. `https://github.com/anthropics/claude-plugins-official`), and install suites with one click. On legacy Web shells without the `settings.section` slot, the same UI falls back to a top-level Agent Plugins Market page entry. Skills appear in the `/` slash menu; MCP tools appear as `mcp__<suite>__<server>__<tool>`; slash commands and `/agent-*` subagents register automatically.
-
-<details>
-<summary><strong>More install options</strong></summary>
-
-**GitHub:**
-
-```sh
-pnpm add github:Sivan757/dsh-agent-plugins-market
-# or
-dsh plugin --profile <name> add github:Sivan757/dsh-agent-plugins-market
 ```
 
-**Manual** — add the package to the profile's `dsh.profile.bundles` (the package's `cordis.patch.yml` inserts the plugin row):
+1. Restart DSH and open **Settings → Agent Plugins Market**.
+2. In **Market**, add a source, for example `https://github.com/anthropics/claude-plugins-official`. No sources are preconfigured.
+3. Open a suite, review its contents, then install it and ensure it is enabled.
+4. For a suite with skills, check the **Skills** tab and type `/` in chat to find its user-invocable skills. For an MCP suite, check **MCP services** and resolve any credential or connection notice before using its tools.
 
-```jsonc
-// ~/.dsh/profiles/<profile>/package.json
-{
-  "dependencies": { "dsh-agent-plugins-market": "^0.4.6" },
-  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-agent-plugins-market"] } }
-}
-```
+Requirements, profile configuration and alternative installs: [usage guide](docs/user/usage.md#installation-options).
 
-Build artifacts (`lib/`, `client/`) are not committed; npm publishes them via `prepack`, and GitHub installs build them automatically through the `prepare` script (requires Node + pnpm toolchain on the installing machine).
-
-</details>
-
-## Features
-
-- **Plugin / suite management** — configure git repository sources (markets), browse every discoverable plugin, install / uninstall / enable / disable / refresh per source or per plugin. Source ids are derived automatically from the repository manifest JSON — no manual input.
-- **Market page in the Web GUI** — source pills + search/actions, status tabs, a two-column card grid, and a plugin detail modal with previews for skills / MCP / hooks / commands / LSP. New shells render it as a localized Settings page; legacy shells without `settings.section` receive a guarded top-level page-mode fallback instead of a duplicate surface.
-- **Runtime injection**
-  - **Skills** — a `ctx.skills` SkillProvider (project rank 250 / user rank 450); `${CLAUDE_PLUGIN_ROOT}` is substituted so Claude Code-authored skills work verbatim, and appear in the `/` slash menu.
-  - **MCP servers** — every valid `mcp.json` server of an enabled plugin mounts a live `dsh-mcp-client` child; tools appear as `mcp__<plugin>__<server>__<tool>`.
-  - **MCP credentials** — `${ENV_NAME}` references resolve through the optional DSH credentials service before a child starts; missing references block the spawn and surface as `needs-credentials`. The Web detail view uses write-only credentials operations and never persists token values in suite state or overrides.
-  - **Hooks** — a plugin's `hooks/hooks.json` mounts the `dsh-hooks-claude-code` bridge on the harness interception points (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop).
-  - **Commands / subagents** — `commands/*.md` register as dsh slash commands; `agents/*.md` register as `agent-<name>` skills.
-  - **Model context** — skills flow through the host-native skill catalog and MCP tools register directly through `dsh-mcp-client`; suite inventory and source metadata remain available in the Web market page without adding a redundant model-facing inventory tool.
-- **Runtime discovery** — installed plugins are discovered from configured source ids under `~/.dsh/agent-plugins/.sources/<sourceId>/` (user dimension) and `<project>/.dsh/agent-plugins/.sources/<sourceId>/` (project dimension). Stale unmanaged user checkouts are ignored, while project checkouts remain state-authorized. Local sources read the working tree directly, including uncommitted changes.
-- **Native project layouts (zero-copy migration)** — a repository's own `.claude/` and `.agents/` directories (skills, agents) are discovered in place as read-only `project-native` suites: no install, no copying, no state file. Repositories migrating from Claude Code or agent-plugins.org conventions work as-is; a project skill shadows an installed suite skill of the same name (project wins).
-
-## Supported plugin layouts
-
-| Layout                           | Manifest                                                         | Notes                                                      |
-| -------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
-| agent-plugins.org v1             | `plugin.json`                                                    | vendored 1.0.0 JSON Schema validation + spec §4 path rules |
-| Claude Code market               | `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json` | marketplace `plugins[].source` relative paths              |
-| Universal                        | `.plugin/plugin.json`                                            | multi-client repos (e.g. vercel-plugin)                    |
-| Cursor                           | `.cursor-plugin/plugin.json`                                     | declared skills paths                                      |
-| Kimi                             | `.kimi-plugin/plugin.json`                                       | inline mcpServers                                          |
-| Codex                            | `.codex-plugin/plugin.json`                                      | —                                                          |
-| Skill collection (manifest-less) | none (synthetic)                                                 | flat `SKILL.md` directory collections                      |
-
-One repo may carry several dialects at once (vercel/vercel-plugin ships all of them); the suite identity comes from the highest-precedence manifest while surfaces are scanned from the directories. `mcp.json` is validated strictly against the agent-plugins.org schema; `.mcp.json` is parsed leniently — top-level server-map shorthand, `type: http` / `local` / omitted `type` (stdio by `command`) normalization, `${CLAUDE_PLUGIN_ROOT}` / `${CLAUDE_PLUGIN_DATA}` / `${NAME:-default}` placeholders, and unknown transports are tolerated per server. The marketplace manifest is authoritative for the suite set; manifest-less marketplace entries that carry skills and manifest-bearing container dirs not listed there are supplemented. Remote URL entries show as "remote reference" cards (metadata + source URL, not directly installable; add the repo as a source to install).
-
-## Configure marketplace sources
-
-Sources persist in `~/.dsh/agent-plugins/state.json`; cordis config seeds them (and re-adds missing ids on every boot):
-
-```yaml
-- id: dsh-agent-plugins-market
-  config:
-    sources:
-      - { id: agent-plugins, url: 'https://github.com/Sivan757/agent-plugins.git' }
-      - { id: mattpocock-skills, url: 'https://github.com/mattpocock/skills.git' }
-      - { id: claude-plugins-official, url: 'https://github.com/anthropics/claude-plugins-official' }
-      - { id: ui-ux-pro-max, url: 'https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git' }
-      - { id: my-local-plugin, url: '/Users/me/work/my-plugin', local: true }
-      - { id: packaged-plugin, url: 'https://example.com/plugin-0.1.zip', kind: archive, sha256: '<64-hex digest>' }
-```
+## Everyday use
 
-A `local: true` source reads the directory in place (live working tree; never deleted on removal). Discovery results are cached for up to 30 seconds and reused across install/enable/panel actions, so working-tree edits of local sources appear on the next cache refresh (any source mutation, the refresh button, or the 30 s TTL). An `archive` source downloads an HTTPS `.zip` / `.tar.gz` / `.tgz` / `.tar` payload (256 MiB cap, optional `sha256` integrity pin) and extracts it as the checkout.
+The workspace has six tabs:
 
-### Manual clones, adoption, and network tuning
+| Tab            | Use it to                                                                                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Market         | Add sources, preview suites, install / uninstall, enable / disable and refresh.                                                              |
+| Skills         | Browse skills and create or edit your own reusable instructions.                                                                             |
+| Commands       | Manage prompt templates invoked as `/name`.                                                                                                  |
+| Agent personas | Manage role instructions and save an exact provider, model and reasoning effort per role; delegate in the background through `subagent_run`. |
+| MCP services   | Add a service or configure an installed one, its credentials and authorization; inspect status and retry failures.                           |
+| LSP servers    | Add and configure language servers and inspect their runtime status.                                                                         |
 
-Cloning from the UI times out on a restricted network? Clone the repository yourself into the checkout root (`~/.dsh/agent-plugins/.sources/<id>/`) — the market page lists it under **unregistered local checkouts** with a one-click **adopt** action that registers it in place (no re-clone, no deletion, ever). Adding a URL whose checkout already exists with a matching `origin` remote adopts it automatically instead of cloning a second copy.
-
-Git/archive acquisition is tunable through the host config:
-
-```yaml
-- id: dsh-agent-plugins-market
-  config:
-    git:
-      proxy: 'http://127.0.0.1:7890' # injected as git http/https proxy
-      insteadOf: { 'https://github.com/': 'https://mirror.example/https://github.com/' }
-      timeoutMs: 300000 # per git invocation (default 120000)
-      cloneRetry: true # one automatic retry (default)
-      fallbackTarball: false # retry a failed github.com clone as a codeload tarball download
-      allowHttpArchives: false # permit plain-http archive URLs (intranet mirrors)
-```
+A **source** is where content comes from; a **suite** is an installable unit discovered there. Adding a source discovers its suites. Installing and enabling a suite controls its runtime capabilities.
 
-## Comparison with other DSH ↔ Claude Code bridges
+Everything you author yourself lives in the shared Agent layout root: skills, commands and personas as Markdown under `~/.agents/`, and the MCP and LSP services you add in the workspace in `~/.agents/mcp.json` and `~/.agents/lsp.json`. Project-native resources stay in the project. See [storage and discovery](docs/user/usage.md#storage-and-discovery) for paths and precedence.
 
-| Capability | **dsh-agent-plugins-market** | [dsh-skills](https://github.com/CocoSgt/dsh-skills) | [@claude2dsh/plugin](https://www.npmjs.com/package/@claude2dsh/plugin) | [@deepseek-ai/dsh-hooks-claude-code](https://github.com/deepseek-ai/deepseek-harness) |
-| --- | --- | --- | --- | --- |
-| Source | **any git marketplace repo** (`.claude-plugin`, `.codex-plugin`, `.cursor-plugin`, `.kimi-plugin`, agent-plugins.org v1, manifest-less skills) | `~/.claude/skills` dirs, project dirs, `.skill` packages | Claude Code sessions + skills | a Claude Code `hooks.json` config |
-| Skills injection | ✅ + `/` slash menu | ✅ global skill library | ✅ | ❌ |
-| MCP servers | ✅ live `dsh-mcp-client` mounts | ❌ | — | ❌ |
-| Hooks | ✅ via `dsh-hooks-claude-code` bridge | ❌ | — | ✅ (direct) |
-| Slash commands / subagents | ✅ `commands/*.md`, `agents/*.md` | ❌ | — | ❌ |
-| Market UI | ✅ full market page in the Web GUI | ✅ settings page | — | ❌ |
-| Direction | CC / Codex / Cursor ecosystem → DSH | CC skills → DSH | CC ↔ DSH session sync | config → DSH |
+All six tabs share a saved grid/list preference. Add and refresh actions sit at the top right; resource state rails are green when active.
 
-Want the opposite direction (dispatch work **from** Claude Code / Codex **to** DSH agents)? See [dsh-crew](https://github.com/ZSeven-W/dsh-crew).
+## Compatibility and boundaries
 
-## FAQ
+Supported **layout dialects** describe how files are organized. The [shared priority table](#layout-detection-precedence) lists suite manifests and Marketplace catalogs together. All ten layout contracts in [`schemas/`](schemas/README.md) have independent reader tests; [the layout audit](docs/user/layout-coverage.md) maps them to pinned repository fixtures.
 
-### How do I install Claude Code plugins in DeepSeek Harness (DSH)?
+Supported **runtime surfaces** describe what DSH can use:
 
-Install this plugin in a dsh profile, then add any Claude Code marketplace repo as a source:
+| Surface  | Runtime support and conditions                                                                                                                                |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Skills   | Host skill catalog and user-invocable slash entries; supported root placeholders are expanded.                                                                |
+| Commands | Slash commands through the host command service.                                                                                                              |
+| Agents   | Dynamic subagent catalog and `subagent_run`; requires host agents, tools, LLM, subagent and session-persistence services.                                     |
+| MCP      | Built-in bridge by default: stdio, Streamable HTTP with OAuth, and legacy SSE. Optional host-client compatibility mode is also available.                     |
+| Hooks    | The command-hook subset mapped by `dsh-hooks-claude-code`.                                                                                                    |
+| LSP      | Self-provisioned: installing the plugin is the whole setup, and `lsp` mounts only while a language server is wanted; the server executable must be on `PATH`. |
 
-```sh
-dsh plugin --profile <name> add dsh-agent-plugins-market
-```
+Agent roles appear in the session catalog and run through `subagent_run(agent, prompt)`. A role may save an exact `provider` plus `model` pair and a `reasoning_effort`; every other declaration is ignored and the child inherits the parent route. `tools` and `disallowedTools` are preserved in the file but never applied. See [agent roles](docs/user/agent-roles.md) for the frontmatter fields and limits.
 
-Then open **Settings → Agent Plugins Market** in the Web GUI, add the marketplace repo URL, and install suites with one click. Skills, MCP servers, hooks and slash commands are injected into your dsh sessions at runtime — no conversion, no file copying.
+### Layout detection precedence
 
-### Does DeepSeek Harness support `.claude-plugin/marketplace.json`?
+When multiple manifests exist in the **same suite directory**, the first existing file in this order selects the layout:
 
-Yes — through this plugin. It reads `.claude-plugin/marketplace.json` + per-plugin `.claude-plugin/plugin.json` natively, plus `.codex-plugin`, `.cursor-plugin`, `.kimi-plugin`, `.plugin` (universal) and agent-plugins.org v1.0.0 `plugin.json` manifests (see the layout table above).
+| Priority | Layout | Suite manifest | Marketplace catalog |
+| --- | --- | --- | --- |
+| 1 | [agent-plugins](https://agent-plugins.org) / root compatibility | `plugin.json` | No dedicated catalog |
+| 2 | Universal compatibility | `.plugin/plugin.json` | `.plugin/marketplace.json` |
+| 3 | Claude Code | `.claude-plugin/plugin.json` | `.claude-plugin/marketplace.json` |
+| 4 | Cursor | `.cursor-plugin/plugin.json` | `.cursor-plugin/marketplace.json` |
+| 5 | Kimi Code | `kimi.plugin.json`, then `.kimi-plugin/plugin.json` | `.kimi-plugin/marketplace.json` |
+| 6 | Codex | `.codex-plugin/plugin.json` | `.agents/plugins/marketplace.json`, then `.agents/plugins/api_marketplace.json` |
+| 7 | ZCode | `.zcode-plugin/plugin.json` | No dedicated catalog |
+| 8 | Qoder CLI | `.qoder-plugin/plugin.json` | `.qoder-plugin/marketplace.json` |
+| 9 | GitHub Copilot CLI | `.github/plugin/plugin.json` | `.github/plugin/marketplace.json` |
+| Fallback | Skill collection / shared catalog | Discover skills when no recognized manifest exists | Root `marketplace.json` |
 
-### Can it inject MCP servers from a plugin suite?
+- **Manifests are tried in order:** a manifest that cannot be read or validated is reported and the next one is tried, down to the fallback. If every candidate fails, the suite is diagnosed instead of loading half of it.
+- **Component fallback:** for a root `plugin.json` that does not declare a recognized agent-plugins `$schema`, missing component declarations can come from `.claude-plugin/plugin.json`; explicit root declarations win, and marketplace entry declarations fill remaining gaps.
+- Marketplace catalogs follow the same order: the first catalog that produces suites wins, and invalid or empty catalogs allow the next candidate to be tried.
 
-Yes. Every valid `mcp.json` server of an enabled suite mounts a live `dsh-mcp-client` child, so MCP tools are callable by the DSH agent. `mcp.json` is validated strictly; `.mcp.json` is parsed leniently with placeholder support (`${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${NAME:-default}`).
+The order is defined in [`src/model/layouts.ts`](src/model/layouts.ts); selection and root-manifest fallback are implemented in [`src/catalog/manifests.ts`](src/catalog/manifests.ts).
 
-### How do MCP servers that require an environment token work?
+### Layout support matrix
 
-Declare the server's environment value as a reference, for example `"env": { "FOO_TOKEN": "${FOO_TOKEN}" }`. Before starting the child, the market resolves that reference through DSH credentials. Open the suite detail view to configure a writable credential through the Host credentials service; the value is write-only and is never stored in the suite or override JSON. A read-only launch-environment credential must be changed before restarting DSH. Missing references block the child start and show `needs-credentials` instead of silently starting an unusable server.
+The table says per layout whether this plugin reads a given surface at all. **Yes** means the layout's own files are read and injected; **Partial** means only part of the formats is understood, or the upstream layout has no such definition — the notes below say which. Evidence: the [compatibility report](docs/reference/compat-report.md) and [layout audit](docs/user/layout-coverage.md).
 
-### What about Claude Code hooks?
+| Layout                                                                                                        | Skills | Agents  | Commands | MCP     | Hooks   | LSP     |
+| ------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------- | ------- | ------- | ------- |
+| [Claude Code](https://code.claude.com/docs/en/plugins-reference)                                              | Yes    | Yes     | Yes      | Yes     | Partial | Yes     |
+| [Codex](https://developers.openai.com/plugins/build/plugins)                                                  | Yes    | Yes     | Yes      | Partial | Partial | Yes     |
+| [Cursor](https://cursor.com/docs/reference/plugins)                                                           | Yes    | Partial | Partial  | Partial | No      | Yes     |
+| Kimi Code                                                                                                     | Yes    | Yes     | Yes      | Yes     | Partial | Partial |
+| [ZCode](https://zcode.z.ai/en/docs/plugin) `.zcode-plugin/`                                                   | Yes    | Yes     | Yes      | Yes     | Partial | Partial |
+| [Qoder CLI](https://docs.qoder.com/cli/plugins-reference) `.qoder-plugin/`                                    | Yes    | Yes     | Yes      | Partial | Partial | Partial |
+| [GitHub Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) | Yes    | Yes     | Yes      | Yes     | Partial | Yes     |
+| Universal compatibility layout `.plugin/`                                                                     | Yes    | Yes     | Yes      | Yes     | Partial | Yes     |
+| [agent-plugins](https://agent-plugins.org)                                                                    | Yes    | Partial | Partial  | Yes     | Partial | Partial |
+| Manifest-less skill collection                                                                                | Yes    | Yes     | Yes      | Yes     | Partial | Partial |
+| Project-native directories                                                                                    | Yes    | Yes     | Yes      | Yes     | Partial | No      |
 
-A suite's `hooks/hooks.json` is mounted through the official `@deepseek-ai/dsh-hooks-claude-code` bridge onto the harness interception points (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop). Only the mapped command-hook subset runs — see the bridge's README for the exact mapping.
+- **Skills** are read from the paths a manifest declares and from the conventional `skills/` directory, including flat `SKILL.md` files.
+- **Agents and commands** are read as Markdown (`agents/*.md`, `commands/*.md`). Cursor commands must be `.md`; its `.mdc`, `.markdown` and `.txt` variants are not read. Codex and Kimi native agent/command formats (TOML, YAML) have no adapter yet.
+- **MCP** covers declared files, inline tables and arrays. Cursor's schema-less `mcp.json` and agent-plugins' strict `mcp.json` both work; Kimi Code is inline-only. Codex app connectors stay outside this adapter.
+- **Hooks** map the command-style events DSH has an equivalent for; events without one (for example `afterFileEdit`) are reported instead of simulated. Cursor's native events are not read.
+- **LSP** accepts declared files, arrays and inline tables plus the conventional `.lsp.json` / `lsp.json` locations. Declarations inside a project are reported but not mounted: the host LSP registry is global. Some layouts only expose LSP directories for preview.
+- **agent-plugins** standardizes portable skills and MCP only. Agents, commands and hooks for that layout are read through this plugin's shared directory conventions, not through the specification.
+- **Universal** is a compatibility-layout label used by this plugin; the [OpenHands SDK](https://docs.openhands.dev/sdk/guides/plugins) documents the same `.plugin/plugin.json` location and a [Vercel repository](https://github.com/vercel/vercel-plugin/blob/main/.plugin/plugin.json) uses it, but no cross-vendor specification exists.
 
-### Do Claude Code-authored skills work verbatim?
+Reading a layout does not guarantee every behavior of its original platform. Invalid declarations are diagnosed and skipped.
 
-Yes. `${CLAUDE_PLUGIN_ROOT}` is substituted automatically at runtime, so Claude Code ecosystem skills run unchanged and appear in the `/` slash menu.
+### Project layout switch
 
-### dsh-agent-plugins-market vs manually copying skill files?
+The plugin settings card has **Scan project Agent layouts** (`dsh-agent-plugins-market.scanProjectLayouts`, default off). It controls one thing: whether the project you are working in contributes skills, commands, agent roles, MCP servers and hooks from its own directories (`.claude`, `.agents`, `.codex`, `.cursor`, `.kimi`, `.zcode`, `.qoder`, `.github`). Turning it on adds those candidates immediately and turning it off removes them; configured sources and installed suites are unaffected.
 
-Manual copying breaks `${CLAUDE_PLUGIN_ROOT}` paths, skips MCP servers/hooks/commands, and gives you no update path. This plugin installs whole suites from git sources with per-plugin enable/disable/refresh, and injects every surface (skills, MCP, hooks, commands, subagents) automatically.
+[Project layouts](docs/user/usage.md#project-layouts) lists the directories and files read per layout and how they are mounted.
 
-### Is it safe to install third-party suites?
+### Verified samples
 
-The plugin never executes third-party code at install time: git sources clone through `execFile` (no shell), and third-party failures (broken manifests, invalid skills, escaping paths, unknown MCP transports, mount failures) are contained as per-plugin diagnostics. As with any third-party code, review a suite before enabling it.
+The README repositories have offline snapshots in [`tests/fixtures/real-layouts/`](tests/fixtures/real-layouts/) with commit IDs, hashes and licenses, and each layout has an isolated reader test. The [compatibility report](docs/reference/compat-report.md) records the sampled repositories, their schema verdicts and the scanner output; [the audit](docs/user/layout-coverage.md) records independent resource checks. These are documentation, source and sample checks — not end-to-end certification for every platform.
 
-### Is it free and open source?
+Review third-party suites before enabling them: enabled services and hooks can execute programs. See the [runtime and security details](docs/user/usage.md#runtime-and-security).
 
-Yes — MIT licensed, published on [npm](https://www.npmjs.com/package/dsh-agent-plugins-market), source on [GitHub](https://github.com/Sivan757/dsh-agent-plugins-market).
+## FAQ
 
-## Requirements
+**Why is an installed skill or tool missing?**
 
-- `ctx.skills` (dsh-skill) is required.
-- Optional peers: `@deepseek-ai/dsh-mcp-client` (MCP injection), `@deepseek-ai/dsh-hooks-claude-code` (hooks bridge); missing capabilities degrade gracefully.
-- The Host credentials service is optional: standard DSH profiles provide it for write-only token configuration and live remounts; without it, `${ENV_NAME}` falls back to the launch environment and requires a restart after changes.
-- Web GUI ≥ 0.1.0-rc.6.
+Check that the suite and the relevant capability are enabled. Skills may restrict manual invocation. MCP / LSP panels show user-service failures. Project resources additionally require the project-scan switch; unsupported native fields and project LSP declarations appear in scan diagnostics.
 
-## Security model
+**Where do I configure MCP tokens?**
 
-- Git sources clone through `git` via `execFile` (no shell), depth 1, shallow `fetch` + `reset` updates, configurable timeouts/proxy/mirrors with a low-speed guard; local sources are read in place and never deleted. Archive sources are HTTPS-only by default, capped at 256 MiB, extracted with path-traversal guards, and optionally pinned to a SHA-256 digest.
-- Mutating HTTP routes accept same-origin POSTs only; bodies capped at 64 KiB.
-- Portable paths must start with `./` and resolve inside the plugin root (symlink escapes rejected); `${PLUGIN_ROOT}` / `${PLUGIN_DATA}` expand.
-- Third-party failures are always contained: broken manifests, invalid skills, escaping paths, unknown MCP transports, missing MCP credentials, and mount failures are per-plugin diagnostics.
-- MCP credential values are resolved in memory through the Host credentials service; status/detail projections redact sensitive fields and credential writes never persist literal values in suite state or overrides.
-- An error boundary wraps the whole market section and the detail modal: any preview render failure degrades to a notice instead of crashing the UI.
+Open the service in **MCP services**. Missing environment references show `needs-credentials`. Host-managed credentials are write-only; launch-environment credentials require changing the environment and restarting DSH.
 
-## Known limitations
+**How do I add a service that no suite declares?**
 
-- Project-dimension MCP servers are not mounted (dsh has no per-session tool scope); the project dimension covers skills and context.
-- Skill discovery has no file watcher: catalog changes apply after a manager action or a host restart (project-dimension snapshots are cached for 5 seconds on the skill-list hot path).
-- Claude Code hooks support the mapped bridge subset; LSP is counted and previewed but not executed.
-- Native project layouts (`.claude/`, `.agents/`) inject skills and subagents; their `commands/*.md` are not registered as slash commands because the harness command registry is process-scoped, not session-cwd-scoped.
+Use **Add** in **MCP services** or **LSP servers**. The declaration is validated, stored in `~/.agents/mcp.json` or `~/.agents/lsp.json`, and mounted through the same lifecycle as suite services. Host-observed services remain read-only.
 
-## Development
+**Do sources refresh automatically?**
 
-```sh
-pnpm install
-pnpm run test        # vitest over fixture suites + multi-dialect parsing
-pnpm run typecheck
-pnpm run lint        # ESLint over the refactored source and tests
-pnpm run format:check
-pnpm run check:architecture
-pnpm run check:refactor
-pnpm run build       # tsc host + tsdown client + module-loader banner
-pnpm pack
-```
+Only when **Background source updates** is on: every configured source is then refreshed every 6 hours, starting one interval after you enable it. The switch is off by default, and the refresh button always works.
 
-The internal modularization decision and staged migration are documented in [`docs/design/engineering-refactor-plan.md`](docs/design/engineering-refactor-plan.md) and [`docs/adr/0001-catalog-centered-modular-refactor.md`](docs/adr/0001-catalog-centered-modular-refactor.md).
+**What if a source download fails?**
 
-The docs website lives in [`docs-site/`](docs-site/) (Astro, deployed to GitHub Pages).
+Use a local directory, adopt a manual checkout, or configure a proxy / mirror. See [source configuration](docs/user/usage.md#configure-marketplace-sources).
 
-## Vendored assets
+**When do local edits become visible?**
 
-The `schemas/1.0.0/` JSON Schemas are vendored from [agentplugins/agent-plugins-spec](https://github.com/agentplugins/agent-plugins-spec) (spec 1.0.0 working draft); the spec forbids fetching schemas at load time.
+There is no file watcher. Local-source discovery caches results for up to 30 seconds; refresh the source to invalidate them immediately. Project discovery has a separate five-second cache. A refresh does not happen automatically on an already-open page.
 
-## Related projects
+**Does removing a source delete its files?**
 
-- [dsh-skills](https://github.com/CocoSgt/dsh-skills) — centralize `~/.claude/skills` and `.skill` packages into a global DSH skill library
-- [@claude2dsh/plugin](https://www.npmjs.com/package/@claude2dsh/plugin) — import Claude Code sessions & skills into DSH, sync sessions back
-- [dsh-crew](https://github.com/ZSeven-W/dsh-crew) — dispatch work from Claude Code / Codex to DSH agents
-- [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — the DeepSeek Harness itself (official)
-- [awesome-deepseek-harness-plugins](https://github.com/imsai-sh/awesome-deepseek-harness-plugins) — community DSH plugin directory
+Only when you tick **also delete the managed market directory** in the confirmation. That removes the source's checkout under `~/.dsh/agent-plugins/.sources/<id>` — including one you cloned yourself and adopted. A local-directory source pointing outside `.sources/` is never deleted.
 
----
+## More documentation
 
-**If this plugin helps you, please give it a ⭐ on GitHub — it helps more people find the Claude Code ecosystem inside DeepSeek Harness.**
+- [Usage guide](docs/user/usage.md): installation, source configuration, storage, host requirements, project layouts, MCP / LSP and feedback settings.
+- [Plugin specifications](schemas/README.md): per-dialect reference schemas and evidence, plus the vendored agent-plugins v1.0.0 contracts.
+- [Compatibility report](docs/reference/compat-report.md): one real repository per schema, with commits, schema verdicts and scanner output.
+- [Contributing](CONTRIBUTING.md): development setup, checks and PR workflow.
+- [Security policy](SECURITY.md) · [Release history](CHANGELOG.md) · [MIT license](LICENSE).
+- [Domain glossary](CONTEXT.md) · [Architecture](docs/developer/decisions/0001-catalog-centered-modular-refactor.md).
+- [Agent roles and storage](docs/user/agent-roles.md): installed-resource editing, model routing and migration.