@hybridlabor-api/aos 4.8.0 → 4.9.0

package/THIRD_PARTY_NOTICES.md

@@ -287,6 +287,94 @@ the upstream offensive exploit content is stripped and not carried over.
 
 ---
 
+## obra/superpowers
+
+<https://github.com/obra/superpowers> — MIT. Copyright (c) 2025 Jesse Vincent.
+
+Tracked in `.agents/vendor-manifest.json` at pinned commit
+`8ca22dba9a94f28898bbce59f2537ff4d87c747d` (v6.4.2).
+
+Five workflow skills are vendored under `skills/global_config/`, each carried
+whole with its companion files: `verification-before-completion`,
+`requesting-code-review` (plus `code-reviewer.md`),
+`finishing-a-development-branch`, `using-git-worktrees`, and
+`dispatching-parallel-agents`. A sixth, `writing-plans`, **replaces** the AOS
+version of that skill; the superseded AOS original is kept alongside it as
+`writing-plans-legacy` (`source: community`, marked `deprecated_by`) rather than
+deleted.
+
+AOS modifications: `category:`, `source:` and `date_added:` added to the
+frontmatter; the `superpowers:` namespace prefix stripped from cross-skill
+references so they resolve to AOS skill names. AOS adaptations to
+`writing-plans`: the plan output path is kept at AOS's `docs/plans/` rather
+than upstream's `docs/superpowers/plans/`, and the AOS `risk: critical` marker
+is carried over.
+
+AOS already vendored four other skills from this repository earlier
+(`brainstorming`, `test-driven-development`, `executing-plans`,
+`subagent-driven-development`) without recording it here. Those imports still
+carry the `superpowers:` prefix in their cross-references.
+
+---
+
+## akin-ozer/cc-devops-skills
+
+<https://github.com/akin-ozer/cc-devops-skills> — Apache-2.0.
+Copyright [yyyy] [name of copyright owner] (upstream ships the unfilled
+Apache-2.0 notice).
+
+Tracked in `.agents/vendor-manifest.json` at pinned commit
+`276af751e659315aaf56d3ad13d7c26f4e72e28a`.
+
+Four generator/validator pairs are vendored under `skills/global_config/`, each
+carried whole including its `references/`, `scripts/`, `examples/`, `docs/` and
+`test/` subtrees: `github-actions-generator` + `github-actions-validator`,
+`dockerfile-generator` + `dockerfile-validator`, `bash-script-generator` +
+`bash-script-validator`, `makefile-generator` + `makefile-validator`.
+
+AOS modifications: `category:`, `source:` and `date_added:` added to the
+frontmatter; the `devops-skills:` namespace prefix stripped from cross-skill
+references so they resolve to AOS skill names; the Docker example user
+`appuser` renamed to `app` throughout `dockerfile-generator` and
+`dockerfile-validator` to satisfy the E-PATH01 username check.
+
+---
+
+## davila7/claude-code-templates
+
+<https://github.com/davila7/claude-code-templates> — MIT.
+Copyright (c) 2025 Daniel (San) Ávila.
+
+`conventional-commits` (`.claude/hooks/conventional-commits.mjs`) and
+`env-file-protection` (`.claude/hooks/env-file-protection.mjs`) are ported from
+upstream's `conventional-commits.py` and `env-file-protection.json`, selected
+from a set of 62 hooks. Tracked in `.agents/vendor-manifest.json`.
+
+Both are ports, not verbatim copies, and the differences are behavioural:
+
+- **Python to .mjs.** Upstream ships Python. Node is already a hard AOS install
+  dependency and every other AOS hook is `.mjs`; `python3` is absent on a stock
+  Windows install, where the installer also runs.
+- **Both harnesses.** Upstream's `env-file-protection` is an inline `echo`
+  guarded by a matcher `if` field, which Antigravity and the Gemini CLI ignore —
+  there it would fire on every write. The check lives in code instead, and both
+  hooks emit the Antigravity `{"decision":...}` stdout form as well as the
+  Claude Code stderr/exit-2 form.
+- **`.env.example` and friends are allowed.** Upstream's matcher blocks
+  `.env*`, which contradicts its own advice to put new values in
+  `.env.example`. Templates (`example`, `sample`, `template`, `dist`) are
+  committed and hold no live secret, so they are exempt here.
+- **Both hooks fail open.** An unreadable payload or an unextractable commit
+  message allows the call, unlike `go-gate`, which fails closed. A regex miss
+  must not wedge a commit.
+
+Upstream's `secret-scanner`, `tdd-gate`, and `dangerous-command-blocker` were
+reviewed and **not** shipped; they remain available on demand from the ECC
+store. Reasons are in `docs/handover/` and the branch description for
+`feat/cicd-skills-import`.
+
+---
+
 ## Note on `mcps/`
 
 Sub-repositories vendored under `mcps/` carry their own `LICENSE` files in

