@hybridlabor-api/aos 4.13.2 → 4.14.0

package/installer.js

@@ -2609,10 +2609,7 @@ async function installOSAgentWorkspace() {
     if (daemonBin !== binTarget) {
         installStep('place the ao binary', () => {
             fs.mkdirSync(localBinDir, { recursive: true });
-            fs.copyFileSync(daemonBin, binTarget);
-            if (!isWin) {
-                fs.chmodSync(binTarget, 0o755);
-            }
+            installBinaryAtomically(daemonBin, binTarget);
             log.step(`Installed ao to ${binTarget}`);
         }, 'AO cannot be started without its binary.');
     }
@@ -3320,7 +3317,16 @@ async function installMcpsForTarget(paths, ctx) {
 // spaces) rather than matching the first alphanumeric run anywhere in the
 // block, so it can't accidentally pick up a word from prose if the heading
 // format changes.
-function parseAgentsMd(content) {
+function loadCommonSkills(dir = srcDir) {
+    try {
+        const reg = JSON.parse(fs.readFileSync(path.join(dir, '.agents', 'nodes.json'), 'utf8'));
+        return Array.isArray(reg.common) ? reg.common.filter((s) => typeof s === 'string') : [];
+    } catch {
+        return [];
+    }
+}
+
+function parseAgentsMd(content, commonSkills = loadCommonSkills()) {
     const blocks = content.split(/\n## /).slice(1);
     const agents = [];
     for (const raw of blocks) {
@@ -3350,7 +3356,7 @@ function parseAgentsMd(content) {
             name,
             role: roleMatch[1].trim(),
             model: modelMatch ? modelMatch[1].trim() : null,
-            skills: extractListAfter('Primary Skills'),
+            skills: [...new Set([...extractListAfter('Primary Skills'), ...commonSkills])],
             mcpServers: extractListAfter('MCP Servers'),
             output: outputMatch ? outputMatch[1].trim() : null,
             systemPrompt: raw.trim(),
@@ -3768,6 +3774,21 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         }
     }
 
+    // The plugin imports its decision logic from ./aos-hooks/ next to itself.
+    const hooksSrc = path.join(srcDir, '.claude', 'hooks');
+    if (fs.existsSync(hooksSrc)) {
+        try {
+            copyDirRecursiveSync(hooksSrc, path.join(opencodeDir, 'plugins', 'aos-hooks'));
+        } catch (e) {
+            log.error(`Could not install OpenCode plugin hooks (OpenCode gates inactive): ${e.message}`);
+        }
+    }
+
+    const trailLibSrc = path.join(srcDir, '.opencode', 'plugins', 'lib');
+    if (fs.existsSync(trailLibSrc)) {
+        try { copyDirRecursiveSync(trailLibSrc, path.join(opencodeDir, 'plugins', 'lib')); } catch (e) { log.warn(`Could not install OpenCode plugin lib: ${e.message}`); }
+    }
+
     // Slash-command payloads. Without these the /startcycle-graph command has no
     // native resolution and only survives as a raw-text match in the plugin.
     const commandsSrc = path.join(srcDir, '.opencode', 'commands');
@@ -3966,14 +3987,14 @@ function installGlobalBinaries() {
 // merged result goes to a .bdb-new.json sidecar -- the same recovery pattern
 // the MCP config merge in installMcpsForTarget uses.
 function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
-    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    const bdbHookScripts = ['go-gate.mjs', 'go-token.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
     // memb-inject reads the machine-global memB store under $HOME and is
     // installed once per machine, so it stays $HOME-anchored even inside a
     // project harness -- unlike the two gate hooks, which are per-checkout by
     // design. Pointing it at $CLAUDE_PROJECT_DIR would make it fail on every
     // prompt in any project the harness was never installed into. trail-relay
     // talks to machine-global live-map daemons, so it is anchored the same way.
-    const machineGlobalHooks = ['memb-inject.mjs', 'trail-relay.mjs'];
+    const machineGlobalHooks = ['memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs'];
     const isBdbEntry = (entry) => {
         const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [])
             .map((h) => (h && typeof h.command === 'string' ? h.command : ''))
@@ -4050,60 +4071,64 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
 // ~/.gemini/config/hooks.json), preserving user-defined foreign hooks.
 function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
     const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'startcycle-dispatch.mjs', 'trail-relay.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
-    const isBdbEntry = (entry) => {
-        const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [entry])
-            .map((h) => (h && typeof h.command === 'string' ? h.command : (typeof h === 'string' ? h : '')))
-            .join(' ');
-        return bdbHookScripts.some((name) => cmds.includes(name));
-    };
+    const isBdbHandler = (h) => typeof h?.command === 'string' && bdbHookScripts.some((name) => h.command.includes(name));
 
     const baseDir = path.dirname(hooksPath);
     const hooksDir = projectLocal ? path.join(currentDir, '.agents', 'hooks') : path.join(baseDir, 'hooks');
     const workflowsDir = projectLocal ? path.join(currentDir, '.agents', 'workflows') : path.join(baseDir, 'workflows');
     const globalHooksDir = projectLocal ? path.join(homeDir, '.gemini', 'config', 'hooks') : hooksDir;
 
+    const cmd = (dir, script, args = '') => `node "${path.join(dir, script)}"${args}`;
     const bdbHooks = {
         PreToolUse: [
             {
                 matcher: "run_command|Bash",
                 hooks: [
-                    { type: "command", command: `node "${path.join(hooksDir, 'go-gate.mjs')}"`, timeout: 10000 },
-                    { type: "command", command: `node "${path.join(hooksDir, 'conventional-commits.mjs')}"`, timeout: 10000 }
+                    { type: "command", command: cmd(hooksDir, 'go-gate.mjs'), timeout: 10 },
+                    { type: "command", command: cmd(hooksDir, 'conventional-commits.mjs'), timeout: 10 }
                 ]
             },
             {
                 matcher: "write_file|edit_file|replace|Write|Edit|MultiEdit",
-                hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'env-file-protection.mjs')}"`, timeout: 10000 }]
+                hooks: [{ type: "command", command: cmd(hooksDir, 'env-file-protection.mjs'), timeout: 10 }]
             },
             {
-                hooks: [{ type: "command", command: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event PreToolUse`, timeout: 2000 }]
+                matcher: "*",
+                hooks: [{ type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event PreToolUse'), timeout: 2 }]
             }
         ],
         Stop: [
-            {
-                hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'graph-gate.mjs')}"`, timeout: 10000 }]
-            },
-            {
-                hooks: [{ type: "command", command: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event Stop`, timeout: 2000 }]
-            }
+            { type: "command", command: cmd(hooksDir, 'graph-gate.mjs'), timeout: 10 },
+            { type: "command", command: cmd(globalHooksDir, 'trail-relay.mjs', ' --agent agy --event Stop'), timeout: 2 }
         ],
         PreInvocation: [
-            {
-                hooks: [
-                    { type: "command", command: `node "${path.join(globalHooksDir, 'memb-inject.mjs')}"`, timeout: 8000 },
-                    { type: "command", command: `node "${path.join(workflowsDir, 'startcycle-dispatch.mjs')}"`, timeout: 30000 }
-                ]
-            }
+            { type: "command", command: cmd(globalHooksDir, 'memb-inject.mjs'), timeout: 8 },
+            { type: "command", command: cmd(workflowsDir, 'startcycle-dispatch.mjs'), timeout: 30 }
         ]
     };
 
+    // Drops BDB handlers (old wrapped or current shape), keeps foreign ones, and
+    // rewraps flat events so previously written `{ hooks: [...] }` entries migrate.
+    const keepForeign = (event, entries) => {
+        const out = [];
+        for (const e of Array.isArray(entries) ? entries : []) {
+            const nested = e && Array.isArray(e.hooks);
+            if (bdbHooks[event][0].hooks) {
+                if (!nested) { if (!isBdbHandler(e)) out.push(e); continue; }
+                const kept = e.hooks.filter((h) => !isBdbHandler(h));
+                if (kept.length) out.push({ ...e, hooks: kept });
+            } else {
+                out.push(...(nested ? e.hooks : [e]).filter((h) => !isBdbHandler(h)));
+            }
+        }
+        return out;
+    };
+
     const buildMerged = (existing) => {
         const merged = existing && typeof existing === 'object' ? existing : {};
         merged.hooks = merged.hooks && typeof merged.hooks === 'object' ? merged.hooks : {};
         for (const [event, entries] of Object.entries(bdbHooks)) {
-            const foreignEntries = (Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [])
-                .filter((e) => !isBdbEntry(e));
-            merged.hooks[event] = [...foreignEntries, ...entries];
+            merged.hooks[event] = [...keepForeign(event, merged.hooks[event]), ...entries];
         }
         return merged;
     };
@@ -4135,7 +4160,9 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
 
     try {
         fs.mkdirSync(path.dirname(hooksPath), { recursive: true });
-        fs.writeFileSync(hooksPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
+        const tmpPath = `${hooksPath}.${process.pid}.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify(buildMerged(existing), null, 2) + '\n');
+        fs.renameSync(tmpPath, hooksPath);
     } catch (e) {
         log.warn(`Could not write ${hooksPath}: ${e.message}`);
     }
@@ -4510,6 +4537,107 @@ function shouldAutostartLaunchpad(overrides = {}) {
     return isDevEnvironment(overrides);
 }
 
+// Plan Canvas autostart is strictly opt-in (--autostart-plan-canvas): unlike
+// the launchpad opener it is NOT implied by a dev checkout. The server never
+// idle-exits there (AOS_PLAN_CANVAS_IDLE_MS=0 is honoured by server.js).
+const PLAN_CANVAS_LABEL = 'com.bdb.plan-canvas';
+
+function shouldAutostartPlanCanvas(overrides = {}) {
+    const argv = overrides.argv || process.argv;
+    return argv.includes('--autostart-plan-canvas');
+}
+
+function buildPlanCanvasPlist({ nodeBin, scriptPath, home, logDir }) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${PLAN_CANVAS_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${nodeBin}</string>
+        <string>${scriptPath}</string>
+        <string>server</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>AOS_PLAN_CANVAS_IDLE_MS</key>
+        <string>0</string>
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>${home}</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>30</integer>
+    <key>StandardOutPath</key>
+    <string>${path.join(logDir, 'plan-canvas.stdout.log')}</string>
+    <key>StandardErrorPath</key>
+    <string>${path.join(logDir, 'plan-canvas.stderr.log')}</string>
+</dict>
+</plist>`;
+}
+
+// Same bat + hidden-vbs-in-Startup mechanism as the OpenWiki visualizer.
+function buildPlanCanvasWinFiles({ nodeBin, scriptPath, home, logDir, batPath }) {
+    const out = path.join(logDir, 'plan-canvas.stdout.log');
+    const err = path.join(logDir, 'plan-canvas.stderr.log');
+    return {
+        bat: `@echo off\r\ncd /d "${home}"\r\nset AOS_PLAN_CANVAS_IDLE_MS=0\r\n"${nodeBin}" "${scriptPath}" server >> "${out}" 2>> "${err}"\r\n`,
+        vbs: `Set WshShell = CreateObject("WScript.Shell")\r\nWshShell.CurrentDirectory = "${home}"\r\nWshShell.Run """${batPath}""", 0, False\r\n`,
+    };
+}
+
+function installPlanCanvasAutostart(overrides = {}) {
+    if (!shouldAutostartPlanCanvas(overrides)) return false;
+    if ((overrides.dryRun ?? DRY_RUN)) {
+        log.step('[dry-run] would register the Plan Canvas background server (Port 4519, no idle exit)');
+        return false;
+    }
+    const home = overrides.homeDir || homeDir;
+    const platform = overrides.platform || process.platform;
+    const scriptPath = [
+        path.join(home, '.agents', 'skills', 'plan-canvas', 'scripts', 'plan-canvas.js'),
+        path.join(srcDir, 'skills', 'global_config', 'plan-canvas', 'scripts', 'plan-canvas.js'),
+    ].find(p => fs.existsSync(p));
+    if (!scriptPath) {
+        log.warn('Plan Canvas autostart skipped: plan-canvas.js not found. Start it with: aos-plan-canvas server');
+        return false;
+    }
+    const nodeBin = overrides.nodeBin || process.execPath;
+    const logDir = path.join(home, '.agents', 'logs');
+    try {
+        fs.mkdirSync(logDir, { recursive: true });
+        if (platform === 'darwin') {
+            const plistPath = path.join(home, 'Library', 'LaunchAgents', `${PLAN_CANVAS_LABEL}.plist`);
+            fs.mkdirSync(path.dirname(plistPath), { recursive: true });
+            fs.writeFileSync(plistPath, buildPlanCanvasPlist({ nodeBin, scriptPath, home, logDir }));
+            if (!overrides.skipLaunchctl) {
+                execSync(`launchctl unload "${plistPath}" 2>/dev/null || true`, { stdio: 'ignore' });
+                execSync(`launchctl load -w "${plistPath}" 2>/dev/null || true`, { stdio: 'ignore' });
+            }
+            log.success('Plan Canvas LaunchAgent registered (Port 4519)');
+        } else if (platform === 'win32') {
+            const startupDir = path.join(overrides.appData || process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+            fs.mkdirSync(startupDir, { recursive: true });
+            const batPath = path.join(home, '.agents', 'run-plan-canvas.bat');
+            const vbsPath = path.join(startupDir, `${PLAN_CANVAS_LABEL}.vbs`);
+            const files = buildPlanCanvasWinFiles({ nodeBin, scriptPath, home, logDir, batPath });
+            fs.writeFileSync(batPath, files.bat, 'utf-8');
+            fs.writeFileSync(vbsPath, files.vbs, 'utf-8');
+            if (!overrides.skipLaunchctl) spawn('wscript.exe', [vbsPath], { detached: true, stdio: 'ignore' }).unref();
+            log.success('Plan Canvas Startup entry registered (Port 4519)');
+        } else {
+            log.step('Plan Canvas autostart is only wired for macOS and Windows. Start it with: aos-plan-canvas server');
+            return false;
+        }
+        return true;
+    } catch (e) { logDebug(e, 'plan canvas autostart'); return false; }
+}
+
 function generateAndOpenLaunchpad(installedModules = []) {
     if (DRY_RUN) {
         log.step('[dry-run] would generate & open BDB Launchpad HTML');
@@ -4645,6 +4773,16 @@ function generateAndOpenLaunchpad(installedModules = []) {
     .card.offline .card-hint {
       display: block;
     }
+    .card-hint code {
+      font-family: var(--mono);
+      font-style: normal;
+      color: #ffffff;
+      background: #0a0a0a;
+      border: 1px solid var(--accent);
+      border-radius: 4px;
+      padding: 1px 6px;
+      cursor: copy;
+    }
     .footer {
       margin-top: 28px;
       text-align: center;
@@ -4835,6 +4973,25 @@ function generateAndOpenLaunchpad(installedModules = []) {
           <span class="status-dot" id="dot-store" title="Checking..."></span>
         </div>
       </a>
+      <a class="card" href="http://127.0.0.1:4519/" target="_blank">
+        <div class="card-content">
+          <div class="card-icon"><svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+            <defs><linearGradient id="grad-plancanvas" x1="50%" y1="0%" x2="50%" y2="100%"><stop offset="0%" stop-color="#FFFFFF"/><stop offset="100%" stop-color="#9b30c4"/></linearGradient></defs>
+            <rect x="18" y="22" width="64" height="56" rx="4" fill="url(#grad-plancanvas)" opacity="0.85"/>
+            <rect x="26" y="30" width="22" height="14" rx="1.5" fill="#0a0a0a" opacity="0.6"/><rect x="52" y="30" width="22" height="14" rx="1.5" fill="#0a0a0a" opacity="0.6"/>
+            <line x1="26" y1="54" x2="74" y2="54" stroke="#0a0a0a" stroke-width="2.5" opacity="0.5"/><line x1="26" y1="64" x2="56" y2="64" stroke="#0a0a0a" stroke-width="2.5" opacity="0.5"/>
+          </svg></div>
+          <div class="card-info">
+            <h2>Plan Canvas</h2>
+            <p>Review plans in the browser: annotate, chat, approve</p>
+            <div class="card-hint">offline — run: <code data-copy="aos-plan-canvas server" title="Click to copy">aos-plan-canvas server</code></div>
+          </div>
+        </div>
+        <div class="card-meta">
+          <span class="port-pill">:4519</span>
+          <span class="status-dot" id="dot-plancanvas" title="Checking..."></span>
+        </div>
+      </a>
     </div>
     <div class="footer">
       <span>Autostart Daemons • 127.0.0.1</span>
@@ -4862,7 +5019,26 @@ function generateAndOpenLaunchpad(installedModules = []) {
       checkHealth('http://127.0.0.1:9080', 'dot-remote');
       checkHealth('http://127.0.0.1:4321', 'dot-openwiki');
       checkHealth('http://127.0.0.1:4322', 'dot-store');
-    }
+      checkHealth('http://127.0.0.1:4519', 'dot-plancanvas');
+    }
+    document.addEventListener('click', (ev) => {
+      const el = ev.target.closest && ev.target.closest('[data-copy]');
+      if (!el) return;
+      ev.preventDefault();
+      ev.stopPropagation();
+      const text = el.getAttribute('data-copy');
+      const fallback = () => {
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        document.body.appendChild(ta);
+        ta.select();
+        try { document.execCommand('copy'); } catch (e) {}
+        ta.remove();
+      };
+      if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).catch(fallback);
+      else fallback();
+      el.title = 'Copied';
+    }, true);
     checkAllHealth();
     setInterval(checkAllHealth, 5000);
   </script>
@@ -5075,6 +5251,7 @@ async function universalHarnessSync(primaryMcpConfigPath, installedModules = [])
     }
     log.success('Universal Sync Complete!');
     generateAndOpenLaunchpad(installedModules);
+    installPlanCanvasAutostart();
 }
 
 async function runQuickUpdate(installState) {
@@ -5241,7 +5418,41 @@ function installAosCli() {
     }
 }
 
+// A running daemon may execute dest; overwriting its inode keeps stale code-signature
+// state on macOS and every new exec dies with SIGKILL. Rename gives dest a fresh inode.
+function installBinaryAtomically(src, dest) {
+    const tmp = path.join(path.dirname(dest), `.${path.basename(dest)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        fs.copyFileSync(src, tmp);
+        if (process.platform !== 'win32') fs.chmodSync(tmp, 0o755);
+        fs.renameSync(tmp, dest);
+    } catch (e) {
+        try { fs.unlinkSync(tmp); } catch (_) {}
+        throw e;
+    }
+}
+
 async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--version') || args.includes('-V')) {
+        console.log(pkg.version);
+        return;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(`Usage: aos [command] [options]
+
+Commands:
+  store            Browse and install skills
+  doctor|checkup   Check the installation
+
+Options:
+  -y, --yes        Non-interactive install (implied without a TTY)
+  --dry-run        Show what would change
+  --verbose, -v    Verbose output
+  -V, --version    Print the version and exit
+  -h, --help       Print this help and exit`);
+        return;
+    }
     if (process.argv[2] === 'store') {
         const storeScript = path.join(srcDir, 'bin', 'aos-store.mjs');
         const result = spawnSync(process.execPath, [storeScript, ...process.argv.slice(3)], { stdio: 'inherit' });
@@ -5695,6 +5906,7 @@ if (require.main === module) {
 
 // Exported for tests -- requiring installer.js must not launch the TUI.
 module.exports = {
+    installBinaryAtomically,
     installOSAgentWorkspace,
     downloadOrUpdateModule,
     detectPlatforms,
@@ -5726,6 +5938,7 @@ module.exports = {
     INSTALL_MANIFEST_PATH,
     // Agent compilers & pipeline helpers
     parseAgentsMd,
+    loadCommonSkills,
     compileClaudeAgents,
     compileOpenCodeAgents,
     compileCodexAgents,
@@ -5736,6 +5949,10 @@ module.exports = {
     generateAndOpenLaunchpad,
     shouldOpenLaunchpad,
     shouldAutostartLaunchpad,
+    shouldAutostartPlanCanvas,
+    buildPlanCanvasPlist,
+    buildPlanCanvasWinFiles,
+    installPlanCanvasAutostart,
     isDevEnvironment,
     LAUNCHPAD_WEB_MODULES,
     LAUNCHPAD_OPEN_FLAGS,

package/mcps/mcsc/packages/mcp/server.js

@@ -64,16 +64,15 @@ async function init() {
 
   const customRulebook = path.resolve(process.cwd(), 'rulebook.yaml');
   const defaultRulebook = path.resolve(__dirname, '../core/rulebook.default.yaml');
-  const rulebookPath = fs.existsSync(customRulebook) ? customRulebook : defaultRulebook;
 
   try {
-    if (fs.existsSync(rulebookPath)) {
-      rules = loadRulebook(rulebookPath);
-      const now = Date.now();
-      offerTable = await buildOfferTable(rules, inventory, now);
-    }
+    rules = await loadRulebook({
+      defaultsPath: defaultRulebook,
+      overridePath: fs.existsSync(customRulebook) ? customRulebook : undefined,
+    });
+    offerTable = await buildOfferTable(rules, inventory, Date.now());
   } catch (e) {
-    console.error(`[mcsc-mcp] Warning: could not load rulebook from ${rulebookPath}: ${e.message}`);
+    console.error(`[mcsc-mcp] Warning: could not load rulebook from ${defaultRulebook}: ${e.message}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.13.2",
+  "version": "4.14.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "engines": {
@@ -18,7 +18,8 @@
     "aos-config": "bin/aos-config.mjs",
     "aos-store": "bin/aos-store.mjs",
     "aos-doctor": "bin/aos-doctor.mjs",
-    "aos-uninstall": "bin/aos-uninstall.mjs"
+    "aos-uninstall": "bin/aos-uninstall.mjs",
+    "aos-acp": "bin/aos-acp.mjs"
   },
   "scripts": {
     "validate": "node scripts/validate-skills.mjs",
@@ -27,7 +28,7 @@
     "plugin:build": "node scripts/build-plugin-manifest.mjs",
     "plugin:check": "node scripts/build-plugin-manifest.mjs --check",
     "doctor": "node bin/aos-doctor.mjs",
-    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node --test tests/opencode-graph-gate.test.js && node --test tests/cross-harness-hooks.test.js && node tests/aos-store.test.mjs && node --test tests/aos-store-ui.test.mjs && node tests/aos-store-scenario.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs && node --test tests/agent-models.test.js && node --test tests/installer-p3.test.js"
+    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node --test tests/opencode-graph-gate.test.js && node --test tests/cross-harness-hooks.test.js && node --test tests/plan-canvas-security.test.mjs && node --test tests/plan-canvas-modes.test.mjs && node --test tests/swarm-wiring.test.js && node tests/aos-store.test.mjs && node --test tests/aos-store-ui.test.mjs && node tests/aos-store-scenario.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs && node --test tests/agent-models.test.js && node --test tests/installer-p3.test.js && node --test tests/installer-binary.test.js && node --test tests/installer-version.test.js && node --test tests/mcsc-server.test.js && node --test tests/antigravity-hooks.test.js && node --test tests/plan-builder.test.mjs && node --test tests/plan-builder-trail.test.mjs && node --test tests/plan-builder-showcase.test.mjs && node --test tests/plan-builder-templates.test.mjs && node --test tests/plan-canvas-home.test.mjs && node --test tests/launchpad-installer.test.js && node --test tests/launchpad-plan-canvas.test.js && node --test tests/go-token.test.js && node --test tests/master-session-skill.test.js && node --test tests/aos-acp.test.js && node --test tests/opencode-go-token.test.js && node --test tests/opencode-adapter.test.js && node --test tests/pr-recap.test.mjs && node --test tests/bdb-visual-edit.test.mjs && node --test tests/opencode-trail-autostart.test.mjs && node --test tests/trail-autostart-hook.test.mjs && node --test tests/agenttrail-ensure.test.mjs"
   },
   "publishConfig": {
     "access": "public"

package/scripts/validate-skills.mjs

@@ -241,6 +241,45 @@ function checkSkillRefs(text, file, known, self, findings) {
   }
 }
 
+// Playbooks are skills with `kind: playbook`; skills without `kind` are untouched.
+const PB_REQUIRED = ['trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation'];
+const DIFFICULTY = new Set(['beginner', 'intermediate', 'advanced']);
+const EXTERNAL = ' (external)';
+
+export function checkPlaybook(byKey, known) {
+  const out = [];
+  if (!byKey.has('kind')) return out;
+  const add = (code, msg, key) => out.push({ level: 'error', code, line: byKey.get(key)?.line, msg });
+  const kind = unquote(byKey.get('kind').value);
+  if (kind !== 'playbook') {
+    add('E-PB01', `\`kind: ${kind}\` is unknown — the only defined kind is \`playbook\``, 'kind');
+    return out;
+  }
+  for (const k of PB_REQUIRED) if (!byKey.has(k)) add('E-PB03', `playbook is missing required key \`${k}\``, 'kind');
+
+  const req = byKey.get('requires');
+  if (req) {
+    const m = /(?:^|\s)skills:\s*\[([^\]]*)\]/.exec(req.value);
+    if (!m) add('E-PB05', '`requires.skills` must be a flow-style list, e.g. `skills: [github, ci-pipeline]`', 'requires');
+    else {
+      for (const raw of m[1].split(',').map((e) => unquote(e)).filter(Boolean)) {
+        if (!raw.endsWith(EXTERNAL) && !known.has(raw)) {
+          add('E-PB02', `requires skill \`${raw}\`, which is not a skill in this repo — fix the name or mark it \`${raw}${EXTERNAL}\``, 'requires');
+        }
+      }
+    }
+  }
+  const diff = byKey.get('difficulty');
+  if (diff && !DIFFICULTY.has(unquote(diff.value))) {
+    add('E-PB04', `\`difficulty: ${unquote(diff.value)}\` is not one of: ${[...DIFFICULTY].join(', ')}`, 'difficulty');
+  }
+  const dmi = byKey.get('disable-model-invocation');
+  if (dmi && unquote(dmi.value) !== 'true') {
+    add('E-PB06', 'playbooks are user-invoked only — set `disable-model-invocation: true`', 'disable-model-invocation');
+  }
+  return out;
+}
+
 function validate() {
   const { skills, strays } = collect();
   const known = new Set(skills.map((f) => basename(dirname(f))));
@@ -311,6 +350,8 @@ function validate() {
       }
     }
 
+    for (const f of checkPlaybook(byKey, known)) findings.push({ ...f, file: rel });
+
     checkLeakedPaths(text, rel, findings);
     checkLocalRefs(text, dir, rel, findings);
     checkSkillRefs(text, rel, known, dirName, findings);
@@ -461,6 +502,41 @@ function selftest() {
   assert.ok(isValidSkillName('a'.repeat(NAME_MAX)), 'a 64-char name is at the limit and valid');
   assert.ok(!isValidSkillName('a'.repeat(NAME_MAX + 1)), 'a 65-char name is over the limit');
 
+  // Playbook frontmatter (kind: playbook).
+  const pb = (over = {}, drop = []) => {
+    const base = {
+      name: 'pb-x', description: 'd', category: 'bdb-core', kind: 'playbook',
+      trigger: '["a"]', inputs: '[repo]',
+      requires: '\n  skills: [github, gh (external)]\n  agents: []\n  mcps: []\n  store: []',
+      go_points: '[]', outputs: '["x"]', verify: '"x"', difficulty: 'beginner',
+      est_time: '5 min', 'disable-model-invocation': 'true', ...over,
+    };
+    const lines = Object.entries(base).filter(([k]) => !drop.includes(k)).map(([k, v]) => `${k}: ${v}`);
+    const fm = scanFrontmatter(['---', ...lines, '---'].join('\n'));
+    return new Map(fm.keys.map((k) => [k.key, k]));
+  };
+  const known = new Set(['github', 'ci-pipeline']);
+  assert.deepEqual(checkPlaybook(pb(), known), [], 'valid playbook is clean');
+  const miss = checkPlaybook(pb({}, ['go_points']), known);
+  assert.equal(miss.length, 1);
+  assert.equal(miss[0].code, 'E-PB03');
+  assert.match(miss[0].msg, /go_points/);
+  assert.equal(checkPlaybook(pb({ difficulty: 'expert' }), known)[0].code, 'E-PB04');
+  const unk = checkPlaybook(pb({ requires: '\n  skills: [github, nope-skill, gh (external)]' }), known);
+  assert.equal(unk.length, 1);
+  assert.equal(unk[0].code, 'E-PB02');
+  assert.match(unk[0].msg, /nope-skill/);
+  const kind = checkPlaybook(pb({ kind: 'recipe' }), known);
+  assert.equal(kind.length, 1);
+  assert.equal(kind[0].code, 'E-PB01');
+  assert.equal(checkPlaybook(pb({ requires: '\n  skills:\n    - github' }), known)[0].code, 'E-PB05');
+  assert.equal(checkPlaybook(pb({ 'disable-model-invocation': 'false' }), known)[0].code, 'E-PB06');
+  assert.deepEqual(checkPlaybook(pb({}, ['kind', 'trigger', 'inputs', 'requires', 'go_points', 'outputs', 'verify', 'difficulty', 'est_time', 'disable-model-invocation']), known).length, 0, 'no kind, no playbook rules');
+  assert.deepEqual(
+    checkPlaybook(pb({ requires: '\n  skills: ["gh (external)", github,]' }), known), [],
+    'quoted item and trailing comma survive',
+  );
+
   console.log('✓ selftest passed');
 }
 

package/skills/basic/bdbmediastorm/SKILL.md

@@ -76,7 +76,7 @@ Define hardware and software nodes as strict bounded contexts:
 
 ## 5. Mandatory — Plan Canvas Review
 
-Before this session concludes, run `aos-plan-canvas open <file>` against `signal-flow.md` (or the combined show-control spec), then `aos-plan-canvas await <file>` and leave it running. The user reviews the signal flow diagram, hardware topology, and failover matrix in the browser (Mermaid renders live, click-to-annotate, chat rail). Do not consider the show architecture finalized before an `approve` verdict. A `request_changes` verdict means revise the artifact and reopen — it live-reloads. This is a plain CLI tool, identical regardless of which agent harness runs this skill. See the `plan-canvas` skill. If a build follows the approve, Trigger A starts the live map (`agenttrail` skill); `aos-archify` can render the signal flow as a workflow or architecture diagram for the review.
+Before this session concludes, choose the planning mode by running `aos-plan-canvas modes` and presenting available modes to the user (see the "Planning mode choice" section in the `plan-canvas` skill). Then run `aos-plan-canvas open <file> --mode <choice>` against `signal-flow.md` (or the combined show-control spec), then `aos-plan-canvas await <file>` and leave it running. The user reviews the signal flow diagram, hardware topology, and failover matrix in the browser (Mermaid renders live, click-to-annotate, chat rail). Do not consider the show architecture finalized before an `approve` verdict. A `request_changes` verdict means revise the artifact and reopen — it live-reloads. This is a plain CLI tool, identical regardless of which agent harness runs this skill. See the `plan-canvas` skill. If a build follows the approve, Trigger A starts the live map (`agenttrail` skill); `aos-archify` can render the signal flow as a workflow or architecture diagram for the review.
 
 ---
 

package/skills/basic/godmode-shipping/SKILL.md

@@ -41,6 +41,9 @@ This Godmode extends beyond standard software development. It STRICTLY governs c
 *   **MediaStorm Deployments:** When executing `/bdbmediastorm` for TouchDesigner, Unreal Engine, or Adobe Suite workflows, you must enforce rigorous release management for `.tox` files, Unreal Blueprints, and showfiles.
 *   **Show-Ready Validation:** Never push a creative-tech update to a live production environment (e.g., a running installation or live show) without a verified fallback or backup showfile. 
 
+## Visual recap
+After the gates pass, `/pr-recap` can build a Plan Builder recap page of the diff with the Verified and Not verified checks. It is informational and does not gate the release. Posting it anywhere stays a human decision.
+
 ## Universal Agent Harness Integration
 This Godmode is universally compatible and governs all extensions, including the BDB Creator Engine.
 *   **Cursor:** Auto-injected via `.cursor/rules/godmode-shipping.mdc`.