@hybridlabor-api/aos 4.4.0 → 4.4.2-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.4.0",
+  "version": "4.4.2-beta.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "bin": {
@@ -8,8 +8,10 @@
     "bdb-dev-optimized-agent-skills": "installer.js",
     "bdb-agent-skills-pro": "installer.js",
     "bdb-agent-skills": "installer.js",
-    "setup-saas": "bin/setup-saas.mjs",
-    "aos-plan-canvas": "skills/global_config/plan-canvas/scripts/plan-canvas.js"
+    "aos-plan-canvas": "skills/global_config/plan-canvas/scripts/plan-canvas.js",
+    "aos-dashboard": "bin/aos-dashboard.mjs",
+    "aos-config": "bin/aos-config.mjs",
+    "aos-uninstall": "bin/aos-uninstall.mjs"
   },
   "scripts": {
     "validate": "node scripts/validate-skills.mjs",
@@ -59,7 +61,14 @@
     "mcps/touchdesigner-mcp/tests/**",
     "!mcps/tdmcp/training/**/data/**",
     "!assets/**/*.mp4",
-    "!assets/**/*.mov"
+    "!assets/**/*.mov",
+    "!mcps/**/queue.db*",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!mcps/vectorworks-mcp/**",
+    "!mcps/davinci-resolve-mcp/**",
+    "!mcps/davinci-mcp-professional/**",
+    "!mcps/blender-mcp-server/**"
   ],
   "keywords": [
     "codex-plugin",

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

@@ -1,10 +1,10 @@
 ---
 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.
+  Interview a project folder into AOS and write the result: a stable slug and
+  domain in .aos/project.json, an OpenWiki wiki that is actually watched and
+  does not index junk, memB memory bound to the slug, a Synapse map, AGENTS.md
+  with its harness symlinks, and optionally CI and issue triage.
 category: bdb-core
 risk: low
 source: bdb
@@ -13,182 +13,149 @@ 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.
+`/aos-setup` prepares the machine. This prepares one folder in it — and unlike
+the machine skill, **this one writes**. It asks what it cannot know, shows what
+it intends to write, and writes it once you agree.
 
-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.
+Everything it decides lands in `.aos/project.json`, so a second run knows what
+was already settled and changes only what you ask it to.
 
 ---
 
-## 1. Measure
+## 1. Preconditions
 
 ```bash
-node ~/.claude/skills/aos-project-init/scripts/aos-project-doctor.mjs [dir]
+aos-config show    # is this machine's vocabulary present?
 ```
 
-`[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>` |
+If it reports *unvollständig*, stop and run `/aos-setup` first. The domain list
+is per-machine and nothing ships with one — guessing here would invent a
+vocabulary the user never chose.
 
-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
+Then measure this folder:
 
 ```bash
-git init && git add -A && git commit -m "chore: initial commit"
-gh repo create <name> --private --source=. --remote=origin
+node ~/.claude/skills/aos-project-init/scripts/aos-project-doctor.mjs
 ```
 
-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.
+Report the failing rows before touching anything. On an existing repo some
+failures are deliberate: a repo public on purpose, a scratch folder with no
+remote, a project nobody wants the wiki daemon to visit. Ask rather than
+"fixing" those.
 
 ---
 
-## 3. AGENTS.md and its symlinks
+## 2. The interview
 
-One file holds the repo's agent rules; every harness reads the same bytes:
+One question at a time, each with a proposal the user can accept in a word.
+Skip anything already settled in `.aos/project.json` unless asked to change it.
 
-```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
-```
+**Name and slug.** Propose the folder name for both. The slug becomes the memB
+`project_id`, and it is written down precisely so it survives a rename: a
+binding derived from the basename orphans every memory the day the folder
+moves, and two folders sharing a basename share one memory scope.
 
-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.
+**Domain.** Offer the list from `aos-config`, preselected by what the path
+implies — the first segment under the workspace root. If the project sits
+outside that root, ask instead of guessing.
 
-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.
+**Wiki.** Three separate questions, because they are three separate things:
+initialise a wiki here at all · **watch it**, so the daemon refreshes it every
+2h · write `.openwikiignore`.
 
----
+Watching is not free. Every watched project with changes costs an LLM call per
+cycle, and a free-tier key hits quota on a handful. Recommend watching repos
+under active work and leaving archives out.
 
-## 4. The dispatcher harness
+**memB.** Bind the slug; offer a one-time ingest of the folder. Ingest reads a
+lot — offer it, never assume it.
 
-Only for projects that will actually run `/startcycle-graph` — it is not
-required for a small repo.
+**Synapse.** A spatial map earns its keep on a codebase too large to hold in
+your head. Ask; do not default it on.
 
-```bash
-npx -y @hybridlabor-api/aos --project-harness
-```
+**AGENTS.md.** If missing, offer the template. If a real `CLAUDE.md` already
+holds content, merge it into `AGENTS.md` first and only then replace it with a
+symlink. Never silently overwrite it.
 
-Copies into the project, writing nothing to `$HOME`:
+**With a GitHub remote, two more.** Skip both entirely without a remote — a
+local-only repo has nowhere to put them, and a skipped question is clearer than
+one answered "no".
 
-- `.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
+- **CI:** none · a gate (lint, typecheck, test — matched to the project type) ·
+  gate plus `release-please`.
+- **Triage:** none · GitHub labels (`needs-triage`, `needs-info`,
+  `ready-for-agent`, `ready-for-human`, `wontfix`) · local markdown in
+  `.scratch/`.
 
-Take all of it or none: a bare `.agents/` copy leaves the graph contract
-half-installed, and the dispatcher's pointers resolve to nothing.
+`release-please` computes the version from Conventional Commits and nothing
+else: an unprefixed subject is invisible to it, and one `feat:` forces a minor
+bump however small the change. Offering it imposes that rule on the project, so
+write the rule into `AGENTS.md` in the same breath — and ask what the version
+policy is. Some repos here move in patch steps only, where `feat:` needs
+explicit permission.
 
 ---
 
-## 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>
+## 3. Write
+
+Show every intended write as one list, then write on agreement.
+
+```json
+{
+  "name": "<Project Name>",
+  "slug": "<stable-slug>",
+  "domain": "<from aos-config>",
+  "openwiki": { "enabled": true, "watch": true },
+  "memb": { "projectId": "<stable-slug>" },
+  "synapse": false,
+  "ci": "gate",
+  "triage": "github"
+}
 ```
 
-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
+Then, only for what the interview enabled:
 
 ```bash
-openwiki --init              # first time, inside the project
-openwiki --update            # after significant changes
+cp ~/.claude/skills/aos-project-init/assets/openwikiignore.template .openwikiignore
+openwiki --init                # needs `openwiki auth <provider>` from /aos-setup
 ```
 
-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>`).
-
----
+When the user chose to watch it, add the absolute path to `projects` in
+`~/.openwiki/projects.json` — that file is the daemon's watch list. Merge into
+it; never rewrite it.
 
-## 7. Synapse — spatial map
+For memB, write decisions through the MCP with the slug as `project_id` and the
+domain as `category`:
 
-```bash
-synapse map .
+```
+add_memory({ text: "…", category: "<domain>", project_id: "<slug>" })
 ```
 
-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).
+Never write credentials or high-entropy strings into memory.
 
 ---
 
-## 8. Confirm
+## 4. 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`.
+Report the doctor's own count, and name anything left failing on purpose. Then
+commit: `chore:` for wiring, `docs:` for `AGENTS.md`. Check the project's
+version policy before reaching for `feat:`.
 
 ---
 
 ## 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`.
+- Inventing a domain because `aos-config` has none. Send the user to
+  `/aos-setup` instead.
+- Deriving the memB binding from the folder name once a slug exists.
+- Treating "has a wiki" as "is watched". They are different, and that gap is
+  why wikis sit stale for months.
+- Turning watching on for every repo. Quota is real.
+- Committing an `AGENTS.md` still full of template placeholders.
+- Asking about CI or GitHub triage in a repo with no remote.
+- Offering `release-please` without writing the Conventional Commits rule into
+  `AGENTS.md` — it is a trap otherwise.

package/skills/global_config/aos-project-init/assets/openwikiignore.template

@@ -0,0 +1,62 @@
+# .openwikiignore — what the wiki agent must not read or write.
+#
+# OpenWiki ships with NO defaults: with no such file it loads zero rules and
+# indexes everything, including dependency trees and its own output. Measured
+# on one small repo: 33 of 145 graph nodes were junk — .venv internals and
+# .openwiki's own pages fed back into itself.
+#
+# gitignore syntax: `!` re-includes, a leading `/` anchors to the repo root,
+# a trailing `/` matches directories, and matching is case-insensitive.
+
+# Its own output — otherwise the wiki documents itself, recursively.
+.openwiki/
+
+# Dependencies. Someone else's code is not this project's documentation.
+node_modules/
+.venv/
+venv/
+vendor/
+Pods/
+.bundle/
+
+# Build output and caches — generated, never a source of truth.
+dist/
+build/
+out/
+target/
+coverage/
+.next/
+.turbo/
+.cache/
+__pycache__/
+*.pyc
+
+# Lockfiles: thousands of lines, no meaning for a reader.
+*.lock
+package-lock.json
+pnpm-lock.yaml
+uv.lock
+
+# Secrets. Nothing here may reach a model or a generated page.
+.env
+.env.*
+*.pem
+*.key
+id_rsa*
+secrets/
+
+# Version control internals.
+.git/
+
+# Binaries and media: no text to summarise, and expensive to read.
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.webp
+*.svg
+*.pdf
+*.zip
+*.tgz
+*.mp4
+*.mov

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

@@ -11,9 +11,18 @@ 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();
 
+// .aos/project.json is what /aos-project-init writes. Its slug is the stable
+// memB project_id: deriving it from the folder name means a rename orphans
+// every memory bound to the old one, and two folders with the same basename
+// share a memory scope.
+const aosConfig = (() => {
+  try { return JSON.parse(readFileSync(path.join(ROOT, '.aos', 'project.json'), 'utf8')); }
+  catch { return null; }
+})();
+const PROJECT = aosConfig?.slug || path.basename(ROOT);
+
 const results = [];
 const add = (area, name, ok, detail, fix) => results.push({ area, name, ok, detail, fix });
 const p = (...rel) => path.join(ROOT, ...rel);
@@ -44,6 +53,19 @@ function checkGit() {
     'Add `.env` and `*.env` to .gitignore; keep live secrets outside the repo.');
 }
 
+// ---------------------------------------------------------------- aos config
+function checkAosConfig() {
+  add('aos', '.aos/project.json', !!aosConfig,
+    aosConfig
+      ? `slug "${aosConfig.slug}"${aosConfig.domain ? ` · domain ${aosConfig.domain}` : ''}${aosConfig.watch ? ' · überwacht' : ''}`
+      : 'missing — memB binding falls back to the folder name, which breaks on rename',
+    'Run /aos-project-init in this folder.');
+
+  if (aosConfig && aosConfig.slug !== path.basename(ROOT)) {
+    add('aos', 'slug vs folder', true, `slug "${aosConfig.slug}" ≠ folder "${path.basename(ROOT)}" — intentional, the slug wins`, '');
+  }
+}
+
 // ---------------------------------------------------------------- agent docs
 function checkAgentDocs() {
   const agents = p('AGENTS.md');
@@ -84,6 +106,20 @@ function checkWiki() {
   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)');
+
+  // Without this file OpenWiki loads zero rules and indexes .venv, node_modules
+  // and its own output — measured at 23% junk on one small repo.
+  add('openwiki', '.openwikiignore', existsSync(p('.openwikiignore')),
+    existsSync(p('.openwikiignore')) ? 'exclusions in place' : 'missing — the wiki will index dependencies and its own pages',
+    'cp ~/.claude/skills/aos-project-init/assets/openwikiignore.template .openwikiignore');
+
+  // A wiki that exists is not a wiki that is refreshed.
+  let watched = false;
+  try { watched = (JSON.parse(readFileSync(path.join(HOME, '.openwiki', 'projects.json'), 'utf8')).projects || []).includes(ROOT); }
+  catch { /* the daemon has not written it yet */ }
+  add('openwiki', 'watched by the daemon', watched || pages.length === 0,
+    watched ? 'in projects.json' : pages.length ? 'has a wiki but the daemon never refreshes it' : 'no wiki, nothing to watch',
+    'Add this path to ~/.openwiki/projects.json, or let /aos-project-init do it.');
 }
 
 // ---------------------------------------------------------------- memB
