@hybridlabor-api/aos 4.16.0 → 4.17.0

package/docs/opencode-setup.md

@@ -0,0 +1,36 @@
+# OpenCode setup
+
+The AOS installer copies these into `~/.config/opencode` (`%APPDATA%\opencode` on Windows):
+
+- `plugins/bdb-aos.js` with `plugins/aos-hooks/` and `plugins/lib/` (go-gate, loop keeper, bus)
+- `commands/startcycle-graph.md` and one generated `commands/bdb-aos-<cmd>.md` per AOS command, called as `/bdb-aos-<cmd>` (flat hyphen names; a colon is not valid in Windows file names)
+
+The command files are generated from `plugin-commands.json` by `node scripts/build-plugin-manifest.mjs` and checked by `--check`. A command may carry `bodies.opencode`; without it the Claude body is used with `/bdb-aos:<cmd>` rewritten to `/bdb-aos-<cmd>`.
+
+## Updating and your edits
+
+- A command file you edited is kept; the shipped version lands next to it as `<file>.new`.
+- A file that already existed under a shipped name but was never installed by AOS is kept the same way.
+- The installer never deletes files it did not create.
+
+## Lean MCP set
+
+OpenCode deliberately runs a small MCP set (`memb_mcp`, `deja`, `zavora_computer_use`). AOS never copies other harnesses' MCP lists into OpenCode and never adds ComfyUI or show-control MCPs there. Media playbooks stop with "Missing MCP" on OpenCode by design.
+
+## Optional components (off by default)
+
+```bash
+AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk aos        # or: aos --opencode-optional=ponytail,loop,rtk
+```
+
+- `ponytail`: appends `@dietrichgebert/ponytail@4.10.0` to `plugin[]`
+- `loop`: appends `@bybrawe/opencode-loop@0.6.2` to `plugin[]`
+- `rtk`: prints `brew install rtk && rtk init -g --opencode`; AOS installs nothing
+
+Entries are appended only when no entry for that package exists, after a timestamped `opencode.jsonc.<ts>.bak` backup. AOS never runs foreign installers (the `opencode-loop` npx installer rewrites the config) and skips `orca-opencode-status.js` (the Orca app maintains it) and `dag.jsonc` / GraphAgent (AGPL engine, different program).
+
+## Known limits
+
+- **`/loop-shell` and the go-gate (unverified).** `opencode-loop` can run shell commands as child processes. `tool.execute.before`, where the AOS go-gate sits, may never see them. Do not schedule `git push`, publish or other gated commands through them. The installer prints this warning whenever `opencode-loop` is in `plugin[]`.
+- **Machine prompts are never human.** Every prompt the plugin sends itself (loop nudge, bus wake) is `synthetic` and carries `aos_loop` or `aos_bus` metadata, so it cannot count as a GO. A test scans the plugin source for this.
+- **Double loading of `bdb-aos.js`.** OpenCode auto-loads `plugins/*.{ts,js}` and also loads paths in `plugin[]`. From the 1.18.30 binary strings: both lists are merged through one de-duplication keyed on the `file://` URL, so the same absolute path loads once (read from the binary, not observed by running OpenCode). A differently spelled second path (checkout path, symlinked config dir) would load twice, giving two gates and two loop keepers. The installer registers exactly one path, `<config>/plugins/bdb-aos.js`, and warns when `plugin[]` holds another spelling.

package/docs/plugin-migration.md

