@hybridlabor-api/aos 4.3.0 → 4.4.1

package/.claude/hooks/memb-inject.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// aos-hook-version: 2
+/**
+ * memB ambient memory hook for Claude Code (UserPromptSubmit).
+ *
+ * The version line above is what /aos-setup's doctor reads to tell a current
+ * hook from a stale one left behind by an older install. Bump it whenever this
+ * file changes in a way a machine must actually pick up, and bump the expected
+ * value in aos-doctor.mjs in the same commit.
+ *
+ * Reads ~/.MemBDB/memb.db directly through node:sqlite and injects the most
+ * relevant memories as ephemeral additionalContext — nothing is written to
+ * disk and nothing lands in git. Fails open: any error exits 0 silently, so a
+ * broken memory store can never block a prompt.
+ *
+ * Install: copy to ~/.claude/hooks/memb-inject.mjs and wire it as a
+ * UserPromptSubmit hook (see the aos-setup skill, section 4).
+ *
+ * Optional: put standing facts (persona, brand, house rules) one per line in
+ * ~/.MemBDB/ambient-persona.txt — they are prepended to every prompt.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// node:sqlite is imported dynamically INSIDE the try below, never at top level:
+// it was flagged behind --experimental-sqlite until Node 22.13, and a top-level
+// import that throws escapes this file's try/catch entirely — surfacing a hook
+// error on every prompt instead of failing open, which is the one thing this
+// hook must never do.
+
+const COLLECTION = 'bdb_agent_memory';
+const failOpen = () => process.exit(0);
+
+try {
+  let inputRaw = '';
+  try { inputRaw = readFileSync(0, 'utf8'); } catch { failOpen(); }
+  if (!inputRaw || !inputRaw.trim()) failOpen();
+
+  let eventData;
+  try { eventData = JSON.parse(inputRaw); } catch { failOpen(); }
+
+  const prompt = (eventData.prompt || '').trim();
+  const cwd = eventData.cwd || process.cwd();
+  const projectName = path.basename(cwd);
+  const home = os.homedir();
+
+  const contextItems = [];
+
+  // 1. Standing facts, if the user keeps any.
+  const personaFile = path.join(home, '.MemBDB', 'ambient-persona.txt');
+  if (existsSync(personaFile)) {
+    for (const line of readFileSync(personaFile, 'utf8').split('\n')) {
+      const t = line.trim();
+      if (t && !t.startsWith('#')) contextItems.push(`- ${t}`);
+    }
+  }
+
+  const dbPath = path.join(home, '.MemBDB', 'memb.db');
+  if (!existsSync(dbPath)) failOpen();
+  const { DatabaseSync } = await import('node:sqlite');
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  db.exec('PRAGMA busy_timeout = 5000;');
+
+  const textOf = (payload) => {
+    const p = JSON.parse(payload);
+    return (p.memory || p.data || '').trim().replace(/\s+/g, ' ');
+  };
+
+  // 2. Memories bound to this project (memB's project_id is the folder name).
+  if (projectName && projectName !== path.basename(home)) {
+    try {
+      const rows = db.prepare(`
+        SELECT payload FROM memb_vectors
+        WHERE collection = ?
+          AND (json_extract(payload, '$.project_id') = ?
+            OR json_extract(payload, '$.metadata.project_id') = ?)
+        ORDER BY rowid DESC
+        LIMIT 3
+      `).all(COLLECTION, projectName, projectName);
+      for (const r of rows) {
+        const text = textOf(r.payload);
+        if (text.length > 10) contextItems.push(`- Project [${projectName}]: ${text.slice(0, 180)}`);
+      }
+    } catch { /* project query is best-effort */ }
+  }
+
+  // 3. Keyword hit against the FTS index for anything else relevant.
+  if (prompt.length > 5) {
+    try {
+      const terms = prompt
+        .replace(/[^\p{L}\p{N}_-]/gu, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 3)
+        .slice(0, 4);
+      if (terms.length) {
+        const rows = db.prepare(`
+          SELECT v.payload
+          FROM memb_fts f
+          JOIN memb_vectors v ON f.id = v.id
+          WHERE f.collection = ? AND memb_fts MATCH ?
+          ORDER BY rank
+          LIMIT 2
+        `).all(COLLECTION, terms.map((t) => `${t}*`).join(' OR '));
+        for (const r of rows) {
+          const text = textOf(r.payload);
+          if (text && !contextItems.some((e) => e.includes(text.slice(0, 50)))) {
+            contextItems.push(`- Domain memory: ${text.slice(0, 180)}`);
+          }
+        }
+      }
+    } catch { /* FTS table may not exist on an empty store */ }
+  }
+
+  if (contextItems.length) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: '[memB Ambient Memory Context]\n' + contextItems.join('\n'),
+      },
+    }) + '\n');
+  }
+  process.exit(0);
+} catch {
+  failOpen();
+}

