feat(plugins): make CCAM installable straight from a Claude Code plugin

Adds a root `ccam` plugin (`.claude-plugin/plugin.json`, `"source": "./"`) so
`/plugin marketplace add` + `/plugin install ccam@...` is enough on a machine
with nothing but Claude Code: no clone, no npm run setup, no manual npm start.

- scripts/plugin-bootstrap.js: SessionStart hook. Fast-path exit, Node >=22.5
  gate (node:sqlite), mkdir lock with stale reclaim, deps installed into
  ~/.claude/agent-dashboard/runtime/ (never the plugin cache), legacy
  checkout-hook cleanup (backed up), ~/.local/bin/ccam launcher, eager UI
  build so client routes like /run work immediately, detached server spawn.
- scripts/plugin-open.js, scripts/plugin-doctor.js: /ccam-open, /ccam-doctor.
- server/index.js: DASHBOARD_CLIENT_DIST override (plugin cache is read-only).
- mcp/build/ is committed (plugin MCP servers start before any bootstrap could
  build them) and kept honest by scripts/check-mcp-build.js (content hash,
  not mtime), enforced by pre-commit when mcp/src changes.
- plugins/ccam-dashboard/.mcp.json moved under plugins/ccam/ with a working
  ${CLAUDE_PLUGIN_ROOT} path (the old relative path never resolved from a
  marketplace-cached subdir).
- Docs: README, INSTALL, SETUP, ARCHITECTURE, CLAUDE.md, docs/PLUGINS.md,
  docs/MCP.md, docs/CLI.md, docs/HOOKS.md.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

server/__tests__/plugins-marketplace.test.js

@@ -40,10 +40,18 @@ function listMd(dir) {
   }
 }
 
+// The marketplace mixes two shapes: the root-source `ccam` plugin (the whole
+// repo — hooks, server, CLI, MCP) and ten subdirectory plugins. The root
+// plugin's commands live in plugins/ccam/, which is therefore NOT a plugin dir.
+const ROOT_PLUGIN = "ccam";
+
 describe("plugin marketplace", () => {
   const marketplace = readJson(MARKETPLACE);
-  const pluginDirs = listDirs(PLUGINS_DIR).sort();
-  const entryNames = marketplace.plugins.map((p) => p.name).sort();
+  const pluginDirs = listDirs(PLUGINS_DIR)
+    .filter((d) => d !== ROOT_PLUGIN)
+    .sort();
+  const subdirEntries = marketplace.plugins.filter((p) => p.name !== ROOT_PLUGIN);
+  const entryNames = subdirEntries.map((p) => p.name).sort();
 
   it("marketplace.json has the required top-level shape", () => {
     assert.equal(typeof marketplace.name, "string");
@@ -69,7 +77,7 @@ describe("plugin marketplace", () => {
     );
   });
 
-  for (const entry of marketplace.plugins) {
+  for (const entry of subdirEntries) {
     describe(`entry: ${entry.name}`, () => {
       it("has name, path, description, tags", () => {
         assert.equal(typeof entry.name, "string");
@@ -154,7 +162,7 @@ describe("plugin marketplace", () => {
         );
       });
 
-      it("contributes at least one skill or agent", () => {
+      it("contributes at least one skill or agent (subdir plugins only)", () => {
         const skills = (() => {
           try {
             return listDirs(path.join(root, "skills")).length;
@@ -167,4 +175,73 @@ describe("plugin marketplace", () => {
       });
     });
   }
+
+  describe(`root plugin: ${ROOT_PLUGIN}`, () => {
+    const entry = marketplace.plugins.find((p) => p.name === ROOT_PLUGIN);
+    const manifest = readJson(path.join(REPO_ROOT, ".claude-plugin", "plugin.json"));
+
+    it("is declared with the repo root as its source", () => {
+      assert.ok(entry, "the root ccam entry is missing from marketplace.json");
+      assert.equal(entry.source, "./");
+      assert.equal(entry.path, undefined, "a root-source entry must not also carry a path");
+      assert.ok(Array.isArray(entry.tags) && entry.tags.length > 0);
+    });
+
+    it("has a manifest whose name matches the entry", () => {
+      assert.equal(manifest.name, ROOT_PLUGIN);
+      assert.ok(manifest.description.length > 20);
+      assert.ok(manifest.author && manifest.author.name);
+      assert.equal(typeof manifest.license, "string");
+    });
+
+    it("wires every hook type through the plugin's own handler path", () => {
+      const withMatcher = ["PreToolUse", "PostToolUse", "Stop", "SubagentStop", "Notification"];
+      const withoutMatcher = ["SessionStart", "SessionEnd", "UserPromptSubmit"];
+      for (const type of [...withMatcher, ...withoutMatcher]) {
+        const entries = manifest.hooks[type];
+        assert.ok(Array.isArray(entries) && entries.length, `hook ${type} is not declared`);
+        const json = JSON.stringify(entries);
+        assert.match(json, /hook-handler\.js/, `hook ${type} does not call the handler`);
+        assert.match(
+          json,
+          /\$\{CLAUDE_PLUGIN_ROOT\}/,
+          `hook ${type} must resolve through CLAUDE_PLUGIN_ROOT, not a checkout path`
+        );
+        if (withMatcher.includes(type)) {
+          assert.equal(entries[0].matcher, "*", `hook ${type} needs a matcher`);
+        } else {
+          assert.equal(entries[0].matcher, undefined, `hook ${type} takes no matcher`);
+        }
+      }
+    });
+
+    it("runs the bootstrap on SessionStart", () => {
+      assert.match(JSON.stringify(manifest.hooks.SessionStart), /plugin-bootstrap\.js/);
+    });
+
+    it("points at command files that exist and carry a description", () => {
+      assert.ok(manifest.commands.length >= 3);
+      for (const rel of manifest.commands) {
+        const file = path.join(REPO_ROOT, rel);
+        assert.ok(fs.existsSync(file), `${rel} does not exist`);
+        const { frontmatter } = parseFrontmatter(fs.readFileSync(file, "utf8"));
+        assert.ok(frontmatter && frontmatter.description, `${rel} has no description`);
+      }
+    });
+
+    it("declares an MCP config that exists and resolves through CLAUDE_PLUGIN_ROOT", () => {
+      const mcpFile = path.join(REPO_ROOT, manifest.mcpServers);
+      assert.ok(fs.existsSync(mcpFile), `${manifest.mcpServers} does not exist`);
+      const mcp = readJson(mcpFile);
+      const args = JSON.stringify(mcp.mcpServers);
+      assert.match(args, /\$\{CLAUDE_PLUGIN_ROOT\}\/mcp\/build\/index\.js/);
+    });
+
+    it("ships the built MCP server the config points at", () => {
+      assert.ok(
+        fs.existsSync(path.join(REPO_ROOT, "mcp", "build", "index.js")),
+        "mcp/build/index.js must be committed — plugin MCP servers start before any bootstrap can build them"
+      );
+    });
+  });
 });