@@ -0,0 +1,61 @@
+# Plugin registration and loose-copy migration
+
+The installer registers the `bdb-aos` plugin for Claude Code, then removes only its own loose skill copies there. Hooks, MCP servers, `trail-autostart` and the bus stay in the installer, so disabling the plugin never disables the go-gate.
+
+| Harness | Loose copies | Why |
+|---|---|---|
+| Claude Code | **removed** from `~/.claude/skills` only after registration **and** evidence that Claude Code installed the plugin | the plugin bundles the skills |
+| Codex | stay (`~/.codex/skills`) | the Codex plugin bundles only the command wrapper skills; nested skill scanning is unverified |
+| agy | stay (`~/.gemini/config/skills`) | skill bundling is unverified (`agy plugin validate` processed 9 skills) |
+| OpenCode | stay | plugins cannot bundle skills |
+| all | `~/.agents/skills` always stays as the shared store | |
+
+## Rules
+
+- **Registration first, evidence second.** Registration means `settings.json` holds the marketplace and `enabledPlugins` keys; that alone proves nothing about an installed plugin. Copies are removed only when Claude's plugin state shows the install: an entry for `bdb-aos@bdb-marketplace` in `~/.claude/plugins/installed_plugins.json`, or a cache directory `~/.claude/plugins/cache/bdb-marketplace/bdb-aos/<version>`. Either way the directory must resolve (realpath) under `~/.claude/plugins`, must not be cached from another (older external) marketplace, and must contain `skills/<name>/SKILL.md` for a skill the install manifest lists for `~/.claude/skills`. `installPath: "/"`, an empty `skills` dir or a path elsewhere do not count. The `installed_plugins.json` shape (`{version, plugins: {"<name>@<marketplace>": [{installPath, ...}]}}`) is verified against other plugins on a local machine; that `bdb-aos` writes the same shape and the cache layout fallback are **inferred**, not observed.
+- **Not verifiable yet.** The installer registers the plugin, keeps every copy and prints "restart Claude Code, then run the installer again to retire the loose copies". The retirement happens on a later run once the evidence exists. Until then the installer keeps writing `~/.claude/skills` as before.
+- **Ordering.** The migration runs before the install target loop. Once Claude is covered, `~/.claude/skills` is not written again, so a rerun changes nothing and creates no backup.
+- **Merge, never overwrite.** Other keys survive. `settings.json` is backed up (`settings.json.<ts>.bak`) before a change; an unchanged file is not rewritten. A symlinked `settings.json` is written through to its real file and stays a link.
+- **Opt-out.** `"bdb-aos@bdb-marketplace": false` in `enabledPlugins` (or `bdb-aos@<old external key>: false`): nothing is registered, nothing is removed.
+- **Own copies only, safely resolved.** A file is removed when the install manifest lists it and its bytes still match the recorded hash. Keys with `..` or relative paths are rejected; each file and the root are resolved with `path.resolve` and `fs.realpathSync`, the real file must be a regular file under the real root. If `~/.claude/skills` itself is a symlink, nothing is removed. Edited files and files not in the manifest stay.
+- **All or nothing.** If any listed copy is edited or unsafe, nothing is removed, Claude is not treated as covered, the installer names the skills involved and keeps updating the copies it owns. Move your edits out and run the installer again to retire them.
+- **OpenWiki daemon.** `openwiki-skill/scripts/` is never retired, and the daemon is installed and run from the installer-owned `~/.agents/skills/openwiki-skill/scripts` (copied there when missing), so scheduled jobs never point into `~/.claude/skills`.
+- **Malformed settings.** If `enabledPlugins` or `extraKnownMarketplaces` exists but is not a plain object, registration is refused and nothing is written.
+- **One at a time.** A lock file (`~/.agents/.bdb-plugin-migration.lock`, stale after ten minutes or a dead pid) keeps two migrations apart; a file that vanishes mid-run is skipped.
+- **Backup before removal.** Removed files are copied to `~/.agents/backups/plugin-migration-<timestamp>/` keeping their path relative to `$HOME`.
+- **External marketplace.** An entry pointing at `hybridlabor-api/bdb-marketplace` is replaced by this repo's marketplace (`hybridlabor-api/aos`) only when no other plugin id uses it. Only `bdb-aos@<oldkey>` is renamed to `bdb-aos@bdb-marketplace`; other plugins' ids are never renamed. A foreign marketplace that also lists other plugins stays in place. If the name `bdb-marketplace` itself is that external marketplace with other plugins, or points at another source, registration is refused with a message and nothing changes. Nothing on GitHub is changed.
+- **Old command files.** Command files from earlier versions that are no longer in the generated table are not touched by the migration; they are neither removed nor backed up. Only the generated `commands/` set is kept in sync by `scripts/build-plugin-manifest.mjs`.
+- **State.** `~/.agents/.bdb-plugin-migration.json` records each change: `addedMarketplace`, `addedEnabled`, `replaced`, `renames`, `keptForeign`. Deregistering reverses exactly those.
+
+## Packaging
+
+The npm package ships `plugins/bdb-aos-codex/` (a real directory) and the root manifests (`plugin.json`, `.codex-plugin/`, `.agents/plugins/marketplace.json`, `commands/`, `agy-commands/`). `plugins/bdb-aos/` is built from symlinks and is **not** in the npm package. The Claude Code plugin directory (`.claude-plugin/` and `plugins/bdb-aos/`) is git-only: Claude installs it from the GitHub marketplace `hybridlabor-api/aos`, not from npm. `.agents/plugins` (the Codex marketplace file) is excluded from the `.agents` copies into `~/.agents` and project directories.
+
+The root `.codex-plugin/.mcp.json` is no longer referenced: the previous manifest pointed at it through an `mcp_config` key, which real Codex plugins do not use (they use `mcpServers`). It stays unreferenced on purpose, because the installer already registers the MCP servers in Codex's config and the plugin would register them twice. The plugin therefore delivers no MCP servers.
+
+## Opt out and preview
+
+```bash
+AOS_PLUGIN_MIGRATION=off   npx -y @hybridlabor-api/aos@latest   # skip entirely
+AOS_PLUGIN_MIGRATION=check npx -y @hybridlabor-api/aos@latest   # report only
+npx -y @hybridlabor-api/aos@latest --plugin-migration=off|check
+```
+
+`--dry-run` implies `check`. Default is on.
+
+## Undo
+
+```bash
+aos-uninstall --restore-plugin-backup   # puts removed files back, never overwrites an existing file
+aos-uninstall                           # also removes the plugin registration it added and restores a replaced external marketplace
+```
+
+## Known limits
+
+- The lock guards migrations only. An installer copy running at the same moment in another process is not serialized; a file removed under it is skipped, and the next run reconciles.
+- Until Claude Code shows the plugin as installed, both copies exist; skills may then appear twice after the plugin loads and before the next installer run retires the copies.
+- `aos-doctor` accepts the plugin evidence as Claude having the skills.
+- A deregister that reverses a marketplace rename keeps the content of `enabledPlugins` but may reorder its keys (cosmetic).
+- Restoring a backup after an uninstall creates a new install manifest and puts the legacy `~/.claude/skills/startcycle` marker back, so AOS is detected as installed again.
+
+Backups survive uninstall (the state keeps its backup index and `~/.agents/backups/plugin-migration-*` is scanned), so `--restore-plugin-backup` also works afterwards. Restored files are recorded in the install manifest, and the restore deregisters the plugin so skills are not loaded twice; the restore also sets `bdb-aos@bdb-marketplace` to `false` in `settings.json` (the opt-out), so the next installer run does not register the plugin or retire the restored files. Set it back to `true` to migrate again.

