dsh-agent-plugins-market 0.6.0 → 0.6.2

package/schemas/README.md

@@ -1,11 +1,73 @@
-# Vendored Agent Plugins JSON Schemas
+# Plugin manifest and marketplace specifications
 
-These files are pinned copies of the official Agent Plugins 1.0.0 schemas:
+This directory is the specification library for the plugin layouts this manager reads. It holds two kinds of files:
 
-- source: https://github.com/agentplugins/agent-plugins-spec (schemas/1.0.0/)
-- spec status: version 1.0.0, working draft
-- license: the Agent Plugins specification repository's license
+1. **Vendored upstream schemas** in [`1.0.0/`](1.0.0/) — pinned copies of the official agent-plugins.org v1.0.0 schemas. These are bundled into the published package and loaded at runtime by [`src/catalog/validate.ts`](../src/catalog/validate.ts), because the specification requires clients to validate plugin packages without retrieving schemas at load time (§7.2.1: "Clients MUST NOT retrieve a schema while loading a plugin").
+2. **Reference contracts** in `<dialect>/` — an authored JSON Schema pair plus a `spec.md` for each layout the manager recognizes. **These are documentation, not runtime validators**: the scanner still applies the strategy-chain rules in `src/catalog/`. They exist so a dialect's field set, file locations, and evidence are pinned in one place.
 
-They are bundled into the published package because the specification requires clients to validate plugin packages without retrieving schemas at load time (§7.2.1: "Clients MUST NOT retrieve a schema while loading a plugin").
+Every authored schema records its provenance in a `$comment`, and every dialect's `spec.md` records the sources, the verification date, and the unresolved gaps.
 
