@rubytech/create-realagent-code 0.1.16 → 0.1.17

package/dist/__tests__/plugin-install.test.js

@@ -0,0 +1,105 @@
+// Unit tests for the installer's plugin-install pure functions.
+// Tests are ephemeral per the sprint workflow — they prove behaviour
+// during the sprint; the installer's runtime exercise on a real Pi is the
+// permanent verification artifact.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parsePluginList, computeInstallActions, computeConfigureActions, parseExternalPlugins, } from "../lib/plugin-install.js";
+test("parsePluginList extracts name@marketplace tuples", () => {
+    const stdout = `
+  ❯ tasks@maxy-platform
+    Version: 0.1.0
+    Scope: local
+
+  ❯ telegram@claude-plugins-official
+    Version: 1.2.3
+`;
+    const out = parsePluginList(stdout);
+    assert.deepEqual(out, [
+        { name: "tasks", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ]);
+});
+test("parsePluginList returns empty array for empty stdout", () => {
+    assert.deepEqual(parsePluginList(""), []);
+    assert.deepEqual(parsePluginList("No plugins installed.\n"), []);
+});
+test("computeInstallActions: every desired plugin needs installing when none present", () => {
+    const desired = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ];
+    const { toInstall, alreadyInstalled } = computeInstallActions(desired, []);
+    assert.equal(toInstall.length, 2);
+    assert.equal(alreadyInstalled.length, 0);
+});
+test("computeInstallActions: idempotent skip for exact name@marketplace match", () => {
+    const desired = [
+        { name: "admin", marketplace: "maxy-platform" },
+        { name: "telegram", marketplace: "claude-plugins-official" },
+    ];
+    const installed = [
+        { name: "admin", marketplace: "maxy-platform" },
+    ];
+    const { toInstall, alreadyInstalled } = computeInstallActions(desired, installed);
+    assert.deepEqual(toInstall.map(p => p.name), ["telegram"]);
+    assert.deepEqual(alreadyInstalled.map(p => p.name), ["admin"]);
+});
+test("computeInstallActions: name-only match skips install (legacy install state)", () => {
+    const desired = [{ name: "admin", marketplace: "maxy-platform" }];
+    const installed = [{ name: "admin", marketplace: "" }];
+    const { toInstall, alreadyInstalled } = computeInstallActions(desired, installed);
+    assert.equal(toInstall.length, 0);
+    assert.equal(alreadyInstalled.length, 1);
+});
+test("computeConfigureActions: skip when no configureSecret declared", () => {
+    const installed = [{ name: "admin", marketplace: "maxy-platform" }];
+    const actions = computeConfigureActions(installed, {});
+    assert.equal(actions.length, 1);
+    assert.equal(actions[0].kind, "skip-no-secret-name");
+});
+test("computeConfigureActions: skip when env var absent", () => {
+    const installed = [{
+            name: "telegram",
+            marketplace: "claude-plugins-official",
+            configureSecret: "TELEGRAM_BOT_TOKEN",
+        }];
+    const actions = computeConfigureActions(installed, {});
+    assert.equal(actions.length, 1);
+    assert.equal(actions[0].kind, "skip-no-secret-value");
+});
+test("computeConfigureActions: configure when env var present", () => {
+    const installed = [{
+            name: "telegram",
+            marketplace: "claude-plugins-official",
+            configureSecret: "TELEGRAM_BOT_TOKEN",
+        }];
+    const actions = computeConfigureActions(installed, { TELEGRAM_BOT_TOKEN: "abc123" });
+    assert.equal(actions.length, 1);
+    assert.equal(actions[0].kind, "configure");
+    if (actions[0].kind === "configure") {
+        assert.equal(actions[0].secretValue, "abc123");
+        assert.equal(actions[0].plugin.name, "telegram");
+    }
+});
+test("parseExternalPlugins: undefined returns []", () => {
+    assert.deepEqual(parseExternalPlugins(undefined), []);
+    assert.deepEqual(parseExternalPlugins(null), []);
+});
+test("parseExternalPlugins: well-formed array round-trips", () => {
+    const raw = [
+        { name: "telegram", marketplace: "claude-plugins-official", configureSecret: "TELEGRAM_BOT_TOKEN", channelPlugin: true },
+        { name: "discord", marketplace: "claude-plugins-official" },
+    ];
+    const out = parseExternalPlugins(raw);
+    assert.deepEqual(out, [
+        { name: "telegram", marketplace: "claude-plugins-official", configureSecret: "TELEGRAM_BOT_TOKEN", channelPlugin: true },
+        { name: "discord", marketplace: "claude-plugins-official" },
+    ]);
+});
+test("parseExternalPlugins: missing marketplace throws", () => {
+    assert.throws(() => parseExternalPlugins([{ name: "telegram" }]));
+});
+test("parseExternalPlugins: missing name throws", () => {
+    assert.throws(() => parseExternalPlugins([{ marketplace: "x" }]));
+});

package/dist/index.js

@@ -12,6 +12,7 @@ import { installAllBrewPackages } from "./brew-install.js";
 import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
 import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
 import { classifyPortHolder } from "./preflight-port-classifier.js";
+import { parsePluginList, computeInstallActions, computeConfigureActions, parseExternalPlugins, } from "./lib/plugin-install.js";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -1875,6 +1876,137 @@ function deployPayload() {
     writeFileSync(join(configDir, `.${BRAND.hostname}-version`), PKG_VERSION, "utf-8");
     console.log(`  Deployed to ${INSTALL_DIR}`);
 }
+// Task 030 — register the local + external Claude Code plugins after the
+// payload is on disk. The bundler stamps `.claude-plugin/marketplace.json`
+// at each plugin-tree root (platform/plugins/, premium-plugins/real-agency/
+// plugins/, premium-plugins/) so this function discovers them generically
+// from the install directory rather than hardcoding names.
+//
+// Idempotent on every step: marketplace add is skipped when already in
+// `marketplace list`; `plugin install` is skipped when the plugin is
+// already in `plugin list` (matched by `<name>@<marketplace>` or by name
+// alone for legacy install state). One `[plugin-install] <name>@<src>
+// idempotent=<bool>` log line per attempt; failures log
+// `[plugin-install] ERROR <name>@<src> exit=<n> stderr=<short>` and do
+// NOT abort — one plugin failing must not block the rest, mirroring the
+// marketplace-add behaviour at src/index.ts:1018-1019.
+function registerLocalAndExternalPlugins() {
+    console.log("  Registering local + external Claude Code plugins...");
+    const localTrees = [];
+    // The three known marketplace.json locations the bundler emits. Missing
+    // ones are silently skipped (e.g. a brand that ships no premium plugins).
+    const candidates = [
+        join(INSTALL_DIR, "platform", "plugins"),
+        join(INSTALL_DIR, "premium-plugins", "real-agency", "plugins"),
+        join(INSTALL_DIR, "premium-plugins"),
+    ];
+    for (const dir of candidates) {
+        const mkPath = join(dir, ".claude-plugin", "marketplace.json");
+        if (!existsSync(mkPath))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(mkPath, "utf-8"));
+            if (typeof parsed.name === "string" && parsed.name.length > 0) {
+                localTrees.push({ name: parsed.name, dir });
+            }
+            else {
+                logFile(`[plugin-marketplace] ERROR malformed marketplace at ${mkPath} reason=no-name`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logFile(`[plugin-marketplace] ERROR parse ${mkPath} error=${JSON.stringify(msg.slice(0, 200))}`);
+        }
+    }
+    // Add each local marketplace. Idempotence via `marketplace list` grep.
+    const mkList = spawnSync("claude", ["plugin", "marketplace", "list"], { stdio: "pipe", encoding: "utf-8" });
+    const mkListed = mkList.stdout ?? "";
+    for (const { name, dir } of localTrees) {
+        if (mkListed.includes(name)) {
+            logFile(`[plugin-marketplace] added ${name} idempotent=true`);
+            continue;
+        }
+        const add = spawnSync("claude", ["plugin", "marketplace", "add", dir], { stdio: "pipe", encoding: "utf-8", timeout: 60_000 });
+        if (add.status === 0) {
+            logFile(`[plugin-marketplace] added ${name} source=${dir} idempotent=false`);
+        }
+        else {
+            const stderrShort = (add.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-marketplace] ERROR add ${name} source=${dir} exit=${add.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+    // Build the desired plugin list = (every local marketplace's plugins) +
+    // (brand.json#externalPlugins). The local entries' `marketplace` field
+    // matches the marketplace.json `name`; the external entries declare
+    // their own.
+    const desired = [];
+    for (const { name: mkName, dir } of localTrees) {
+        const mkPath = join(dir, ".claude-plugin", "marketplace.json");
+        try {
+            const parsed = JSON.parse(readFileSync(mkPath, "utf-8"));
+            for (const p of parsed.plugins ?? []) {
+                if (typeof p.name === "string" && p.name.length > 0) {
+                    desired.push({ name: p.name, marketplace: mkName });
+                }
+            }
+        }
+        catch {
+            // Already logged above.
+        }
+    }
+    let externals = [];
+    try {
+        externals = parseExternalPlugins(BRAND.externalPlugins);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logFile(`[plugin-install] ERROR brand.externalPlugins parse error=${JSON.stringify(msg.slice(0, 200))}`);
+    }
+    desired.push(...externals);
+    // Snapshot what's installed to compute the install set.
+    const pluginList = spawnSync("claude", ["plugin", "list"], { stdio: "pipe", encoding: "utf-8" });
+    const installed = parsePluginList(pluginList.stdout ?? "");
+    const { toInstall, alreadyInstalled } = computeInstallActions(desired, installed);
+    for (const ref of alreadyInstalled) {
+        logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=true`);
+    }
+    for (const ref of toInstall) {
+        const install = spawnSync("claude", ["plugin", "install", `${ref.name}@${ref.marketplace}`, "--scope", "user"], { stdio: "pipe", encoding: "utf-8", timeout: 120_000 });
+        if (install.status === 0) {
+            logFile(`[plugin-install] ${ref.name}@${ref.marketplace} idempotent=false`);
+        }
+        else {
+            const stderrShort = (install.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-install] ERROR ${ref.name}@${ref.marketplace} exit=${install.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+    // Configure-token pass — only the externals carry configureSecret. For
+    // each, pipe `/<name>:configure <secret>` into a one-shot `claude`
+    // invocation. Missing env vars log SKIP and continue — pairing is a
+    // manual per-operator step per the channels-reference docs.
+    const configureActions = computeConfigureActions(externals, process.env);
+    for (const action of configureActions) {
+        if (action.kind === "skip-no-secret-name") {
+            // Local plugins and externals without configureSecret — nothing to do.
+            continue;
+        }
+        if (action.kind === "skip-no-secret-value") {
+            logFile(`[plugin-configure] SKIP ${action.plugin.name} reason=no-secret-in-env env-var=${action.plugin.configureSecret}`);
+            continue;
+        }
+        // The piped-stdin form: `echo '/<name>:configure <secret>' | claude --print`
+        // is the documented one-shot configure path. We do not log the secret value.
+        const cmd = `/${action.plugin.name}:configure ${action.secretValue}`;
+        const configure = spawnSync("claude", ["--print", "--input-format", "text"], { input: cmd, stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8", timeout: 60_000 });
+        if (configure.status === 0) {
+            logFile(`[plugin-configure] ${action.plugin.name} ok env-var=${action.plugin.configureSecret}`);
+        }
+        else {
+            const stderrShort = (configure.stderr ?? "").split("\n")[0]?.slice(0, 200) ?? "";
+            logFile(`[plugin-configure] ERROR ${action.plugin.name} exit=${configure.status} stderr=${JSON.stringify(stderrShort)}`);
+        }
+    }
+}
 function buildPlatform() {
     log("9", TOTAL, "Installing dependencies and building...");
     console.log(`  Installing platform dependencies (${join(INSTALL_DIR, "platform")})...`);
@@ -3336,6 +3468,7 @@ try {
     ensureNeo4jPassword(); // Now config/.neo4j-password is available if it existed before
     provisionRemoteSessionSecret(); // Task 653: shared HMAC key readable by maxy-edge + maxy-ui
     buildPlatform();
+    registerLocalAndExternalPlugins(); // Task 030: install-time plugin registration
     setupVncViewer();
     setupAccount();
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract

package/dist/lib/plugin-install.js

@@ -0,0 +1,108 @@
+// Pure-function support for the installer's plugin-install loop. The runtime
+// callers in src/index.ts wrap these with the actual `spawnSync` / fs reads;
+// keeping the logic side-effect-free here makes the install / configure
+// branches unit-testable without stubbing every shell invocation.
+/**
+ * `claude plugin list` prints rows like:
+ *   ❯ tasks@maxy-platform
+ *     Version: 0.1.0
+ *     Scope: local
+ *
+ * Parse the `<name>@<marketplace>` line so the installer can skip already-
+ * installed plugins. Plugins whose row lacks the `@` suffix (legacy
+ * installer state) are returned with marketplace='' so a name-only check
+ * still de-dupes.
+ */
+export function parsePluginList(stdout) {
+    const out = [];
+    for (const raw of stdout.split("\n")) {
+        const line = raw.replace(/^\s*❯\s+/, "").trim();
+        if (!line || !/^[a-z0-9][a-z0-9-]*(@[a-zA-Z0-9-]+)?$/.test(line))
+            continue;
+        const atIdx = line.indexOf("@");
+        if (atIdx < 0)
+            out.push({ name: line, marketplace: "" });
+        else
+            out.push({ name: line.slice(0, atIdx), marketplace: line.slice(atIdx + 1) });
+    }
+    return out;
+}
+/**
+ * Given the desired plugins and what's already installed, return the
+ * subset that still needs `claude plugin install <name>@<marketplace>`.
+ * Idempotence rule: a plugin is "already installed" if either its
+ * exact `<name>@<marketplace>` is in the installed set, OR a row exists
+ * with the same name and any marketplace (the spawn would re-attach in
+ * the operator's chosen scope). This mirrors the marketplace-add
+ * idempotence used in src/index.ts:1012.
+ */
+export function computeInstallActions(desired, installed) {
+    const byName = new Map();
+    for (const i of installed) {
+        if (!byName.has(i.name))
+            byName.set(i.name, new Set());
+        byName.get(i.name).add(i.marketplace);
+    }
+    const toInstall = [];
+    const alreadyInstalled = [];
+    for (const d of desired) {
+        const marketplaces = byName.get(d.name);
+        if (marketplaces && (marketplaces.has(d.marketplace) || marketplaces.has(""))) {
+            alreadyInstalled.push(d);
+        }
+        else {
+            toInstall.push(d);
+        }
+    }
+    return { toInstall, alreadyInstalled };
+}
+export function computeConfigureActions(installed, env) {
+    const out = [];
+    for (const p of installed) {
+        if (!p.configureSecret) {
+            out.push({ kind: "skip-no-secret-name", plugin: p });
+            continue;
+        }
+        const value = env[p.configureSecret];
+        if (typeof value !== "string" || value.length === 0) {
+            out.push({ kind: "skip-no-secret-value", plugin: p });
+            continue;
+        }
+        out.push({ kind: "configure", plugin: p, secretValue: value });
+    }
+    return out;
+}
+/** Brand-config validator. brand.json#externalPlugins is optional; when
+ *  present, each entry must declare name + marketplace as non-empty
+ *  strings. Other fields are optional. Returns a normalised array; throws
+ *  on any malformed entry (loud failure at install time beats silent
+ *  drop). */
+export function parseExternalPlugins(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new Error("brand.json#externalPlugins must be an array");
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object") {
+            throw new Error("brand.json#externalPlugins entries must be objects");
+        }
+        const e = entry;
+        if (typeof e.name !== "string" || e.name.length === 0) {
+            throw new Error("brand.json#externalPlugins entry missing 'name'");
+        }
+        if (typeof e.marketplace !== "string" || e.marketplace.length === 0) {
+            throw new Error(`brand.json#externalPlugins[${e.name}] missing 'marketplace'`);
+        }
+        const ref = { name: e.name, marketplace: e.marketplace };
+        if (typeof e.configureSecret === "string" && e.configureSecret.length > 0) {
+            ref.configureSecret = e.configureSecret;
+        }
+        if (e.channelPlugin === true) {
+            ref.channelPlugin = true;
+        }
+        out.push(ref);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/config/brand.json

@@ -51,5 +51,10 @@
     "defaultEnabled": ["sales"],
     "available": ["deep-research", "waitlist", "projects", "whatsapp", "replicate", "linkedin-import"],
     "excluded": ["telegram"]
-  }
+  },
+
+  "externalPlugins": [
+    { "name": "discord",  "marketplace": "claude-plugins-official", "configureSecret": "DISCORD_BOT_TOKEN", "channelPlugin": true },
+    { "name": "imessage", "marketplace": "claude-plugins-official", "channelPlugin": true }
+  ]
 }

package/payload/platform/plugins/.claude-plugin/marketplace.json

@@ -0,0 +1,103 @@
+{
+  "name": "maxy-platform",
+  "owner": {
+    "name": "Rubytech LLC"
+  },
+  "plugins": [
+    {
+      "name": "admin",
+      "source": "./admin",
+      "version": "0.1.0"
+    },
+    {
+      "name": "anthropic",
+      "source": "./anthropic",
+      "version": "0.1.0"
+    },
+    {
+      "name": "business-assistant",
+      "source": "./business-assistant",
+      "version": "0.1.0"
+    },
+    {
+      "name": "cloudflare",
+      "source": "./cloudflare",
+      "version": "0.1.0"
+    },
+    {
+      "name": "contacts",
+      "source": "./contacts",
+      "version": "0.1.0"
+    },
+    {
+      "name": "deep-research",
+      "source": "./deep-research",
+      "version": "0.1.0"
+    },
+    {
+      "name": "docs",
+      "source": "./docs",
+      "version": "0.1.0"
+    },
+    {
+      "name": "email",
+      "source": "./email",
+      "version": "0.1.0"
+    },
+    {
+      "name": "linkedin-import",
+      "source": "./linkedin-import",
+      "version": "0.1.0"
+    },
+    {
+      "name": "memory",
+      "source": "./memory",
+      "version": "0.1.0"
+    },
+    {
+      "name": "outlook",
+      "source": "./outlook",
+      "version": "0.1.0"
+    },
+    {
+      "name": "projects",
+      "source": "./projects",
+      "version": "0.1.0"
+    },
+    {
+      "name": "replicate",
+      "source": "./replicate",
+      "version": "0.1.0"
+    },
+    {
+      "name": "sales",
+      "source": "./sales",
+      "version": "0.1.0"
+    },
+    {
+      "name": "scheduling",
+      "source": "./scheduling",
+      "version": "0.1.0"
+    },
+    {
+      "name": "tasks",
+      "source": "./tasks",
+      "version": "0.1.0"
+    },
+    {
+      "name": "waitlist",
+      "source": "./waitlist",
+      "version": "0.1.0"
+    },
+    {
+      "name": "whatsapp",
+      "source": "./whatsapp",
+      "version": "0.1.0"
+    },
+    {
+      "name": "workflows",
+      "source": "./workflows",
+      "version": "0.1.0"
+    }
+  ]
+}

package/payload/platform/plugins/admin/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "admin",
+  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver — single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), brand-settings, account-manage, account-update, admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name — the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), render-component, session-reset, session-resume, file-attach, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the Maxy platform.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "admin": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ]
+    }
+  }
+}

package/payload/platform/plugins/anthropic/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "anthropic",
+  "description": "Guide users through obtaining an Anthropic API key to power the public agent.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/business-assistant/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "business-assistant",
+  "description": "Business assistant for small businesses. Handles customer enquiries, appointment booking, quote formatting, invoice generation, and daily briefings. Responds instantly, triages by urgency, and never lets a message fall through the cracks.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/cloudflare/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "cloudflare",
+  "description": "Cloudflare Tunnel operations — setup, reset, dashboard guidance. Zero agent-facing MCP tools; every operation is a shell script or a dashboard click-path the operator performs themselves.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "cloudflare": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ]
+    }
+  }
+}

package/payload/platform/plugins/contacts/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "contacts",
+  "description": "CRM contacts plugin. Provides contact-create, contact-lookup, contact-update, contact-delete, contact-list, contact-export, contact-erase, group-create, and group-manage tools for managing the customer contact graph and group conversations.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "contacts": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ]
+    }
+  }
+}

package/payload/platform/plugins/deep-research/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "deep-research",
+  "description": "Structured multi-source research workflow — query decomposition, search strategy, source evaluation, synthesis, and citation formatting. Uses Claude Code's native WebSearch and WebFetch tools.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/docs/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "docs",
+  "description": "Comprehensive user guide and platform documentation for Maxy. Load references when users ask how-to, setup, or troubleshooting questions. Also contains platform architecture references for admin use.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/docs/references/deployment.md

@@ -117,6 +117,56 @@ The post-install acceptance gate at `platform/scripts/test-laptop-vnc-boot.sh` r
 
 A separate operator-side harness at `platform/scripts/installer-device-verify.sh <published-version>` runs after every npm publish to confirm the installer reaches a terminal-success marker on each device in the operator's manifest. Two markers are accepted because the installer's CDP probe behaves differently per `DISPLAY_MODE`: `Browser automation ready (CDP connected)` on Pi (virtual display, persistent Chromium) and `[cdp-check] skipped reason=native-display` on laptop (native display, on-demand Chromium). Either is a pass. The harness is operator-only — end users do not run it.
 
+## Plugin registration at install time
+
+The installer registers Claude Code plugins on the device as the last step before the brand service starts. After registration, `claude plugin list` on the Pi shows every Maxy platform plugin shipped by the brand, every premium sub-plugin shipped by the brand, and any external plugins the brand declares (e.g. Telegram, Discord, iMessage from `claude-plugins-official`). Spawned `claude` sessions inherit those plugins from `~/.claude/` — the session manager passes no `--mcp-config` argv.
+
+**Where the manifests come from.** The Maxy plugin source tree uses `PLUGIN.md` (YAML frontmatter) for plugin metadata, not Claude Code's native `.claude-plugin/plugin.json`. At bundle time, `scripts/generate-plugin-manifests.mjs` walks the payload and synthesises a Claude-Code-native `plugin.json` per plugin plus a `marketplace.json` at each tree root. The generator runs in `packages/create-maxy/scripts/bundle.js` after platform + premium plugins are copied into the payload, so the deployed install directory carries:
+
+- `<INSTALL_DIR>/platform/plugins/<name>/.claude-plugin/plugin.json` per platform plugin
+- `<INSTALL_DIR>/platform/plugins/.claude-plugin/marketplace.json` (marketplace `maxy-platform`)
+- `<INSTALL_DIR>/premium-plugins/real-agency/plugins/<sub>/.claude-plugin/plugin.json` per sub-plugin
+- `<INSTALL_DIR>/premium-plugins/real-agency/plugins/.claude-plugin/marketplace.json` (`maxy-premium-real-agency`)
+- `<INSTALL_DIR>/premium-plugins/{teaching,writer-craft}/.claude-plugin/plugin.json` for bundle-root plugins
+- `<INSTALL_DIR>/premium-plugins/.claude-plugin/marketplace.json` (`maxy-premium`)
+
+Generator schema:
+
+| Field | Source | Notes |
+|---|---|---|
+| `name` | directory name (or `PLUGIN.md#name`) | Used as `<name>` in `plugin install` |
+| `description` | `PLUGIN.md` frontmatter `description` | Falls back to "{name} plugin" if absent |
+| `version` | `"0.1.0"` | Single version across all generated manifests |
+| `author` | `{ "name": "Rubytech LLC" }` | Object form required by Claude Code's validator |
+| `mcpServers["<name>"]` | only when `mcp/dist/index.js` exists | `{ "type": "stdio", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"] }` |
+
+Skills, agents, hooks, and commands directories at the plugin root are auto-discovered by Claude Code — no explicit field needed.
+
+**Install flow** (`registerLocalAndExternalPlugins()` in `packages/create-maxy/src/index.ts`):
+
+1. Discover every `.claude-plugin/marketplace.json` under the install directory.
+2. For each one not already in `claude plugin marketplace list`, run `claude plugin marketplace add <dir>`. Pre-existing entries log `[plugin-marketplace] added <name> idempotent=true`.
+3. Snapshot `claude plugin list` once.
+4. Build the desired plugin set = (every local marketplace's plugin entries) + (`brand.json#externalPlugins`).
+5. For each desired plugin not in the snapshot, run `claude plugin install <name>@<marketplace> --scope user`. Already-installed plugins log `idempotent=true`. Failures log `[plugin-install] ERROR <name>@<src> exit=<n> stderr=<short>` but do not abort the installer — one plugin failing must not block the rest.
+6. For each external plugin with a `configureSecret` field whose env var is set, pipe `/<name>:configure <secret>` into a one-shot `claude --print` invocation. Missing env vars log `[plugin-configure] SKIP <name> reason=no-secret-in-env env-var=<NAME>` and continue — pairing remains a per-operator manual step.
+
+**Brand declaration** — `brands/<brand>/brand.json#externalPlugins`:
+
+```jsonc
+"externalPlugins": [
+  { "name": "telegram", "marketplace": "claude-plugins-official",
+    "configureSecret": "TELEGRAM_BOT_TOKEN", "channelPlugin": true },
+  { "name": "discord",  "marketplace": "claude-plugins-official",
+    "configureSecret": "DISCORD_BOT_TOKEN",  "channelPlugin": true },
+  { "name": "imessage", "marketplace": "claude-plugins-official", "channelPlugin": true }
+]
+```
+
+`channelPlugin: true` signals the session manager to include the entry in the spawn-time `--channels plugin:<name>@<marketplace>` argv. The session manager's `/spawn` and `/resume` HTTP routes accept an optional `channels: string[]` body field that maps directly to those argv flags. When the field is absent or empty, the spawn argv is byte-identical to today's `['--verbose', '--remote-control']` shape.
+
+**Diagnostic path** — `grep "\[plugin-install\]" ~/.<brand>/logs/install-*.log | tail -50`; compare row count against `cat brand.json | jq '.externalPlugins | length'` plus the on-disk plugin count under `<INSTALL_DIR>/platform/plugins/` and `<INSTALL_DIR>/premium-plugins/`.
+
 ## Running multiple brands on one device
 
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.