package/.claude/settings.json

@@ -20,6 +20,16 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/memb-inject.mjs\""
+          }
+        ]
+      }
     ]
   }
 }

package/README.de.md

@@ -146,7 +146,6 @@ Nachfolgend finden Sie die vollständige Übersicht aller in diesem Paket enthal
 | `github-repo` | Standards and workflows for writing, formatting, sanitizing, and publishing high-quality GitHub repositories, complementing openwiki-skill. |
 | `github-workflow-automation` | Patterns for automating GitHub workflows with AI assistance, inspired by [Gemini CLI](https://github.com/google-gemini/gemini-cli) and modern DevOps practices. |
 | `go-playwright` | Expert capability for robust, stealthy, and efficient browser automation using Playwright Go. |
-| `google-sheets-automation` | Lightweight Google Sheets integration with standalone OAuth authentication. No MCP server required. Full read/write access. |
 | `n8n-code-javascript` | Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with $helpers, working with dates using DateTime, troubleshooting Code node errors, or choosing between Code node modes. |
 | `n8n-code-python` | Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes. |
 | `n8n-expression-syntax` | Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows. |
@@ -294,7 +293,6 @@ Nachfolgend finden Sie die vollständige Übersicht aller in diesem Paket enthal
 | `bdb-updater` | Proactively check for and install updates to the BDB Antigravity Skills package via NPM. |
 | `monorepo-management` | Build efficient, scalable monorepos that enable code sharing, consistent tooling, and atomic changes across multiple packages and applications. |
 | `obsidian-markdown` | Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes. |
-| `senior-fullstack` | Complete toolkit for senior fullstack with modern tools and best practices. |
 | `token-saver-config` | Context window output compression engine for CLI commands (60-99% token reduction). |
 | `web-performance-optimization` | Optimize website and web application performance including loading speed, Core Web Vitals, bundle size, caching strategies, and runtime performance |
 

package/README.md

@@ -373,7 +373,6 @@ While heavily optimized for the creative tech industry, these skills are deeply
 
 | Skill | Description |
 |-------|-------------|
-| `google-sheets-automation` | Lightweight Google Sheets integration with standalone OAuth authentication. Full read/write access. |
 | `MCP_Manage` | Manages the BDB specialized MCP servers including Unreal Engine, Rhino 7/8, DaVinci Resolve, grandMA3, Resolume, GitHub, Chrome DevTools, and TouchDesigner. |
 | `n8n-code-javascript` | Write JavaScript code in n8n Code nodes. `$input`/`$json`/`$node` syntax, HTTP requests, DateTime handling. |
 | `n8n-code-python` | Write Python code in n8n Code nodes. `_input`/`_json`/`_node` syntax and standard library. |
@@ -383,7 +382,6 @@ While heavily optimized for the creative tech industry, these skills are deeply
 | `notion-automation` | Automate Notion tasks via Rube MCP (Composio): pages, databases, blocks, comments, users. |
 | `obsidian-markdown` | Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and Obsidian-specific syntax. |
 | `playwright-skill` | Browser automation and testing with Playwright. Path-aware installation across plugin systems. |
-| `senior-fullstack` | Complete toolkit for senior fullstack development with modern tools and best practices. |
 | `slack-automation` | Automate Slack workspace operations: messaging, search, channel management, and reaction workflows. |
 | `token-saver-config` | Context window output compression engine for CLI commands (60-99% token reduction). |
 | `webapp-testing` | Test local web applications with native Python Playwright scripts. |

package/README.pt.md

@@ -150,7 +150,6 @@ Abaixo está a visão geral completa de todas as skills curadas de agentes inclu
 | `github-repo` | Padrões e fluxos de trabalho para escrever, formatar, higienizar e publicar repositórios GitHub de alta qualidade, complementando a skill openwiki-skill. |
 | `github-workflow-automation` | Padrões para automatizar fluxos de trabalho do GitHub com assistência de IA, inspirados pelo [Gemini CLI](https://github.com/google-gemini/gemini-cli) e práticas modernas de DevOps. |
 | `go-playwright` | Capacidade especialista para automação de navegador robusta, furtiva e eficiente usando Playwright Go. |
-| `google-sheets-automation` | Integração leve com Google Sheets com autenticação OAuth autônoma. Não requer servidor MCP. Acesso completo de leitura/escrita. |
 | `n8n-code-javascript` | Escreva código JavaScript em nós Code do n8n. Use ao escrever JavaScript no n8n, usando sintaxe $input/$json/$node, fazendo requisições HTTP com $helpers, trabalhando com datas usando DateTime, solucionando erros de nó Code, ou escolhendo entre modos de nó Code. |
 | `n8n-code-python` | Escreva código Python em nós Code do n8n. Use ao escrever Python no n8n, usando sintaxe _input/_json/_node, trabalhando com a biblioteca padrão, ou quando precisar entender as limitações do Python em nós Code do n8n. |
 | `n8n-expression-syntax` | Valide a sintaxe de expressões n8n e corrija erros comuns. Use ao escrever expressões n8n, usando sintaxe {{}}, acessando variáveis $json/$node, solucionando erros de expressão, ou trabalhando com dados de webhook em fluxos de trabalho. |
@@ -298,7 +297,6 @@ Abaixo está a visão geral completa de todas as skills curadas de agentes inclu
 | `bdb-updater` | Verifique proativamente e instale atualizações no pacote BDB Antigravity Skills via NPM. |
 | `monorepo-management` | Construa monorepos eficientes e escaláveis que possibilitem compartilhamento de código, ferramentas consistentes e alterações atômicas em múltiplos pacotes e aplicações. |
 | `obsidian-markdown` | Crie e edite Obsidian Flavored Markdown com wikilinks, embeds, callouts, propriedades e outras sintaxes específicas do Obsidian. Use ao trabalhar com arquivos .md no Obsidian, ou quando o usuário mencionar wikilinks, callouts, frontmatter, tags, embeds ou notas Obsidian. |
-| `senior-fullstack` | Kit de ferramentas completo para fullstack sênior com ferramentas modernas e melhores práticas. |
 | `token-saver-config` | Motor de compressão de saída de janela de contexto para comandos CLI (60-99% de redução de tokens). |
 | `web-performance-optimization` | Otimize o desempenho de sites e aplicações web, incluindo velocidade de carregamento, Core Web Vitals, tamanho de bundle, estratégias de cache e desempenho de tempo de execução. |
 

package/THIRD_PARTY_NOTICES.md

@@ -195,7 +195,7 @@ quoted verbatim from that file.
 | [anthropics/skills](https://github.com/anthropics/skills) | Apache-2.0 (per-skill `LICENSE.txt`; the repo has no root licence) | Copyright 2026 Anthropic, PBC. | `webapp-testing`, `web-artifacts-builder` |
 | [AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo) | MIT | Copyright (c) 2026 agricidaniel | `seo`, `seo-technical` |
 | [neondatabase/agent-skills](https://github.com/neondatabase/agent-skills) | Apache-2.0 | template placeholder upstream; holder is Neon | `using-neon` |
-| [sanjay3290/ai-skills](https://github.com/sanjay3290/ai-skills) | Apache-2.0 | see upstream `LICENSE` | `deep-research`, `google-sheets-automation` |
+| [sanjay3290/ai-skills](https://github.com/sanjay3290/ai-skills) | Apache-2.0 | see upstream `LICENSE` | `deep-research` |
 | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) | MIT | Copyright (c) 2023 shadcn | `shadcn` |
 | [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) | MIT | Copyright (c) 2026 Steph Ango | `obsidian-markdown` |
 | [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | MIT | Copyright (c) 2025 Alireza Rezvani | `senior-frontend`, `landing-page-generator` |

package/docs/skills_table.md

@@ -35,7 +35,6 @@
 | `github-repo` | Standards and workflows for writing, formatting, sanitizing, and publishing high-quality GitHub repositories, complementing openwiki-skill. |
 | `github-workflow-automation` | Patterns for automating GitHub workflows with AI assistance, inspired by [Gemini CLI](https://github.com/google-gemini/gemini-cli) and modern DevOps practices. |
 | `go-playwright` | Expert capability for robust, stealthy, and efficient browser automation using Playwright Go. |
-| `google-sheets-automation` | Lightweight Google Sheets integration with standalone OAuth authentication. No MCP server required. Full read/write access. |
 | `n8n-code-javascript` | Write JavaScript code in n8n Code nodes. Use when writing JavaScript in n8n, using $input/$json/$node syntax, making HTTP requests with $helpers, working with dates using DateTime, troubleshooting Code node errors, or choosing between Code node modes. |
 | `n8n-code-python` | Write Python code in n8n Code nodes. Use when writing Python in n8n, using _input/_json/_node syntax, working with standard library, or need to understand Python limitations in n8n Code nodes. |
 | `n8n-expression-syntax` | Validate n8n expression syntax and fix common errors. Use when writing n8n expressions, using {{}} syntax, accessing $json/$node variables, troubleshooting expression errors, or working with webhook data in workflows. |
@@ -188,7 +187,6 @@
 | `bdb-updater` | Proactively check for and install updates to the BDB Antigravity Skills package via NPM. |
 | `monorepo-management` | Build efficient, scalable monorepos that enable code sharing, consistent tooling, and atomic changes across multiple packages and applications. |
 | `obsidian-markdown` | Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes. |
-| `senior-fullstack` | Complete toolkit for senior fullstack with modern tools and best practices. |
 | `token-saver-config` | Context window output compression engine for CLI commands (60-99% token reduction). |
 | `web-performance-optimization` | Optimize website and web application performance including loading speed, Core Web Vitals, bundle size, caching strategies, and runtime performance |
 

package/installer.js

@@ -508,10 +508,30 @@ function resolveFileConflict(sourcePath, targetPath, manifest, knownSourceHashes
 
     const diskHash = computeFileHash(targetPath);
 
-    // Case: foreign – no manifest entry AND disk hash unknown to this payload.
+    // Case: unrecognised content at a path this payload owns.
+    //
+    // This used to skip, on the reading that unknown content means a file the
+    // installer did not place. But resolveFileConflict only ever sees paths the
+    // payload is actively writing, so the path IS ours -- and the commonest
+    // cause of unknown content is simply an older release of our own file,
+    // installed before manifest tracking existed and therefore never adopted.
+    // Skipping froze those permanently: v4.4.0 still found skills on disk
+    // carrying pre-reorg ~/bdb-dev paths and a stale `category:`, untouched
+    // across every update since, because bootstrap adoption only catches a file
+    // that is byte-identical to the current payload.
+    //
+    // So update it, and keep the protection where it belongs -- in the backup,
+    // not in refusing to write. A genuine local edit is recoverable from .bak
+    // rather than silently outvoting the shipped version forever.
     if (!manifestEntry && !knownSourceHashes.has(diskHash)) {
-        log.warn(`[manifest] Foreign file at ${targetPath} — left untouched.`);
-        return 'skipped';
+        const bakPath = `${targetPath}.bak`;
+        try { fs.copyFileSync(targetPath, bakPath); } catch (e) {
+            log.warn(`[manifest] Could not create backup ${bakPath}: ${e.message}`);
+        }
+        fs.copyFileSync(sourcePath, targetPath);
+        manifest[targetPath] = { path: targetPath, sha256: sourceHash, version: pkg.version, installedAt: new Date().toISOString() };
+        log.warn(`[manifest] Unrecognised ${path.basename(targetPath)} backed up to ${bakPath}, shipped version written.`);
+        return 'bak';
     }
 
     // Case: first-run bootstrap – disk hash matches source hash but no manifest entry.
@@ -2717,7 +2737,7 @@ function injectHarnessRules() {
                     log.step(`Copied ${dir} to ${targetPath}`);
                 }
             });
-            mergeBdbSettingsHooks(path.join(homeDir, '.claude', 'settings.json'));
+            installGlobalHooks();
         }, '');
 
         installStep('sync global .agents/', () => {
@@ -2731,26 +2751,53 @@ function injectHarnessRules() {
     }
 }
 
-// Merge the BDB gate hooks into a Claude Code settings.json without clobbering
+// Deliver the hook scripts to ~/.claude/hooks/ and wire them in settings.json.
+// Both the full install and Quick Update funnel through here. Quick Update used
+// to do neither: it refreshes skills and submodules, but hooks are harness
+// plumbing rather than skills, so an existing install updating to a version
+// that adds or changes a hook silently never received it -- which is exactly
+// what happened to memb-inject.mjs in v4.4.0, on the machines that needed it
+// most (a fresh install got it; every machine that already had AOS did not).
+function installGlobalHooks() {
+    const hooksSrc = path.join(srcDir, '.claude', 'hooks');
+    if (fs.existsSync(hooksSrc)) {
+        copyDirRecursiveSync(hooksSrc, path.join(homeDir, '.claude', 'hooks'));
+        log.step(`Installed hooks to ${path.join(homeDir, '.claude', 'hooks')}`);
+    }
+    mergeBdbSettingsHooks(path.join(homeDir, '.claude', 'settings.json'));
+}
+
+// Merge the BDB hooks -- the two gates plus the memB ambient-memory hook --
+// into a Claude Code settings.json without clobbering
 // user-owned keys (v3.13 audit BLOCKER-3: the harness-dir copy used to
 // overwrite the file wholesale, silently dropping e.g. enabledPlugins). Only
 // BDB-owned hook entries -- identified by their script name inside `command` --
 // are replaced or added; every other key and every foreign hook entry survives
 // untouched. With projectLocal, `${HOME}` hook paths are rewritten to
 // `$CLAUDE_PROJECT_DIR` so a project harness is self-contained on every
-// collaborator's checkout. If the existing file is not valid JSON(C), nothing
+// collaborator's checkout -- the shipped template already writes the gates
+// with `$CLAUDE_PROJECT_DIR` directly, so today that rewrite is a safety net
+// for a future `${HOME}`-written gate rather than machinery in active use. If the existing file is not valid JSON(C), nothing
 // is overwritten: the original is backed up as .corrupt_<ts>.bak and the
 // merged result goes to a .bdb-new.json sidecar -- the same recovery pattern
 // the MCP config merge in installMcpsForTarget uses.
 function mergeBdbSettingsHooks(settingsPath, { projectLocal = false } = {}) {
-    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs'];
+    const bdbHookScripts = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs'];
+    // memb-inject reads the machine-global memB store under $HOME and is
+    // installed once per machine, so it stays $HOME-anchored even inside a
+    // project harness -- unlike the two gate hooks, which are per-checkout by
+    // design. Pointing it at $CLAUDE_PROJECT_DIR would make it fail on every
+    // prompt in any project the harness was never installed into.
+    const machineGlobalHooks = ['memb-inject.mjs'];
     const isBdbEntry = (entry) => {
         const cmds = (entry && Array.isArray(entry.hooks) ? entry.hooks : [])
             .map((h) => (h && typeof h.command === 'string' ? h.command : ''))
             .join(' ');
         return bdbHookScripts.some((name) => cmds.includes(name));
     };
-    const localize = (cmd) => (projectLocal ? cmd.split('${HOME}').join('$CLAUDE_PROJECT_DIR') : cmd);
+    const localize = (cmd) => (projectLocal && !machineGlobalHooks.some((n) => cmd.includes(n))
+        ? cmd.split('${HOME}').join('$CLAUDE_PROJECT_DIR')
+        : cmd);
     const cloneBdbEntries = (entries) =>
         JSON.parse(JSON.stringify(entries)).map((e) => ({
             ...e,
@@ -2833,11 +2880,11 @@ function installProjectHarness() {
         }
     }, '/startcycle dispatch degrades to graph.md as a manual guide.');
 
-    installStep('copy gate hooks into project', () => {
+    installStep('copy hooks into project', () => {
         const hooksSrc = path.join(srcDir, '.claude', 'hooks');
         if (fs.existsSync(hooksSrc)) {
             copyDirRecursiveSync(hooksSrc, path.join(projectClaudeDir, 'hooks'));
-            log.step(`Copied gate hooks to ${path.join(projectClaudeDir, 'hooks')}`);
+            log.step(`Copied hooks to ${path.join(projectClaudeDir, 'hooks')}`);
         }
     }, 'go-gate / graph-gate enforcement stays inactive in this project.');
 
@@ -3287,6 +3334,10 @@ async function runQuickUpdate(installState) {
     syncSkillsToGlobalHarnesses(excludeSkills);
     s.stop('Skills refreshed');
 
+    installStep('refresh gate + memory hooks', () => {
+        installGlobalHooks();
+    }, 'Hooks keep whatever version this machine already had.');
+
     // OpenWiki setup only ever ran on a brand-new install (main()'s fresh-install
     // branch below) -- an existing install running Quick Update never got offered
     // it and never had its daemon schedule refreshed. promptCredentials() already
@@ -3717,6 +3768,7 @@ if (require.main === module) {
 // Exported for tests -- requiring installer.js must not launch the TUI.
 module.exports = {
     mergeBdbSettingsHooks,
+    installGlobalHooks,
     installProjectHarness,
     mirrorMcpServersTo,
     // Manifest store (exported for verification tests)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "bin": {
@@ -45,7 +45,21 @@
     "skills/",
     "mcps/",
     "scripts/",
-    "vendor/"
+    "vendor/",
+    "!mcps/**/*.png",
+    "!mcps/**/*.jpg",
+    "!mcps/**/*.jpeg",
+    "!mcps/**/*.gif",
+    "!mcps/**/*.webp",
+    "!mcps/**/docs/**",
+    "!mcps/**/tests/**",
+    "!mcps/**/test/**",
+    "!mcps/**/__tests__/**",
+    "mcps/tdmcp/tests/**",
+    "mcps/touchdesigner-mcp/tests/**",
+    "!mcps/tdmcp/training/**/data/**",
+    "!assets/**/*.mp4",
+    "!assets/**/*.mov"
   ],
   "keywords": [
     "codex-plugin",

package/skills/global_config/aos-project-init/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: aos-project-init
+description: >-
+  Wire one project folder into AOS — git and private remote, AGENTS.md with its
+  harness symlinks, the dispatcher harness, an OpenWiki wiki, memB project
+  memory, and a Synapse map. Use when starting a new project, or when an
+  existing repo has drifted and its agents behave like they know nothing about it.
+category: bdb-core
+risk: low
+source: bdb
+date_added: "2026-09-13"
+---
+
+# AOS Project Init — Per Workspace
+
+A machine-level AOS install gives an agent the skills. It gives it nothing
+about *this* project: no repo rules, no memory bound to it, no wiki, no
+dispatcher contract. That per-project layer is what this skill installs.
+
+Machine-level setup is `/aos-setup` and comes first — this skill assumes memB,
+OpenWiki and Synapse already exist on the machine.
+
+**This is prompt-driven, not a script that runs blind.** Explore, report,
+confirm, then write.
+
+---
+
+## 1. Measure
+
+```bash
+node ~/.claude/skills/aos-project-init/scripts/aos-project-doctor.mjs [dir]
+```
+
+`[dir]` defaults to the current directory. `--json` for machine-readable
+output. Up to 16 checks across five areas — a folder that is not a git repo
+yet reports that one row and skips the rest of the `git` block, and the
+visibility row appears only for a GitHub remote:
+
+| Area | What is verified |
+|---|---|
+| `git` | repo, `origin`, **private** visibility, `.gitignore` covers `.env` |
+| `docs` | `AGENTS.md`, and `CLAUDE.md` / `GEMINI.md` / `CODEX.md` as symlinks to it |
+| `harness` | `.agents/graph.md`, `.agents/nodes.json`, `.claude/{workflows,hooks,agents,settings.json}` |
+| `openwiki` | `.openwiki/` holds pages |
+| `memB` | memories bound to `project_id = <folder name>` |
+
+Report the failing rows before touching anything. On an existing repo, some
+failures are deliberate — a public repo that is meant to be public, a scratch
+folder with no remote. Ask rather than "fixing" those.
+
+---
+
+## 2. Git and the remote
+
+```bash
+git init && git add -A && git commit -m "chore: initial commit"
+gh repo create <name> --private --source=. --remote=origin
+```
+
+Repositories are **private by default**. Verify rather than assume — the
+doctor reads actual visibility through `gh`, not intent. Live secrets never
+enter the repo: keep `.env` files outside it and commit a placeholder.
+
+---
+
+## 3. AGENTS.md and its symlinks
+
+One file holds the repo's agent rules; every harness reads the same bytes:
+
+```bash
+cp ~/.claude/skills/aos-project-init/assets/AGENTS.template.md AGENTS.md
+ln -sf AGENTS.md CLAUDE.md
+ln -sf AGENTS.md GEMINI.md
+ln -sf AGENTS.md CODEX.md
+```
+
+Then fill the template in — see [AGENTS.template.md](./assets/AGENTS.template.md).
+Do not leave the placeholders: an `AGENTS.md` full of `<PROJECT NAME>` is worse
+than none, because agents will trust it. Interview the user for the stack, the
+commands, and above all the **domain notes** — the constraints that are not
+derivable from the code.
+
+If a real `CLAUDE.md` already exists with content of its own, merge it into
+`AGENTS.md` first and only then replace it with the symlink. Never silently
+overwrite it.
+
+---
+
+## 4. The dispatcher harness
+
+Only for projects that will actually run `/startcycle-graph` — it is not
+required for a small repo.
+
+```bash
+npx -y @hybridlabor-api/aos --project-harness
+```
+
+Copies into the project, writing nothing to `$HOME`:
+
+- `.agents/` — the graph contract, node registry, state schema
+- `.claude/workflows/` — the dispatcher
+- `.claude/hooks/` — `go-gate.mjs`, `graph-gate.mjs` and `memb-inject.mjs`
+  (the memory hook stays `$HOME`-anchored; only the gates become project-local)
+- `.claude/agents/` — the agent definitions the dispatcher's prompts reference
+- `.claude/settings.json` — wired to the project-local hooks
+
+Take all of it or none: a bare `.agents/` copy leaves the graph contract
+half-installed, and the dispatcher's pointers resolve to nothing.
+
+---
+
+## 5. memB — bind memory to this project
+
+memB scopes memories by `project_id`, and `project_id` is **the folder's
+basename**. Two consequences worth stating out loud:
+
+- Renaming the folder orphans every memory bound to the old name.
+- Two folders with the same basename share one memory scope.
+
+Seed the project by ingesting it:
+
+```bash
+MCP=~/.gemini/config/mcps/memb-mcp          # Gemini / Antigravity install
+"$MCP/.venv/bin/python" "$MCP/memb_ingest.py" <project dir>
+```
+
+The MCP payload does not always land there — the installer picks the directory
+per harness, so on a Claude-only machine it sits under
+`~/Library/Application Support/Claude/mcps/` (`%APPDATA%\Claude\mcps\` on
+Windows), and under `.cursor` / `.codex` / `.windsurf` for those. Take the path
+`/aos-setup`'s doctor prints in its `memb-mcp server` row rather than assuming
+this one.
+
+Add `--transcripts` only when past conversation logs should be pulled in too —
+that is off by default for a reason.
+
+Afterwards, write the decisions that matter through the memB MCP with an
+explicit `project_id`: `add_memory({ text: "…", category: "project_node",
+project_id: "<folder name>" })`. Never write credentials or high-entropy
+strings into memory.
+
+Re-run the doctor to confirm the count went above zero. An ingest script that
+exits `0` is not evidence that anything was stored.
+
+---
+
+## 6. OpenWiki — the project wiki
+
+```bash
+openwiki --init              # first time, inside the project
+openwiki --update            # after significant changes
+```
+
+Pages land in `.openwiki/`. The machine-level daemon refreshes wikis every two
+hours once the repo has one; without `--init` this repo is simply skipped.
+
+Requires provider credentials from `/aos-setup` (`openwiki auth <provider>`).
+
+---
+
+## 7. Synapse — spatial map
+
+```bash
+synapse map .
+```
+
+Optional, and useful mainly on a codebase large enough that structure is hard
+to hold in your head. Needs the daemon on `:7781` (`/aos-setup` covers it).
+
+---
+
+## 8. Confirm
+
+```bash
+node ~/.claude/skills/aos-project-init/scripts/aos-project-doctor.mjs
+# 16/16 checks pass. Project is fully wired.
+```
+
+Report the doctor's own count, and name explicitly anything left failing on
+purpose. Then commit the new files — `chore:` for the harness wiring, `docs:`
+for `AGENTS.md`.
+
+---
+
+## Red flags
+
+- Committing an `AGENTS.md` still holding template placeholders.
+- Replacing an existing `CLAUDE.md` with a symlink without merging its content.
+- Reporting the memB ingest as done from the script's exit code instead of the
+  memory count.
+- Installing the dispatcher harness into a repo that will never run the graph —
+  five directories of machinery nobody uses.
+- Renaming a project folder later without moving its memories to the new
+  `project_id`.

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).