-Update procedure: replace both files from the upstream repository at the pinned spec version and bump the spec-version references in `src/validate.ts`.
+## Layout
+
+```text
+schemas/
+├── 1.0.0/                     # vendored agent-plugins.org v1.0.0 (runtime-loaded)
+│   ├── plugin.schema.json
+│   └── mcp.schema.json
+├── agent-plugins/spec.md      # the published cross-vendor standard (schemas live in 1.0.0/)
+├── skill-collection/spec.md   # manifest-less layout; nothing to validate
+└── <dialect>/
+    ├── plugin.schema.json
+    ├── marketplace.schema.json
+    └── spec.md
+```
+
+## Dialect index
+
+This table records **upstream client conventions**, including their own fallback orders; it does not define this plugin's discovery priority. DSH uses one shared layout order for suite manifests and Marketplace catalogs, shown in the [README priority table](../README.md#layout-detection-precedence) ([中文](../README.zh.md#布局识别优先级)). Catalogs without a dedicated layout use root `marketplace.json` as the final fallback.
+
+| Dialect | Upstream plugin manifest conventions | Upstream marketplace conventions | Upstream schema |
+| --- | --- | --- | --- |
+| [Claude Code](claude-code/spec.md) | `.claude-plugin/plugin.json` (optional) | `.claude-plugin/marketplace.json`, or any `marketplace.json` added by path/URL | None; the URL the official catalog declares returns 404 |
+| [Codex](codex/spec.md) | `plugin.json` (agent-plugins `$schema`) → `.codex-plugin/` → `.claude-plugin/` → `.cursor-plugin/` | `.agents/plugins/marketplace.json` → `.agents/plugins/api_marketplace.json` → `.claude-plugin/` → `.cursor-plugin/` | agent-plugins v1.0.0 for root `plugin.json`; none otherwise |
+| [Cursor](cursor/spec.md) | `.cursor-plugin/plugin.json`, or root `plugin.json` (agent-plugins) | `.cursor-plugin/marketplace.json` | None for `.cursor-plugin/`; agent-plugins v1.0.0 for root |
+| [Kimi (kimi-code)](kimi/spec.md) | `kimi.plugin.json` → `.kimi-plugin/plugin.json` | `KIMI_CODE_PLUGIN_MARKETPLACE_URL`, default `https://code.kimi.com/kimi-code/plugins/marketplace.json` | None reachable; the declared URI serves HTML |
+| [Kimi (kimi-cli, legacy)](kimi/spec.md#kimi-cli-legacy-a-different-format) | `plugin.json` with a `tools` array | None | None |
+| [Universal `.plugin/`](universal/spec.md) | `.plugin/plugin.json` | `.plugin/marketplace.json` | None — an observed convention, not a specification |
+| [agent-plugins.org v1](agent-plugins/spec.md) | `plugin.json` (required) | Vendor-specific; not part of the standard | **Vendored 1.0.0** |
+| [Skill collection](skill-collection/spec.md) | None | None | n/a |
+| [ZCode](zcode/spec.md) | `.zcode-plugin/plugin.json` → `.claude-plugin/` → `.codex-plugin/` | `.claude-plugin/marketplace.json` → `marketplace.json` | None |
+| [Qoder CLI](qoder/spec.md) | `.qoder-plugin/plugin.json` → `.claude-plugin/plugin.json` | `.qoder-plugin/marketplace.json` → `.claude-plugin/` → `marketplace.json` | None |
+| [GitHub Copilot CLI](github-copilot/spec.md) | `.plugin/plugin.json` → `plugin.json` → `.github/plugin/plugin.json` → `.claude-plugin/` | `marketplace.json` → `.plugin/` → `.github/plugin/` → `.claude-plugin/` | None; agent-plugins optional via `$schema` |
+
+## Cross-dialect conventions
+
+These are the points where the layouts actually differ; they cause the most silent failures.
+
+| Dialect              | MCP configuration                                                                     | Hooks                              |
+| -------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- |
+| Claude Code          | `.mcp.json`; inline `mcpServers` is additive                                          | `hooks/hooks.json` or inline       |
+| Codex                | legacy: `.mcp.json` (validator rejects `mcp.json`); agent-plugins dialect: `mcp.json` | manifest `hooks` or `hooks/`       |
+| Cursor               | `mcp.json` (dot-file only via an explicit `mcpServers` field)                         | `hooks/hooks.json` or inline       |
+| Kimi (kimi-code)     | inline `mcpServers` only                                                              | inline `hooks` array               |
+| Universal `.plugin/` | `.mcp.json`, `.github/mcp.json`                                                       | `hooks.json` or `hooks/hooks.json` |
+| agent-plugins.org v1 | `mcp.json`, required and closed; inline is forbidden                                  | Not defined                        |
+| ZCode                | `.mcp.json` only                                                                      | `hooks/hooks.json`                 |
+| Qoder CLI            | `.mcp.json` → `mcp.json` (never merged)                                               | `hooks/hooks.json`                 |
+| GitHub Copilot CLI   | `.mcp.json`, `.github/mcp.json`                                                       | `hooks.json` or `hooks/hooks.json` |
+
+Claude Code and Copilot (including the Universal convention) define usable LSP declarations. Qoder/ZCode record the field without native execution. Cursor, Codex, Kimi and agent-plugins do not define a native LSP surface; this manager's shared LSP extension must not be confused with an upstream feature.
+
+## Executable coverage
+
+All ten active layouts are covered by [offline README repository tests](../tests/real-layouts.test.ts). Fixtures retain original Git blobs, commit IDs, hashes and licenses. Competing manifests are removed at every suite root in isolated cases, and the scanner reports the productive marketplace rather than inferring it from file presence. [Component contract tests](../tests/component-declarations.test.ts) cover path/array/inline forms and validation failures. See the [coverage audit](../docs/layout-coverage.md) for the exact boundary between layout compatibility and vendor-native runtime behavior.
+
+## Provenance and update policy
+
+- `1.0.0/*.schema.json` are vendored. Replace both files from [`agentplugins/agent-plugins-spec`](https://github.com/agentplugins/agent-plugins-spec) at the pinned spec version and bump the spec-version references in `src/catalog/validate.ts`. Never edit them by hand.
+- `<dialect>/*.schema.json` and `spec.md` are authored here. They are **not** upstream copies and carry no upstream compatibility guarantee. When a cited source changes, re-verify and update the schema, the `spec.md`, and the `$comment` provenance line together.
+- `agent-plugins/spec.md` documents the published standard but deliberately keeps its schemas in `1.0.0/` so there is exactly one copy in the tree.
+
+## Validation
+
+`tests/schemas.test.ts` compiles every schema with Ajv 2020-12, asserts `$id` uniqueness, pins the vendored ids to the runtime constants in `src/catalog/validate.ts`, and requires each dialect to keep a `spec.md` and a paired marketplace schema. Run `pnpm run test` after touching this directory; run `pnpm run format:check` for formatting.

package/schemas/agent-plugins/spec.md

@@ -0,0 +1,48 @@
+# Agent Plugins (agent-plugins.org) v1 specification
+
+The only published cross-vendor plugin format in this directory. Unlike the other dialects, its schemas are **vendored upstream** and loaded at runtime by this plugin.
+
+- **Schemas:** [../1.0.0/plugin.schema.json](../1.0.0/plugin.schema.json), [../1.0.0/mcp.schema.json](../1.0.0/mcp.schema.json)
+- **Specification:** https://agent-plugins.org/specification
+- **Repository:** [`agentplugins/agent-plugins-spec`](https://github.com/agentplugins/agent-plugins-spec) (`spec/1.0.0.md`, `schemas/1.0.0/`)
+- **Status:** 1.0.0 published; 1.1.0 is a working draft whose plugin schema is currently byte-identical to 1.0.0.
+- **Runtime use:** `src/catalog/validate.ts` loads both 1.0.0 schemas through Ajv, and `src/catalog/manifests.ts` selects this dialect only when a root `plugin.json` declares a recognized `$schema`.
+
+## Manifest location
+
+Normative (§5.1): clients MUST check for a manifest at `plugin.json` in the plugin root. The core specification defines exactly one portable manifest per plugin, and no other file can replace, supplement, or override its core fields. The specification text contains no reference to `.plugin/`, `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/`, or `.kimi-plugin/`.
+
+## Plugin manifest fields
+
+Closed schema: `additionalProperties: false`, `required: ["$schema", "name"]`, and no `default` keyword anywhere.
+
+| Field | Type | Required | Constraints |
+| --- | --- | --- | --- |
+| `$schema` | string | yes | `const: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` |
+| `name` | string | yes | 1–64 chars, `^(?!.*(?:--\|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$` |
+| `version` | string | no | SemVer recommended, not enforced. |
+| `description` | string | no |  |
+| `author` | `{name?, email?, url?}` | no | Closed object; fields unvalidated. |
+| `homepage`, `repository` | string | no | Not URL-validated. |
+| `license` | string | no | SPDX recommended, not enforced. |
+| `keywords` | string[] | no | No `minItems`/`uniqueItems`. |
+| `extensions` | object of object | no | Client-specific data keyed by reverse-domain namespace; the specification assigns no semantics to namespace contents. |
+
+## Fixed component locations
+
+Clients MUST discover each supported component type from its fixed location, and `plugin.json` cannot override those locations or carry inline component configuration.
+
+| Component   | Location   | Pattern                                        |
+| ----------- | ---------- | ---------------------------------------------- |
+| Skills      | `skills/`  | Immediate subdirectories containing `SKILL.md` |
+| MCP servers | `mcp.json` | JSON configuration                             |
+
+v1 defines exactly these two component types. Commands, hooks, agents, rules, and LSP servers are explicitly outside the format "until their formats converge". MCP configuration MUST NOT be declared inline in `plugin.json`. The `mcp.json` schema is closed and requires `$schema` and `mcpServers` with no other top-level fields; every server requires `type` and must match exactly one closed variant.
+
+## Governance and adoption
+
+The technical steering committee is Amazon, Cursor, Microsoft, OpenAI, and Vercel (lead), with a rule that no single vendor may control a majority of core maintainer seats. Adopters list Agent Skills and MCP: VS Code, Cursor, GitHub Copilot, ChatGPT and Codex, Kiro, Hermes Agent, OpenClaw, Grok Bot, and NanoClaw. **Claude Code and Vercel are absent from that list**, and Vercel's own `vercel-plugin` repository is non-conformant (no root `plugin.json`, no `$schema`, ships `commands/`/`agents/`/`hooks/`, and puts MCP at `.mcp.json` instead of `mcp.json`). The OpenHands SDK vendors the schema and implements the format but keeps it out of its active format list pending its `mcp.json` loader.
+
+## Update procedure
+
+Replace both files from the upstream repository at the pinned spec version and bump the spec-version references in `src/catalog/validate.ts`. Do not edit the vendored files by hand.

package/schemas/claude-code/marketplace.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/claude-code/marketplace.schema.json",
+  "title": "Claude Code Marketplace Manifest",
+  "description": "Marketplace catalog read by Claude Code at .claude-plugin/marketplace.json, or from any marketplace.json file added by direct path or URL. Authored from the official plugin marketplace reference and the official claude-plugins-official catalog; Anthropic publishes no JSON Schema.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Sources: https://code.claude.com/docs/en/plugin-marketplaces ; anthropics/claude-plugins-official/.claude-plugin/marketplace.json (291 entries). forceRemoveDeletedPlugins appears only in the community schemastore schema and in no current official doc. Entry source variants observed in the official catalog: url 153, git-subdir 85, relative path 53.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Ignored at load. The official catalog declares https://anthropic.com/claude-code/marketplace.schema.json, which currently returns 404."
+    },
+    "name": { "type": "string", "description": "Kebab-case marketplace identifier. Registration is per name per user; a reserved-name list applies." },
+    "owner": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string" }
+      },
+      "required": ["name"],
+      "additionalProperties": true
+    },
+    "plugins": { "type": "array", "items": { "$ref": "#/$defs/entry" } },
+    "description": { "type": "string", "description": "Also accepted under metadata for backward compatibility." },
+    "version": { "type": "string", "description": "Also accepted under metadata for backward compatibility." },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "pluginRoot": {
+          "type": "string",
+          "description": "Directory under which bare source names resolve; must be a relative path inside the marketplace and is ignored for ./ sources."
+        },
+        "description": { "type": "string" },
+        "version": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "allowCrossMarketplaceDependenciesOn": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Marketplace names whose plugins may be auto-installed as dependencies. Only the root marketplace's allowlist applies; there is no transitive trust."
+    },
+    "renames": {
+      "type": "object",
+      "description": "Old plugin name to new name, or null when removed. Chains are followed; cycles are rejected by `claude plugin validate`.",
+      "additionalProperties": { "type": ["string", "null"] }
+    },
+    "forceRemoveDeletedPlugins": { "type": "boolean", "description": "Community-schema field with no current official documentation; treat as unverified." }
+  },
+  "required": ["name", "owner", "plugins"],
+  "additionalProperties": true,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "description": "Kebab-case plugin identifier used by enabledPlugins and /plugin." },
+        "source": { "$ref": "#/$defs/source" },
+        "displayName": { "type": "string" },
+        "description": { "type": "string" },
+        "version": { "type": "string", "description": "Pins the plugin. The plugin.json version wins when both are set; ignored for command sources." },
+        "author": {
+          "type": "object",
+          "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string" } },
+          "required": ["name"],
+          "additionalProperties": true
+        },
+        "homepage": { "type": "string" },
+        "repository": { "type": "string" },
+        "license": { "type": "string" },
+        "keywords": { "type": "array", "items": { "type": "string" } },
+        "metadata": { "type": "object" },
+        "category": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "strict": {
+          "type": "boolean",
+          "default": true,
+          "description": "true: plugin.json is authoritative and this entry supplements it. false: this entry is the whole definition; a conflicting plugin.json fails to load."
+        },
+        "relevance": { "type": "object", "description": "Suggestion signals; only honored for admin-allowlisted marketplaces." },
+        "defaultEnabled": { "type": "boolean", "default": true, "description": "Takes precedence over the manifest value." },
+        "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "HTTP headers for this entry's archive download." },
+        "headersHelper": { "type": "string", "description": "Command printing header JSON; the entry must also set strict: false." },
+        "skills": { "anyOf": [{ "type": "string" }, { "type": "array" }] },
+        "commands": { "anyOf": [{ "type": "string" }, { "type": "array" }] },
+        "agents": { "anyOf": [{ "type": "string" }, { "type": "array" }] },
+        "hooks": { "anyOf": [{ "type": "string" }, { "type": "object" }] },
+        "mcpServers": { "anyOf": [{ "type": "string" }, { "type": "object" }] },
+        "lspServers": { "anyOf": [{ "type": "string" }, { "type": "object" }] }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": true
+    },
+    "source": {
+      "description": "Where to fetch the plugin. When both ref and sha are set on a git source, sha is the effective pin.",
+      "anyOf": [
+        { "type": "string", "description": "Relative path beginning with ./, or a bare name resolved under metadata.pluginRoot." },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "github" }, "repo": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" } },
+          "required": ["source", "repo"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "url" }, "url": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" } },
+          "required": ["source", "url"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "git-subdir" },
+            "url": { "type": "string" },
+            "path": { "type": "string" },
+            "ref": { "type": "string" },
+            "sha": { "type": "string", "pattern": "^[a-f0-9]{40}$" }
+          },
+          "required": ["source", "url", "path"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "npm" }, "package": { "type": "string" }, "version": { "type": "string" }, "registry": { "type": "string" } },
+          "required": ["source", "package"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "archive" }, "url": { "type": "string" }, "sha256": { "type": "string" } },
+          "required": ["source", "url"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "command" }, "command": { "type": "string" }, "timeout": { "type": "number" }, "mode": { "enum": ["copy", "link"] } },
+          "required": ["source", "command"],
+          "additionalProperties": true
+        }
+      ]
+    }
+  }
+}

