diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index f81f4ffcc..fe2f48add 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,8 +1,9 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "melodic-software",
   "owner": {
     "name": "Melodic Software",
-    "url": "https://github.com/melodic-software"
+    "email": "info@melodicsoftware.com"
   },
   "description": "Reusable, repo-agnostic Claude Code plugins — skills, hooks, and agents.",
   "metadata": {
diff --git a/CLAUDE.md b/CLAUDE.md
index 03bad0229..f9f2ae10d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,15 +14,25 @@ from a fetched page this session, treat it as unverified and say so.
 |---|---|
 | Create plugins | https://code.claude.com/docs/en/plugins |
 | Plugins reference (schemas, variables, CLI) | https://code.claude.com/docs/en/plugins-reference |
+| Plugin dependencies (version constraints) | https://code.claude.com/docs/en/plugin-dependencies |
 | Create & distribute a marketplace | https://code.claude.com/docs/en/plugin-marketplaces |
 | Discover & install plugins | https://code.claude.com/docs/en/discover-plugins |
 | Skills | https://code.claude.com/docs/en/skills |
+| Slash commands | https://code.claude.com/docs/en/commands |
 | Hooks reference | https://code.claude.com/docs/en/hooks |
 | Subagents | https://code.claude.com/docs/en/sub-agents |
 | Settings | https://code.claude.com/docs/en/settings |
+| Memory — CLAUDE.md, `.claude/rules/`, auto memory | https://code.claude.com/docs/en/memory |
+| The `.claude` directory | https://code.claude.com/docs/en/claude-directory |
 | MCP | https://code.claude.com/docs/en/mcp |
+| Tools reference (monitors) | https://code.claude.com/docs/en/tools-reference |
 | Docs index (discover any other page) | https://code.claude.com/docs/llms.txt |
 
+Machine-readable JSON Schemas (editor validation for the JSON in this repo; Claude Code ignores the
+`$schema` field at load time): `marketplace.json` →
+`https://json.schemastore.org/claude-code-marketplace.json`, `plugin.json` →
+`https://json.schemastore.org/claude-code-plugin-manifest.json` (published on SchemaStore).
+
 ## Design rules for plugins added here
 
 - **Repo-agnostic.** No hardcoded paths, repo names, or project-specific values. Read the consumer's
diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md
index 0a43fed45..17cd6f317 100644
--- a/docs/MIGRATION-PLAYBOOK.md
+++ b/docs/MIGRATION-PLAYBOOK.md
@@ -36,7 +36,7 @@ Prefer them in this order; the earlier ones are simplest and least surprising.
 |---|---|---|
 | Consumer `CLAUDE.md` / `.claude/rules` | The skill reads the consuming project's own context and rules | Project-specific conventions, naming, policies — the default extension surface |
 | `${CLAUDE_PROJECT_DIR}` | Path to the consumer's project root, substituted in hook/MCP/monitor commands and exported to subprocesses | Referencing project-local scripts/config |
-| `userConfig` → `${user_config.KEY}` | Values Claude Code prompts for at enable time (typed: string/number/boolean, optional sensitive). Also exported as `CLAUDE_PLUGIN_OPTION_<KEY>`. Non-sensitive stored in `settings.json` `pluginConfigs`; sensitive in keychain | Endpoints, toggles, tokens — consumer config without editing the plugin |
+| `userConfig` → `${user_config.KEY}` | Values Claude Code prompts for at enable time (typed: string/number/boolean/directory/file, optional sensitive). Also exported as `CLAUDE_PLUGIN_OPTION_<KEY>`. Non-sensitive stored in `settings.json` under `pluginConfigs[<id>].options`; sensitive in the system keychain | Endpoints, toggles, tokens — consumer config without editing the plugin |
 | `${CLAUDE_PLUGIN_ROOT}` | Path to the plugin's own installed directory | Referencing bundled scripts/assets (mandatory under cache isolation) |
 | `${CLAUDE_PLUGIN_DATA}` | Persistent per-plugin directory that survives updates (`~/.claude/plugins/data/<id>/`) | Installed deps, caches, generated state |
 | `hooks/hooks.json` | Event handlers the plugin ships | Behavior consumers opt into by enabling the plugin |
@@ -51,8 +51,9 @@ Catalog these per migration; they are the usual failures when an in-repo skill b
 - **Cache isolation.** Installed plugins are copied to `~/.claude/plugins/cache`. Any reference to files
   outside the plugin directory (`../../tools/...`, `.claude/rules/...`) breaks. Fix: bundle dependencies
   inside the plugin and reference them via `${CLAUDE_PLUGIN_ROOT}`; persist state via `${CLAUDE_PLUGIN_DATA}`.
-- **Namespacing.** An in-repo `/foo` becomes `/melodic-software:foo` (plugin-namespaced). Internal
-  cross-references to the bare name break — update them.
+- **Namespacing.** Components are namespaced by the plugin's own `name`, not the marketplace name —
+  an in-repo `/foo` becomes `/<plugin-name>:foo`. Internal cross-references to the bare name break —
+  update them.
 - **Agent shadowing.** Project/user `.claude/agents/` override same-named plugin agents. A leftover
   in-repo copy masks the plugin version until removed from the source repo.
 - **Headless registration.** `extraKnownMarketplaces` auto-registration requires the interactive trust