dsh-agent-plugins-market 0.6.2 → 0.7.0

package/README.md

@@ -4,7 +4,9 @@
 
 **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. Manage your own skills, commands, agent personas, MCP services and LSP servers in the DSH Web GUI. Supported layouts are read in place, without converting manifests or manually copying files into DSH. See the capability matrix for format-specific limits.
+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)
 
@@ -12,77 +14,104 @@ English | [简体中文](README.zh.md) | [Documentation](https://sivan757.github
 
 [Quick start](#quick-start) · [Everyday use](#everyday-use) · [Compatibility](#compatibility-and-boundaries) · [FAQ](#faq)
 
-![Current six-tab Agent Plugins workspace](docs/screenshot-workspace.png)
+## 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
 
-- **Reuse ecosystem suites.** Add a Git repository, local directory or archive as a source; browse, preview, install and enable its suites. Supported capabilities become available to DSH at runtime.
-- **Build your own toolkit.** Create skills, reusable slash commands and agent personas. Edit or disable your own entries without deleting them.
-- **Keep project resources in place.** Project `.claude/` and `.agents/` skills and agents are discovered without an installation step or file copying.
-- **Manage services where you use them.** Add your own MCP services and LSP servers, configure credentials and authorization for installed ones, inspect status, and diagnose unavailable services from one workspace.
+- **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
 
-You need Node.js 22+, Git for Git sources, and a DSH Web profile with the skill service enabled. This repository declares DSH peer packages in the `^0.1.2-rc.1` range; individual capabilities also depend on the services in your profile. See [host requirements](docs/guides/usage.md#host-requirements).
-
 Install into your profile, replacing `<name>` with its name:
 
 ```sh
 dsh plugin --profile <name> add dsh-agent-plugins-market
 ```
 
-1. Restart DSH and open **Settings → Agent Plugins Market**. Older shells may show a top-level page entry instead.
+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 notices before using its tools.
+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.
 
-For GitHub installation and profile configuration, see the [usage guide](docs/guides/usage.md#installation-options).
+Requirements, profile configuration and alternative installs: [usage guide](docs/user/usage.md#installation-options).
 
 ## Everyday use
 
-MCP details separate Retry connection (keeps credentials) from confirmed OAuth reauthorization. There is no enable switch in the detail dialog.
-
 The workspace has six tabs:
 
-| 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`; `$ARGUMENTS` inserts the text supplied after the command.                             |
-| Agent personas | Select providers, models and reasoning effort from DSH, manage role instructions and tools, and delegate through `subagents_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.                                                              |
+| 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.                                                                         |
 
-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. Suite details preview files; MCP credentials and overrides are edited in **MCP services**.
+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.
 
-Your own skills, commands and personas are stored as Markdown under `~/.dsh/agent-plugins/user/`. Project-native resources stay in the project. See [storage and discovery](docs/guides/usage.md#storage-and-discovery) for paths and precedence.
+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.
 
 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.
 
-Resource details share a wide dialog. Markdown resources open with rendered content and structured frontmatter; switch to Markdown to edit. MCP/LSP provide fixed forms and JSON editing over the same configuration.
-
-Services you add yourself are validated before saving, persist under `~/.dsh/agent-plugins/data/`, and mount through the same lifecycle as suite services. Services observed from the host configuration stay read-only.
-
-Asynchronous workspace actions show a blocking overlay on the active settings panel or detail dialog, with rotating waiting messages. The overlay is released on success or failure; background status polling stays silent.
-
 ## Compatibility and boundaries
 
-Supported **layout dialects** describe how files are organized. The [shared priority table](#layout-detection-precedence) lists suite manifests and Marketplace catalogs together.
-
-All ten active layout contracts in [`schemas/`](schemas/README.md) have independent reader tests. [The layout audit](docs/layout-coverage.md) maps them to commit-pinned README repository fixtures and distinguishes layout/component compatibility from full original-client runtime equivalence.
+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.
 
 Supported **runtime surfaces** describe what DSH can use:
 
-| 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 `subagents_run`; requires host agents, tools, LLM and subagent 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      | Live mounts when the host provides LSP packages; the profile must expose the LSP tool for agent use.                                      |
+| 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`. |
 
-Agent roles are published directly in a dynamic `subagent-catalog`, using the same per-step comparison, durable entries and complete replacement mechanism as DSH's skills catalog. Call `subagents_run(role, prompt)` with the catalog's exact ID; it resolves the role's provider, model and `reasoning_effort`, then applies the persona and tool restrictions. Roles no longer generate `agent-*` or `persona-*` skill/command entries. See [agent roles](docs/guides/agent-roles.md) for model inheritance, catalog refresh and migration from `market_agent`.
+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.
 
 ### Layout detection precedence
 
@@ -90,7 +119,7 @@ When multiple manifests exist in the **same suite directory**, the first existin
 
 | Priority | Layout | Suite manifest | Marketplace catalog |
 | --- | --- | --- | --- |
-| 1 | agent-plugins.org v1 / root compatibility | `plugin.json` | No dedicated 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` |
@@ -101,83 +130,57 @@ When multiple manifests exist in the **same suite directory**, the first existin
 | 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` |
 
-- **Selection precedes parsing:** an invalid higher-priority manifest produces diagnostics; it does not trigger a retry with a lower-priority manifest.
-- **Root manifest identity:** root `plugin.json` uses strict v1 validation only when it declares a recognized agent-plugins.org `$schema`. Otherwise it is read as a Claude-compatible manifest.
-- **Component fallback:** manifests are not generally merged. For a non-v1 root `plugin.json`, missing component declarations can come from `.claude-plugin/plugin.json`. Explicit root declarations win; marketplace entry declarations fill remaining gaps.
-
-**Both columns follow the same layout priority.** Catalog lookup skips layouts without a dedicated catalog; aliases are tried in the listed order. Root `marketplace.json` is a shared fallback, not a skill-collection manifest or an agent-plugins.org v1 catalog, and does not inherit the priority of root `plugin.json`.
-
-All existing catalogs are read, but suite scanning selects the first catalog that produces suites, rather than merging every catalog. Invalid or empty catalogs allow the next candidate to be tried. This priority does not make native project directories mutually exclusive.
+- **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.
 
 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).
 
-### Layout capability matrix
-
-Checked against official documentation, this plugin's source, and one real repository per schema on 2026-09-08. This table describes **integration by this plugin**. “Shared” means the plugin's common scanning conventions, not an upstream-defined capability. “Partial” requires the limitations below. The [compatibility report](docs/compat-report.md) records the sampled repositories, their commits, the schema verdicts and the scanner output.
-
-| Layout | Skills | Agents | Commands | MCP | Hooks | LSP |
-| --- | --- | --- | --- | --- | --- | --- |
-| [Claude Code](https://code.claude.com/docs/en/plugins-reference) | Declared + default skills | Declared Markdown | Declared Markdown | Files / inline | Command-hook subset | Files / inline |
-| [Codex](https://developers.openai.com/plugins/build/plugins) | Supported | Shared | Shared | Partial: `.mcp.json` | Compatible event subset | Shared inline |
-| [Cursor](https://cursor.com/docs/reference/plugins) | Supported | Partial: `.md` only | Partial: `.md` only | Partial: see below | Native events unsupported | Shared inline |
-| Kimi Code | Declared skills + startup | Declared Markdown | Declared commands | Inline | Inline command events | Shared extension, non-native |
-| [ZCode](https://zcode.z.ai/en/docs/plugin) `.zcode-plugin/` | Shared | Shared | Shared | `.mcp.json` + inline overrides | Shared | Shared inline, non-native |
-| [Qoder CLI](https://docs.qoder.com/cli/plugins-reference) `.qoder-plugin/` | Shared | Shared | Shared | Partial: prefers `.mcp.json` | Shared | Shared inline, non-native |
-| [GitHub Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) | Declared skills | `.md` / `.agent.md` | Declared Markdown | Files / inline | Mapped command events | Files / inline |
-| Universal compatibility layout `.plugin/` | Shared | Shared | Shared | Shared | Claude-format subset | Shared inline |
-| [agent-plugins.org v1](https://agent-plugins.org/specification) | Supported | Shared, nonstandard | Shared, nonstandard | Standard `mcp.json` | Shared, nonstandard | Directory preview only, nonstandard |
-| Manifest-less skill collection | Supported | Shared | Shared | Shared files | Claude-format subset | Directory preview only |
-| Project-native directories (see below) | Supported | Portable Markdown roles | Scoped commands | JSON / Codex TOML | Mapped command-hook subset | Diagnosed, not mounted |
-
-- **Component paths:** declared files, directory trees and arrays resolve inside the suite by realpath. Commands, agents and detail panels use the same resources. Cursor also accepts `.mdc`, `.markdown` and `.txt` commands; Qoder maps support files and inline content. Claude/Codex skills supplement default discovery. Flat skill Markdown files work in manifest-less collections.
-- **Agent identities:** `reviewer.agent.md` and `reviewer.md` retain distinct role IDs in the subagent catalog. Roles have no generated `agent-*` skill or command aliases. Ordinary skills with those names remain skills.
-- **MCP:** declared files, inline maps and arrays are resolved by dialect. Cursor's schema-less `mcp.json` is supported; agent-plugins v1 stays schema-strict. Claude/ZCode declarations add to defaults, Cursor declarations replace defaults, Copilot/Universal include `.github/mcp.json`, and Kimi Code uses inline declarations. Invalid explicit configs cannot revive defaults. Codex app connectors remain outside this adapter.
-- **Hooks:** declared files/directories and inline configs are supported, including Kimi arrays and ZCode process hooks with quoted argv. Supported Copilot/Cursor lifecycle names map to the existing command-hook bridge. Events without a DSH equivalent, such as `afterFileEdit`, are diagnosed rather than simulated.
-- **LSP:** user suites accept declared files, arrays and inline tables, plus `.lsp.json` and Copilot/Universal `lsp.json`, `.github/lsp.json`, `lsp-config/servers.json`. Reverse-domain directory definitions remain previews. Project LSP retains its host-scope limitation.
-- **Specification boundaries:** agent-plugins.org v1 standardizes portable skills and MCP only; shared agents / commands / hooks scanning is not a standard capability. 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.
-- **Kimi Code:** the active schema covers both manifest spellings, startup skills, appended skill instructions, system prompts, inline hooks and catalog aliases. The historical `kimi-cli` root tools protocol is a different system; it must not be confused with the current Kimi Code schema.
-- **ZCode boundary:** `.zcode-plugin/plugin.json` and root `marketplace.json` are recognized, including keyed plugin maps. Inline MCP servers override matching `.mcp.json` keys. The zip + `sha256` marketplace distribution contract is not implemented.
-- **Qoder boundary:** `.qoder-plugin/plugin.json` and `.qoder-plugin/marketplace.json` are recognized. MCP prefers `.mcp.json`, with schema-less `mcp.json` as fallback.
-- **GitHub Copilot CLI:** `.plugin/plugin.json` retains the Universal identity. Both spellings consume declared component paths and fallback MCP/LSP files. Isolated tests suppress competing manifests at nested suite roots, preventing a Claude fallback from masquerading as a passing Copilot test.
-- **Project directories:** [Claude project skills](https://code.claude.com/docs/en/skills) and [Codex `.agents/skills`](https://developers.openai.com/codex/skills) are documented upstream; `.agents/agents` and `.agents/commands` are this plugin's shared discovery conventions.
+### Layout support matrix
+
+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).
+
+| 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      |
+
+- **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.
+
+Reading a layout does not guarantee every behavior of its original platform. Invalid declarations are diagnosed and skipped.
 
 ### Project layout switch
 
-The plugin settings card exposes **Scan project Agent layouts** (`dsh-agent-plugins-market.scanProjectLayouts`, default `true`). Turning it off removes this plugin's native project candidates immediately; configured sources and the harness's own skill providers remain independent. Files are read in place and are never installed, rewritten or deleted.
+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.
 
-The registry reads skills under `.claude`, `.agents`, `.codex`, `.cursor`, `.kimi`, `.zcode`, `.qoder` and `.github`. Portable Markdown agents are enabled for all except `.codex` and `.kimi`; their TOML/YAML formats need separate adapters. Role execution resolves the calling session's project. Project commands, supported MCP servers and mapped command hooks register in each agent's scoped context and refresh on session startup or catalog changes; disabling the switch removes them.
-
-MCP reads root `.mcp.json`, `.cursor/mcp.json`, and the `mcpServers` tables in `.qoder/settings.json` and `.qoder/settings.local.json` (local keys override project keys). ZCode reads `mcp.servers` from `zcode.json` and `.zcode/config.json`, with `.agents/mcp.json` as an empty-native-table fallback. Codex reads `[mcp_servers.*]` from `.codex/config.toml` through `smol-toml`, preserving stdio/HTTP configuration, environment/header references, enabled flags, tool filters and timeouts. Unsupported server options produce diagnostics; host-client mode rejects policies it cannot enforce. Relative executables resolve from the project root. Claude/Qoder settings hooks and enabled ZCode configuration hooks use the bridge's supported command-event subset. Validated hooks become private temporary runtime files removed on teardown; project files remain unchanged. Project LSP is diagnosed and not mounted: host changes are outside this plugin's scope. See the [architecture decision and supported boundaries](docs/adr/2026-09-09-layout-registry.md).
+[Project layouts](docs/user/usage.md#project-layouts) lists the directories and files read per layout and how they are mounted.
 
 ### Verified samples
 
-The nine README repository samples have offline snapshots in [`tests/fixtures/real-layouts/`](tests/fixtures/real-layouts/), with commit IDs, hashes and licenses. Tests validate real schemas, scan original trees and isolate each dialect independently. The [compatibility report](docs/compat-report.md) records natural precedence; [the audit](docs/layout-coverage.md) records independent resource checks.
-
-| Layout | Sample repository | Dialect manifest | Schema | Scanner |
-| --- | --- | --- | --- | --- |
-| Claude Code | [grafana/mcp-grafana](https://github.com/grafana/mcp-grafana) | `.claude-plugin/plugin.json` | valid | integrated |
-| Codex | [saadeghi/daisyui](https://github.com/saadeghi/daisyui) | `.codex-plugin/plugin.json` | valid | shadowed |
-| Cursor | [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | `.cursor-plugin/plugin.json` + marketplace | valid | shadowed |
-| Kimi | [obra/superpowers](https://github.com/obra/superpowers) | `.kimi-plugin/plugin.json` | valid | shadowed |
-| Universal | [muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) | `.plugin/plugin.json` | valid | integrated |
-| agent-plugins.org v1 | [saadeghi/daisyui](https://github.com/saadeghi/daisyui) | `plugin.json` | valid | integrated |
-| ZCode | [zenstory-ai/oh-story-claudecode](https://github.com/zenstory-ai/oh-story-claudecode) | `.zcode-plugin/plugin.json` + `marketplace.json` | valid | shadowed |
-| Qoder CLI | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | `.qoder-plugin/plugin.json` | valid | shadowed |
-| GitHub Copilot CLI | [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom) | `.github/plugin/marketplace.json` | valid | shadowed |
-
-**Scanner** describes the unmodified repository: **integrated** means its own manifest won; **shadowed** means another won; **unread** means no suite. These verdicts are separate from passing isolated tests. Skill collection is tested with the real Universal repository's skills and no manifests, completing coverage of all ten layouts.
-
-Source checks covered `src/catalog/manifests.ts`, `surfaces.ts`, `validate.ts`, `native-project.ts`, and `src/runtime/hooks-mounts.ts`. The [compatibility report](docs/compat-report.md) adds one real repository per schema, read by this plugin's own scanner. This is a documentation, source and sample audit, not end-to-end compatibility certification for every platform.
+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.
 
-Reading a layout does not guarantee every behavior of its original platform. Invalid declarations are diagnosed and skipped. Project-native commands and supported MCP servers use agent-scoped host registration; project MCP server names include session identity to avoid app-wide namespace conflicts.
-
-Review third-party suites before enabling them: enabled services and hooks can execute programs. See the [runtime and security details](docs/guides/usage.md#runtime-and-security).
+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).
 
 ## FAQ
 
 **Why is an installed skill or tool missing?**
 
-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, while scoped mount failures are logged by the host.
+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.
 
 **Where do I configure MCP tokens?**
 
@@ -185,11 +188,15 @@ Open the service in **MCP services**. Missing environment references show `needs
 
 **How do I add a service that no suite declares?**
 
-Use **Add** in **MCP services** or **LSP servers**. The declaration is validated, stored under `~/.dsh/agent-plugins/data/`, and mounted through the same lifecycle as suite services. Host-observed services remain read-only.
+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.
+
+**Do sources refresh automatically?**
+
+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.
 
 **What if a source download fails?**
 
-Use a local directory, adopt a manual checkout, or configure a proxy / mirror. See [source configuration](docs/guides/usage.md#configure-marketplace-sources).
+Use a local directory, adopt a manual checkout, or configure a proxy / mirror. See [source configuration](docs/user/usage.md#configure-marketplace-sources).
 
 **When do local edits become visible?**
 
@@ -201,11 +208,10 @@ Only when you tick **also delete the managed market directory** in the confirmat
 
 ## More documentation
 
-- [Usage guide](docs/guides/usage.md): installation, source configuration, storage, host requirements, MCP / LSP and feedback settings.
-- [Plugin specifications](schemas/README.md): per-dialect reference schemas and evidence, plus the vendored agent-plugins.org v1.0.0 contracts.
-- [Compatibility report](docs/compat-report.md): one real repository per schema, with commits, schema verdicts and scanner output.
+- [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/adr/0001-catalog-centered-modular-refactor.md).
-
-See [agent roles and storage](docs/guides/agent-roles.md) for installed-resource editing, model routing and migration.
+- [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.