package/schemas/claude-code/plugin.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/claude-code/plugin.schema.json",
+  "title": "Claude Code Plugin Manifest",
+  "description": "Plugin manifest accepted by Claude Code at .claude-plugin/plugin.json. The manifest is optional: when omitted the client discovers components from default locations and derives the name from the directory. Authored from the official plugin reference; Anthropic publishes no JSON Schema (the $schema URL the official marketplace itself uses returns 404).",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Source: https://code.claude.com/docs/en/plugins-reference. Unrecognized top-level fields are ignored with a warning (--strict turns them into errors), so this schema is open. Paths are relative to the plugin root and must begin with ./ (skills also accepts \".\"). Claude Code is not listed among agent-plugins.org compatible clients.",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string", "description": "Editor autocomplete only; ignored at load. The docs cite https://json.schemastore.org/claude-code-plugin-manifest.json." },
+    "name": {
+      "type": "string",
+      "description": "Kebab-case unique identifier; namespaces the plugin's components as <plugin>:<component>."
+    },
+    "displayName": { "type": "string", "description": "Human-readable UI name; falls back to name and is never used for lookup." },
+    "version": { "type": "string", "description": "Semantic version. When both the manifest and a marketplace entry declare a version, the manifest wins without warning." },
+    "description": { "type": "string" },
+    "author": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "email": { "type": "string" },
+        "url": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": { "type": "array", "items": { "type": "string" }, "description": "A wrong type is a load error." },
+    "metadata": { "type": "object", "description": "Free-form; Claude Code does not read it." },
+    "defaultEnabled": { "type": "boolean", "default": true, "description": "Ship the plugin disabled. A marketplace entry value takes precedence." },
+    "skills": { "$ref": "#/$defs/pathList", "description": "Adds to the default skills/ scan." },
+    "commands": { "$ref": "#/$defs/pathList", "description": "Replaces the default commands/ directory." },
+    "agents": { "$ref": "#/$defs/pathList", "description": "Replaces the default agents/ directory." },
+    "workflows": { "$ref": "#/$defs/pathList", "description": "Replaces the default workflows/ directory." },
+    "outputStyles": { "$ref": "#/$defs/pathList", "description": "Replaces the default output-styles/ directory." },
+    "hooks": { "$ref": "#/$defs/configOrPath", "description": "Path(s) to a hooks configuration file or inline config. Default hooks/hooks.json." },
+    "mcpServers": { "$ref": "#/$defs/configOrPath", "description": "Path(s) to an MCP configuration file or inline config. Default .mcp.json; inline servers are additive." },
+    "lspServers": { "$ref": "#/$defs/configOrPath", "description": "Path(s) to an LSP configuration file or inline config. Default .lsp.json." },
+    "experimental": {
+      "type": "object",
+      "description": "Newer home for themes and monitors; the top-level spellings still work but warn.",
+      "properties": {
+        "themes": { "$ref": "#/$defs/pathList" },
+        "monitors": { "$ref": "#/$defs/pathList" }
+      },
+      "additionalProperties": true
+    },
+    "themes": { "$ref": "#/$defs/pathList", "description": "Deprecated top-level spelling of experimental.themes." },
+    "monitors": { "$ref": "#/$defs/pathList", "description": "Deprecated top-level spelling of experimental.monitors." },
+    "userConfig": {
+      "type": "object",
+      "description": "Options prompted when the plugin is enabled. Referenced as ${user_config.<key>}; exported as CLAUDE_PLUGIN_OPTION_<KEY>. Shell-form hooks, monitor commands, and MCP headersHelper reject the substitution.",
+      "additionalProperties": { "$ref": "#/$defs/userConfigOption" }
+    },
+    "channels": { "type": "array", "description": "Message-channel declarations; each entry's server must match a key in mcpServers." },
+    "dependencies": {
+      "type": "array",
+      "description": "Plugins this one depends on.",
+      "items": {
+        "anyOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "properties": { "name": { "type": "string" }, "version": { "type": "string" } },
+            "required": ["name"],
+            "additionalProperties": true
+          }
+        ]
+      }
+    },
+    "settings": { "type": "object", "description": "Default settings. The settings.json file takes priority over this field." }
+  },
+  "required": ["name"],
+  "additionalProperties": true,
+  "$defs": {
+    "pathList": {
+      "description": "A plugin-relative path or an array of them; each must begin with ./.",
+      "anyOf": [
+        { "type": "string", "pattern": "^\\." },
+        { "type": "array", "items": { "type": "string", "pattern": "^\\." } }
+      ]
+    },
+    "configOrPath": {
+      "description": "A plugin-relative path, an array of paths, or inline configuration.",
+      "anyOf": [{ "type": "string", "pattern": "^\\." }, { "type": "array" }, { "type": "object" }]
+    },
+    "userConfigOption": {
+      "type": "object",
+      "properties": {
+        "type": { "enum": ["string", "number", "boolean", "directory", "file"] },
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "sensitive": { "type": "boolean" },
+        "required": { "type": "boolean" },
+        "default": {},
+        "multiple": { "type": "boolean", "description": "String type only." },
+        "min": { "type": "number", "description": "Number type only." },
+        "max": { "type": "number", "description": "Number type only." }
+      },
+      "required": ["type", "title", "description"],
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/claude-code/spec.md

@@ -0,0 +1,108 @@
+# Claude Code plugin and marketplace specification
+
+Reference contract for Claude Code plugin repositories. Machine-readable companions: [plugin.schema.json](plugin.schema.json) and [marketplace.schema.json](marketplace.schema.json).
+
+- **Verified:** 2026-09-08.
+- **Evidence:** official reference pages [`plugins-reference`](https://code.claude.com/docs/en/plugins-reference) and [`plugin-marketplaces`](https://code.claude.com/docs/en/plugin-marketplaces); the official catalog [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official) (291 entries).
+- **Upstream JSON Schema:** none. The `$schema` URL the official catalog itself declares, `https://anthropic.com/claude-code/marketplace.schema.json`, returns 404. The SchemaStore schemas are community-maintained and stale (generated 2026-04-23, missing `displayName`, `metadata`, `defaultEnabled`, `experimental`, `workflows`, and `renames`).
+- **Spec status:** Claude Code is not listed among agent-plugins.org compatible clients.
+
+## Manifest locations and precedence
+
+| Artifact | Location |
+| --- | --- |
+| Plugin manifest | `.claude-plugin/plugin.json`; optional — without it components are auto-discovered and the name comes from the directory |
+| Marketplace manifest | `.claude-plugin/marketplace.json`, or any `marketplace.json` added by direct path or URL |
+| Skills | `skills/` (manifest `skills` **adds** to this scan) |
+| Commands / agents / workflows / output styles / themes / monitors | `commands/`, `agents/`, `workflows/`, `output-styles/`, `themes/`, `monitors/monitors.json` (manifest fields **replace** these) |
+| Hooks | `hooks/hooks.json` or inline |
+| MCP | `.mcp.json` or inline `mcpServers` (additive) |
+| LSP | `.lsp.json` or inline `lspServers` |
+| Executables / settings | `bin/`, `settings.json` (only `agent` and `subagentStatusLine` keys) |
+
+Only `plugin.json` may live inside `.claude-plugin/`; every component directory belongs at the plugin root. A root `SKILL.md` with no `skills/` directory and no `skills` field loads as a single-skill plugin. A root `CLAUDE.md` is not loaded as context.
+
+## Plugin manifest (`plugin.json`)
+
+Required: `name`. All paths are relative to the plugin root and must begin with `./` (`skills` also accepts `"."`); traversal outside the plugin is rejected.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string | Kebab-case id; namespaces components as `<plugin>:<component>`. |
+| `displayName` | string | UI label; falls back to `name`. |
+| `version` | string | Pins updates. The manifest value wins over a marketplace entry without warning. |
+| `description`, `homepage`, `repository`, `license` | string |  |
+| `author` | `{name, email, url}` |  |
+| `keywords` | string[] | A wrong type is a load error. |
+| `metadata` | object | Free-form; not read by the client. |
+| `defaultEnabled` | boolean | Default `true`; a marketplace entry value takes precedence. |
+| `$schema` | string | Editor autocomplete only. |
+| `skills`, `commands`, `agents`, `workflows`, `outputStyles` | string \| string[] | See precedence above. |
+| `hooks`, `mcpServers`, `lspServers` | string \| string[] \| object | Path(s) or inline configuration. |
+| `experimental` | `{themes?, monitors?}` | The top-level `themes`/`monitors` spellings still work but warn. |
+| `userConfig` | object | Options prompted at enable time; each requires `type`, `title`, `description`, plus optional `sensitive`, `required`, `default`, `multiple` (string), `min`/`max` (number). |
+| `channels` | array | Message-channel declarations; each `server` must match a key in `mcpServers`. |
+| `dependencies` | (string \| `{name, version?}`)[] |  |
+| `settings` | object | `settings.json` takes priority over this field. |
+
+Unrecognized top-level fields are ignored with a warning (`--strict` makes them errors), deliberately so a manifest can double as a VS Code or Cursor extension manifest, a `package.json`, or an MCPB/DXT bundle manifest.
+
+## Marketplace manifest (`marketplace.json`)
+
+Required: `name`, `owner`, `plugins`.
+
+| Field                                 | Type                   | Notes                                                                 |
+| ------------------------------------- | ---------------------- | --------------------------------------------------------------------- |
+| `name`                                | string                 | Kebab-case; one registration per name per user; reserved names apply. |
+| `owner`                               | `{name, email?, url?}` |                                                                       |
+| `plugins`                             | array                  |                                                                       |
+| `description`, `version`              | string                 | Also accepted under `metadata` for backward compatibility.            |
+| `metadata.pluginRoot`                 | string                 | Directory for bare `source` names; ignored for `./` sources.          |
+| `allowCrossMarketplaceDependenciesOn` | string[]               | Only the root marketplace's allowlist applies; no transitive trust.   |
+| `renames`                             | `{old: new \| null}`   | Chains are followed; cycles are rejected by `claude plugin validate`. |
+| `forceRemoveDeletedPlugins`           | boolean                | Community-schema field with no current official documentation.        |
+
+Plugin entries require `name` and `source`; optional fields include `displayName`, `description`, `version`, `author`, `homepage`, `repository`, `license`, `keywords`, `metadata`, `category`, `tags`, `strict` (default `true`), `relevance`, `defaultEnabled`, `headers`, `headersHelper`, `skills`, `commands`, `agents`, `hooks`, `mcpServers`, and `lspServers`. With `strict: true` the plugin manifest is authoritative and the entry supplements it; with `strict: false` the entry is the whole definition, and a conflicting component-declaring manifest fails to load.
+
+## Plugin sources
+
+| Variant       | Shape                                    | Notes                                                                                                            |
+| ------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| relative path | string                                   | `./…`, or a bare name under `metadata.pluginRoot`; resolved against the marketplace root, not `.claude-plugin/`. |
+| `github`      | `{source, repo, ref?, sha?}`             | `owner/repo`.                                                                                                    |
+| `url`         | `{source, url, ref?, sha?}`              | Any git URL, including SSH.                                                                                      |
+| `git-subdir`  | `{source, url, path, ref?, sha?}`        | Sparse partial clone.                                                                                            |
+| `npm`         | `{source, package, version?, registry?}` |                                                                                                                  |
+| `archive`     | `{source, url, sha256?}`                 | HTTPS zip, at most 256 MiB.                                                                                      |
+| `command`     | `{source, command, timeout?, mode?}`     | Prints one absolute path; `mode` is `copy` (default) or `link`.                                                  |
+
+When both `ref` and `sha` are set, `sha` is the effective pin. In the official catalog the observed distribution is `url` 153, `git-subdir` 85, relative path 53.
+
+## Version and enablement resolution
+
+1. Version: `plugin.json` → marketplace entry → git commit SHA → archive `sha256` prefix → `unknown`.
+2. `defaultEnabled`: marketplace entry > manifest; a user's `enabledPlugins` setting beats both.
+3. `--plugin-dir` local plugins take precedence over a marketplace install for that session.
+
+## Directory layout
+
+```text
+enterprise-plugin/
+├── .claude-plugin/plugin.json   # optional manifest
+├── skills/  commands/  agents/  workflows/  output-styles/
+├── themes/  monitors/monitors.json
+├── hooks/hooks.json
+├── bin/                         # executables added to PATH
+├── settings.json
+├── .mcp.json
+└── .lsp.json
+```
+
+Placeholders: `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` (`~/.claude/plugins/data/{id}/`), `${CLAUDE_PROJECT_DIR}`, `${user_config.KEY}` (rejected in shell-form hooks, monitor commands, and MCP `headersHelper`).
+
+## Evidence gaps
+
+1. Hook, MCP, and LSP merge semantics are described only as "own merge rules"; only MCP's additivity with `.mcp.json` is documented.
+2. `.lsp.json` versus inline `lspServers` precedence is unstated.
+3. Whether a root `marketplace.json` can coexist with `.claude-plugin/marketplace.json`, and which wins, is undocumented.
+4. `forceRemoveDeletedPlugins` has no current official documentation.

package/schemas/codex/marketplace.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sivan757.github.io/dsh-agent-plugins-market/schemas/codex/marketplace.schema.json",
+  "title": "Codex Marketplace Manifest",
+  "description": "Marketplace catalog read by Codex at .agents/plugins/marketplace.json, .agents/plugins/api_marketplace.json, .claude-plugin/marketplace.json, or .cursor-plugin/marketplace.json (first match wins). Authored from the OpenAI Codex source; OpenAI publishes no JSON Schema for this manifest.",
+  "$comment": "Provenance: authored (not upstream-vendored) 2026-09-08. Sources: openai/codex codex-rs/core-plugins/src/marketplace.rs (MARKETPLACE_MANIFEST_RELATIVE_PATHS, raw structs), marketplace_tests.rs fixtures, installed_marketplaces.rs, marketplace_add/source.rs, and the bundled plugin-creator skill. There is no github source variant: the tagged enum has only Local, Url, GitSubdir, and Npm. Entry order is render order.",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$", "description": "Marketplace identifier." },
+    "interface": {
+      "type": "object",
+      "properties": { "displayName": { "type": "string" } },
+      "additionalProperties": true
+    },
+    "plugins": { "type": "array", "items": { "$ref": "#/$defs/entry" }, "description": "Ordered plugin entries; the order is the render order." }
+  },
+  "required": ["name", "plugins"],
+  "additionalProperties": true,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "description": "Any plugin-manifest field may be inlined here as a flattened fallback used when the plugin source cannot be read.",
+      "properties": {
+        "name": { "type": "string", "description": "Must match the folder name and the plugin.json name." },
+        "source": { "$ref": "#/$defs/source" },
+        "category": { "type": "string" },
+        "policy": { "$ref": "#/$defs/policy" }
+      },
+      "required": ["name", "source"],
+      "additionalProperties": true
+    },
+    "policy": {
+      "type": "object",
+      "properties": {
+        "installation": { "enum": ["NOT_AVAILABLE", "AVAILABLE", "INSTALLED_BY_DEFAULT"], "default": "AVAILABLE" },
+        "authentication": { "enum": ["ON_INSTALL", "ON_USE"], "default": "ON_INSTALL" },
+        "products": { "type": "array", "items": { "type": "string" }, "description": "Product gating override; an empty array denies every product." }
+      },
+      "additionalProperties": true
+    },
+    "source": {
+      "description": "Where to fetch the plugin. A bare string is treated as a local relative path. The github variant is not supported.",
+      "anyOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "local" }, "path": { "type": "string" } },
+          "required": ["source", "path"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "url" }, "url": { "type": "string" }, "path": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" } },
+          "required": ["source", "url"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": {
+            "source": { "const": "git-subdir" },
+            "url": { "type": "string" },
+            "path": { "type": "string" },
+            "ref": { "type": "string" },
+            "sha": { "type": "string" }
+          },
+          "required": ["source", "url", "path"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "source": { "const": "npm" }, "package": { "type": "string" }, "version": { "type": "string" }, "registry": { "type": "string" } },
+          "required": ["source", "package"],
+          "additionalProperties": true
+        }
+      ]
+    }
+  }
+}