@@ -129,6 +165,7 @@ function report() {
 }
 
 checkGit();
+checkAosConfig();
 checkAgentDocs();
 checkHarness();
 checkWiki();

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

@@ -21,8 +21,30 @@ 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.
+This is also where a **new agent harness** gets wired: adding Codex or
+Antigravity to a machine that already runs Claude Code is this skill's job, not
+a reinstall.
+
+For per-project wiring — a folder's slug, its wiki, its memB binding — use
+`/aos-project-init` after this one.
+
+### What each harness can actually do
+
+Portability is not uniform, and pretending otherwise is how people end up
+believing memory works everywhere:
+
+| | Skills | MCP | Hooks |
+|---|---|---|---|
+| Claude Code | `~/.claude/skills` | `~/.claude.json` | **yes** |
+| Antigravity | `~/.gemini/config/skills` | `mcp_config.json` | no |
+| Codex | `~/.codex/skills` | `config.toml` | no |
+| OpenCode | — | `opencode.jsonc` | no |
+| Cursor / Roo | `bdb-skills` | `mcp.json` | no |
+
+Only Claude Code has hooks, so only there can memB inject per prompt. Elsewhere
+the same context arrives through the rule files that harness loads at start —
+see section 5 — which means it is as fresh as the last write, not as fresh as
+the prompt. Say so plainly rather than letting someone assume parity.
 
 ---
 
