@hybridlabor-api/aos 4.16.0 → 4.18.0

package/THIRD_PARTY_NOTICES.md

@@ -309,7 +309,7 @@ dependency.
 
 <https://github.com/BuilderIO/skills> — MIT. Copyright (c) 2026 Builder.io.
 
-Eleven skills are adapted under `skills/global_config/`: `read-the-damn-docs`, `stay-within-limits`, `quick-recap`, `plan-arbiter`, `factory-human-digest`, `factory-collect`, `factory-lookback`, `factory-review-prs`, `visual-plan`, `visual-recap`, and `visual-edit`. The four Factory skills and `plan-arbiter` have `installer-group` dropped and `category`/`source` added; in `factory-collect`, `factory-lookback` and `factory-review-prs` reply, close, approve, merge and publish actions are reduced to drafts or readiness reports that need the user's GO, and all of them carry an "AOS safety rules" section. `plan-arbiter` drops `agents/openai.yaml` and adds an AOS section on double plans. `stay-within-limits` and `quick-recap` are carried over with `category:` and `source:` added; `stay-within-limits` pins `ccusage` to 20.0.26 instead of `@latest`, and `quick-recap` no longer asks the installer to inject a managed `AGENTS.md` / `CLAUDE.md` block. The three visual skills (`visual-plan`, `visual-recap`, `visual-edit`) are optional and drive the Agent-Native Plan/Design services through MCP connectors (`plan` and `design`) that AOS does NOT register; you connect them yourself if needed. Each carries an "AOS notes" section. `read-the-damn-docs` is described below:
+Eight skills are adapted under `skills/global_config/`: `read-the-damn-docs`, `stay-within-limits`, `quick-recap`, `plan-arbiter`, `factory-human-digest`, `factory-collect`, `factory-lookback`, and `factory-review-prs`. The four Factory skills and `plan-arbiter` have `installer-group` dropped and `category`/`source` added; in `factory-collect`, `factory-lookback` and `factory-review-prs` reply, close, approve, merge and publish actions are reduced to drafts or readiness reports that need the user's GO, and all of them carry an "AOS safety rules" section. `plan-arbiter` drops `agents/openai.yaml` and adds an AOS section on double plans. `stay-within-limits` and `quick-recap` are carried over with `category:` and `source:` added; `stay-within-limits` pins `ccusage` to 20.0.26 instead of `@latest`, and `quick-recap` no longer asks the installer to inject a managed `AGENTS.md` / `CLAUDE.md` block. `read-the-damn-docs` is described below:
 the docs-first trigger list, the source hierarchy, the required workflow, the
 must-trigger examples, and the "if docs are unavailable" rule. AOS additionally
 adds a Verification section, a `category:` key (Builder's own validator forbids
@@ -318,7 +318,7 @@ guesswork* rule, and a pointer to the installed `firecrawl-search` /
 `firecrawl-scrape` tools. Prose only — the upstream `agents/openai.yaml` and
 README were not carried over, and no executable from the repo is referenced.
 
-In the three visual skills, five path-like mentions (`/sign-in`, `/live-edit-bridge`, `/read-file`, `/write-file`, `/visualize-repo`) were reworded so the AOS validator does not read them as skill references. The other 13 skills in that repo (as of commit 0dba9ef) are **not** vendored. Three of them
+The other 13 skills in that repo (as of commit 0dba9ef) are **not** vendored. Three of them
 (`an`, `turn-into-app`, `rewind`) plus three others
 are build artefacts synced from a different upstream by
 `scripts/sync-agent-native-skills.mjs`, and the repo's own documentation says

package/agy-commands/loop.md

@@ -0,0 +1,5 @@
+---
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates."
+---
+
+Unverified, no loop mechanism confirmed for agy. Manual repeat: fill a `loop-templates` template, re-send it yourself at each interval, and stop at its limits or stop condition. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: whatever the user wrote after the command name

package/bin/aos-acp.mjs

@@ -14,10 +14,11 @@
 import { spawn } from "node:child_process";
 import { appendFileSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
 import { GUARDED_PATTERNS, slug, tokenGrantsGo } from "../.claude/hooks/go-gate.mjs";
+import { emitTrail } from "../mcps/mcsc/packages/core/src/trail.js";
 
 export const ADAPTERS = {
   claude: { cmd: ["npx", "-y", "@agentclientprotocol/claude-agent-acp"], consume: false },
@@ -113,6 +114,25 @@ export class AcpClient {
   notify(method, params) { this.write({ jsonrpc: "2.0", method, params }); }
 }
 
+// Same agenttrail protocol as mcsc's adapters (SessionStart/SessionEnd, PreToolUse/PostToolUse),
+// so the GO board reads ACP workers and mcsc runs from one source.
+const cap = (t) => (t ? t.charAt(0).toUpperCase() + t.slice(1) : "Tool");
+
+export function trailToolEvent(u, seen, cwd) {
+  const prev = seen.get(u.toolCallId) || {};
+  const info = { title: u.title ?? prev.title, kind: u.kind ?? prev.kind };
+  seen.set(u.toolCallId, info);
+  const done = u.status === "completed" || u.status === "failed";
+  if (u.sessionUpdate === "tool_call_update" && !done) return null;
+  const tool_input = {};
+  const file = u.locations?.[0]?.path ?? prev.file;
+  if (typeof file === "string" && file) tool_input.file_path = isAbsolute(file) ? file : resolve(cwd, file);
+  info.file = tool_input.file_path;
+  const command = commandOf(u);
+  if (command) tool_input.command = command;
+  return { hook_event_name: done ? "PostToolUse" : "PreToolUse", tool_name: cap(info.kind || info.title), tool_input };
+}
+
 function textOf(block) {
   return block && block.type === "text" ? block.text : "";
 }
@@ -134,6 +154,9 @@ export async function run(opts) {
   const consume = opts.consume ?? adapter?.consume ?? true;
   log("start", { adapter: opts.adapter, cmd: cmd.join(" "), cwd: opts.cwd, allow_default: opts.allowDefault, consume, model: opts.model || "adapter default" });
 
+  const trail = { session_id: `aos-acp-${process.pid}-${Date.now()}`, cwd: opts.cwd, agent: `${opts.adapter}:${opts.name}` };
+  const seenTools = new Map();
+  emitTrail({ ...trail, hook_event_name: "SessionStart" });
   let sessionId;
   const out = opts.stdout || process.stdout;
   const client = new AcpClient(cmd, {
@@ -148,6 +171,8 @@ export async function run(opts) {
         if (t) { out.write(t); log("text", { text: t }); }
       } else if (u.sessionUpdate === "tool_call" || u.sessionUpdate === "tool_call_update") {
         log(u.sessionUpdate, { id: u.toolCallId, title: u.title, kind: u.kind, status: u.status, command: commandOf(u) || undefined });
+        const ev = trailToolEvent(u, seenTools, opts.cwd);
+        if (ev) emitTrail({ ...trail, ...ev });
       } else log("update", { kind: u.sessionUpdate });
     },
     onRequest: (method, p) => {
@@ -182,6 +207,7 @@ export async function run(opts) {
   } finally {
     if (timer) clearTimeout(timer);
     client.child.kill();
+    await emitTrail({ ...trail, hook_event_name: "SessionEnd" });
   }
 }
 

package/bin/aos-doctor.mjs

@@ -12,6 +12,7 @@ import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 
+const pm = createRequire(import.meta.url)('../lib/plugin-migration.js');
 const HOME = os.homedir();
 const JSON_OUT = process.argv.includes('--json');
 const NET = process.argv.includes('--net');
@@ -168,6 +169,40 @@ function checkAosCore() {
   }
 }
 
+// JSONC to JSON: drops comments (not inside strings) and trailing commas.
+function parseJsonc(text) {
+  let out = '';
+  for (let i = 0, str = false; i < text.length; i++) {
+    const c = text[i];
+    if (str) { out += c; if (c === '\\') out += text[++i] ?? ''; else if (c === '"') str = false; continue; }
+    if (c === '"') { str = true; out += c; continue; }
+    if (c === '/' && text[i + 1] === '/') { while (i < text.length && text[i] !== '\n') i++; out += '\n'; continue; }
+    if (c === '/' && text[i + 1] === '*') { i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++; i++; continue; }
+    out += c;
+  }
+  try { return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1')); } catch { return null; }
+}
+
+// Zen gateway limit: a tool name (OpenCode builds it from the MCP server name) is at most 64 characters.
+// Names only, no network: the tool part of the name is not known here.
+const ZEN_TOOL_NAME_MAX = 64;
+
+function checkOpencodeMcpNames() {
+  const dirs = [process.platform === 'win32' ? path.join(process.env.APPDATA || HOME, 'opencode') : h('.config', 'opencode')];
+  const file = firstExisting(dirs.flatMap((d) => ['opencode.jsonc', 'opencode.json'].map((f) => path.join(d, f))));
+  if (!file) return;
+  const conf = parseJsonc(readFileSync(file, 'utf8'));
+  if (!conf) {
+    add('harnesses', 'OpenCode MCP names', false, `${tilde(file)} is not valid JSON(C); names not checked`, 'Fix the OpenCode config syntax.', true);
+    return;
+  }
+  const names = Object.keys(conf.mcp && typeof conf.mcp === 'object' ? conf.mcp : {});
+  const tooLong = names.filter((n) => n.length > ZEN_TOOL_NAME_MAX);
+  add('harnesses', 'OpenCode MCP names', tooLong.length === 0,
+    tooLong.length ? `${tooLong.length} MCP name(s) over ${ZEN_TOOL_NAME_MAX} characters (Zen gateway limit): ${tooLong.join(', ')}` : `${names.length} MCP name(s) in ${tilde(file)}, none over ${ZEN_TOOL_NAME_MAX} characters`,
+    `Rename the MCP server(s) in ${tilde(file)} to a shorter name; tool names are built from them and a name over ${ZEN_TOOL_NAME_MAX} characters is rejected by the Zen gateway. Keeping the MCP set lean also helps.`, true);
+}
+
 // ---------------------------------------------------------------- 3. Harness Placement & Skills Sync
 function checkHarnesses() {
   const harnesses = [
@@ -183,10 +218,11 @@ function checkHarnesses() {
     const exists = existsSync(hr.path);
     const count = dirCount(hr.path);
     const hasSentinel = existsSync(path.join(hr.path, SENTINEL, 'SKILL.md'));
-    const ok = exists && count > 0 && hasSentinel;
+    const viaPlugin = hr.name === 'Claude Code' && !hasSentinel && pm.pluginInstalled(HOME, [SENTINEL]);
+    const ok = viaPlugin || (exists && count > 0 && hasSentinel);
     add('harnesses', `${hr.name} Skills`, ok,
-      ok ? `${tilde(hr.path)} (${count} skills, sentinel verified)` : (exists ? `${tilde(hr.path)} (${count} skills, sentinel missing)` : `${tilde(hr.path)} not synced`),
-      `Run 'npx @hybridlabor-api/aos@latest' and select ${hr.name} to sync skills.`, !exists);
+      viaPlugin ? 'delivered by the bdb-aos Claude Code plugin (installed_plugins.json / plugin cache)' : ok ? `${tilde(hr.path)} (${count} skills, sentinel verified)` : (exists ? `${tilde(hr.path)} (${count} skills, sentinel missing)` : `${tilde(hr.path)} not synced`),
+      `Run 'npx @hybridlabor-api/aos@latest' and select ${hr.name} to sync skills.`, !exists && !viaPlugin);
   }
 
   // OpenCode Plugin check
@@ -197,12 +233,13 @@ function checkHarnesses() {
   add('harnesses', 'OpenCode Plugin', !!opencodePlugin,
     opencodePlugin ? tilde(opencodePlugin) : 'bdb-aos.js not installed in OpenCode plugins',
     'Run the AOS installer to wire OpenCode telemetry plugin.', true);
+  checkOpencodeMcpNames();
 }
 
 // ---------------------------------------------------------------- 4. Hooks & Security Gates
 function checkHooks() {
   const claudeHooksDir = h('.claude', 'hooks');
-  const EXPECTED_VERSION = { 'memb-inject.mjs': 7 };
+  const EXPECTED_VERSION = { 'memb-inject.mjs': 8 };
   const versionOf = (text) => {
     const m = /^\/\/\s*aos-hook-version:\s*(\d+)/m.exec(text);
     return m ? Number(m[1]) : null;

package/bin/aos-uninstall.mjs

@@ -5,6 +5,9 @@
 //   aos-uninstall --purge      also the memory store, wikis and credentials
 //   aos-uninstall --dry-run    list everything, delete nothing
 //   aos-uninstall --yes        skip the confirmations (CI only)
+//   aos-uninstall --restore-plugin-backup
+//                              put back the loose skill copies the installer removed when it
+//                              registered the bdb-aos plugin (never overwrites an existing file)
 //
 // The file-level install manifest records every path AOS wrote together with
 // the sha256 it wrote. That is what makes a precise uninstall possible: a file
@@ -19,6 +22,10 @@ import { createHash } from 'node:crypto';
 import { createInterface } from 'node:readline/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const pm = createRequire(import.meta.url)('../lib/plugin-migration.js');
+const cn = createRequire(import.meta.url)('../lib/codenotch.js');
 
 const HOME = os.homedir();
 const h = (...p) => path.join(HOME, ...p);
@@ -27,6 +34,7 @@ const tilde = (p) => p.replace(HOME, '~');
 const PURGE = process.argv.includes('--purge');
 const DRY = process.argv.includes('--dry-run');
 const YES = process.argv.includes('--yes');
+const RESTORE = process.argv.includes('--restore-plugin-backup');
 
 const MANIFEST = h('.agents', '.bdb-install-manifest.json');
 
@@ -96,7 +104,9 @@ function plan() {
   const legacy = LEGACY_MARKERS.filter(existsSync);
   const data = PURGE ? DATA_PATHS.filter((d) => existsSync(d.path)) : [];
 
-  return { manifest, ours, edited, gone, agents, modules, legacy, data };
+  const codenotch = cn.planCodenotchUninstall({ stateFile: cn.stateFilePath(HOME) });
+
+  return { manifest, ours, edited, gone, agents, modules, legacy, data, codenotch };
 }
 
 function describe(p) {
@@ -133,6 +143,12 @@ function describe(p) {
     for (const l of legacy) console.log(`    ${tilde(l)}`);
   }
 
+  if (p.codenotch) {
+    const c = p.codenotch;
+    const note = { remove: 'is removed (still the recorded build)', keep: 'is kept (replaced or modified since AOS installed it)', gone: 'is already gone' }[c.action];
+    console.log(`\nBDB AO Codenotch ${tilde(c.state.path || c.state.uninstallPath)} ${note}`);
+  }
+
   console.log('\nBleibt erhalten:');
   if (!PURGE) for (const d of DATA_PATHS.filter((d) => existsSync(d.path))) console.log(`    ${tilde(d.path).padEnd(18)} ${d.what}`);
   console.log('    jede Datei ohne Manifest-Eintrag — eigene Skills, fremde Hooks, alles Selbstgeschriebene');
@@ -162,7 +178,7 @@ function dirSize(p) {
 
 // ------------------------------------------------------------------ execute
 function execute(p) {
-  const { ours, edited, agents, modules, legacy, data } = p;
+  const { ours, edited, agents, modules, legacy, data, codenotch } = p;
   const stamp = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
   let removed = 0, backed = 0;
 
@@ -235,16 +251,27 @@ function execute(p) {
     } catch { console.log(`  ${tilde(codexToml)} nicht lesbar — von Hand prüfen`); }
   }
 
+  if (codenotch) {
+    const r = cn.uninstallCodenotch(codenotch, { stateFile: cn.stateFilePath(HOME) });
+    console.log(`  Codenotch: ${r === 'remove' ? 'removed' : r === 'keep' ? 'kept, not the recorded build' : r === 'error' ? 'uninstaller failed, left in place' : 'already gone'}`);
+  }
+
   for (const l of legacy) { try { rmSync(l); } catch { /* already gone */ } }
   if (legacy.length) console.log(`  ${legacy.length} Installations-Marker entfernt`);
 
+  const reg = pm.readState(HOME).registered.claudecode;
+  if (reg) {
+    const r = pm.deregisterClaude({ home: HOME, record: reg });
+    if (r.changed) console.log(`  bdb-aos Plugin-Registrierung aus settings.json entfernt${reg.replaced ? ` (externer Marketplace ${reg.replaced.key} wiederhergestellt)` : ''}`);
+  }
+
   // Only the BDB hook entries leave settings.json; everything else in it is
   // the user's and must survive an uninstall exactly as it survives an install.
   const settings = h('.claude', 'settings.json');
   if (existsSync(settings)) {
     try {
       const s = JSON.parse(readFileSync(settings, 'utf8'));
-      const bdb = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+      const bdb = ['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'];
       let touched = false;
       for (const [event, entries] of Object.entries(s.hooks || {})) {
         const kept = entries.filter((e) => !(e.hooks || []).some((x) => bdb.some((n) => String(x.command).includes(n))));
@@ -266,6 +293,7 @@ function execute(p) {
   for (const f of [MANIFEST, h('.agents', '.bdb-manifest.json')]) {
     try { rmSync(f); } catch { /* already gone */ }
   }
+  pm.retireState(HOME);
 }
 
 // ---------------------------------------------------------------------- main
@@ -276,6 +304,16 @@ const ask = async (q) => {
   return a;
 };
 
+if (RESTORE) {
+  const r = pm.restorePluginBackups({ home: HOME });
+  if (!r.dirs.length) { console.log('Keine Plugin-Migrations-Sicherung gefunden.'); process.exit(1); }
+  console.log(`  ${r.files.length} Dateien aus ${r.dirs.length} Sicherung(en) wiederhergestellt, im Install-Manifest erfasst`);
+  console.log('Vorhandene Dateien wurden nicht überschrieben.');
+  if (r.deregistered) console.log('  bdb-aos Plugin-Registrierung entfernt, damit die Skills nicht doppelt geladen werden. Setze AOS_PLUGIN_MIGRATION=off, damit der Installer sie nicht erneut entfernt.');
+  else if (r.files.length && r.stillEnabled) console.log('  WARNUNG: das bdb-aos Plugin ist weiterhin aktiv, die Skills erscheinen doppelt. Plugin in Claude Code deaktivieren und AOS_PLUGIN_MIGRATION=off setzen.');
+  process.exit(0);
+}
+
 const p = plan();
 console.log(PURGE ? '\x1b[31mAOS UNINSTALL — PURGE\x1b[0m' : 'AOS Uninstall');
 if (!describe(p)) process.exit(1);

package/bin/go-check.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// go-check: one fixed answer to "may this worker run this guarded command?" for callers that
+// are not a harness hook (AO). Installed at ~/.aos/bin/go-check.mjs.
+//
+//   node go-check.mjs --session <Name> --command "<shell string>" [--consume]
+//   node go-check.mjs --write-patterns <file>
+//
+// stdout: {"guarded":bool,"ok":bool,"scope":[...]|null,"reason":"..."}
+// exit 0 allowed (not guarded, or a valid GO token; --consume uses it up), 1 guarded without a
+// valid GO, 2 error (the caller must treat 2 as denied). Only `GO <Name>` tokens count: mode
+// soft grants and mode off belong to the human session and are never read here. Nothing in
+// this file writes a token; the tool is synchronous, offline and reads no stdin.
+
+import { existsSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+async function loadGate() {
+  for (const f of [join(here, "go-gate.mjs"), join(here, "..", ".claude", "hooks", "go-gate.mjs")]) {
+    if (existsSync(f)) return import(pathToFileURL(f).href);
+  }
+  throw new Error("go-gate.mjs not found next to go-check.mjs or in ../.claude/hooks");
+}
+
+export const patternsJson = (gate) => ({
+  version: 1,
+  source: "go-gate.mjs GUARDED_PATTERNS (JavaScript RegExp syntax, lookaheads included; not RE2)",
+  scopes: gate.SCOPES,
+  patterns: gate.GUARDED_PATTERNS.map((r) => ({ source: r.source, flags: r.flags })),
+});
+
+export function check(gate, { session, command, consume = false }) {
+  if (typeof command !== "string" || !command.trim()) return { code: 2, out: { guarded: null, ok: false, scope: null, reason: "--command is empty" } };
+  const storeReason = gate.gateStoreReason(command);
+  if (storeReason) return { code: 1, out: { guarded: true, ok: false, scope: null, reason: storeReason } };
+  if (!gate.isGuardedCommand(command)) return { code: 0, out: { guarded: false, ok: true, scope: [], reason: "" } };
+  const scope = gate.commandScopes(command);
+  if (typeof session !== "string" || !gate.slug(session)) {
+    return { code: 2, out: { guarded: true, ok: false, scope, reason: "--session is missing or has no usable name" } };
+  }
+  const r = gate.tokenGrantsGo(session, { consume });
+  return r.ok
+    ? { code: 0, out: { guarded: true, ok: true, scope, reason: consume ? "GO token consumed" : "GO token valid (not consumed)" } }
+    : { code: 1, out: { guarded: true, ok: false, scope, reason: r.reason } };
+}
+
+export function parseArgs(argv) {
+  const o = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--session") o.session = argv[++i];
+    else if (a === "--command") o.command = argv[++i];
+    else if (a === "--write-patterns") o.writePatterns = argv[++i];
+    else if (a === "--consume") o.consume = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return o;
+}
+
+const done = (code, out) => process.stdout.write(JSON.stringify(out) + "\n", () => process.exit(code));
+
+const invokedAs = (() => { try { return realpathSync(process.argv[1] || ""); } catch { return ""; } })();
+if (invokedAs === fileURLToPath(import.meta.url)) {
+  try {
+    const o = parseArgs(process.argv.slice(2));
+    const gate = await loadGate();
+    if (o.writePatterns) {
+      writeFileSync(o.writePatterns, JSON.stringify(patternsJson(gate), null, 2) + "\n");
+      done(0, { ok: true, reason: `wrote ${o.writePatterns}` });
+    } else {
+      const { code, out } = check(gate, o);
+      done(code, out);
+    }
+  } catch (e) {
+    done(2, { guarded: null, ok: false, scope: null, reason: String(e?.message || e).slice(0, 300) });
+  }
+}

package/bin/guarded-patterns.json

@@ -0,0 +1,106 @@
+{
+  "version": 1,
+  "source": "go-gate.mjs GUARDED_PATTERNS (JavaScript RegExp syntax, lookaheads included; not RE2)",
+  "scopes": [
+    "push-feature",
+    "push-main",
+    "merge",
+    "publish",
+    "destructive",
+    "github-write"
+  ],
+  "patterns": [
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+push|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+push)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?npm\\s+publish\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?npm\\s+version\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+pr\\s+merge|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+pr\\s+merge)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+release\\s+create|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+release\\s+create)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+reset\\s+--hard|(?:git\\s+|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+)reset\\b[^;&|\\n]*\\s--hard)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+clean|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+clean)\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*f[a-zA-Z]*|--force)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?rm\\s+(?:[^;&|\\n]*\\s)?['\"]?(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+branch|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+branch)\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*D[a-zA-Z]*|-[a-zA-Z]*(?:df|fd)[a-zA-Z]*)(?=\\s|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+branch|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+branch)\\b(?=[^;&|\\n]*\\s(?:-d|--delete)\\b)(?=[^;&|\\n]*\\s(?:-f|--force)\\b)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:git\\s+worktree|git(?:\\s+(?:-[cC]\\s*(?:\"[^\"]*\"|'[^']*'|\\S+)|--[\\w-]+(?:=(?:\"[^\"]*\"|'[^']*'|\\S+))?))+\\s+worktree)\\s+remove\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)pr\\s+(?:create|comment|edit|review|close)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)issue\\s+(?:create|comment)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)release\\s+(?:edit|delete)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)repo\\s+(?:create|edit|delete)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)api\\b[^;&|\\n]*\\s(?:-X\\s*|--method[\\s=]+)(?:POST|PATCH|PUT|DELETE)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?(?:gh\\s+|gh(?:\\s+(?:-R|--repo)(?:\\s+|=)\\S+)+\\s+)api\\b[^;&|\\n]*\\s(?:-[fF]|--field|--raw-field|--input)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?git\\s+(?:-[cC]\\s*\\S+\\s+)*-c\\s*['\"]?alias\\.",
+      "flags": "i"
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?opencode\\s+run\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*[sc]\\S*|--session|--continue)(?=[\\s=]|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?claude\\b[^;&|\\n]*\\s(?:-[a-zA-Z]*[cr]\\S*|--resume|--continue)(?=[\\s=]|$)",
+      "flags": ""
+    },
+    {
+      "source": "(?:^|[;&|\\n({\\x60])\\s*(?:(?:sudo|env|command|builtin|exec|nohup|time|xargs|eval|then|do|else)(?:\\s+-{1,2}[\\w-]+(?:=\\S*)?(?:\\s+(?![-'\"])(?!(?:\\S*\\/)?(?:git|gh|npm|rm|opencode|curl|wget)\\b)[^\\s;&|'\"]+)?)*\\s+|(?:bash|sh|zsh|dash|ksh)(?:\\s+-\\w+)*\\s+-c\\s+|\\w+=\\S*\\s+)*['\"]?(?:[^\\s;&|()'\"]*\\/)?opencode\\s+attach\\b",
+      "flags": "i"
+    },
+    {
+      "source": "\\/session\\/[^\\s/'\"]+\\/(?:message|prompt_async|command|shell)\\b",
+      "flags": "i"
+    },
+    {
+      "source": "\\/\\/[^\\s'\"]*\\/tui\\/|\\/tui\\/(?:append|submit|clear|execute|open|show|publish|control)",
+      "flags": "i"
+    }
+  ]
+}

package/commands/brainstorm.md

@@ -0,0 +1,5 @@
+---
+description: "Brainstorm a topic with the matching skill: bdbrainstorm, bdbmediastorm for event tech, grill-me for a stress test."
+---
+
+Pick by topic: `bdbmediastorm` for live event technology and show control, `grill-me` when the human wants an existing idea stress-tested, `bdbrainstorm` otherwise. Say which one you chose. Topic: $ARGUMENTS

package/commands/doctor.md

@@ -0,0 +1,5 @@
+---
+description: "Check the machine and the current project, and print suggested permissions.allow entries without writing any settings."
+---
+
+Run `aos-doctor` (machine check) and report the result. If the current folder is an AOS project, also run the project check `node <aos-project-init skill dir>/scripts/aos-project-doctor.mjs` (it covers `.aos/project.json`, AGENTS.md and the wiki). Print suggested `permissions.allow` entries as text for the human to copy. Never write to settings.json or settings.local.json. Arguments: $ARGUMENTS

package/commands/graph.md

@@ -0,0 +1,5 @@
+---
+description: "Run the startcycle-graph pipeline: durable state, repair loop, quality gate, escalation."
+---
+
+Run the `startcycle-graph` skill; its contract defines the flow. Task: $ARGUMENTS

package/commands/init.md

@@ -0,0 +1,5 @@
+---
+description: "Set up the current project folder for AOS: slug, wiki, memory, Synapse map, AGENTS.md."
+---
+
+Run the `aos-project-init` skill for the current project folder. This is project setup, not machine setup (that is `/bdb-aos:setup`). Arguments: $ARGUMENTS

package/commands/loop.md

@@ -0,0 +1,5 @@
+---
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates."
+---
+
+Use the built-in `/loop <interval> <prompt>` (omit the interval to self-pace). Offer a `loop-templates` template when the human has no prompt yet. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: $ARGUMENTS

package/commands/mastersession.md

@@ -0,0 +1,5 @@
+---
+description: "Supervise other Claude Code sessions on this machine: roster, status requests, GO board, idle notices."
+---
+
+Act as the master session with the `master-session` skill (ACP bridge: `bin/aos-acp.mjs`, see docs/master-session-acp.md). Keep the overview, relay the human's decisions, never decide for the human. Arguments: $ARGUMENTS

package/commands/memb.md

@@ -0,0 +1,5 @@
+---
+description: "Query or store long-term memory with memB."
+---
+
+Use `memb-skill` to search or remember and `memb-ingest` to import material. Never store secrets, tokens or credentials. Arguments: $ARGUMENTS

package/commands/orchestrator.md

@@ -0,0 +1,5 @@
+---
+description: "Coordinate parallel coding agents across repositories through the AO daemon."
+---
+
+Use the `ao-orchestrator` skill. It needs the AO daemon; check that it is running first and stop with a clear message if not. Do not confuse it with `agent-orchestrator`. Arguments: $ARGUMENTS

package/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: "Plan end to end: draft, render in plan-canvas or Plan Builder, annotate, await approval, then hand off."
+---
+
+Run the full planning pipeline: 1) draft the plan with `concise-planning`; 2) always offer the choice between plan-canvas and Plan Builder (`aos-plan-canvas open <dir> --mode bdb-plan-builder`) for rendering; 3) collect annotations and wait for the human's approval; 4) only after approval continue with `writing-plans` or `/bdb-aos:graph`. Topic: $ARGUMENTS

package/commands/playbooks.md

@@ -0,0 +1,5 @@
+---
+description: "List all pb-* playbooks with duration, difficulty and requirements, and start one."
+---
+
+Run `node <bdb-aos skill dir>/scripts/list-playbooks.mjs` and show its output (name, est_time, difficulty, requires of every `pb-*` skill). If the human names a playbook in the arguments or picks one, start that `pb-*` skill; start nothing otherwise. Each playbook keeps its own go-gate points. Arguments: $ARGUMENTS

package/commands/setup.md

@@ -0,0 +1,5 @@
+---
+description: "Bring this machine to a complete, verified AOS installation (skills, MCP servers, gate hooks, memB, OpenWiki, Synapse)."
+---
+
+Run the `aos-setup` skill for this machine. Report what is installed, what was repaired and what is still missing. Arguments: $ARGUMENTS

package/commands/shipping.md

@@ -0,0 +1,5 @@
+---
+description: "Pre-ship framing and the technical release gate, with approvals under the go-gate rules."
+---
+
+Use `bdb-shipping-skill` for the pre-flight and `godmode-shipping` for the gate. The playbook `pb-ship` can drive the whole flow. Push, merge and publish need the human's GO under the go-gate rules; never request one on the human's behalf. Arguments: $ARGUMENTS

package/commands/startproject.md

@@ -0,0 +1,5 @@
+---
+description: "Start a new composition: project init, brainstorm, then ask whether graph or startcycle follows."
+---
+
+Sequence: 1) `aos-project-init`; 2) `bdbrainstorm`; 3) stop and ask the human whether `/bdb-aos:graph` (startcycle-graph) or `startcycle` follows. Do not start a pipeline on your own. Idea: $ARGUMENTS

package/commands/store.md

@@ -0,0 +1,5 @@
+---
+description: "Browse and preview AOS skills, agents and playbooks in the local store UI."
+---
+
+Start the `aos-store` interface. Preview freely, but install nothing until the human says yes for that specific item. Arguments: $ARGUMENTS

package/docs/codenotch.md

@@ -0,0 +1,44 @@
+# BDB AO Codenotch (macOS and Windows, default on)
+
+The AOS installer installs the BDB AO Codenotch desktop app by default on **macOS and Windows**. On Linux the step is never offered and no code of it runs.
+
+## Controlling it
+
+| Mode | Behavior |
+|---|---|
+| Interactive | Prompt "Install BDB AO Codenotch?", default **yes** |
+| Non-interactive (`-y`, no TTY) | Installs unless opted out |
+| Opt out | `AOS_CODENOTCH=0` or `--no-codenotch` (wins over everything) |
+| Force on | `AOS_CODENOTCH=1` or `--codenotch` (skips the question) |
+
+A failure at any step (no release yet, 404, offline, rate limit, checksum mismatch, mount error) prints a warning and the AOS install continues; the exit code is never affected. The installer ends with one line saying whether Codenotch was installed, skipped or failed, and how to remove it.
+
+## Windows
+
+- Asset: `Codenotch-Setup-<version>.exe` plus `Codenotch-Setup-<version>.exe.sha256` from the same release. If the exact name is absent, the single `*Setup*.exe` that has a matching `.sha256` is used; anything ambiguous is refused.
+- The SHA-256 is verified before the installer runs; a mismatch only warns.
+- Runs the NSIS installer silently as `Setup.exe /S`, per-user, no admin, no elevation, with a 5 minute timeout, then checks the version in the per-user uninstall registry key (`HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall`, key `Codenotch`, fallback scan for a subkey whose DisplayName is Codenotch).
+- Installed version same or newer: skipped. An older install AOS did not record is kept unless you confirm interactively.
+- The path of the uninstaller and the version are recorded in `~/.agents/.bdb-codenotch.json` (`%USERPROFILE%` on Windows).
+- `aos-uninstall` runs `<recorded uninstall.exe> /S` only if that file still exists and the registry version and uninstaller path still match the record; otherwise the install is left alone.
+- Default install dir is `%LOCALAPPDATA%\Codenotch` (codenotch.exe, codenotch-hook.exe, uninstall.exe). The installer is unsigned, so Windows SmartScreen may warn.
+- **Unverified:** the registry key (`Codenotch`), `DisplayVersion`, `UninstallString`, and the silent `/S` install and uninstall come from Tauri's stock NSIS template, not from a real build. They must be checked on Windows with the first CI-built installer.
+
+## What it does (macOS)
+
+1. Reads the release list of the public repo `hybridlabor-api/bdb-ao-codenotch` (`https://api.github.com/repos/hybridlabor-api/bdb-ao-codenotch/releases`, unauthenticated) and picks the newest release that is neither draft nor prerelease and carries this platform's asset plus a `.sha256`; other releases are ignored. A missing repo (404), no matching release, or a GitHub rate limit prints a friendly note and the install continues; nothing fails.
+2. Downloads the `.dmg` and verifies its `.sha256` asset from the same release **before** mounting. A mismatch or a missing checksum refuses the install.
+3. Mounts with `hdiutil attach -nobrowse -readonly -mountpoint <temp dir>` and always detaches again, even on failure.
+4. Copies the single `.app` from the DMG to `/Applications`, or to `~/Applications` when `/Applications` is not writable. Never uses sudo.
+5. Runs `xattr -dr com.apple.quarantine` on the copy. The app is **ad-hoc signed** until Apple developer certificates are in place, so Gatekeeper would otherwise block it.
+6. Records path, version and bundle id in `~/.agents/.bdb-codenotch.json`.
+
+## Idempotence and safety
+
+- Installed version same or newer (`CFBundleShortVersionString`): skipped.
+- Older and installed by AOS (recorded path, bundle id and version still match): asked in interactive mode, replaced automatically with `AOS_CODENOTCH=1`. The old copy is restored if the new copy fails.
+- Older and not installed by AOS: kept with a note in non-interactive mode; in interactive mode replaced only after you confirm.
+
+## Uninstall
+
+`aos-uninstall` removes only the recorded `.app`, and only while its bundle id and version still match the record. A replaced or otherwise unknown app is kept. `--dry-run` lists the decision.