package/docs/skills_table.md

@@ -52,7 +52,7 @@
 #### 🎨 Frontend & UI/UX
 | Skill Name | Description |
 |------------|-------------|
-| `MCP_Manage` | Manages the BDB specialized MCP servers including Unreal Engine, Rhino 7/8, DaVinci Resolve, grandMA3, Resolume, GitHub, Chrome DevTools, and TouchDesigner. |
+| `mcp-manage` | Manages the BDB specialized MCP servers including Unreal Engine, Rhino 7/8, DaVinci Resolve, grandMA3, Resolume, GitHub, Chrome DevTools, and TouchDesigner. |
 | `api-design-principles` | Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time. |
 | `api-patterns` | API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. |
 | `bdbdesignpro` | Use when choosing an animation engine, defining motion tokens, adding scroll effects or micro-interactions, or auditing motion for accessibility and performance in BDB projects. Covers engine selection (GSAP, Motion.dev, Anime.js, React-Spring, Three.js, CSS Native), BDB brand-locked motion tokens, and the anti-slop/a11y quality gate. |

package/installer.js

@@ -115,8 +115,8 @@ if (mcpsArgRaw && mcpsArg === null) {
 // not express that in a script or CI, and got Antigravity as their primary
 // target instead. Values match the menu: 0 universal, 1 Antigravity,
 // 2 Claude Desktop/Code, 3 Cursor, 4 custom, 5 Codex, 6 Windsurf, 7 Roo/Cline,
-// 8 Aider (9 = project harness has its own --project-harness flag).
-const VALID_PLATFORMS = ['0', '1', '2', '3', '4', '5', '6', '7', '8'];
+// 8 Aider, 10 AOS CLI (9 = project harness has its own --project-harness flag).
+const VALID_PLATFORMS = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '10'];
 const platformsArgRaw = process.argv.find(a => a === '--platforms' || a.startsWith('--platforms='));
 let PLATFORMS_ARG = null;
 if (platformsArgRaw) {
@@ -1257,6 +1257,7 @@ function syncSkillsToGlobalHarnesses(excludeSkills = []) {
         { dir: path.join(homeDir, '.codex', 'skills'), key: 'codex' },
         { dir: path.join(homeDir, '.cursor', 'skills'), key: 'cursor' },
         { dir: path.join(homeDir, '.roo', 'skills'), key: 'vscode' },
+        { dir: process.platform === 'win32' ? path.join(process.env.APPDATA || homeDir, 'opencode', 'skills') : path.join(homeDir, '.config', 'opencode', 'skills'), key: 'opencode' },
     ].filter((d) => d.key === null || detectedKeys.has(d.key));
 
     for (const { dir: dest } of extraSkillDestinations) {
@@ -1709,8 +1710,12 @@ function checkModuleUpdate(pkgName, targetDir) {
         let remoteVer = null;
         let checkFailed = false;
         try {
-            const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-            remoteVer = execFileSync(npmBin, ['view', pkgName, 'version'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000, shell: process.platform === 'win32' }).trim();
+            const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+            if (process.platform === 'win32') {
+                remoteVer = execSync(`"${npmCmd}" view ${pkgName} version`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim();
+            } else {
+                remoteVer = execFileSync(npmCmd, ['view', pkgName, 'version'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim();
+            }
         } catch (e) {
             // Offline, a proxy, or a misconfigured registry. Swallowing this
             // made every module report "up to date" forever on such a machine,
@@ -1805,15 +1810,40 @@ function downloadOrUpdateModule(pkgName, targetDir, displayName) {
             }
         }
 
+        // Phase 1: retire the live tree. On Windows a running daemon holds open
+        // file handles into targetDir — retry with brief backoff before failing.
+        // ponytail: 3 retries × 600ms; escalate to process kill if this ceiling matters
+        let phase1Done = false;
+        for (let attempt = 0; attempt < 3 && !phase1Done; attempt++) {
+            try {
+                fs.renameSync(targetDir, retiredDir);
+                phase1Done = true;
+            } catch (retireError) {
+                const retriable = retireError.code === 'EPERM' || retireError.code === 'EBUSY';
+                if (retriable && attempt < 2) {
+                    const delayMs = 600 * (attempt + 1);
+                    try {
+                        if (process.platform === 'win32') {
+                            execSync(`powershell -NoProfile -Command "Start-Sleep -Milliseconds ${delayMs}"`, { stdio: 'ignore' });
+                        } else {
+                            execSync(`sleep ${delayMs / 1000}`, { stdio: 'ignore' });
+                        }
+                    } catch (_) {}
+                    continue;
+                }
+                safeRmDirSync(stagingDir);
+                throw retireError;
+            }
+        }
+
+        // Phase 2: promote the staging tree. stagingDir was just unpacked and
+        // has no open handles, so a single attempt is sufficient.
         try {
-            fs.renameSync(targetDir, retiredDir);
             fs.renameSync(stagingDir, targetDir);
-        } catch (swapError) {
-            if (fs.existsSync(retiredDir) && !fs.existsSync(targetDir)) {
-                try { fs.renameSync(retiredDir, targetDir); } catch (_) {}
-            }
+        } catch (promoteError) {
+            try { fs.renameSync(retiredDir, targetDir); } catch (_) {}
             safeRmDirSync(stagingDir);
-            throw swapError;
+            throw promoteError;
         }
 
         // On Windows especially, deleting a directory that was just renamed or contains
@@ -1886,6 +1916,21 @@ async function installMemB(interactive) {
         }));
     }
     const membDir = path.join(moduleBasePath(), 'memB');
+    // On Windows the memB WebUI process holds open file handles inside membDir.
+    // The atomic rename inside downloadOrUpdateModule fails with EPERM as long as
+    // those handles are live — retry backoff cannot help. Kill the process on
+    // port 8088 before attempting the download so the rename succeeds.
+    if (process.platform === 'win32') {
+        try {
+            execSync(
+                'powershell -NoProfile -Command "' +
+                'Get-NetTCPConnection -LocalPort 8088 -ErrorAction SilentlyContinue |' +
+                ' Select-Object -ExpandProperty OwningProcess |' +
+                ' ForEach-Object { Stop-Process -Id $_ -Force -ErrorAction SilentlyContinue }"',
+                { stdio: 'ignore' }
+            );
+        } catch (_) {}
+    }
     // A failed download used to fall through into venv setup and daemon
     // registration, each of which then failed on its own terms or, worse,
     // "succeeded" against a stale tree -- and the run still ended in a success
@@ -2561,10 +2606,15 @@ async function installOSAgentWorkspace() {
         execFileSync(binTarget, ['service', 'install'], { stdio: 'ignore' });
     }, 'Start it by hand with: ao service install');
 
-    if (await verifyDaemonListening(3101, 'AO Orchestrator', 8000)) {
+    // Windows startup entries fire asynchronously — give the service more time
+    const aoTimeout = process.platform === 'win32' ? 20000 : 8000;
+    if (await verifyDaemonListening(3101, 'AO Orchestrator', aoTimeout)) {
         log.success('AO Orchestrator running on http://localhost:3101');
     } else {
-        log.warn('AO did not answer on :3101 — check `ao service status` and `ao service logs`.');
+        const hint = process.platform === 'win32'
+            ? 'Run `ao service install` again or log out and back in, then check `ao service status`.'
+            : 'Check `ao service status` and `ao service logs`.';
+        log.warn(`AO did not answer on :3101 — ${hint}`);
     }
 }
 async function promptMemBIngestion(mcpCodeTarget) {
@@ -2638,8 +2688,10 @@ function verifyEcosystemInstallation() {
                 let newerVersion = null;
                 let newerTag = null;
                 try {
-                    const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-                    const distTagsJson = execFileSync(npmBin, ['view', mod.pkg, 'dist-tags', '--json'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000, shell: process.platform === 'win32' }).trim();
+                    const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+                    const distTagsJson = process.platform === 'win32'
+                        ? execSync(`"${npmCmd}" view ${mod.pkg} dist-tags --json`, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim()
+                        : execFileSync(npmCmd, ['view', mod.pkg, 'dist-tags', '--json'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 4000 }).trim();
                     const distTags = JSON.parse(distTagsJson);
                     for (const [tag, ver] of Object.entries(distTags)) {
                         if (isNewerVersion(localVer, ver)) {
@@ -2685,7 +2737,7 @@ function verifyEcosystemInstallation() {
 
     console.log('');
     console.log(`  ${colors.bold}━━━ BDB Agent OS Dashboard ━━━${colors.reset}`);
-    console.log(`  Interactive Control Center: npx aos-dashboard`);
+    console.log(`  Interactive Control Center: aos-dashboard`);
     console.log(`  ${colors.dim}(Live status & service control at http://127.0.0.1:7900)${colors.reset}`);
 }
 
@@ -3625,23 +3677,23 @@ function injectHarnessRules() {
 // that adds or changes a hook silently never received it -- which is exactly
 // what happened to memb-inject.mjs in v4.4.0, on the machines that needed it
 // most (a fresh install got it; every machine that already had AOS did not).
-function installGlobalHooks() {
+function installGlobalHooks({ targetHome = homeDir, targetGemini = geminiDir } = {}) {
     const hooksSrc = path.join(srcDir, '.claude', 'hooks');
     const workflowsSrc = path.join(srcDir, '.claude', 'workflows');
 
     // 1. Claude Code
     if (fs.existsSync(hooksSrc)) {
-        copyDirRecursiveSync(hooksSrc, path.join(homeDir, '.claude', 'hooks'));
-        log.step(`Installed hooks to ${path.join(homeDir, '.claude', 'hooks')}`);
+        copyDirRecursiveSync(hooksSrc, path.join(targetHome, '.claude', 'hooks'));
+        log.step(`Installed hooks to ${path.join(targetHome, '.claude', 'hooks')}`);
     }
     if (fs.existsSync(workflowsSrc)) {
-        copyDirRecursiveSync(workflowsSrc, path.join(homeDir, '.claude', 'workflows'));
+        copyDirRecursiveSync(workflowsSrc, path.join(targetHome, '.claude', 'workflows'));
     }
-    mergeBdbSettingsHooks(path.join(homeDir, '.claude', 'settings.json'));
+    mergeBdbSettingsHooks(path.join(targetHome, '.claude', 'settings.json'));
 
     // 2. Google Antigravity
-    const agyHooksDir = path.join(geminiDir, 'config', 'hooks');
-    const agyWorkflowsDir = path.join(geminiDir, 'config', 'workflows');
+    const agyHooksDir = path.join(targetGemini, 'config', 'hooks');
+    const agyWorkflowsDir = path.join(targetGemini, 'config', 'workflows');
     if (fs.existsSync(hooksSrc)) {
         copyDirRecursiveSync(hooksSrc, agyHooksDir);
         log.step(`Installed hooks to ${agyHooksDir}`);
@@ -3649,14 +3701,24 @@ function installGlobalHooks() {
     if (fs.existsSync(workflowsSrc)) {
         copyDirRecursiveSync(workflowsSrc, agyWorkflowsDir);
     }
-    mergeAntigravityHooks(path.join(geminiDir, 'config', 'hooks.json'));
-    if (fs.existsSync(path.join(geminiDir, 'antigravity-cli'))) {
-        mergeAntigravityHooks(path.join(geminiDir, 'antigravity-cli', 'hooks.json'));
+    mergeAntigravityHooks(path.join(targetGemini, 'config', 'hooks.json'));
+    const agyCliDir = path.join(targetGemini, 'antigravity-cli');
+    if (fs.existsSync(agyCliDir)) {
+        const agyCliHooksDir = path.join(agyCliDir, 'hooks');
+        const agyCliWorkflowsDir = path.join(agyCliDir, 'workflows');
+        if (fs.existsSync(hooksSrc)) {
+            copyDirRecursiveSync(hooksSrc, agyCliHooksDir);
+            log.step(`Installed hooks to ${agyCliHooksDir}`);
+        }
+        if (fs.existsSync(workflowsSrc)) {
+            copyDirRecursiveSync(workflowsSrc, agyCliWorkflowsDir);
+        }
+        mergeAntigravityHooks(path.join(agyCliDir, 'hooks.json'));
     }
 
     // 3. OpenAI Codex CLI
-    const codexHooksDir = path.join(homeDir, '.codex', 'hooks');
-    const codexWorkflowsDir = path.join(homeDir, '.codex', 'workflows');
+    const codexHooksDir = path.join(targetHome, '.codex', 'hooks');
+    const codexWorkflowsDir = path.join(targetHome, '.codex', 'workflows');
     if (fs.existsSync(hooksSrc)) {
         copyDirRecursiveSync(hooksSrc, codexHooksDir);
         log.step(`Installed hooks to ${codexHooksDir}`);
@@ -3664,12 +3726,12 @@ function installGlobalHooks() {
     if (fs.existsSync(workflowsSrc)) {
         copyDirRecursiveSync(workflowsSrc, codexWorkflowsDir);
     }
-    mergeCodexTomlHooks(path.join(homeDir, '.codex', 'config.toml'));
+    mergeCodexTomlHooks(path.join(targetHome, '.codex', 'config.toml'));
 
     // 4. OpenCode CLI
     const opencodeDir = process.platform === 'win32'
-        ? path.join(process.env.APPDATA || homeDir, 'opencode')
-        : path.join(homeDir, '.config', 'opencode');
+        ? path.join(process.env.APPDATA || targetHome, 'opencode')
+        : path.join(targetHome, '.config', 'opencode');
     const opencodePluginSrc = path.join(srcDir, '.opencode', 'plugins', 'bdb-aos.js');
     if (fs.existsSync(opencodePluginSrc)) {
         const opencodePluginsDir = path.join(opencodeDir, 'plugins');
@@ -3745,7 +3807,7 @@ 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'];
+    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.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
@@ -3817,7 +3879,7 @@ function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
 // Merge the BDB hooks into Google Antigravity's hooks.json (.agents/hooks.json or
 // ~/.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'];
+    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 : '')))
@@ -3834,7 +3896,14 @@ function mergeAntigravityHooks(hooksPath, { projectLocal = false } = {}) {
         PreToolUse: [
             {
                 matcher: "run_command|Bash",
-                hooks: [{ type: "command", command: `node "${path.join(hooksDir, 'go-gate.mjs')}"`, timeout: 10000 }]
+                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 }
+                ]
+            },
+            {
+                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: `node "${path.join(globalHooksDir, 'trail-relay.mjs')}" --agent agy --event PreToolUse`, timeout: 2000 }]
@@ -4856,18 +4925,24 @@ async function runQuickUpdate(installState) {
         injectHarnessRules();
     }, 'Harness files keep whatever version this machine already had.');
 
-    // OpenWiki setup only ever ran on a brand-new install (main()'s fresh-install
-    // branch below) -- an existing install running Quick Update never got offered
-    // it and never had its daemon schedule refreshed. promptCredentials() already
-    // detects an existing key and collapses to a single "keep existing" prompt in
-    // that case, so this is a no-op confirm for anyone already configured and a
-    // real one-time offer for anyone who isn't (including installs from before
-    // this feature existed).
+    // OpenWiki: if already configured, refresh the daemon silently (no prompt).
+    // Only ask when there is no key yet — i.e. a first-time offer or a machine
+    // that predates this feature. This avoids the "keep existing?" confirmation
+    // on every Quick Update for users who have already set up OpenWiki.
     if (!isAutoYes) {
-        const creds = await promptCredentials(paths.targetMcpDir);
-        if (creds !== BACK) {
-            await installOpenWikiDaemon(creds.gemini, paths.targetSkillDir, { provider: creds.openwikiProvider, model: creds.openwikiModel, baseUrl: creds.openwikiBaseUrl });
+        const _owEnv = loadExistingEnv(paths.targetMcpDir);
+        const _owProvider = _owEnv['OPENWIKI_PROVIDER'] || 'google';
+        const _owKeyName = PROVIDER_KEY_ENV_NAMES[_owProvider] || 'GEMINI_API_KEY';
+        const _owKey = _owEnv[_owKeyName] || _owEnv['GEMINI_API_KEY'] || _owEnv['GOOGLE_API_KEY'] || _owEnv['OPENWIKI_API_KEY'] || '';
+        if (_owKey || _owProvider === 'ollama') {
+            await installOpenWikiDaemon(_owKey, paths.targetSkillDir, { provider: _owProvider, model: _owEnv['OPENWIKI_MODEL'] || '', baseUrl: _owEnv['OPENWIKI_BASE_URL'] || '' });
             await installOpenWikiVisualizer();
+        } else {
+            const creds = await promptCredentials(paths.targetMcpDir);
+            if (creds !== BACK) {
+                await installOpenWikiDaemon(creds.gemini, paths.targetSkillDir, { provider: creds.openwikiProvider, model: creds.openwikiModel, baseUrl: creds.openwikiBaseUrl });
+                await installOpenWikiVisualizer();
+            }
         }
     }
 
@@ -4920,6 +4995,40 @@ function buildAoAnnouncementBanner() {
     ].join('\n');
 }
 
+// AOS CLI ships as a separate npm package under packages/ for one reason: pi
+// updates on its own cadence, and folding it into this release cycle would turn
+// every pi bump into a full AOS reinstall. So it installs as an ordinary global
+// package and pulls pi in as its own dependency -- and it writes nothing to
+// ~/.agents, because it reads that directory rather than owning it.
+function installAosCli() {
+    const pkgDir = path.join(srcDir, 'packages', 'aos-cli');
+    const manual = 'cd packages/aos-cli && npm install -g .';
+
+    if (!fs.existsSync(path.join(pkgDir, 'package.json'))) {
+        log.warn(`AOS CLI package missing at ${pkgDir} -- skipped. Install it later: ${manual}`);
+        return;
+    }
+    if (hasExecutable('aos-cli')) {
+        log.step('aos-cli is already on PATH.');
+        return;
+    }
+    if (DRY_RUN) {
+        log.step('[dry-run] would run: npm install -g <packages/aos-cli>');
+        return;
+    }
+
+    const res = installStep('install AOS CLI', () => {
+        log.step('Installing AOS CLI globally (pi is installed as its dependency)...');
+        execSync(`npm install -g ${JSON.stringify(pkgDir)}`, { stdio: 'ignore' });
+    }, `The rest of AOS is installed. Install AOS CLI later: ${manual}`);
+
+    if (res.ok && hasExecutable('aos-cli')) {
+        log.success('AOS CLI installed -- run `aos-cli`.');
+    } else if (res.ok) {
+        log.warn('AOS CLI is installed but `aos-cli` is not on PATH. launchd and some Windows shells start with a PATH that omits npm\'s global bin.');
+    }
+}
+
 async function main() {
     if (process.argv[2] === 'store') {
         const storeScript = path.join(srcDir, 'bin', 'aos-store.mjs');
@@ -5061,6 +5170,7 @@ async function main() {
         { value: '7', label: 'Roo Code / Cline / VS Code', hint: '~/.roo' },
         { value: '8', label: 'Aider CLI', hint: '~/.aider' },
         { value: '9', label: '📁 Local Project Harness', hint: 'copy dispatcher contract to current project' },
+        { value: '10', label: '🖥️ AOS CLI', hint: 'pi harness -- reads ~/.agents, no own skill copy' },
         { value: '4', label: '⚙️ Custom Installation', hint: 'specify paths manually' }
     ];
 
@@ -5090,7 +5200,7 @@ async function main() {
         selectedMcps = await promptMcpSelection(tier);
     } else {
         const ctx = { tier: '1', selectedPlatforms: ['0'], mode: 'merge', customPaths: null, creds: null, selectedMcps: null };
-        const platformNames = { '0': '🌐 Universal Harness', '1': 'Google Antigravity', '2': 'Claude Desktop/Code', '3': 'Cursor/Generic IDE', '4': 'Custom Paths', '5': 'ChatGPT Codex CLI', '6': 'Windsurf', '7': 'Roo Code / Cline / VS Code', '8': 'Aider CLI', '9': 'Local Project Harness' };
+        const platformNames = { '0': '🌐 Universal Harness', '1': 'Google Antigravity', '2': 'Claude Desktop/Code', '3': 'Cursor/Generic IDE', '4': 'Custom Paths', '5': 'ChatGPT Codex CLI', '6': 'Windsurf', '7': 'Roo Code / Cline / VS Code', '8': 'Aider CLI', '9': 'Local Project Harness', '10': 'AOS CLI' };
 
         const stepTier = async () => {
             const t = await selectWithBack({
@@ -5256,7 +5366,22 @@ async function main() {
         fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
     }, 'The installation continues, but existing files are not backed up.');
 
-    const targets = specificPlatforms.map(p => ({
+    // '10' is an action, not a directory target. AOS CLI reads
+    // ~/.agents/skills, which syncSkillsToGlobalHarnesses() already writes --
+    // left in this list it would fall through resolveTargetPaths()'s universal
+    // defaults and install a second full copy of every skill somewhere nobody
+    // reads them from.
+    const aosCliRequested = specificPlatforms.includes('10');
+    const dirPlatforms = specificPlatforms.filter(p => p !== '10');
+
+    if (aosCliRequested && dirPlatforms.length === 0) {
+        // AOS CLI alone would have no skills to load, and an empty target list
+        // leaves primaryTarget undefined for everything downstream of it.
+        log.warn('AOS CLI was the only target -- adding the universal skill target so it has something to load.');
+        dirPlatforms.push('1');
+    }
+
+    const targets = dirPlatforms.map(p => ({
         value: p,
         ...resolveTargetPaths(p, customPaths)
     }));
@@ -5343,10 +5468,13 @@ async function main() {
     // Flush file-level install manifest after all writes are done.
     flushSessionManifest();
 
+    // After the skill sync, because AOS CLI is useless without ~/.agents.
+    if (aosCliRequested) installAosCli();
+
     console.log('');
     verifyEcosystemInstallation();
 
-    outro(`🎉 Installation complete! Targets: ${targets.map(t => t.value).join(', ')} · Tier: ${tier === '1' ? 'Pro MEDIA' : 'Basic'}${DRY_RUN ? ' · DRY-RUN (nothing was modified)' : ''}`);
+    outro(`🎉 Installation complete! Targets: ${targets.map(t => t.value).join(', ')}${aosCliRequested ? ' + AOS CLI' : ''} · Tier: ${tier === '1' ? 'Pro MEDIA' : 'Basic'}${DRY_RUN ? ' · DRY-RUN (nothing was modified)' : ''}`);
 }
 
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.8.0",
+  "version": "4.9.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": {
@@ -24,8 +24,10 @@
     "validate": "node scripts/validate-skills.mjs",
     "validate:strict": "node scripts/validate-skills.mjs --strict",
     "store:index": "node scripts/build-ecc-store-index.mjs",
+    "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 tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs"
+    "test": "node scripts/validate-skills.mjs --selftest && node scripts/validate-skills.mjs && node scripts/build-plugin-manifest.mjs --check && node tests/aos-store.test.mjs && node tests/aos-doctor.test.mjs && node tests/build-plugin-manifest.test.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -58,6 +60,8 @@
     "mcps/",
     "scripts/",
     "vendor/",
+    "packages/aos-cli/",
+    "!packages/aos-cli/node_modules",
     "!mcps/**/*.png",
     "!mcps/**/*.jpg",
     "!mcps/**/*.jpeg",

package/packages/aos-cli/README.md

@@ -0,0 +1,80 @@
+# AOS CLI
+
+The AOS dispatcher contract and AOS skills, on the [pi](https://github.com/earendil-works/pi) coding agent.
+
+```
+aos-cli
+aos-cli "why is the go build failing"
+aos-cli --continue
+```
+
+## Which skills are loaded
+
+**Ten, not all of them.** pi advertises every discovered skill by name and description in *every* system prompt. Measured on this machine: 210 skills, **~11,150 tokens per request**, of which the four `firecrawl` entries alone are ~2,250. That is a permanent tax on every turn.
+
+`core-skills.json` narrows that to the handful worth having always:
+
+```
+ask-tim  aos-setup  aos-project-init  mcp-manage  systematic-debugging
+planning-with-files  token-saver-config  archify  deja-memory  grill-me
+```
+
+Edit the file. It is a flat list of directory names under `~/.agents/skills/`, nothing more.
+
+**The tradeoff, stated plainly:** a skill outside that list is not merely unadvertised — it is unreachable, `/skill:name` included. That is the cost of `--no-skills`, and it is why `aos-store` is how one gets added. If you want a skill in every session, put it in the list.
+
+Names that are not installed are skipped with a note rather than being fatal: the list should quietly shrink when a skill is pruned, not stop pi from starting.
+
+## In-session commands
+
+| | |
+|---|---|
+| `/aos-status` | Runs `aos-doctor --json` and shows every check, with the failing ones marked |
+| `/aos` | Menu: status, or the command to run outside for install / update / uninstall |
+
+Both are **read-only**. `aos-doctor --json` exits 1 whenever a check is not ok, which is the normal "something needs attention" answer, so the exit code is ignored and the report's own `ok` field decides. The install, update and uninstall entries do not spawn the installer: it animates and prompts, and nesting it inside pi's TUI corrupts both renderers. They report the command to run in a separate terminal instead.
+
+## What it actually is
+
+A launcher, not a reimplementation. It adds three things to a plain `pi`:
+
+| | |
+|---|---|
+| **AOS theme** | `themes/aos.json` — pi's `dark`, with the AOS palette (purple, amethyst, gold, forge, emerald, beige) |
+| **Dispatcher graph** | `~/.agents/AGENTS.md` appended to the system prompt |
+| **AOS skills** | nothing to do — pi already discovers `~/.agents/skills` (Agent Skills spec) |
+
+Everything else — the agent loop, the model providers, the TUI, sessions, MCP-less tool use — is pi's. AOS CLI does not fork pi and does not wrap it; it starts it with three flags.
+
+## What it deliberately does not do
+
+**It does not depend on `@hybridlabor-api/aos`.** It reads `~/.agents/` at runtime, which the `aos` installer writes. That is the whole contract:
+
+- AOS CLI and the AOS installer version and update independently. A pi update never drags in a 98 MB AOS reinstall.
+- AOS CLI runs without AOS installed — it just starts with no AOS skills and says so.
+- **It is not a pipeline executor.** The 7-node dispatcher graph reaches pi as instructions in `~/.agents/AGENTS.md`, not as machinery: the nodes are agent definitions, and the main session acts as the dispatcher, which is what `.agents/graph.md` specifies anyway. There is no `state.json` loop.
+- **No MCP.** pi has no MCP client, so memB, deja and mcsc are not available here. AOS CLI is a chat + skills harness; the other seven harnesses remain the machinery.
+
+## Install
+
+Through the AOS installer (picks this up automatically once the menu entry lands), or directly:
+
+```sh
+npm i -g @earendil-works/pi-coding-agent   # if you do not have pi yet
+cd packages/aos-cli && npm i && npm link
+```
+
+Requires Node >= 22.19 — pi's floor. The AOS installer itself still supports Node >= 20, because AOS CLI is a separate install step.
+
+## Layout
+
+```
+bin/aos-cli.mjs          the launcher (~40 lines)
+themes/aos.json          pi dark theme, AOS palette
+extensions/aos.ts        /aos and /aos-status
+scripts/check-theme.mjs  theme contract guard, run by `npm test`
+```
+
+## Licence
+
+MIT, same as AOS. pi is MIT, © the pi authors.