@@ -59,7 +81,35 @@ one covers a block the doctor can flag.
 
 ---
 
-## 2. Install or update AOS itself
+## 2. Machine configuration
+
+Two things are machine-specific and ship with **no** value, because AOS is a
+public package: one person's `web, media, infra` means nothing on someone
+else's disk.
+
+```bash
+aos-config propose     # read this machine's layout, suggest nothing more
+aos-config show        # what is configured now
+```
+
+`propose` looks for a workspace root (`~/dev`, `~/Projects`, `~/src`, `~/code`)
+and offers its immediate subdirectories as the domain vocabulary. **Present the
+proposal, do not apply it** — the user decides which of those are real domains
+and which are just folders. Then ask for the memB `user_id`, which must never
+be invented either.
+
+```bash
+aos-config set workspaceRoot ~/dev
+aos-config set domains bdb-core,web,media,agents,infra
+aos-config set userId <the user's memB id>
+```
+
+The result lands in `~/.agents/aos-config.json`. `/aos-project-init` reads it
+to offer a domain per project and refuses to guess when it is missing.
+
+---
+
+## 3. Install or update AOS itself
 
 ```bash
 npx -y @hybridlabor-api/aos@latest
@@ -88,7 +138,7 @@ a harness directory.
 
 ---
 
-## 3. memB — memory that actually retains
+## 4. memB — memory that actually retains
 
 memB is three separate pieces, and a machine can have any subset:
 
@@ -115,7 +165,7 @@ machine — `/aos-project-init` seeds it per project.
 
 ---
 
-## 4. The ambient memory hook
+## 5. 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
@@ -123,9 +173,11 @@ 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:
+wires it as a `UserPromptSubmit` hook. **v4.4.0's Quick Update did not** — it
+refreshes skills and submodules, and hooks are harness plumbing rather than
+skills, so a machine that already had AOS updated to 4.4.0 without ever
+receiving the hook. Fixed in v4.4.1; a machine that took that update needs one
+more run:
 
 ```bash
 npx -y @hybridlabor-api/aos@latest