package/installer.js

@@ -23,6 +23,7 @@ const net = require('net');
 const readline = require('readline');
 const util = require('util');
 const crypto = require('crypto');
+const pluginMigration = require('./lib/plugin-migration');
 
 function verifyDaemonListening(port, name, timeoutMs = 4000) {
     return new Promise((resolve) => {
@@ -1277,9 +1278,94 @@ function reportFatal(stage, e) {
     process.exitCode = 1;
 }
 
+// AOS_PLUGIN_MIGRATION=off skips plugin registration and loose-copy removal; =check only reports.
+function pluginMigrationMode(argv = process.argv, env = process.env) {
+    const flag = argv.find((a) => a.startsWith('--plugin-migration='));
+    const raw = String(flag ? flag.slice('--plugin-migration='.length) : (env.AOS_PLUGIN_MIGRATION || '')).trim().toLowerCase();
+    if (raw === 'off' || raw === '0' || raw === 'false') return 'off';
+    return raw === 'check' || DRY_RUN ? 'check' : 'on';
+}
+
+// .agents/plugins holds the Codex marketplace file; it belongs to the repo checkout, not to ~/.agents or a project.
+const AGENTS_COPY_EXCLUDE = ['plugins'];
+
+let _pluginMigration = null;
+function runPluginMigration({ targetHome = homeDir, detected = null, mode = pluginMigrationMode(), registrars } = {}) {
+    if (_pluginMigration && targetHome === homeDir) return _pluginMigration;
+    const keys = detected || detectPlatforms().map((d) => d.key);
+    const ownsManifest = !_sessionManifest;
+    const manifest = _sessionManifest || loadInstallManifest();
+    let result;
+    try {
+        result = pluginMigration.migrate({ home: targetHome, manifest, detected: keys, mode, ...(registrars ? { registrars } : {}) });
+    } catch (e) {
+        log.warn(`Plugin migration skipped: ${e.message}`);
+        result = { covered: new Set(), lines: [] };
+    }
+    for (const line of result.lines) log.step(line);
+    if (ownsManifest && mode === 'on') saveInstallManifest(manifest);
+    if (targetHome === homeDir) _pluginMigration = result;
+    return result;
+}
+
+// The plugin migration runs first: when it retires Claude's loose copies, ~/.claude/skills is not
+// written again, so a rerun neither recreates nor re-backs-up what the plugin now delivers.
+function installTargetSkills(targets, { mode, backupDir, excludeSkills, skillsBase }) {
+    const detected = detectPlatforms().map((d) => d.key);
+    if (targets.some((t) => t.value === '2') && !detected.includes('claudecode')) detected.push('claudecode');
+    const pluginCovered = runPluginMigration({ detected }).covered;
+
+    for (const t of targets) {
+        const viaPlugin = t.value === '2' && pluginCovered.has('claudecode');
+        if (mode === 'replace') {
+            if (!viaPlugin) {
+                moveIfExists(t.targetSkillDir, path.join(backupDir, `config_skills_backup_${t.value}`), `global config skills (${t.value})`);
+                moveIfExists(t.targetLegacyDir, path.join(backupDir, `legacy_skills_backup_${t.value}`), `legacy skills (${t.value})`);
+            }
+            moveIfExists(t.targetWorkspaceDir, path.join(backupDir, `workspace_skills_backup_${t.value}`), `workspace skills (${t.value})`);
+        }
+
+        installStep(`create the skill target directories (${t.value})`, () => {
+            if (!viaPlugin) {
+                fs.mkdirSync(t.targetSkillDir, { recursive: true });
+                retireObsoleteLegacyDir(t.targetLegacyDir);
+            }
+            fs.mkdirSync(t.targetWorkspaceDir, { recursive: true });
+        }, 'The skill copies below will most likely be skipped as well.');
+
+        if (fs.existsSync(skillsBase)) {
+            installStep(`install the skills (${t.value})`, () => {
+                const rawDirs = fs.readdirSync(skillsBase);
+                const dirs = rawDirs.sort((a, b) => {
+                    const aIsLeaf = fs.existsSync(path.join(skillsBase, a, 'SKILL.md'));
+                    const bIsLeaf = fs.existsSync(path.join(skillsBase, b, 'SKILL.md'));
+                    if (aIsLeaf && !bIsLeaf) return 1;
+                    if (!aIsLeaf && bIsLeaf) return -1;
+                    return 0;
+                });
+                for (const dir of dirs) {
+                    const fullPath = path.join(skillsBase, dir);
+                    if (!fs.statSync(fullPath).isDirectory()) continue;
+
+                    if (viaPlugin && dir !== 'workspace_agents') continue;
+                if (dir === 'global_legacy') {
+                        copyDirRecursiveSync(fullPath, t.targetLegacyDir, excludeSkills);
+                    } else if (dir === 'workspace_agents') {
+                        copyDirRecursiveSync(fullPath, t.targetWorkspaceDir, excludeSkills);
+                    } else {
+                        syncSkillEntry(fullPath, dir, t.targetSkillDir, excludeSkills);
+                    }
+                }
+                log.step(`Installed all global config & core skills to ${t.targetSkillDir}`);
+            }, 'The skills are missing or incomplete; the rest of the installation continues.');
+        }
+    }
+}
+
 function syncSkillsToGlobalHarnesses(excludeSkills = []) {
     const skillsBase = path.join(srcDir, 'skills');
     if (!fs.existsSync(skillsBase)) return;
+    const pluginCovered = runPluginMigration().covered;
 
     // Mirror only into harnesses that are actually present. This list used to
     // be unconditional, which both wrote skills nobody would read and planted
@@ -1300,7 +1386,7 @@ function syncSkillsToGlobalHarnesses(excludeSkills = []) {
         { 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));
+    ].filter((d) => d.key === null || (detectedKeys.has(d.key) && !pluginCovered.has(d.key)));
 
     for (const { dir: dest } of extraSkillDestinations) {
         try {
@@ -1549,6 +1635,17 @@ async function promptCredentials(referenceMcpDir) {
 
 const DAEMON_LOGON_FALLBACK_EXIT_CODE = 10;
 
+// The daemon job points at these scripts for good, so they live in the installer-owned shared store
+// (~/.agents/skills), which the plugin migration never retires, not in ~/.claude/skills.
+function stableOpenWikiScripts() {
+    const dest = path.join(homeDir, '.agents', 'skills', 'openwiki-skill');
+    if (!fs.existsSync(path.join(dest, 'scripts', 'install_daemon.sh'))) {
+        const src = path.join(srcDir, 'skills', 'global_config', 'openwiki-skill');
+        if (fs.existsSync(src)) copyDirRecursiveSync(src, dest);
+    }
+    return path.join(dest, 'scripts');
+}
+
 async function installOpenWikiDaemon(apiKey, targetSkillDir, openwikiEnv = {}) {
     const prov = openwikiEnv.provider || "google";
     if (!apiKey && !["ollama", "lmstudio"].includes(prov)) {
@@ -1562,7 +1659,7 @@ async function installOpenWikiDaemon(apiKey, targetSkillDir, openwikiEnv = {}) {
     const s = spinner();
     s.start('Installing OpenWiki Daemon...');
 
-    const scriptBase = path.join(targetSkillDir, 'openwiki-skill', 'scripts');
+    const scriptBase = stableOpenWikiScripts();
 
     const daemonEnv = Object.assign({}, process.env, {
         OPENWIKI_PROVIDER:  prov,
@@ -3886,7 +3983,7 @@ function injectHarnessRules() {
                     const targetPath = path.join(homeDir, dir);
                     // settings.json is merged separately below: a wholesale
                     // copy would clobber user-owned keys like enabledPlugins.
-                    const exclude = dir === '.claude' ? ['settings.json'] : [];
+                    const exclude = dir === '.claude' ? ['settings.json'] : dir === '.agents' ? AGENTS_COPY_EXCLUDE : [];
                     copyDirRecursiveSync(sourcePath, targetPath, exclude);
                     log.step(`Copied ${dir} to ${targetPath}`);
                 }
@@ -3898,13 +3995,109 @@ function injectHarnessRules() {
             const globalAgentsDir = path.join(os.homedir(), '.agents');
             const agentsDirSrc = path.join(srcDir, '.agents');
             if (fs.existsSync(agentsDirSrc)) {
-                copyDirRecursiveSync(agentsDirSrc, globalAgentsDir);
+                copyDirRecursiveSync(agentsDirSrc, globalAgentsDir, AGENTS_COPY_EXCLUDE);
                 log.step(`Synced global .agents/ to ${globalAgentsDir}`);
             }
         }, 'agents.md and workflows/startcycle.md may be missing globally.');
     }
 }
 
+// Optional third-party OpenCode components. Off unless named in
+// AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk or --opencode-optional=ponytail,loop,rtk.
+// Pinned entries only; the foreign installers (opencode-loop's npx installer, rtk init)
+// are never run because they rewrite the user's opencode config.
+const OPENCODE_OPTIONAL_PINS = {
+    ponytail: '@dietrichgebert/ponytail@4.10.0',
+    loop: '@bybrawe/opencode-loop@0.6.2',
+};
+const OPENCODE_RTK_HINT = 'rtk is not installed by AOS. Run yourself: brew install rtk && rtk init -g --opencode';
+const OPENCODE_LOOP_SHELL_WARNING = 'opencode-loop: /loop-shell style commands run shell commands as child processes. ' +
+    'tool.execute.before, and so the AOS go-gate, may never see them (unverified). ' +
+    'Do not schedule git push, publish or other gated commands through them.';
+
+function parseOpencodeOptional(argv = process.argv, env = process.env) {
+    const flag = argv.find((a) => a.startsWith('--opencode-optional='));
+    const raw = [env.AOS_OPENCODE_OPTIONAL, flag && flag.slice('--opencode-optional='.length)].filter(Boolean).join(',');
+    return new Set(raw.split(',').map((x) => x.trim().toLowerCase()).filter(Boolean));
+}
+
+const pluginPackageName = (entry) => {
+    const str = typeof entry === 'string' ? entry : (Array.isArray(entry) ? String(entry[0]) : '');
+    return str.replace(/(?<=.)@[^@/]*$/, '');
+};
+
+// OpenCode auto-loads plugins/*.js and also loads plugin[] paths, then dedupes by file
+// URL (verified in the 1.18.30 binary strings, not by running it). Same path = one load;
+// a second differing spelling would load the gate and loop keeper twice.
+function warnOnDuplicateAosPlugin(plugins, canonical) {
+    const norm = (v) => String(Array.isArray(v) ? v[0] : v).replace(/\\/g, '/');
+    const others = plugins.filter((p) => /bdb-aos\.js$/.test(norm(p)) && norm(p) !== canonical);
+    if (others.length > 0) {
+        log.warn(`opencode.jsonc lists bdb-aos.js under another path (${others.map(norm).join(', ')}). ` +
+            `plugins/bdb-aos.js is auto-loaded too; remove the extra entry to avoid a double gate.`);
+    }
+}
+
+function appendOptionalOpencodePlugins(data, configPath, optional) {
+    const wanted = optional instanceof Set ? optional : new Set(optional || []);
+    for (const name of wanted) {
+        if (!(name in OPENCODE_OPTIONAL_PINS) && name !== 'rtk') log.warn(`Unknown OpenCode optional component "${name}" ignored.`);
+    }
+    if (wanted.has('rtk')) log.message(OPENCODE_RTK_HINT);
+    let backedUp = false;
+    for (const name of Object.keys(OPENCODE_OPTIONAL_PINS)) {
+        if (!wanted.has(name) || DRY_RUN) continue;
+        const pin = OPENCODE_OPTIONAL_PINS[name];
+        if (data.plugin.some((p) => pluginPackageName(p) === pluginPackageName(pin))) continue;
+        if (!backedUp && configPath && fs.existsSync(configPath)) {
+            const bak = `${configPath}.${timestamp}.bak`;
+            try { fs.copyFileSync(configPath, bak); backedUp = true; } catch (e) {
+                log.warn(`Could not back up ${configPath}, skipping optional ${name}: ${e.message}`);
+                continue;
+            }
+        }
+        data.plugin.push(pin);
+        log.step(`Added opt-in OpenCode plugin ${pin}`);
+    }
+    if (data.plugin.some((p) => pluginPackageName(p) === pluginPackageName(OPENCODE_OPTIONAL_PINS.loop))) {
+        log.warn(OPENCODE_LOOP_SHELL_WARNING);
+    }
+}
+
+// Idempotent and edit-safe: a file is overwritten only when it is absent, already
+// identical, or still byte-equal to what this installer last recorded. Anything else
+// (user edit, or an untracked file with the same name) is kept and the shipped copy
+// lands as <file>.new. Files the installer did not create are never removed.
+function installOpencodeCommands(srcDirPath, destDirPath) {
+    if (DRY_RUN) {
+        log.message(`[dry-run] install OpenCode commands: ${srcDirPath} -> ${destDirPath}`);
+        return;
+    }
+    const ownsManifest = !_sessionManifest;
+    const manifest = _sessionManifest || loadInstallManifest();
+    fs.mkdirSync(destDirPath, { recursive: true });
+    let wrote = 0;
+    for (const file of fs.readdirSync(srcDirPath)) {
+        const src = path.join(srcDirPath, file);
+        if (!fs.statSync(src).isFile()) continue;
+        const dest = path.join(destDirPath, file);
+        const srcHash = computeFileHash(src);
+        const diskHash = fs.existsSync(dest) ? computeFileHash(dest) : null;
+        if (diskHash === null || diskHash === srcHash || diskHash === manifest[dest]?.sha256) {
+            if (diskHash !== srcHash) { fs.copyFileSync(src, dest); wrote++; }
+            manifest[dest] = { path: dest, sha256: srcHash, version: pkg.version, installedAt: new Date().toISOString() };
+        } else {
+            fs.copyFileSync(src, `${dest}.new`);
+            keptUserEdits.push(dest);
+        }
+    }
+    if (ownsManifest) {
+        saveInstallManifest(manifest);
+        reportKeptUserEdits();
+    }
+    log.step(`OpenCode commands in ${destDirPath}: ${wrote} written`);
+}
+
 // Copy the OpenCode plugin + command payload and register both in
 // opencode.jsonc. This is the single copy site: the Quick Update path
 // (injectHarnessRules -> installGlobalHooks) and the fresh-install path
@@ -3915,7 +4108,7 @@ function injectHarnessRules() {
 // Sync merges MCP servers in the same pass and writes once). When `data` is
 // omitted the function loads and saves the config itself, which is what lets the
 // Quick Update path register the plugin as well as copy it.
-function installOpencodePlugin({ targetHome = homeDir, configPath = null, data = null } = {}) {
+function installOpencodePlugin({ targetHome = homeDir, configPath = null, data = null, optional = parseOpencodeOptional() } = {}) {
     const opencodeDir = configPath
         ? path.dirname(configPath)
         : (process.platform === 'win32'
@@ -3952,13 +4145,11 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         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.
+    // Slash-command payloads (/startcycle-graph and the generated /bdb-aos-<cmd> files).
     const commandsSrc = path.join(srcDir, '.opencode', 'commands');
     if (fs.existsSync(commandsSrc)) {
         try {
-            copyDirRecursiveSync(commandsSrc, path.join(opencodeDir, 'commands'));
-            log.step(`Installed OpenCode commands to ${path.join(opencodeDir, 'commands')}`);
+            installOpencodeCommands(commandsSrc, path.join(opencodeDir, 'commands'));
         } catch (e) {
             log.warn(`Could not install OpenCode commands: ${e.message}`);
         }
@@ -3985,6 +4176,8 @@ function installOpencodePlugin({ targetHome = homeDir, configPath = null, data =
         return str.includes('bdb-aos');
     });
     if (!alreadyRegistered) data.plugin.push(pluginPathNormalized);
+    warnOnDuplicateAosPlugin(data.plugin, pluginPathNormalized);
+    appendOptionalOpencodePlugins(data, configPath, optional);
 
     // Skill paths. `.agents/skills` stays project-relative on purpose: it is the
     // per-project contract, and OpenCode resolves it against each project, so it
@@ -4150,7 +4343,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', 'go-token.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+    const bdbHookScripts = ['go-gate.mjs', 'go-token.mjs', 'go-grant.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
@@ -4557,7 +4750,7 @@ function installProjectHarness() {
     installStep('copy .agents/ contract into project', () => {
         const agentsSrc = path.join(srcDir, '.agents');
         if (!fs.existsSync(agentsSrc)) throw new Error(`missing payload: ${agentsSrc}`);
-        copyDirRecursiveSync(agentsSrc, projectAgentsDir);
+        copyDirRecursiveSync(agentsSrc, projectAgentsDir, AGENTS_COPY_EXCLUDE);
         log.step(`Copied .agents/ contract to ${projectAgentsDir}`);
     }, 'graph.md / state.schema.json may be missing in the project.');
 
@@ -5655,11 +5848,11 @@ function installBinaryAtomically(src, dest) {
 
 async function main() {
     const args = process.argv.slice(2);
-    if (args.includes('--version') || args.includes('-V')) {
+    if (args.includes('--version') || args.includes('-V') || args[0] === 'version') {
         console.log(pkg.version);
         return;
     }
-    if (args.includes('--help') || args.includes('-h')) {
+    if (args.includes('--help') || args.includes('-h') || args[0] === 'help') {
         console.log(`Usage: aos [command] [options]
 
 Commands:
@@ -5669,6 +5862,15 @@ Commands:
 Options:
   -y, --yes        Non-interactive install (implied without a TTY)
   --dry-run        Show what would change
+  --opencode-optional=LIST
+                   Opt in to OpenCode extras (comma list: ponytail, loop, rtk), or set
+                   AOS_OPENCODE_OPTIONAL. Pinned plugin[] entries are appended after a
+                   config backup; rtk only prints a brew hint. Off by default. AOS never
+                   runs foreign installers and never touches OpenCode's mcp set.
+  --plugin-migration=off|check
+                   Skip (off) or only report (check) the bdb-aos plugin registration and
+                   removal of AOS's own loose skill copies; same as AOS_PLUGIN_MIGRATION.
+                   --dry-run implies check. Default: on.
   --verbose, -v    Verbose output
   -V, --version    Print the version and exit
   -h, --help       Print this help and exit`);
@@ -6036,45 +6238,7 @@ Options:
     const s = spinner();
     s.start(`Installing optimized skills${tier === '2' ? ' [Basic Tier]' : ''} to ${targets.length} target(s)...`);
 
-    for (const t of targets) {
-        if (mode === 'replace') {
-            moveIfExists(t.targetSkillDir, path.join(backupDir, `config_skills_backup_${t.value}`), `global config skills (${t.value})`);
-            moveIfExists(t.targetLegacyDir, path.join(backupDir, `legacy_skills_backup_${t.value}`), `legacy skills (${t.value})`);
-            moveIfExists(t.targetWorkspaceDir, path.join(backupDir, `workspace_skills_backup_${t.value}`), `workspace skills (${t.value})`);
-        }
-
-        installStep(`create the skill target directories (${t.value})`, () => {
-            fs.mkdirSync(t.targetSkillDir, { recursive: true });
-            retireObsoleteLegacyDir(t.targetLegacyDir);
-            fs.mkdirSync(t.targetWorkspaceDir, { recursive: true });
-        }, 'The skill copies below will most likely be skipped as well.');
-
-        if (fs.existsSync(skillsBase)) {
-            installStep(`install the skills (${t.value})`, () => {
-                const rawDirs = fs.readdirSync(skillsBase);
-                const dirs = rawDirs.sort((a, b) => {
-                    const aIsLeaf = fs.existsSync(path.join(skillsBase, a, 'SKILL.md'));
-                    const bIsLeaf = fs.existsSync(path.join(skillsBase, b, 'SKILL.md'));
-                    if (aIsLeaf && !bIsLeaf) return 1;
-                    if (!aIsLeaf && bIsLeaf) return -1;
-                    return 0;
-                });
-                for (const dir of dirs) {
-                    const fullPath = path.join(skillsBase, dir);
-                    if (!fs.statSync(fullPath).isDirectory()) continue;
-
-                    if (dir === 'global_legacy') {
-                        copyDirRecursiveSync(fullPath, t.targetLegacyDir, excludeSkills);
-                    } else if (dir === 'workspace_agents') {
-                        copyDirRecursiveSync(fullPath, t.targetWorkspaceDir, excludeSkills);
-                    } else {
-                        syncSkillEntry(fullPath, dir, t.targetSkillDir, excludeSkills);
-                    }
-                }
-                log.step(`Installed all global config & core skills to ${t.targetSkillDir}`);
-            }, 'The skills are missing or incomplete; the rest of the installation continues.');
-        }
-    }
+    installTargetSkills(targets, { mode, backupDir, excludeSkills, skillsBase });
 
     syncSkillsToGlobalHarnesses(excludeSkills);
     pruneRemovedSkills(_sessionManifest);
@@ -6154,6 +6318,10 @@ module.exports = {
     mergeCodexTomlMcpServers,
     installGlobalHooks,
     installOpencodePlugin,
+    installOpencodeCommands,
+    parseOpencodeOptional,
+    pluginMigrationMode,
+    runPluginMigration,
     installProjectHarness,
     promptMcpSelection,
     mirrorMcpServersTo,
@@ -6166,6 +6334,9 @@ module.exports = {
     resolveFileConflict,
     buildKnownSourceHashes,
     initSessionManifest,
+    installTargetSkills,
+    stableOpenWikiScripts,
+    AGENTS_COPY_EXCLUDE,
     flushSessionManifest,
     copyDirRecursiveSync,
     INSTALL_MANIFEST_PATH,