Add portable BotMRR Markdown playbooks

README.md

@@ -139,6 +139,20 @@ Keep Work, Personal, and each project in separate channels without cloning your
 its own transcript, shared instructions, working folder, responder rules, and editable bot roster. File a
 channel and its bots under a named context, then rename it or change its members whenever the team changes.
 
+### 📦 Install a complete team from one Markdown file
+
+Browse outcome-driven teams on [BotMRR](https://botmrr.io), then choose **Add to OpenMausBot**. The app
+opens a review screen before creating the bots, Chief of Staff, channels, playbooks, connector checklist,
+and suggested routines. You can also import the same `.md` file from disk or paste its public GitHub URL
+in **Teams → Import**.
+
+The format stays portable: OpenMausBot reads the structured YAML frontmatter for a reliable one-click
+install, while Grok, Claude, ChatGPT, and people can follow the ordinary Markdown playbook. Connections
+remain off until you approve them, routines arrive paused, and packages never carry credentials,
+conversations, permissions, memory, or computer access. Browse the
+[open-source playbook repository](https://github.com/milind-soni/openmausbot-teams) or read its
+[portable format](https://github.com/milind-soni/openmausbot-teams/blob/main/FORMAT.md).
+
 ### 🎧 Bots that talk back
 
 Press the speaker on any reply, or switch a bot to read its answers out as they land — so you can listen

electron-builder.yml

@@ -2,6 +2,10 @@ appId: com.openmausbot.app
 productName: OpenMausBot
 artifactName: OpenMausBot-${version}-${arch}.${ext}
 
+protocols:
+  - name: OpenMausBot package install
+    schemes: [openmausbot]
+
 # In-app auto-update reads latest-mac.yml + the .zip (macOS) or latest.yml +
 # the NSIS .exe (Windows) from this PUBLIC releases repo (separate from the
 # source repo). Public → no token on users' machines. Baked into

electron/main.mjs

@@ -18,6 +18,7 @@ import { startUpdater, registerUpdaterIpc } from "./updater.mjs";
 import { buildDiagnosticsReport, decodeLogTail, diagnosticsFileName } from "./diagnostics.mjs";
 import { migrateWorkspaceCredentials, workspaceCredentialEnv } from "./workspace-credentials.mjs";
 import { activateExistingWindow } from "./single-instance.mjs";
+import { packageUrlFromCommandLine, packageUrlFromDeepLink } from "./package-link.mjs";
 import capabilitiesModule from "./capabilities.cjs";
 
 const { desktopCapabilities, nativeDesktopActions } = capabilitiesModule;
@@ -40,6 +41,7 @@ const APP_ICON = path.join(__dirname, "resources/app-icon.png");
 let desktopViewerWindow = null;
 let desktopViewerOwner = null;
 let desktopViewerContextId = null;
+let pendingPackageInstallUrl = packageUrlFromCommandLine(process.argv);
 let mainWindow = null;
 let unreadCount = 0;
 let unreadOverlayIcon = null;
@@ -120,8 +122,34 @@ if (!app.requestSingleInstanceLock()) {
   console.log("[desktop] OpenMausBot is already running — focusing that window");
   process.exit(0);
 }
-app.on("second-instance", () => {
+function deliverPackageInstall(win) {
+  if (!pendingPackageInstallUrl || !win || win.isDestroyed()) return;
+  if (win.webContents.isLoadingMainFrame()) return;
+  win.webContents.send("package:install", pendingPackageInstallUrl);
+  pendingPackageInstallUrl = null;
+}
+
+function queuePackageInstall(rawLink) {
+  const packageUrl = packageUrlFromDeepLink(rawLink);
+  if (!packageUrl) return false;
+  pendingPackageInstallUrl = packageUrl;
+  activateExistingWindow(BrowserWindow.getAllWindows());
+  const target = BrowserWindow.getAllWindows().find((win) => !win.isDestroyed());
+  deliverPackageInstall(target);
+  return true;
+}
+
+app.on("open-url", (event, url) => {
+  if (!queuePackageInstall(url)) return;
+  event.preventDefault();
+});
+
+app.on("second-instance", (_event, commandLine) => {
+  const packageUrl = packageUrlFromCommandLine(commandLine);
+  if (packageUrl) pendingPackageInstallUrl = packageUrl;
   activateExistingWindow(BrowserWindow.getAllWindows());
+  const target = BrowserWindow.getAllWindows().find((win) => !win.isDestroyed());
+  deliverPackageInstall(target);
 });
 
 // Packaged: the harness server ships in Resources (compiled JS, zero deps)
@@ -636,6 +664,7 @@ function createWindow() {
     shell.openExternal(url);
     return { action: "deny" };
   });
+  win.webContents.on("did-finish-load", () => deliverPackageInstall(win));
 
   // Packaged CI smoke hook. It validates the real renderer/preload bridge and
   // same-origin embedded server, then follows the normal window-close path.
@@ -1047,6 +1076,7 @@ setCuaStateListener((connection) => {
 });
 
 app.whenReady().then(async () => {
+  if (app.isPackaged) app.setAsDefaultProtocolClient("openmausbot");
   if (process.platform === "darwin") app.dock.setIcon(APP_ICON);
   secureCredentials = await loadSecureCredentials();
   if (app.isPackaged) {

electron/package-link.mjs

@@ -0,0 +1,36 @@
+const ALLOWED_PACKAGE_HOSTS = new Set(["github.com", "www.github.com", "raw.githubusercontent.com"]);
+
+export function packageUrlFromDeepLink(rawValue) {
+  let link;
+  try {
+    link = new URL(String(rawValue));
+  } catch {
+    return null;
+  }
+  if (link.protocol !== "openmausbot:" || link.hostname !== "install") return null;
+  const rawPackage = link.searchParams.get("url");
+  if (!rawPackage) return null;
+  let packageUrl;
+  try {
+    packageUrl = new URL(rawPackage);
+  } catch {
+    return null;
+  }
+  if (
+    packageUrl.protocol !== "https:" ||
+    packageUrl.username ||
+    packageUrl.password ||
+    packageUrl.port ||
+    !ALLOWED_PACKAGE_HOSTS.has(packageUrl.hostname) ||
+    !packageUrl.pathname.match(/\.(?:md|json)$/)
+  ) return null;
+  return packageUrl.toString();
+}
+
+export function packageUrlFromCommandLine(argv) {
+  for (const value of argv) {
+    const parsed = packageUrlFromDeepLink(value);
+    if (parsed) return parsed;
+  }
+  return null;
+}

electron/package-link.node-test.mjs

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { packageUrlFromCommandLine, packageUrlFromDeepLink } from "./package-link.mjs";
+
+describe("BotMRR package deep links", () => {
+  it("accepts a public GitHub package URL", () => {
+    const target = "https://raw.githubusercontent.com/acme/bots/main/reddit-lead-miner.md";
+    assert.equal(packageUrlFromDeepLink(`openmausbot://install?url=${encodeURIComponent(target)}`), target);
+    assert.equal(packageUrlFromCommandLine(["OpenMausBot", "--flag", `openmausbot://install?url=${encodeURIComponent(target)}`]), target);
+  });
+
+  it("rejects other commands, hosts, protocols, credentials, and unsupported file types", () => {
+    assert.equal(packageUrlFromDeepLink("openmausbot://settings"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://evil.example/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=http://raw.githubusercontent.com/a/b/main/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://user@example.com/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://github.com/acme/bot/run.sh"), null);
+  });
+});

electron/preload.cjs

@@ -2,6 +2,14 @@
 // this narrow surface (window.ogb), never Node or ipcRenderer itself.
 const { contextBridge, ipcRenderer, webUtils } = require("electron");
 
+let pendingPackageInstallUrl = null;
+const packageInstallListeners = new Set();
+ipcRenderer.on("package:install", (_event, url) => {
+  if (typeof url !== "string") return;
+  pendingPackageInstallUrl = url;
+  for (const listener of packageInstallListeners) listener(url);
+});
+
 contextBridge.exposeInMainWorld("ogb", {
   /** Host platform ("darwin" | "win32" | "linux") — for platform-aware UI. */
   platform: process.platform,
@@ -100,6 +108,12 @@ contextBridge.exposeInMainWorld("ogb", {
   /** Open a web link in the default browser. Unlike renderer window.open,
    * this remains reliable after an asynchronous API request. */
   openExternal: (url) => ipcRenderer.invoke("desktop:open-external", url),
+  /** A reviewed BotMRR package opened through openmausbot://install. */
+  onPackageInstall: (cb) => {
+    packageInstallListeners.add(cb);
+    if (pendingPackageInstallUrl) cb(pendingPackageInstallUrl);
+    return () => packageInstallListeners.delete(cb);
+  },
   /** Mirrors durable unread state into the native Dock/taskbar badge. */
   setUnreadCount: (count) => ipcRenderer.send("desktop:unread-count", count),
   /** Live VNC/noVNC in a sandboxed window owned by the app window. */

package.json

@@ -33,9 +33,10 @@
     "dev:desktop": "electron .",
     "build": "tsc -b && tsc -p tsconfig.server.json && vite build",
     "typecheck": "tsc -b && tsc -p tsconfig.server.json",
-    "test": "node scripts/test-floor.mjs && pnpm broker:test && pnpm test:updater && pnpm test:desktop-viewer && pnpm test:packaged-server",
+    "test": "node scripts/test-floor.mjs && pnpm broker:test && pnpm test:updater && pnpm test:desktop-viewer && pnpm test:package-link && pnpm test:packaged-server",
     "test:updater": "node --test electron/updater-coordinator.node-test.mjs",
     "test:desktop-viewer": "node --test electron/desktop-viewer.node-test.mjs",
+    "test:package-link": "node --test electron/package-link.node-test.mjs",
     "bench:observation": "node --experimental-strip-types scripts/bench-observation.ts",
     "test:watch": "vitest",
     "test:cua": "pnpm build:cua && node scripts/smoke-cua.mjs",

server/bot-package.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+
+import { packageAgentAsMember, parseBotPackage, renderBotPackageMarkdown } from "./bot-package.ts";
+
+const validPackage: any = {
+  format: "openmaus.package",
+  version: 1,
+  package: {
+    id: "research-desk",
+    release: "1.0.0",
+    name: "Research Desk",
+    tagline: "Turn a question into a sourced brief.",
+    summary: "A small research team.",
+    category: "Research",
+    author: { name: "OpenMausBot" },
+    license: "MIT",
+    outcomes: ["Produce a sourced brief."],
+    setupMinutes: 3,
+    requirements: { apps: [], capabilities: [] },
+    agents: [
+      {
+        key: "lead",
+        name: "Ada",
+        title: "Research Lead",
+        description: "Own the brief.",
+        appearance: { color: "purple" },
+        playbooks: ["source-check"],
+        autoApprove: true,
+      },
+    ],
+    chiefOfStaff: "lead",
+    rooms: [
+      {
+        key: "desk",
+        name: "Research Desk",
+        members: ["lead"],
+        bulletin: "Cite sources.",
+        defaultResponder: { kind: "agent", agent: "lead" },
+      },
+    ],
+    playbooks: [
+      {
+        key: "source-check",
+        name: "Source Check",
+        summary: "Verify sources.",
+        triggers: ["research brief"],
+        instructions: "Separate facts from inference.",
+      },
+    ],
+  },
+};
+
+describe("bot packages", () => {
+  it("parses the complete portable structure and strips authority fields", () => {
+    const parsed = parseBotPackage(validPackage);
+    expect(parsed.package.rooms![0]?.defaultResponder).toEqual({ kind: "agent", agent: "lead" });
+    expect(parsed.package.agents[0]).not.toHaveProperty("autoApprove");
+    expect(packageAgentAsMember(parsed.package.agents[0]!)).toEqual({
+      key: "lead",
+      name: "Ada",
+      title: "Research Lead",
+      description: "Own the brief.",
+      appearance: { color: "purple" },
+    });
+  });
+
+  it("round-trips one Chief-of-Staff-readable Markdown playbook", () => {
+    const markdown = renderBotPackageMarkdown(parseBotPackage(validPackage));
+    expect(markdown).toContain("## Activation");
+    expect(markdown).toContain("Give this file to your Chief of Staff");
+    expect(markdown).not.toContain("autoApprove");
+    expect(parseBotPackage(markdown).package).toMatchObject({
+      id: "research-desk",
+      chiefOfStaff: "lead",
+      agents: [{ key: "lead", name: "Ada" }],
+    });
+  });
+
+  it("rejects dangling agent, room, playbook, chief, and routine references", () => {
+    expect(() => parseBotPackage({
+      ...validPackage,
+      package: { ...validPackage.package, chiefOfStaff: "missing" },
+    })).toThrow("Unknown Chief of Staff");
+    expect(() => parseBotPackage({
+      ...validPackage,
+      package: {
+        ...validPackage.package,
+        agents: [{ ...validPackage.package.agents[0], playbooks: ["missing"] }],
+      },
+    })).toThrow("unknown playbook");
+  });
+});