@@ -135,11 +187,30 @@ 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.
 
+The hook carries an `aos-hook-version:` line on its second line, and the doctor
+compares it against what the installed release expects. That is why the row can
+read *stale* rather than simply passing: a hook file that exists and is wired
+can still be an old copy carrying a bug this version fixed. When you change the
+hook in a way machines must pick up, bump that line and the expected value in
+`aos-doctor.mjs` in the same commit — the test suite fails if the two disagree.
+
 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.
 
+**On a harness without hooks** — everything except Claude Code — the same
+context is written into the rule files that harness loads instead:
+
+```bash
+python3 ~/.agents/memB/memb_auto_inject.py --global      # GEMINI.md, CODEX.md, …
+python3 ~/.agents/memB/memb_auto_inject.py --dir <repo>  # a project's AGENTS.md
+```
+
+It merges into a delimited block and leaves everything outside it alone. The
+block carries the time it was written, because this path is only ever as fresh
+as its last run.
+
 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
@@ -150,7 +221,7 @@ Verify by starting a session and checking that the first prompt carries a
 
 ---
 
-## 5. OpenWiki
+## 6. OpenWiki
 
 ```bash
 npm install -g openwiki@latest        # CLI, needs Node >= 22
@@ -175,7 +246,7 @@ Wikis themselves are per-repository (`.openwiki/` in each project) — that is
 
 ---
 
-## 6. Synapse
+## 7. Synapse
 
 The installer downloads the module, symlinks the binary to
 `~/.local/bin/synapse` and registers a daemon on port `7781`. Two failure modes
@@ -191,7 +262,35 @@ If no pre-built binary exists for the platform, build it:
 
 ---
 
-## 7. Confirm
+## 8. The dashboard
+
+`aos-dashboard` serves one page on `http://127.0.0.1:7900` showing every BDB
+service live — memB, Synapse, the OpenWiki daemon, AO Orchestrator and RemoteOS
+— with its version, port, LaunchAgent state, start/stop/restart, and its log
+files inline. It polls every five seconds.
+
+```bash
+aos-dashboard                 # opens the browser
+aos-dashboard --no-open       # just serve
+aos-dashboard --port 7901     # if 7900 is taken
+```
+
+It binds to `127.0.0.1` only, and every control action is matched against a
+fixed service table — an id or action the table does not contain is refused,
+and no value from the request ever reaches a shell or a file path.
+
+It also surfaces causes a port probe cannot see. The AO Orchestrator card
+checks the code signature of `~/.local/bin/ao`: a binary rebuilt and copied
+into place unsigned is SIGKILLed by AMFI at launch (exit 137), which otherwise
+looks like a daemon that is simply down, with nothing in the log. The fix it
+names is `codesign -s - -f ~/.local/bin/ao`.
+
+Use it when the user asks what is running, or when a doctor row says a port is
+closed and the question is why.
+
+---
+
+## 9. Confirm
 
 Re-run the doctor. Do not report success from the fact that commands ran —
 report the doctor's own count: