@hybridlabor-api/aos 4.2.0 → 4.4.0

package/skills/global_config/aos-project-init/assets/AGENTS.template.md

@@ -0,0 +1,56 @@
+# <PROJECT NAME> — Agent Rules
+
+One-paragraph description of what this project is and who uses it. An agent
+that reads only this file should understand what it is touching.
+
+> Harness files: `CLAUDE.md`, `GEMINI.md` and `CODEX.md` are symlinks to this
+> file. Every rule lives here exactly once.
+
+## Stack
+
+- Language / runtime:
+- Framework:
+- Package manager:
+- Database / storage:
+- Deploy target:
+
+## Commands
+
+```bash
+# install
+# dev
+# test
+# lint / typecheck
+# build
+```
+
+Run the test and typecheck commands before reporting any change as done.
+
+## Architecture
+
+Where the code lives and which direction dependencies point. Name the
+boundaries an agent must not cross, not every file.
+
+- `src/…` —
+- `…` —
+
+## Project rules
+
+1. **Git snapshot first.** Commit or snapshot before refactoring or deleting.
+2. **English only** in code, docs and commit messages.
+3. **No secrets in the repo.** Live `.env` files stay outside it; the repo
+   carries placeholders only.
+4. **Private repository** unless explicitly decided otherwise.
+5. **Ask before destructive actions** — mass deletion, history rewriting,
+   discarding uncommitted work.
+
+## Domain notes
+
+Non-obvious constraints, hardware quirks, external-service limits, and
+decisions that would look like bugs to someone reading the code cold. This
+section is why the file exists — keep it current.
+
+## Out of scope
+
+What agents should not touch here (generated files, vendored code, another
+team's directory).

package/skills/global_config/aos-project-init/scripts/aos-project-doctor.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// AOS project doctor: reports how completely one project folder is wired into
+// AOS. Read-only — it never installs or edits anything.
+//   node aos-project-doctor.mjs [dir] [--json]
+
+import { existsSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+const args = process.argv.slice(2).filter((a) => a !== '--json');
+const JSON_OUT = process.argv.includes('--json');
+const ROOT = path.resolve(args[0] || process.cwd());
+const PROJECT = path.basename(ROOT);
+const HOME = os.homedir();
+
+const results = [];
+const add = (area, name, ok, detail, fix) => results.push({ area, name, ok, detail, fix });
+const p = (...rel) => path.join(ROOT, ...rel);
+const git = (...a) => { try { return execFileSync('git', ['-C', ROOT, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; } };
+
+// ---------------------------------------------------------------- git
+function checkGit() {
+  const inRepo = git('rev-parse', '--is-inside-work-tree') === 'true';
+  add('git', 'repository', inRepo, inRepo ? git('rev-parse', '--show-toplevel').replace(HOME, '~') : 'not a git repo',
+    'git init && git add -A && git commit -m "chore: initial commit"');
+  if (!inRepo) return;
+
+  const remote = git('remote', 'get-url', 'origin');
+  add('git', 'origin remote', !!remote, remote || 'local-only (fine for a scratch project, blocks gh/CI)',
+    'gh repo create <name> --private --source=. --remote=origin');
+
+  if (remote && remote.includes('github.com')) {
+    let vis = null;
+    try {
+      vis = execFileSync('gh', ['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: ROOT, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch { /* gh missing or not authenticated */ }
+    add('git', 'repo is private', vis === 'PRIVATE', vis ? `visibility: ${vis}` : 'could not read visibility (gh missing or unauthenticated)',
+      'gh repo edit --visibility private --accept-visibility-change-consequences');
+  }
+
+  const ignore = existsSync(p('.gitignore')) ? readFileSync(p('.gitignore'), 'utf8') : '';
+  add('git', '.gitignore covers .env', /(^|\n)\s*\.?\*?\.env/.test(ignore), ignore ? '.gitignore present' : 'no .gitignore',
+    'Add `.env` and `*.env` to .gitignore; keep live secrets outside the repo.');
+}
+
+// ---------------------------------------------------------------- agent docs
+function checkAgentDocs() {
+  const agents = p('AGENTS.md');
+  add('docs', 'AGENTS.md', existsSync(agents), existsSync(agents) ? `${readFileSync(agents, 'utf8').split('\n').length} lines` : 'missing — no repo-specific agent rules',
+    'Write AGENTS.md (see the /aos-project-init template).');
+
+  for (const alias of ['CLAUDE.md', 'GEMINI.md', 'CODEX.md']) {
+    const f = p(alias);
+    let ok = false; let detail = 'missing';
+    if (existsSync(f)) {
+      const isLink = lstatSync(f).isSymbolicLink();
+      const target = isLink ? readlinkSync(f) : null;
+      ok = isLink && path.basename(target) === 'AGENTS.md';
+      detail = isLink ? `-> ${target}` : 'a real file, not a symlink (will drift from AGENTS.md)';
+    }
+    add('docs', alias, ok, detail, `ln -sf AGENTS.md ${alias}`);
+  }
+}
+
+// ---------------------------------------------------------------- harness
+function checkHarness() {
+  for (const [rel, what] of [
+    ['.agents/graph.md', 'dispatcher-graph contract'],
+    ['.agents/nodes.json', 'node registry'],
+    ['.claude/workflows', 'dispatcher workflow'],
+    ['.claude/hooks/go-gate.mjs', 'release gate hook'],
+    ['.claude/agents', 'agent definitions'],
+    ['.claude/settings.json', 'project hook wiring'],
+  ]) {
+    add('harness', rel, existsSync(p(rel)), existsSync(p(rel)) ? what : `missing — ${what} unavailable here`,
+      'npx -y @hybridlabor-api/aos --project-harness   (run inside the project)');
+  }
+}
+
+// ---------------------------------------------------------------- openwiki
+function checkWiki() {
+  const dir = p('.openwiki');
+  const pages = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+  add('openwiki', 'wiki initialised', pages.length > 0, pages.length ? `${pages.length} pages: ${pages.slice(0, 4).join(', ')}${pages.length > 4 ? ' …' : ''}` : 'no .openwiki pages',
+    'openwiki --init   (run inside the project; needs `openwiki auth <provider>` first)');
+}
+
+// ---------------------------------------------------------------- memB
+async function checkMemb() {
+  const dbPath = path.join(HOME, '.MemBDB', 'memb.db');
+  if (!existsSync(dbPath)) {
+    add('memB', 'project memories', false, 'no memB store on this machine', 'Run /aos-setup first.');
+    return;
+  }
+  try {
+    const { DatabaseSync } = await import('node:sqlite');
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    db.exec('PRAGMA busy_timeout = 5000;');
+    const row = db.prepare(`
+      SELECT COUNT(*) AS n FROM memb_vectors
+      WHERE json_extract(payload, '$.project_id') = ?
+         OR json_extract(payload, '$.metadata.project_id') = ?
+    `).get(PROJECT, PROJECT);
+    const n = Number(row?.n || 0);
+    add('memB', 'project memories', n > 0, `${n} memories bound to project_id "${PROJECT}"`,
+      'Ingest the project: python3 memb_ingest.py <project dir>  (see /aos-project-init, section 5)');
+  } catch (e) {
+    add('memB', 'project memories', false, `could not read the store (${e.message.split('\n')[0]})`,
+      'node:sqlite is unflagged only from Node 22.13; on 22.5-22.12 upgrade Node (or pass --experimental-sqlite). Otherwise inspect via the memB WebUI on :8088.');
+  }
+}
+
+// ---------------------------------------------------------------- report
+function report() {
+  if (JSON_OUT) {
+    console.log(JSON.stringify({ project: PROJECT, root: ROOT.replace(HOME, '~'), ok: results.every((r) => r.ok), results }, null, 2));
+    return;
+  }
+  console.log(`\nProject: ${PROJECT}  (${ROOT.replace(HOME, '~')})`);
+  let area = '';
+  for (const r of results) {
+    if (r.area !== area) { area = r.area; console.log(`\n${area.toUpperCase()}`); }
+    console.log(`  ${r.ok ? '✅' : '❌'} ${r.name.padEnd(24)} ${r.detail}`);
+    if (!r.ok) console.log(`     ↳ fix: ${r.fix}`);
+  }
+  const bad = results.filter((r) => !r.ok);
+  console.log(`\n${results.length - bad.length}/${results.length} checks pass.` + (bad.length ? ` ${bad.length} need attention.` : ' Project is fully wired.'));
+}
+
+checkGit();
+checkAgentDocs();
+checkHarness();
+checkWiki();
+await checkMemb();
+report();
+process.exit(results.some((r) => !r.ok) ? 1 : 0);

package/skills/global_config/aos-setup/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: aos-setup
+description: >-
+  Bring a machine to a complete, verified AOS installation: the skills pack,
+  MCP servers, gate hooks, memB (engine, MCP, ambient hook, WebUI), OpenWiki
+  (CLI, auth, harness integrations, refresh daemon) and Synapse. Run once on a
+  new computer, and again whenever something in the ecosystem stopped working.
+category: bdb-core
+risk: low
+source: bdb
+date_added: "2026-09-13"
+---
+
+# AOS Setup — Machine Level
+
+Installing the AOS npm package is the easy half. The half that quietly fails is
+everything around it: memB has no venv, the ambient memory hook was never
+wired, OpenWiki has a CLI but no provider credentials, Synapse's binary is not
+on `PATH`. The result is a machine where most skills work and the memory,
+documentation and visualization layers silently do nothing.
+
+This skill closes that gap: **measure first, then fix only what is broken.**
+
+For per-project wiring — a new project folder, its `AGENTS.md`, its memB
+project binding, its wiki — use `/aos-project-init` after this one.
+
+---
+
+## 1. Measure
+
+Run the doctor. It is read-only; it installs and edits nothing.
+
+```bash
+node skills/global_config/aos-setup/scripts/aos-doctor.mjs        # from the AOS repo
+node ~/.claude/skills/aos-setup/scripts/aos-doctor.mjs            # from an installed copy
+```
+
+Flags: `--json` for machine-readable output, `--net` to also compare the
+installed AOS version against npm.
+
+It reports up to 26 checks across six areas, each with the exact fix command.
+The exact number varies by machine: the LaunchAgent rows are macOS-only, the
+OpenWiki integrations row needs the CLI on `PATH`, the npm-version row needs
+`--net`, and the optional-module rows appear only for modules the manifest
+claims are installed.
+
+| Area | What is verified |
+|---|---|
+| `prereq` | Node ≥ 22, `python3`, `git`, `uv`, `gh` |
+| `aos` | `~/.agents/.bdb-manifest.json`, skills synced into each harness's skill directory |
+| `hooks` | `go-gate.mjs`, `graph-gate.mjs`, `memb-inject.mjs` — present **and** wired in `~/.claude/settings.json` |
+| `memB` | module, venv, `~/.MemBDB/memb.db`, WebUI on `:8088`, autostart, `memb-mcp` venv, MCP registration |
+| `openwiki` | CLI, `~/.openwiki/.env` credentials, harness integrations, 2-hourly refresh daemon |
+| `synapse` | binary on `PATH`, daemon on `:7781` |
+
+Exit code is `0` only when every check passes. **Report the failing rows to the
+user before changing anything**, then work the sections below in order — each
+one covers a block the doctor can flag.
+
+---
+
+## 2. Install or update AOS itself
+
+```bash
+npx -y @hybridlabor-api/aos@latest
+```
+
+The interactive installer asks which harnesses to target (Claude Code, Gemini /
+Antigravity, Codex, OpenCode, Claude Desktop, …), which MCP servers to wire,
+and which optional modules to pull. Non-interactive variants:
+
+```bash
+npx -y @hybridlabor-api/aos -y --platforms=2      # unattended, one platform
+npx -y @hybridlabor-api/aos --dry-run             # show what it would do
+```
+
+Two things worth insisting on when the installer asks:
+
+- **Pick every harness the user actually runs.** A harness left unselected gets
+  no skills at all, which is the single most common "AOS doesn't work here".
+- **Enable the optional modules** — memB, Synapse, OS Remote, Creator
+  Extension, Tool Installer. They are what the doctor's memB and Synapse
+  sections check for.
+
+The installer writes `~/.agents/.bdb-manifest.json`. If that file is absent,
+nothing was ever installed globally, no matter how many skills happen to sit in
+a harness directory.
+
+---
+
+## 3. memB — memory that actually retains
+
+memB is three separate pieces, and a machine can have any subset:
+
+| Piece | Lives at | Doctor row |
+|---|---|---|
+| Engine + WebUI | `~/.agents/memB` (venv, `:8088` daemon) | `module`, `python venv`, `WebUI :8088`, `autostart` |
+| MCP server | `~/.gemini/config/mcps/memb-mcp` (venv + `run.py`) | `memb-mcp server`, `memb_mcp registered` |
+| Ambient hook | `~/.claude/hooks/memb-inject.mjs` | `memb-inject.mjs`, `memb-inject.mjs wired` |
+
+The engine and the MCP come from the installer. If the venv is missing, repair
+it in place rather than reinstalling everything:
+
+```bash
+cd ~/.agents/memB
+uv venv --seed .venv
+uv pip install --python .venv/bin/python -r requirements.txt
+```
+
+`uv venv --seed` has been observed to create a venv without `pip`; that is why
+`uv pip install --python <venv>` is the command above and not `python -m pip`.
+
+The store lives in `~/.MemBDB/memb.db`. An empty store is normal on a fresh
+machine — `/aos-project-init` seeds it per project.
+
+---
+
+## 4. The ambient memory hook
+
+The hook is what makes memB *ambient* rather than something an agent has to
+remember to query. On every prompt it reads the SQLite store directly and
+injects the relevant memories as context. It fails open: any error exits `0`
+and the prompt proceeds untouched.
+
+Since v4.4.0 the installer ships `memb-inject.mjs` into `~/.claude/hooks/` and
+wires it as a `UserPromptSubmit` hook, so on a current install both doctor rows
+pass on their own. A machine where they fail is running an older AOS — the fix
+is the installer, not a manual copy:
+
+```bash
+npx -y @hybridlabor-api/aos@latest
+```
+
+The wiring is merged into `~/.claude/settings.json`, never written over it:
+user keys and foreign hook entries survive, and a re-run replaces the BDB entry
+rather than adding a second copy.
+
+Unlike the two gate hooks, this one stays `$HOME`-anchored even in a project
+harness — the memB store is machine-global, and pointing it at
+`$CLAUDE_PROJECT_DIR` would make it fail on every prompt in any project the
+harness was never installed into.
+
+Standing facts that should reach every prompt — persona, brand rules, house
+style — go one per line into `~/.MemBDB/ambient-persona.txt`. Lines starting
+with `#` are ignored. This file is deliberately *not* shipped: ask the user
+what belongs there rather than inventing it, and never copy another machine's.
+
+Verify by starting a session and checking that the first prompt carries a
+`[memB Ambient Memory Context]` block.
+
+---
+
+## 5. OpenWiki
+
+```bash
+npm install -g openwiki@latest        # CLI, needs Node >= 22
+openwiki auth <provider>              # google | openai | groq | openrouter | ollama | …
+openwiki integrations list            # per-harness host integration status
+openwiki integrations install claude  # repeat for codex / cursor / opencode
+```
+
+Credentials land in `~/.openwiki/.env`. Without them every wiki run fails at
+auth — the CLI being on `PATH` proves nothing on its own.
+
+The 2-hourly refresh daemon comes from the AOS installer when an OpenWiki API
+key is supplied. To install it separately:
+
+```bash
+bash ~/.claude/skills/openwiki-skill/scripts/install_daemon.sh          # macOS / Linux
+powershell -ExecutionPolicy Bypass -File install_daemon.ps1             # Windows
+```
+
+Wikis themselves are per-repository (`.openwiki/` in each project) — that is
+`/aos-project-init`'s job, not this one's.
+
+---
+
+## 6. Synapse
+
+The installer downloads the module, symlinks the binary to
+`~/.local/bin/synapse` and registers a daemon on port `7781`. Two failure modes
+the doctor separates deliberately:
+
+- **Binary not found** — usually `~/.local/bin` missing from `PATH`. Add it to
+  the shell profile; do not copy the binary somewhere else.
+- **Port closed** — the daemon is not running. On macOS:
+  `launchctl load -w ~/Library/LaunchAgents/com.bdb.synapse.plist`.
+
+If no pre-built binary exists for the platform, build it:
+`cd ~/.agents/bdb-synapse && go build -o synapse ./cmd/synapse/`.
+
+---
+
+## 7. Confirm
+
+Re-run the doctor. Do not report success from the fact that commands ran —
+report the doctor's own count:
+
+```bash
+node skills/global_config/aos-setup/scripts/aos-doctor.mjs
+# 26/26 checks pass. AOS is fully wired.
+```
+
+Anything still failing that the user deliberately does not want (no Synapse on
+a headless server, no OpenWiki daemon on a laptop) is fine — say so explicitly
+instead of leaving it looking broken.
+
+Then hand off: **the machine is ready; per-project setup runs through
+`/aos-project-init` in each repository.**
+
+---
+
+## Red flags
+
+- Reporting "AOS installed" on the strength of a successful `npx` run. The
+  installer succeeds happily with memB skipped and no hook wired.
+- Overwriting `~/.claude/settings.json` instead of merging into its `hooks`
+  object — that silently removes the go-gate.
+- Treating an empty `~/.MemBDB` as a defect. It is the expected state until
+  something is ingested.
+- Copying the reference machine's persona file verbatim onto someone else's
+  computer. Ask what their standing facts are.

package/skills/global_config/aos-setup/scripts/aos-doctor.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+// AOS machine doctor: reports what a full AOS install needs and what this
+// machine actually has. Read-only — it never installs or edits anything.
+//   node aos-doctor.mjs [--json] [--net]
+// --net additionally asks npm whether a newer AOS is published (needs network).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { connect } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+const JSON_OUT = process.argv.includes('--json');
+const NET = process.argv.includes('--net');
+const IS_MAC = process.platform === 'darwin';
+const IS_WIN = process.platform === 'win32';
+
+const h = (...p) => path.join(HOME, ...p);
+
+const firstExisting = (candidates) => candidates.find((c) => existsSync(c)) || null;
+
+// installer.js moduleBasePath() resolves to ~/.agents only under npx; a global
+// `npm i -g` or a dev checkout puts the modules next to the package instead.
+// Probe every base rather than assuming the npx one, or a perfectly good
+// install reports as missing.
+const MODULE_BASES = [
+  h('.agents'),
+  h('.claude'),
+  ...(process.env.npm_config_prefix ? [path.join(process.env.npm_config_prefix, 'lib', 'node_modules')] : []),
+  '/usr/local/lib/node_modules',
+  '/opt/homebrew/lib/node_modules',
+];
+const findModule = (name) => firstExisting(MODULE_BASES.map((b) => path.join(b, name)));
+
+// resolveTargetPaths() sends the MCP payload to a different directory per
+// harness (installer.js:1968+), so ~/.gemini is one option among several.
+const MCP_DIRS = [
+  h('.gemini', 'config', 'mcps'),
+  h('Library', 'Application Support', 'Claude', 'mcps'),
+  ...(process.env.APPDATA ? [path.join(process.env.APPDATA, 'Claude', 'mcps')] : []),
+  h('.cursor', 'mcps'),
+  h('.codex', 'mcps'),
+  h('.windsurf', 'mcps'),
+];
+
+const results = [];
+const add = (area, name, ok, detail, fix) => results.push({ area, name, ok, detail, fix });
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const tilde = (p) => (p || '').replace(HOME, '~');
+// `which` does not exist on native Windows; cmd ships `where`, which prints one
+// path per line.
+const which = (bin) => {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  try { return tilde(execFileSync(probe, [bin], { encoding: 'utf8' }).trim().split(/\r?\n/)[0]); } catch { return null; }
+};
+const dirCount = (p) => { try { return readdirSync(p, { withFileTypes: true }).filter(d => d.isDirectory()).length; } catch { return 0; } };
+
+function portOpen(port, timeout = 1200) {
+  return new Promise((resolve) => {
+    const s = connect({ host: '127.0.0.1', port });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout);
+    s.once('connect', () => done(true));
+    s.once('timeout', () => done(false));
+    s.once('error', () => done(false));
+  });
+}
+
+// ---------------------------------------------------------------- prereqs
+function checkPrereqs() {
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  add('prereq', 'node >= 22', nodeMajor >= 22, `v${process.versions.node}`,
+    'OpenWiki needs Node 22+. Install via nvm/homebrew, then re-run.');
+
+  for (const [bin, why, fix] of [
+    ['python3', 'memB venv + OpenWiki daemon', 'Install Python 3 (brew install python / python.org).'],
+    ['git', 'every per-project step', 'Install git.'],
+    ['uv', 'fast, reliable memB venv seeding', 'curl -LsSf https://astral.sh/uv/install.sh | sh (optional but recommended — pip fallback exists).'],
+    ['gh', 'private-repo creation in /aos-project-init', 'brew install gh && gh auth login (optional).'],
+  ]) {
+    const p = which(bin);
+    add('prereq', bin, !!p, p || `missing — needed for ${why}`, fix);
+  }
+}
+
+// ---------------------------------------------------------------- AOS core
+function checkAos() {
+  const manifestPath = h('.agents', '.bdb-manifest.json');
+  const manifest = readJson(manifestPath);
+  add('aos', 'install manifest', !!manifest,
+    manifest ? `v${manifest.version} · tier ${manifest.tier} · modules: ${(manifest.installedModules || []).join(', ') || 'none'}` : `${manifestPath} missing`,
+    'npx -y @hybridlabor-api/aos@latest');
+
+  if (manifest && NET) {
+    try {
+      const latest = execFileSync('npm', ['view', '@hybridlabor-api/aos', 'version'], { encoding: 'utf8', timeout: 8000 }).trim();
+      add('aos', 'version vs npm', manifest.version === latest, `local v${manifest.version} · npm v${latest}`,
+        'npx -y @hybridlabor-api/aos@latest');
+    } catch {
+      add('aos', 'version vs npm', false, 'npm view failed (offline?)', 'Re-run with network, or skip --net.');
+    }
+  }
+
+  const harnesses = [
+    ['Claude Code', h('.claude', 'skills')],
+    ['Gemini / Antigravity', h('.gemini', 'config', 'skills')],
+    ['Codex', h('.codex', 'skills')],
+  ];  // OpenCode gets an MCP config but no skill sync from installer.js — no row for it.
+  // A non-empty skills directory proves nothing — it can hold one unrelated
+  // skill, or a stale partial sync. Require a sentinel that only AOS ships.
+  const SENTINEL = 'startcycle';
+  const synced = harnesses.filter(([, p]) => dirCount(p) > 0);
+  const withSentinel = synced.filter(([, p]) => existsSync(path.join(p, SENTINEL, 'SKILL.md')));
+  add('aos', 'skills synced to harnesses', withSentinel.length > 0,
+    synced.length
+      ? synced.map(([n, p]) => `${n}: ${dirCount(p)}${existsSync(path.join(p, SENTINEL, 'SKILL.md')) ? '' : ' (no ' + SENTINEL + ' — partial/foreign)'}`).join(' · ')
+      : 'no harness skill directory holds any skill',
+    'npx -y @hybridlabor-api/aos@latest and pick every harness you actually use.');
+
+  // The optional modules are opt-in, so absence is not a failure — but a
+  // manifest that claims one is installed while its directory is gone is.
+  const claimed = new Set(manifest?.installedModules || []);
+  for (const [id, dir, label] of [
+    ['memb', 'memB', 'memB'],
+    ['synapse', 'bdb-synapse', 'Synapse'],
+    ['remote', 'bdb-os-remote', 'OS Remote'],
+    ['creator', 'bdb-dev-creator-extension', 'Creator Extension'],
+    ['installer', 'bdb-dev-tool-installer', 'Tool Installer'],
+  ]) {
+    if (!claimed.has(id)) continue;
+    const found = findModule(dir);
+    add('aos', `module ${label}`, !!found, found ? tilde(found) : 'the manifest claims it is installed, but its directory is gone',
+      'npx -y @hybridlabor-api/aos@latest and re-enable the module.');
+  }
+}
+
+// ---------------------------------------------------------------- hooks
+function checkHooks() {
+  const hooksDir = h('.claude', 'hooks');
+  for (const file of ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs']) {
+    const p = path.join(hooksDir, file);
+    add('hooks', file, existsSync(p), existsSync(p) ? p.replace(HOME, '~') : 'missing',
+      'npx -y @hybridlabor-api/aos@latest (the installer ships and wires all three).');
+  }
+
+  const settings = readJson(h('.claude', 'settings.json'));
+  const wired = JSON.stringify(settings?.hooks || {});
+  for (const [file, event] of [['go-gate.mjs', 'PreToolUse'], ['graph-gate.mjs', 'Stop'], ['memb-inject.mjs', 'UserPromptSubmit']]) {
+    add('hooks', `${file} wired`, wired.includes(file), wired.includes(file) ? `present in ${event}` : `not referenced in ~/.claude/settings.json`,
+      'Add it under the matching hooks event in ~/.claude/settings.json (see this skill, section 4).');
+  }
+}
+
+// ---------------------------------------------------------------- memB
+async function checkMemb() {
+  const membDir = findModule('memB');
+  add('memB', 'module', !!membDir, membDir ? tilde(membDir) : `not found under: ${MODULE_BASES.map(tilde).join(', ')}`,
+    'Run the installer and enable the memB optional module.');
+
+  const venvPy = membDir && path.join(membDir, IS_WIN ? '.venv/Scripts/python.exe' : '.venv/bin/python');
+  add('memB', 'python venv', !!venvPy && existsSync(venvPy), venvPy && existsSync(venvPy) ? tilde(venvPy) : 'no .venv — requirements were never installed',
+    'Re-run the installer, or: uv venv --seed .venv && uv pip install --python .venv/bin/python -r requirements.txt (in ~/.agents/memB).');
+
+  const db = h('.MemBDB', 'memb.db');
+  add('memB', 'vector store', existsSync(db), existsSync(db) ? '~/.MemBDB/memb.db' : 'no database yet (empty memory)',
+    'Created on first write; run an ingest from /aos-project-init to seed it.');
+
+  add('memB', 'WebUI :8088', await portOpen(8088), 'something is listening (a bare TCP probe — it does not prove it is memB)',
+    IS_MAC ? 'launchctl load -w ~/Library/LaunchAgents/com.bdb.memb.webui.plist (installer writes it).' : 'Start src/backend/server.py from the memB module.');
+
+  if (IS_MAC) {
+    const plist = h('Library', 'LaunchAgents', 'com.bdb.memb.webui.plist');
+    add('memB', 'autostart', existsSync(plist), existsSync(plist) ? 'LaunchAgent installed' : 'no LaunchAgent — WebUI will not survive a reboot',
+      'Re-run the installer with the memB WebUI option enabled.');
+  }
+
+  const mcpPy = firstExisting(MCP_DIRS.map((d) => path.join(d, 'memb-mcp', IS_WIN ? '.venv/Scripts/python.exe' : '.venv/bin/python')));
+  add('memB', 'memb-mcp server', !!mcpPy, mcpPy ? tilde(mcpPy) : `no memb-mcp venv under: ${MCP_DIRS.map(tilde).join(', ')}`,
+    'Re-run the installer and select the memb-mcp MCP.');
+
+  const claudeCfg = readJson(h('.claude.json'));
+  const servers = Object.keys(claudeCfg?.mcpServers || {});
+  add('memB', 'memb_mcp registered', servers.some(s => s.includes('memb')), servers.length ? `${servers.length} MCP servers configured` : 'no mcpServers in ~/.claude.json',
+    'Re-run the installer; it writes the MCP block for every harness you pick.');
+}
+
+// ---------------------------------------------------------------- OpenWiki
+function checkOpenWiki() {
+  const bin = which('openwiki');
+  add('openwiki', 'CLI', !!bin, bin || 'not on PATH', 'npm install -g openwiki@latest');
+
+  const env = h('.openwiki', '.env');
+  add('openwiki', 'provider credentials', existsSync(env), existsSync(env) ? '~/.openwiki/.env' : 'no ~/.openwiki/.env — every run will fail auth',
+    'openwiki auth <provider>   (google | openai | groq | openrouter | ollama …)');
+
+  if (bin) {
+    try {
+      const out = execFileSync(bin, ['integrations', 'list'], { encoding: 'utf8', timeout: 15000 });
+      // The status enum includes "not-installed", whose substring would match a
+      // naive includes('installed') — compare the exact tab-separated field.
+      const installed = out.split('\n')
+        .map(l => l.split('\t'))
+        .filter(f => f[1]?.trim() === 'installed')
+        .map(f => f[0].trim());
+      add('openwiki', 'host integrations', installed.length > 0, installed.length ? installed.join(', ') : 'no harness integration installed',
+        'openwiki integrations install claude   (repeat for codex/cursor/opencode as needed).');
+    } catch {
+      add('openwiki', 'host integrations', false, 'integrations list failed', 'Check `openwiki integrations list` manually.');
+    }
+  }
+
+  if (IS_MAC) {
+    const plist = h('Library', 'LaunchAgents', 'com.bdb.openwiki.daemon.plist');
+    add('openwiki', 'refresh daemon', existsSync(plist), existsSync(plist) ? 'LaunchAgent installed (2-hourly)' : 'no daemon — wikis only update when you run openwiki by hand',
+      'Re-run the installer with an OpenWiki API key, or run the skill script: openwiki-skill/scripts/install_daemon.sh');
+  }
+}
+
+// ---------------------------------------------------------------- Synapse
+async function checkSynapse() {
+  // installer.js skips the ~/.local/bin symlink on Windows and leaves the
+  // binary inside the module, so look there too before calling it missing.
+  const moduleDir = findModule('bdb-synapse');
+  const inModule = moduleDir && firstExisting([
+    path.join(moduleDir, 'bin', IS_WIN ? 'synapse.js' : 'synapse'),
+    path.join(moduleDir, 'bin', 'synapse-darwin-arm64'),
+    path.join(moduleDir, 'bin', 'synapse-linux-amd64'),
+  ]);
+  const bin = which('synapse') || (existsSync(h('.local', 'bin', 'synapse')) ? '~/.local/bin/synapse' : null) || (inModule && tilde(inModule));
+  add('synapse', 'binary available', !!bin, bin || 'no binary on PATH or in the module',
+    IS_WIN ? 'Re-run the installer; on Windows the binary stays in the module rather than being symlinked.'
+           : 'Re-run the installer (it symlinks ~/.local/bin/synapse), and add ~/.local/bin to PATH.');
+  add('synapse', 'daemon :7781', await portOpen(7781), 'something is listening (a bare TCP probe — it does not prove it is Synapse)',
+    IS_MAC ? 'launchctl load -w ~/Library/LaunchAgents/com.bdb.synapse.plist' : 'synapse serve --port 7781');
+}
+
+// ---------------------------------------------------------------- report
+function report() {
+  if (JSON_OUT) {
+    console.log(JSON.stringify({ ok: results.every(r => r.ok), results }, null, 2));
+    return;
+  }
+  let area = '';
+  for (const r of results) {
+    if (r.area !== area) { area = r.area; console.log(`\n${area.toUpperCase()}`); }
+    console.log(`  ${r.ok ? '✅' : '❌'} ${r.name.padEnd(26)} ${r.detail}`);
+    if (!r.ok) console.log(`     ↳ fix: ${r.fix}`);
+  }
+  const bad = results.filter(r => !r.ok);
+  console.log(`\n${results.length - bad.length}/${results.length} checks pass.` + (bad.length ? ` ${bad.length} need attention.` : ' AOS is fully wired.'));
+}
+
+checkPrereqs();
+checkAos();
+checkHooks();
+await checkMemb();
+checkOpenWiki();
+await checkSynapse();
+report();
+process.exit(results.some(r => !r.ok) ? 1 : 0);