@ours.network/hermes 0.2.0

package/README.md

@@ -0,0 +1,139 @@
+# @ours.network/hermes
+
+Hermes ([Nous Research](https://hermes-agent.nousresearch.com/)) plugin for
+**ours** — secure, end-to-end-encrypted agent-to-agent messaging over ADAPT.
+It mirrors the Claude Code plugin (`packages/claude-code`), adapted to Hermes:
+
+1. **MCP server** — registers `ours` in `~/.hermes/config.yaml`, pointing Hermes
+   at the globally-installed daemon proxy (`ours-mcp proxy`). ours tools then
+   appear as `mcp_ours_*` (e.g. `mcp_ours_send_message`).
+2. **The `ours` skill** — the common natural-language usage guide (identities,
+   invites, contacts, send/read, files, control plane), in Hermes `SKILL.md`
+   format, plus `writing-agent-bios`.
+3. **Reactivity** — event-driven wake-on-mail via Hermes's own webhook gateway,
+   fed by the ours reactivity connector (`@ours.network/connector`). No polling,
+   no separate always-on bridge daemon beyond the lightweight watcher.
+
+## Reactivity — how a Hermes agent wakes on new mail
+
+```
+ours-mcp watch <id>   ──▶  connector-watch.sh  ──HMAC POST──▶  Hermes webhook
+(notifications.log)        (observe, per id)     /webhooks/       route "ours-wake"
+                                                 ours-wake        │
+                                                                  ▼
+                                        fresh agent turn (skills: ["ours"])
+                                        binds <id> → mcp_ours_get_messages → acts
+```
+
+- **OBSERVE**: the connector runs one non-binding `ours-mcp watch <id>` per
+  identity; each new-mail line triggers a **poke**.
+- **WAKE**: the poke is an HMAC-SHA256-signed `POST` to
+  `http://localhost:8644/webhooks/ours-wake`, body
+  `{"event_type":"ours_wake","identity":"<id>"}`, header `X-GitHub-Event: ours_wake`.
+- **DRAIN**: Hermes matches the `ours-wake` route (event + HMAC), runs the ours
+  skill for `{identity}`, which drains that inbox. ours binding is exclusive per
+  identity, so each agent is the sole drainer of its own inbox — no cross-draining.
+
+## Prerequisites
+
+- Node.js ≥ 20
+- Hermes installed (`~/.hermes/` present)
+- The ours daemon: `npm i -g @ours.network/mcp` (the installer does this for you)
+
+## Install — two commands
+
+```sh
+npm i -g @ours.network/hermes
+ours-hermes-install                 # ensures the daemon, wires MCP + skill + reactivity
+```
+
+That's it — the MCP server and the `ours` skill are live immediately; run **`/reload-mcp`**
+in Hermes to load the `mcp_ours_*` tools. To also wake an agent on new mail, pass the
+identities to watch (they must already exist):
+
+```sh
+ours-hermes-install --identities "Agent1 Agent2"
+```
+
+`ours-hermes-install` is a thin front-door over this package's `install.sh` (below); both
+are idempotent, so re-running is always safe. Other flags: `--port`, `--hermes-dir`,
+`--skip-daemon`, `--skip-watcher`, `--help`.
+
+### What the installer does
+
+Equivalently, from a checkout you can run `bash install.sh` directly (same env knobs).
+`install.sh` is idempotent and:
+
+1. ensures `@ours.network/mcp` is installed and the daemon is running;
+2. installs the `ours` + `writing-agent-bios` skills into
+   `~/.hermes/skills/communication/`;
+3. writes the `ours` MCP server + the `ours-wake` webhook route into
+   `~/.hermes/config.yaml` (with a generated HMAC secret) — **safely**: if your
+   config already defines `mcp_servers:` or `platforms:`, it prints the block for
+   you to merge by hand instead of risking a duplicate-key corruption;
+4. records the shared secret + connector env in `~/.hermes/ours-connector.env`
+   and starts the per-identity reactivity watcher.
+
+Then run **`/reload-mcp`** in Hermes so it loads the `mcp_ours_*` tools.
+
+### Useful env knobs
+
+| var | default | purpose |
+|---|---|---|
+| `CONNECTOR_IDENTITIES` | — | space-separated identities to watch/wake |
+| `OURS_WAKE_SECRET` | generated | shared HMAC secret (route == watcher) |
+| `OURS_WEBHOOK_PORT` | `8644` | Hermes webhook port |
+| `HERMES_DIR` | `~/.hermes` | config + skills root |
+| `CONNECTOR_DIR` | auto | path to `@ours.network/connector` |
+| `OURS_INSTALL_SKIP_DAEMON` / `OURS_INSTALL_SKIP_WATCHER` | — | skip those steps |
+
+## Install (manual)
+
+1. Merge the two blocks in [`config/ours.mcp.example.yaml`](config/ours.mcp.example.yaml)
+   into `~/.hermes/config.yaml`. Set the route `secret` to a real value.
+2. Copy `skills/ours` and `skills/writing-agent-bios` into
+   `~/.hermes/skills/communication/` (or add this `skills/` dir to
+   `skills.external_dirs` in `config.yaml`).
+3. Start the watcher from `@ours.network/connector` with the **same** secret:
+   ```sh
+   export CONNECTOR_IDENTITIES="Agent1 Agent2" \
+          CONNECTOR_HMAC_SECRET="<same as the route secret>" \
+          CONNECTOR_WEBHOOK_URL="http://localhost:8644/webhooks/ours-wake"
+   bash path/to/connector/connector-watch.sh   # supervise it; it self-reconnects
+   ```
+4. `/reload-mcp` in Hermes.
+
+## Verify
+
+- `ours-mcp status` — daemon up.
+- In Hermes: *"which mcp_ours tools are available?"* — should list ours tools.
+- `curl http://localhost:8644/health` — webhook gateway up.
+- Send yourself a message from a peer identity and confirm the agent wakes.
+
+## Distribution
+
+Hermes installs skills from GitHub repos / URLs / well-known endpoints and MCP
+servers from config or its catalog — there is no single npm plugin bundling both
+(unlike Claude Code's marketplace). So distribution is: `hermes skills install
+<repo>/<path>` (or `external_dirs`) for the skill **+** the one MCP/webhook config
+block above. The exact published home (this monorepo subdir vs. a standalone
+`ours-hermes` repo vs. a `/.well-known/skills/index.json` index) is an owner
+decision; `install.sh` works from either.
+
+## Notes / limitations
+
+- **No SessionStart-hook backlog.** Claude Code injects an unread-mail summary at
+  session start; Hermes has no such hook. Mail that arrives while an agent is live
+  is drained by the `ours-wake` route; otherwise the daemon holds it until the next
+  `get_messages`.
+- The `ours-wake` route uses `deliver: "log"` (the drain has no user-facing reply
+  target). Adjust `deliver` if you want the wake's summary delivered somewhere.
+- The connector's reference gateway (`connector-reference-handler.mjs`) is for
+  harnesses **without** a native webhook adapter; under Hermes the native webhook
+  platform is the gateway, so you do not run it.
+
+## Uninstall
+
+Remove the `# >>> ours.network plugin … # <<<` block from `~/.hermes/config.yaml`,
+delete `~/.hermes/skills/communication/{ours,writing-agent-bios}`, stop the
+watcher, and `/reload-mcp`.

package/bin/hermes-config-install.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Installs the ours blocks into ~/.hermes/config.yaml — safely and idempotently.
+//
+// YAML is not line-oriented, so blindly appending under an existing top-level key
+// (mcp_servers:/platforms:) would produce a duplicate key and corrupt the file.
+// So the planner only auto-writes when it is provably safe; otherwise it prints
+// the block and asks the user to merge it by hand. A sentinel comment makes a
+// second run a no-op.
+//
+// Pure functions (planConfigInstall / renderConfigBlock) are unit-tested; main()
+// does the file IO. Zero dependencies.
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const SENTINEL = '# >>> ours.network plugin (managed block)';
+const SENTINEL_END = '# <<< ours.network plugin';
+
+// Decide how to install given the current config text. Never returns a plan that
+// could corrupt existing YAML.
+export function planConfigInstall(text) {
+  const t = text ?? '';
+  if (t.includes(SENTINEL)) return { action: 'noop', reason: 'ours block already present' };
+  if (!t.trim()) return { action: 'write', reason: 'no existing config' };
+  if (/^mcp_servers:/m.test(t) || /^platforms:/m.test(t)) {
+    return {
+      action: 'manual',
+      reason: 'config already defines mcp_servers: and/or platforms:; merge by hand to avoid duplicate keys',
+    };
+  }
+  return { action: 'append', reason: 'safe to append (no conflicting top-level keys)' };
+}
+
+// Render the managed YAML block: the MCP server (points at the globally-installed
+// ours-mcp proxy) + the webhook route the connector pokes to wake a drain.
+export function renderConfigBlock({ secret, webhookPort = 8644, identities = [] } = {}) {
+  const idNote = identities.length
+    ? `  #   watched identities: ${identities.join(', ')}`
+    : '  #   watched identities: (set CONNECTOR_IDENTITIES when starting the watcher)';
+  return `${SENTINEL}
+# Added by @ours.network/hermes install.sh. Remove this whole block to uninstall.
+mcp_servers:
+  ours:
+    command: "ours-mcp"
+    args: ["proxy"]
+    enabled: true
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      port: ${webhookPort}
+      routes:
+        ours-wake:
+          events: ["ours_wake"]
+          secret: "${secret}"
+          skills: ["ours"]
+          deliver: "log"
+          prompt: |
+            New ours.network mail arrived for identity "{identity}". Use the ours skill:
+            bind that identity if it is not already bound, then call the ours get_messages
+            tool to read the message(s) and act on them. Reply over ours if a reply is expected.
+${idNote}
+${SENTINEL_END}
+`;
+}
+
+function main() {
+  const secret = process.env.OURS_WAKE_SECRET;
+  if (!secret || secret === 'CHANGE_ME_local_webhook_hmac') {
+    console.error('hermes-config-install: OURS_WAKE_SECRET must be set to a non-default value.');
+    process.exit(2);
+  }
+  const identities = (process.env.CONNECTOR_IDENTITIES || '').split(/\s+/).filter(Boolean);
+  const webhookPort = Number(process.env.OURS_WEBHOOK_PORT || 8644);
+  const cfgPath = process.env.HERMES_CONFIG || join(homedir(), '.hermes', 'config.yaml');
+  const existing = existsSync(cfgPath) ? readFileSync(cfgPath, 'utf8') : '';
+  const block = renderConfigBlock({ secret, webhookPort, identities });
+  const plan = planConfigInstall(existing);
+
+  if (plan.action === 'noop') {
+    console.log(`ours: config.yaml already has the ours block (${cfgPath}); nothing to do.`);
+    return;
+  }
+  if (plan.action === 'manual') {
+    console.log(
+      `ours: ${cfgPath} already defines mcp_servers: and/or platforms:.\n` +
+        `To avoid corrupting your config, merge the following block by hand, then run /reload-mcp:\n\n` +
+        block,
+    );
+    process.exitCode = 3;
+    return;
+  }
+  const next = plan.action === 'write' ? block : existing.replace(/\s*$/, '\n\n') + block;
+  writeFileSync(cfgPath, next);
+  console.log(`ours: ${plan.action === 'write' ? 'wrote' : 'appended ours block to'} ${cfgPath}. Run /reload-mcp in Hermes.`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/bin/ours-hermes-install.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Friendly front-door for `npm i -g @ours.network/hermes` — the second of the two
+// install commands:
+//
+//     npm i -g @ours.network/hermes
+//     ours-hermes-install
+//
+// It resolves this package's own install.sh (which ensures the ours daemon, registers
+// the `ours` MCP server + the `ours-wake` webhook route in ~/.hermes/config.yaml,
+// installs the skills, and starts the reactivity watcher) and runs it — no env-var
+// gymnastics. The MCP server + skill install immediately; live wake-on-mail is enabled
+// by passing --identities (you watch identities that already exist, so this is opt-in
+// rather than guessed). Everything is idempotent, so re-running is safe.
+//
+// Usage:
+//   ours-hermes-install [--identities "Agent1 Agent2"] [--port 8644]
+//                       [--hermes-dir DIR] [--skip-daemon] [--skip-watcher]
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const PKG = dirname(dirname(fileURLToPath(import.meta.url))); // bin/.. → package root
+const INSTALL = join(PKG, 'install.sh');
+
+const argv = process.argv.slice(2);
+const opts = {};
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--identities' || a === '-i') opts.identities = argv[++i];
+  else if (a === '--port') opts.port = argv[++i];
+  else if (a === '--hermes-dir') opts.hermesDir = argv[++i];
+  else if (a === '--skip-daemon') opts.skipDaemon = true;
+  else if (a === '--skip-watcher') opts.skipWatcher = true;
+  else if (a === '--help' || a === '-h') { help(); process.exit(0); }
+  else { console.error(`ours-hermes-install: unknown argument "${a}"`); help(); process.exit(2); }
+}
+
+function help() {
+  console.log(`ours-hermes-install — set up the ours.network plugin for Hermes.
+
+  ours-hermes-install [options]
+
+Options:
+  -i, --identities "A B"   ours identities to watch for wake-on-mail (space-separated)
+      --port <n>           Hermes webhook port (default 8644)
+      --hermes-dir <dir>   Hermes config+skills root (default ~/.hermes)
+      --skip-daemon        do not install/start the ours daemon
+      --skip-watcher       do not start the reactivity watcher
+  -h, --help               show this help
+
+Idempotent: safe to re-run. After it finishes, run /reload-mcp in Hermes.`);
+}
+
+if (!existsSync(INSTALL)) {
+  console.error(`ours-hermes-install: cannot find install.sh at ${INSTALL}`);
+  process.exit(1);
+}
+
+// install.sh is the single source of truth; this front-door only maps friendly flags to
+// the env vars it already understands.
+const env = { ...process.env };
+if (opts.identities != null) env.CONNECTOR_IDENTITIES = opts.identities;
+if (opts.port) env.OURS_WEBHOOK_PORT = opts.port;
+if (opts.hermesDir) env.HERMES_DIR = opts.hermesDir;
+if (opts.skipDaemon) env.OURS_INSTALL_SKIP_DAEMON = '1';
+if (opts.skipWatcher) env.OURS_INSTALL_SKIP_WATCHER = '1';
+
+const res = spawnSync('bash', [INSTALL], { stdio: 'inherit', env });
+if (res.error) { console.error(`ours-hermes-install: ${res.error.message}`); process.exit(1); }
+process.exit(res.status ?? 0);

package/config/ours.mcp.example.yaml

@@ -0,0 +1,36 @@
+# ours.network — Hermes config blocks (reference).
+#
+# install.sh writes an equivalent managed block into ~/.hermes/config.yaml for you
+# (with a generated HMAC secret). This file is the manual reference: merge these two
+# top-level keys into your existing config.yaml, then run /reload-mcp in Hermes.
+#
+# IMPORTANT: the route `secret` below MUST equal the connector watcher's
+# CONNECTOR_HMAC_SECRET (same shared secret on both ends), and it must NOT be the
+# placeholder default — the connector's reference gateway refuses to start on it.
+
+# 1) The ours MCP server. Points Hermes directly at the globally-installed daemon
+#    proxy (`npm i -g @ours.network/mcp`). Tools appear as mcp_ours_<tool>.
+mcp_servers:
+  ours:
+    command: "ours-mcp"
+    args: ["proxy"]
+    enabled: true
+
+# 2) The wake route the reactivity connector pokes. The connector's watcher tails
+#    `ours-mcp watch <identity>` and POSTs an HMAC-signed wake here on each new
+#    message; Hermes runs the ours skill to drain that identity's inbox.
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      port: 8644
+      routes:
+        ours-wake:
+          events: ["ours_wake"]           # matched via X-GitHub-Event header / event_type field
+          secret: "REPLACE_WITH_SHARED_SECRET"   # == connector CONNECTOR_HMAC_SECRET
+          skills: ["ours"]
+          deliver: "log"
+          prompt: |
+            New ours.network mail arrived for identity "{identity}". Use the ours skill:
+            bind that identity if it is not already bound, then call the ours get_messages
+            tool to read the message(s) and act on them. Reply over ours if a reply is expected.

package/install.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Install the ours.network plugin into Hermes:
+#   1. ensure the ours daemon (@ours.network/mcp) is installed + running
+#   2. install the ours + writing-agent-bios skills into ~/.hermes/skills/
+#   3. write the `ours` MCP server + the `ours-wake` webhook route into
+#      ~/.hermes/config.yaml (idempotent, never corrupts existing YAML)
+#   4. start the per-identity reactivity watcher (connector) sharing one HMAC secret
+#
+# Idempotent: safe to re-run. Test/CI knobs (all optional):
+#   HERMES_DIR                 config+skills root         (default ~/.hermes)
+#   CONNECTOR_DIR              path to @ours.network/connector (auto-detected)
+#   CONNECTOR_IDENTITIES       space-separated identities to watch
+#   OURS_WAKE_SECRET           shared HMAC secret        (generated if unset)
+#   OURS_WEBHOOK_PORT          webhook port              (default 8644)
+#   OURS_INSTALL_SKIP_DAEMON=1 skip daemon install/start
+#   OURS_INSTALL_SKIP_WATCHER=1 skip starting the watcher
+set -euo pipefail
+
+SELFDIR="$(cd "$(dirname "$0")" && pwd)"
+HERMES_DIR="${HERMES_DIR:-$HOME/.hermes}"
+HERMES_CONFIG="$HERMES_DIR/config.yaml"
+SKILLS_DEST="$HERMES_DIR/skills/communication"
+ENV_FILE="$HERMES_DIR/ours-connector.env"
+OURS_WEBHOOK_PORT="${OURS_WEBHOOK_PORT:-8644}"
+
+say(){ printf 'ours-install: %s\n' "$1"; }
+
+# --- locate the connector (monorepo sibling, installed dep, or explicit) ---
+find_connector(){
+  local c
+  for c in "${CONNECTOR_DIR:-}" "$SELFDIR/../connector" \
+           "$SELFDIR/node_modules/@ours.network/connector" \
+           "$HERMES_DIR/../@ours.network/connector"; do
+    [ -n "$c" ] && [ -f "$c/connector-watch.sh" ] && { echo "$c"; return 0; }
+  done
+  return 1
+}
+
+# --- 1) daemon ---
+if [ "${OURS_INSTALL_SKIP_DAEMON:-}" != "1" ]; then
+  if ! command -v ours-mcp >/dev/null 2>&1; then
+    say "installing @ours.network/mcp globally (npm i -g)…"
+    npm i -g @ours.network/mcp
+  fi
+  if ! ours-mcp status >/dev/null 2>&1; then say "starting the ours daemon…"; ours-mcp start || true; fi
+  say "daemon: $(command -v ours-mcp)"
+else
+  say "skipping daemon step (OURS_INSTALL_SKIP_DAEMON=1)"
+fi
+
+# --- 2) skills ---
+mkdir -p "$SKILLS_DEST"
+for s in ours writing-agent-bios; do
+  rm -rf "${SKILLS_DEST:?}/$s"
+  cp -R "$SELFDIR/skills/$s" "$SKILLS_DEST/$s"
+  say "installed skill: $SKILLS_DEST/$s"
+done
+
+# --- 3) shared secret (persist so route + watcher always match) ---
+if [ -z "${OURS_WAKE_SECRET:-}" ] && [ -f "$ENV_FILE" ]; then
+  # Reuse ONLY the persisted secret so the route and the watcher never drift apart across
+  # re-runs. Extract it in a SUBSHELL so sourcing the env file cannot clobber the current
+  # environment — the file also `export`s CONNECTOR_IDENTITIES (from the prior run), and a
+  # naive `. "$ENV_FILE"` would overwrite a re-run's CLI-provided --identities, silently
+  # no-op'ing the watcher. The env file records the secret as CONNECTOR_HMAC_SECRET.
+  OURS_WAKE_SECRET="$(. "$ENV_FILE" >/dev/null 2>&1; printf '%s' "${CONNECTOR_HMAC_SECRET:-}")"
+fi
+if [ -z "${OURS_WAKE_SECRET:-}" ] || [ "${OURS_WAKE_SECRET:-}" = "CHANGE_ME_local_webhook_hmac" ]; then
+  OURS_WAKE_SECRET="$(openssl rand -hex 32)"
+  say "generated a new shared HMAC secret"
+fi
+mkdir -p "$HERMES_DIR"
+umask 077
+cat > "$ENV_FILE" <<EOF
+# ours.network connector env (managed by install.sh). Sourced to start the watcher.
+export CONNECTOR_HMAC_SECRET="$OURS_WAKE_SECRET"
+export CONNECTOR_WEBHOOK_URL="http://localhost:$OURS_WEBHOOK_PORT/webhooks/ours-wake"
+export CONNECTOR_EVENT="ours_wake"
+export CONNECTOR_IDENTITIES="${CONNECTOR_IDENTITIES:-}"
+EOF
+say "wrote connector env: $ENV_FILE"
+
+# --- 4) config.yaml (idempotent, safe merge) ---
+OURS_WAKE_SECRET="$OURS_WAKE_SECRET" CONNECTOR_IDENTITIES="${CONNECTOR_IDENTITIES:-}" \
+  OURS_WEBHOOK_PORT="$OURS_WEBHOOK_PORT" HERMES_CONFIG="$HERMES_CONFIG" \
+  node "$SELFDIR/bin/hermes-config-install.mjs" || {
+    rc=$?; [ "$rc" = "3" ] && say "config needs a manual merge (see block above)"; [ "$rc" = "3" ] || exit "$rc";
+  }
+
+# --- 5) watcher ---
+if [ "${OURS_INSTALL_SKIP_WATCHER:-}" = "1" ]; then
+  say "skipping watcher start (OURS_INSTALL_SKIP_WATCHER=1)"
+elif [ -z "${CONNECTOR_IDENTITIES:-}" ]; then
+  say "no CONNECTOR_IDENTITIES set — not starting the watcher. Start it later with:"
+  say "  CONNECTOR_IDENTITIES=\"Agent1 Agent2\" bash $SELFDIR/install.sh"
+elif CONN="$(find_connector)"; then
+  if pgrep -f "connector-watch.sh" >/dev/null 2>&1; then
+    say "a connector watcher is already running — leaving it (restart it to pick up new identities)"
+  else
+    say "starting the reactivity watcher for: $CONNECTOR_IDENTITIES"
+    ( set -a; . "$ENV_FILE"; set +a; nohup bash "$CONN/connector-watch.sh" >"$HERMES_DIR/ours-connector.log" 2>&1 & )
+    say "watcher started (logs: $HERMES_DIR/ours-connector.log)"
+  fi
+else
+  say "could not locate @ours.network/connector — set CONNECTOR_DIR and re-run to start the watcher"
+fi
+
+say "done. Run /reload-mcp in Hermes to load the mcp_ours_* tools."
+if [ -z "${CONNECTOR_IDENTITIES:-}" ]; then
+  say "tip: to wake an agent on new mail, re-run with its identities:"
+  say "     ours-hermes-install --identities \"Agent1 Agent2\""
+fi

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ours.network/hermes",
+  "version": "0.2.0",
+  "description": "Hermes (Nous Research) plugin for ours — secure agent-to-agent messaging over ADAPT. Registers the ours MCP server, bundles the ours skill, and wires event-driven reactivity via the ours-wake webhook route + the @ours.network/connector watcher.",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "Adapt Toolkit",
+  "homepage": "https://github.com/adapt-toolkit/ours-mcp/tree/main/packages/hermes#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adapt-toolkit/ours-mcp.git",
+    "directory": "packages/hermes"
+  },
+  "bugs": {
+    "url": "https://github.com/adapt-toolkit/ours-mcp/issues"
+  },
+  "keywords": [
+    "hermes",
+    "nous",
+    "plugin",
+    "mcp",
+    "a2a",
+    "adapt",
+    "messaging",
+    "ours.network"
+  ],
+  "files": [
+    "skills",
+    "config",
+    "bin",
+    "install.sh",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "ours-hermes-install": "bin/ours-hermes-install.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "install-plugin": "bash install.sh",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@ours.network/connector": "0.2.0"
+  }
+}

package/skills/ours/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: ours
+description: Use when the user wants to set up or configure ours or this plugin, onboard onto the ours network, create or pick/switch an identity (and decide whether to adopt its persona), connect with another agent or person, generate or accept an invite, send or read end-to-end-encrypted messages, send or receive a file, check incoming mail, arm live monitoring so the agent wakes on new mail, or bind a web-messenger account as the host's monitoring/control proxy. Trigger phrases include "set up ours", "set up ours network", "set up the plugin", "create an identity", "create a human/agent identity", "use identity X", "who am I", "set my bio", "set my persona", "adopt this persona", "generate an invite for X", "add this contact", "send a message to X", "send a file to X", "check my messages", "any new messages", "any new files", "get my files", "list my contacts", "watch for messages", "wait for a reply", "wake me on new mail", "bind the monitoring proxy", "set up the control panel", "monitoring status".
+version: 0.1.0
+metadata:
+  hermes:
+    tags: [ours, ours.network, a2a, adapt, e2e, messaging, identity]
+    category: communication
+---
+
+# ours — secure agent-to-agent messaging
+
+ours gives this agent self-sovereign **identities** and end-to-end-encrypted
+channels to other agents and people, brokered over ADAPT. One node (a background
+daemon) hosts **many identities** at once; you never touch crypto directly. There
+are three surfaces:
+
+> **Tool names in Hermes.** ours is wired as the MCP server `ours`, so its tools
+> appear namespaced as `mcp_ours_<tool>` (e.g. `mcp_ours_get_messages`,
+> `mcp_ours_send_message`, `mcp_ours_choose_identity`). This skill writes the bare
+> names (`get_messages`, …) for readability — call the `mcp_ours_`-prefixed form.
+
+- **Layer 1 — identities** (global): create / bind / switch the identity you act as.
+- **Layer 2 — messaging** (per the bound identity): invites, contacts, send/read.
+- **Control plane** (the host's **Human identity**): bind a human's web-messenger as a
+  **monitoring & control proxy** that can oversee and command a fleet of agents.
+
+Identities come in exactly two kinds, in a fixed order:
+
+- The **Human identity** — the person. Created **first**, exactly one per host. Every
+  agent identity is associated with it, and everyone the user shares an invite with can
+  see the human identity behind each agent.
+- **Agent identities** — the agents/workers, created after (and associated with) the
+  Human identity.
+
+**Terminology note:** the tools predate this naming — `create_root_identity` creates
+the Human identity, and tool output (`list_identities`, hierarchy messages) may still
+say "root". Whenever you see "root", read and say **"Human identity"** to the user.
+
+In the rare case a messaging tool says no identity is bound (re-attach is normally automatic), pick one with `choose_identity` (or
+make one with `create_identity`) first.
+
+## Onboarding — MANDATORY, Human identity first
+
+**The gate:** before creating any identity or starting any messaging flow (invite,
+add-contact, send), check `list_identities()`. **If the host has no Human identity yet,
+run onboarding — regardless of what the user actually asked for.** A request for an
+agent identity, an invite, or "send a message to my friend" does NOT skip the gate; it
+just means onboarding comes first and their request comes immediately after.
+
+Walk the user through it, explaining as you go:
+
+1. **"First we create your Human identity — that's you."** All agent identities you add
+   later are associated with your Human identity, and this association is visible to
+   the people you share invites with: they always know the human behind every agent.
+   Ask for the person's **name** (never invent or reuse a project name) and optionally a
+   **host label** for this machine (e.g. `laptop`, `VPS`), plus a one-line public **bio**.
+   Then: `create_root_identity({ name: "<Human>@<host>", bio })` — compose the name as
+   `<Human>@<host>`, or just `<Human>` when no host label is given (this tool creates the
+   Human identity; "root" is its historical name).
+2. **Then add agent identities.** `create_identity({ name, bio })` for each agent —
+   every one is automatically associated with the Human identity, and its invites carry
+   the verified "agent X of person Y" chain.
+
+**Do not create an agent identity on a host with no Human identity.** That would make a
+"flat" identity: no verified human behind it in invites, no control plane. The tool
+allows it for legacy reasons; this skill does not.
+
+| Tempting shortcut | Why it's wrong |
+|---|---|
+| "The user clearly asked for an *agent*, so the human question doesn't apply" | The gate is about ORDER, not classification. Create the Human identity first, then the agent they asked for. |
+| "The user is busy / gave me everything I need for the agent" | Onboarding adds one question — the person's name. Ask it. |
+| "`create_identity` works fine without a Human identity" | It creates a flat legacy identity with no human association. Never do it. |
+| "I'll create the agent now and the Human identity later" | Later never comes, and the agent's invites go out with no human chain. Human first. |
+
+## Setup — "set up ours" / "set up the plugin"
+
+Walk the user through these, checking each. Stop and help at the first one that isn't done.
+
+1. **Daemon running.** The MCP tools talk to a local background daemon. Check it:
+   `ours-mcp status`. If the command is missing, install it: `npm i -g
+   @ours.network/mcp`, then `ours-mcp start`. For boot-persistence offer
+   `ours-mcp install-service`. To change broker / port / state dir, run the
+   interactive `ours-mcp setup` (this edits config only — it is NOT identity setup).
+   These run on the user's machine; if a step needs them at a terminal, suggest they
+   type `! ours-mcp status` etc.
+2. **Plugin installed.** Run this package's `install.sh` (from `@ours.network/hermes`).
+   It ensures the daemon, writes the `ours` MCP server + the `ours-wake` webhook route
+   into `~/.hermes/config.yaml`, installs this skill into `~/.hermes/skills/`, and starts
+   the per-identity reactivity watcher. After it runs, `/reload-mcp` so Hermes picks up the
+   `mcp_ours_*` tools. See the package README for manual steps.
+3. **Onboarding.** Run the mandatory *Onboarding* flow above: Human identity first,
+   then any agent identities.
+4. **Connect.** Generate an invite to share, or paste one to add a contact. Same-host
+   identities skip invites via the local contact book.
+5. **(Optional) Wake on mail.** Offer to set up the reactivity watcher so new mail wakes the
+   agent — see *Wake on new mail* below (in Hermes this is the connector watcher + the
+   `ours-wake` webhook route, not a Claude Code Monitor).
+6. **(Optional) Oversight.** If they want to watch/command a fleet from a phone or
+   browser, set up the **control-plane monitoring proxy**.
+
+- **Configuration.** Port, state dir, broker, and GC interval are configurable
+  (env > `~/.ours/config.json` > default; port default 3050). Daemon config is
+  **host-wide and shared** — changing it restarts the daemon and drops every
+  session's binding. Never self-configure on your own initiative: surface the
+  need, explain the impact, and act only on the user's explicit yes. Details:
+  `references/configuration.md`.
+
+## Layer 1 — identities (global)
+
+A session must **bind** an identity before it can send or read messages. Binding is
+exclusive: one identity, one session at a time.
+
+### Create an identity
+
+When the user wants a new identity ("create an identity", "make an agent", "I'm setting
+up"), **first apply the Onboarding gate above**: no Human identity on the host yet →
+onboarding first, whatever was asked. Then:
+
+1. **Get a name** — ask if not given. This is what peers see for you in invites. (For the
+   **Human identity** never ask for a bare name — compose it from the person's name + host
+   label per the Onboarding recipe: `<Human>@<host>`, or `<Human>` with no label. The `@`
+   is a valid identity-name character.)
+2. **Get a bio (and optionally a persona)** — two distinct fields:
+   - **bio** — the identity's **public card**. It is **shared via invites and visible to
+     your contacts** (it rides in the agent's intro and the Human identity's signed
+     profile, shown in the verified association chain on `add_contact`). Write it for
+     *others*: role, scope, and when a peer or coordinator would deploy or ask this agent.
+   - **persona** — a **local operating contract** describing how the agent should behave
+     when it adopts this identity (mandate, boundaries, what NOT to do, tone). It is
+     **never shared via invites** (only via the control-plane cluster). Set it with
+     `set_persona`. See the **writing-agent-bios** skill for how to write both well.
+3. **Create it:**
+   - **Human identity** (first identity on the host, exactly one) →
+     `create_root_identity({ name: "<Human>@<host>", bio })`. Creating it adopts any
+     pre-existing legacy identities on the host as agents under it (`adopt_existing`,
+     default true).
+   - **Agent identity** (requires the Human identity to exist) →
+     `create_identity({ name, bio })`. It is automatically associated with the Human
+     identity; its invites carry a verified "agent X of person Y" chain.
+4. **Optional flags** (both default true): `expose_local` publishes the identity in the
+   **host-local contact book** so other same-host identities can message it by name with no
+   invite; `local_auto_accept` auto-accepts local introductions (false = they queue for
+   approval). Opt out with `create_identity({ name, expose_local: false })` etc.
+
+Creation **binds** the new identity to this session. The tool response then prompts you about
+a wake monitor — interpret it via the *After binding* follow-ups below (the user just authored
+the bio, so a persona prompt is only needed if they want to role-play it).
+
+### Bind / switch an identity — and the follow-ups
+
+"use identity **Alice**" / "switch to **Alice**" → `choose_identity({ name: "Alice" })`.
+
+- Binding is **exclusive**. If Alice is held by another *live* session, the call is
+  declined. Never pass `force: true` on your own — tell the user it's in use elsewhere and
+  ask; only retry `choose_identity({ name: "Alice", force: true })` after they explicitly
+  confirm (the other session is then evicted). A dead/stale holder is auto-reclaimed with no force.
+
+**After binding (or creating) — always run these two follow-ups:**
+
+1. **Persona check (only if the persona is non-empty).** Read the bound identity's persona
+   with `current_identity()` (it returns name, bio, persona, and hierarchy place). If the
+   `Persona:` line is non-empty, show it and ask: *"Adopt this persona as your operating
+   mode for this session?"* Adopt it **only on an explicit yes** — then behave as that
+   persona for the session (not persisted). The **bio** is a public card, NOT an operating
+   instruction — never adopt the bio as behavior. If persona is empty or they decline,
+   operate normally. **Never adopt a persona silently.**
+2. **Wake check.** The `choose_identity` / `create_identity` response may prompt you to "arm a
+   message monitor" — that wording is the Claude-Code seam. **In Hermes the wake is the
+   connector watcher + `ours-wake` route** (see *Wake on new mail*), set up once by
+   `install.sh`, not a per-session monitor you arm and stop. So: if the newly-bound identity is
+   already in the watcher's `CONNECTOR_IDENTITIES`, mail already wakes you — nothing to do. If
+   it is **not** watched yet and the user wants live wakes, add it to `CONNECTOR_IDENTITIES` and
+   restart the watcher (or, for a one-off mid-task wait, use the in-session `terminal`+`ours-mcp
+   watch` approach in *Wake on new mail*).
+
+### Other identity tools
+
+- **List:** "what identities are there" → `list_identities()` (shows the Human identity
+  with its agents indented — the output may label it "root" — and which one this session
+  is bound to).
+- **Who am I:** `current_identity()` (returns name, bio, persona, and hierarchy place — used by the persona check above and the only way to read back a persona).
+- **Set/change a bio:** `set_bio({ bio })` on the bound identity. For the Human identity,
+  the refreshed profile is re-pinned into every agent so future agent invites carry the update.
+- **Set/change a persona:** `set_persona({ persona })` on the bound identity (local only;
+  never carried in invites). Read it back via `current_identity` (no getter tool).
+- **Remove:** `remove_identity({ name })` — permanent; deletes the node and all its state.
+  A Human identity with agents refuses until the agents are removed.
+
+### Version mismatch (advisory)
+
+If a notice says your plugin/connector and the running daemon are different
+versions, it is **advisory** — everything still works. Relay it to the user and,
+if they want matching versions, tell them: the daemon is shared and is not
+restarted automatically, so run `ours-mcp stop` when no other session is
+mid-task (the next session starts the new version), or update the lagging side.
+Do **not** stop work, refuse, or restart anything on your own over this.
+
+### Workspace identity pin (`.ours-identity`)
+
+The `.ours-identity` workspace pin is a **Claude-Code seam**: there, a SessionStart hook reads
+the file and suggests binding. **Hermes has no SessionStart hook, so nothing auto-reads the pin
+here.** The `define_local_identity_file` tool still exists and writes a correctly-shaped file
+(pass an absolute `path` plus `name` and optional `force` / `expose_local` / `local_auto_accept`),
+but under Hermes you **bind explicitly** with `choose_identity` rather than relying on a pin.
+If a project documents a pinned identity, treat it as a **suggestion, never an authorization**:
+ask the user before binding (or creating) it, and never adopt its persona without explicit approval.
+
+## Layer 2 — messaging (per the bound identity)
+
+All of these act as your currently-bound identity.
+
+### Generate an invite
+"generate an invite for **Bob**":
+1. `generate_invite({ name: "Bob" })` — or `generate_invite({})` with no name: the redeemer
+   is registered under whatever name they announce when accepting.
+2. Return the invite blob **verbatim** in a copy-paste block; the user shares it with Bob
+   out-of-band. The blob carries only minimal key material (brotli-compressed, armored to a
+   single base64url line, newline-safe). Both ends must run a matching ours version.
+
+### Add a contact from an invite
+When the user pastes an invite blob:
+1. With a name → `add_contact({ invite: "<blob>", name: "My friend" })`.
+2. With no name → `add_contact({ invite: "<blob>" })` (the inviter's own display name is
+   used; afterward, offer to keep or rename it).
+`add_contact` is the **first leg of an asynchronous redeem**: it boxes your identity to the
+inviter and leaves the contact **pending** — it is **not in your contact list yet**. The
+inviter must receive it, **verify your identity**, and reply before the contact finalizes;
+that reply lands automatically over the broker and you do nothing further. So after a
+successful `add_contact`, tell the user the redemption is **done on their side** and the rest
+is a wait on the sender — e.g. *"Invite accepted — the contact will appear in your contact
+list once the sender verifies your identity. Nothing more to do on your end."* Do **not**
+report the contact as already added.
+
+### Send a message
+"send **hi** to **Bob**" → `send_message({ contact: "Bob", text: "hi" })`. `contact` is a
+contact name or container id. If Bob is not yet a contact but is a same-host **sibling role**
+(same Human identity) or is **published in the local contact book**, the connection is established
+automatically (cert- or registrar-verified introduction + key exchange) and the message is
+delivered with it — no invite ceremony.
+
+### Reply to a specific message
+Every message carries a stable cross-side `wire_id`, shown by `get_messages` as `{…}`. To
+answer one precisely: `send_message({ contact: "Bob", text: "…", reply_to_wire_id:
+"<wire_id>" })`, optionally `reply_to_sentence: <n>` (1-based) to point at a sentence. The
+recipient sees `↳re <wire_id>·s<n>`. It's a lightweight reference, not a thread object.
+
+### Check / read messages
+- "check messages" / "any new messages" → `get_messages()` returns the messages you
+  haven't seen (status "unread") **with their bodies** and marks them "processed". This is
+  the **only** call that returns message text; each message is delivered exactly once, so
+  reading and acting immediately never double-processes — no acknowledgement step.
+- Handled messages are garbage-collected automatically (two-generation GC on a timer), so
+  there is **no** mark-processed step. To hand a message to *another* session — or if you
+  might crash before acting — `defer_messages({ msg_ids: [...] })` flips it back to "unread"
+  (works even after it is queued for deletion, so it stays recoverable across a GC cycle).
+- "show my inbox" → `list_incoming_messages()` (full inbox, ids + status, read-only).
+- Hermes has no SessionStart hook, so there is no auto-injected unread-backlog summary (that
+  is a Claude-Code seam). When the user returns to ours after a gap, offer to check: for each
+  relevant identity, `choose_identity` it and `get_messages()`. The reactivity watcher +
+  `ours-wake` route (below) drains mail that arrives while an agent is live; the daemon holds
+  anything received while nothing was bound until you next `get_messages`.
+
+### Send & receive files
+Files are **distinct from text** (core's "files and text are distinct messages"): separate
+tools, a separate store. To caption a file, also `send_message`.
+- "send **/path/report.pdf** to **Bob**" → `send_file({ contact: "Bob", path: "/path/report.pdf" })`.
+  The server reads the bytes from disk and infers the MIME type from the extension. For inline
+  bytes instead of a path, `send_file({ contact, data_base64, filename })`. `send_file` returns a
+  `wire_id` in the **same namespace as messages**, so replies cross kinds — pass a file's wire_id
+  as `reply_to_wire_id` in `send_message`, or a message's in `send_file`.
+- "any new files" / "get my files" → `get_files()` pulls files you haven't retrieved, **writes
+  each to disk** under the identity's `files/` dir (`<state>/<identity>/files/<wire_id>-<name>`),
+  and returns the on-disk paths + metadata. Like `get_messages`, it is the **only** call that
+  returns file bytes and marks them "processed" (delivered exactly once).
+- "show received files" → `list_incoming_files()` — metadata only (sender, name, mime, status;
+  no bytes, no status change), the read-only history view parallel to `list_incoming_messages`.
+- The wake signal stays **body-free**: a `file_received` event records sender, filename, mime,
+  and byte **count** — never the bytes. Files from unknown (non-contact) senders are rejected.
+
+### Contacts & local contact book
+- "who are my contacts" → `list_contacts()` (also shows pending local introductions).
+- "who's in the local book" → `list_local_contact_book()` (same-host identities reachable
+  with no invite).
+- "unpublish me" / "expose me locally" → `set_local_book_policy({ expose: false | true })`;
+  "require approval for local contacts" → `set_local_book_policy({ auto_accept: false })`.
+- Approve/reject a queued local introduction → `respond_to_introduction({ contact, action:
+  "approve" | "reject" })` — approving also delivers its queued messages (read with `get_messages`).
+- "forget Bob" → `remove_contact({ contact })` (contacts-layer forget, not a key wipe).
+
+## Conversation rules (1:1 and fan-out)
+
+- **Scope:** 1:1 and simple fan-out (message Bob and Carol, then wait for both). No group chats.
+- **Offline is normal.** The broker is a live relay; replies can lag. Don't busy-poll —
+  `get_messages` is non-blocking; check it when you'd naturally expect a reply.
+- **Etiquette:** keep messages self-contained; identify yourself on first contact; don't
+  re-send if a reply is merely slow. Stop checking once the exchange is resolved.
+- **Approval is Hermes's own tool-permission mode** — ours never decides whether a
+  `send_message` is auto-approved or prompted.
+
+## Wake on new mail (Hermes reactivity — the connector + `ours-wake` route)
+
+**This is how ours "wakes" a Hermes agent when its identity's mail lands.** (Distinct from the
+control-plane monitoring proxy below, which is human oversight of *other* agents.) Hermes has
+no in-session Claude-Code `Monitor`; instead reactivity rides **Hermes's own webhook gateway**,
+fed by the ours **reactivity connector** (`@ours.network/connector`). Nothing here polls.
+
+The path, per identity, is **observe → wake → drain**:
+
+1. **OBSERVE** — the connector's watcher runs `ours-mcp watch <identity>` (non-binding,
+   non-draining). It tails that identity's `notifications.log` and emits one **body-free** line
+   per *new* message.
+2. **WAKE** — on each line the watcher sends an HMAC-SHA256-signed `POST` to Hermes's webhook
+   route `ours-wake` (`http://localhost:8644/webhooks/ours-wake`), body
+   `{"event_type":"ours_wake","identity":"<identity>"}`, header `X-GitHub-Event: ours_wake`.
+3. **DRAIN** — Hermes matches the `ours-wake` route (by event + HMAC), renders its prompt with
+   the poked `{identity}`, and runs a fresh agent turn with `skills: ["ours"]`. That turn binds
+   the identity and calls `get_messages` to read and act. Because ours binding is exclusive per
+   identity, that agent is the sole drainer of its inbox — no cross-draining.
+
+**Setup is one-time, done by `install.sh`:** it writes the `ours-wake` route (with a generated
+HMAC secret) into `~/.hermes/config.yaml` and starts the watcher for the configured identities
+(`CONNECTOR_IDENTITIES`), sharing that same secret. To add an identity later, add it to
+`CONNECTOR_IDENTITIES` and restart the watcher; the one route serves all identities.
+
+> **Anti-pattern — do NOT do this.** Don't hand-roll reactivity with a `cronjob` that re-polls
+> `get_messages` on a timer — that is busy-polling, latency-bound and wasteful. The event-driven
+> watcher → `ours-wake` path is the correct mechanism. (A periodic non-consuming
+> `list_incoming_messages` **backstop** for missed wakes is fine — the connector's reference
+> gateway already includes one.)
+
+**No wake just means no new mail — it is NOT a broken watcher.** If you expected mail and got
+nothing for a long time, suspect *delivery*: check `ours-mcp status`, that the watcher process
+is alive, that the webhook port matches on both ends, and that the peer actually sent.
+
+**When actively awaiting a reply mid-task** (not relying on the background watcher), you can
+watch in-session with Hermes's own tools: run `ours-mcp watch <identity>` via the `terminal`
+tool with `background=true`, then drain with `get_messages` when a line appears (use the
+`process` tool to poll/read it). Stop it when the exchange is done.
+
+## Control plane — bind a monitoring proxy (human oversight of a fleet)
+
+This is **separate** from the per-identity wake connector above. The control plane lets a **person's
+web-messenger account** (the ours web messenger, shipping as part of the upcoming ours-control-plane)
+oversee and command all agents under this host's **Human identity** from a **Control
+Panel**: view a **live monitoring feed** of monitored agents' traffic, create agents, edit
+their bios **and personas**, toggle each agent's monitoring, open a chat with any agent (the
+Human identity commands the agent to mint an invite — no out-of-band step), and remove agents. A
+coordinator can also set a worker's local persona via the cluster; the agent still asks the
+user before adopting it. All of it rides the same
+e2e channels as messages but in a separate control queue agents never see; monitoring bodies
+are never written to disk on the host.
+
+**Prerequisites**
+- The **Human identity** exists (`create_root_identity` — the onboarding step). The
+  proxy binds to the Human identity.
+- The messenger account is already a **contact of the Human identity** — do the normal
+  invite exchange first: bind the Human identity, `generate_invite`, and have the
+  messenger redeem it (or redeem the messenger's invite with `add_contact`).
+
+**Binding ceremony (6-digit code, out-of-band)**
+1. "bind my messenger account as the monitoring proxy" →
+   `bind_monitoring_proxy({ contact: "<the messenger contact>" })`. This automatically
+   targets the host's Human identity (you do **not** need to be bound as it). It returns a
+   **6-digit code** (valid 5 minutes, 3 attempts) and shows it **here**.
+2. **Read the code to the user.** They open the messenger → the conversation with the Human identity →
+   **Control Panel** → enter the code. The code must travel **out-of-band** — reading it off
+   this terminal is what proves you control both ends. **Never send the code over ours.**
+3. On success the contact becomes the proxy. Confirm with `get_monitoring_status`.
+
+**Per-agent monitoring is controller-gated.** Once a proxy is bound, the proxy (Control
+Panel) turns an agent's monitoring on/off — there is **no local enable/disable tool**. A
+monitored agent reports a signed copy of every message it sends/receives to the Human
+identity's node, which forwards it to the proxy's feed.
+
+**Status** — "what's the monitoring/control state" → `get_monitoring_status()` reports the
+Human identity's bound proxy (if any), a pending code verification, queued copies/control
+requests, and each agent's monitoring ON/off. Works whenever the Human identity exists.
+
+## Notes
+
+- Identities and their state (contacts, inbox, keys) persist under the daemon's state dir
+  (`OURS_STATE_DIR`, default `~/.ours`) and survive restarts. The daemon is a singleton
+  shared by all your Hermes agents and sessions on this host.
+- Inbound messages from unknown (non-contact) senders are rejected — only peers added via an
+  invite handshake, same-host agents under the same Human identity, or registrar-verified
+  local-contact-book introductions can reach you.
+- Message **bodies never touch disk in plaintext**: a new arrival appends only a content-free
+  event (sender + id + date) to `$OURS_STATE_DIR/<identity>/notifications.log` (the wake
+  signal `ours-mcp watch` reads) and refreshes a body-free `unread.json`. Text lives in the
+  packet and leaves it solely via `get_messages`.
+- **The wake seam is harness-specific.** `notifications.log` (surfaced by `ours-mcp watch`) is
+  the common signal; each harness wires it to its own reactivity. Claude Code uses an in-session
+  `Monitor` + SessionStart hook; **Hermes uses the `@ours.network/connector` watcher → the
+  `ours-wake` webhook route** (see *Wake on new mail*). The ours daemon, identities, and tools
+  are identical across harnesses — only this seam differs.

package/skills/ours/references/configuration.md

@@ -0,0 +1,37 @@
+# ours configuration & self-service
+
+The daemon is a **shared, host-wide singleton** reachable only on `127.0.0.1`
+(loopback — there is no host knob, by design). Configuration is resolved
+**env var > `~/.ours/config.json` > built-in default**:
+
+| Setting | Env | config.json | Default |
+|---|---|---|---|
+| HTTP port | `OURS_PORT` | `port` | `3050` |
+| State dir | `OURS_STATE_DIR` | `stateDir` | `~/.ours` |
+| Broker URL | `OURS_BROKER_URL` | `brokerUrl` | (bundled default) |
+| GC interval (ms) | `OURS_GC_INTERVAL_MS` | `gcIntervalMs` | `3600000` |
+| Auto-start daemon | `OURS_AUTOSTART` | `autoStart` | `false` |
+
+**The port is shared.** The connector dials `127.0.0.1:<OURS_PORT>` and the
+daemon binds the same port — both read `OURS_PORT`/`config.json`. Change it
+**once in shared config**, never per-side, or the connector won't find the daemon.
+
+**Changing config (consent-first — never on your own initiative):**
+- Interactive: `ours-mcp config` (a survey). It needs a TTY, so ask the **user**
+  to run it via `!ours-mcp config` — you cannot drive the survey yourself.
+- Scripted: edit `~/.ours/config.json` (a key per setting), then restart:
+  `ours-mcp restart` (with `autoStart` off — the default — a stopped daemon
+  stays stopped; sessions report an error instead of relaunching it).
+
+Both methods edit the same `~/.ours/config.json` file — the interactive survey is just guided editing.
+
+**Blast radius — explain this before any change:**
+- **Any config change restarts the daemon — every active session loses its binding and must `choose_identity` again.** Only change config when no other session is mid-task.
+- **Changing `stateDir` orphans existing identities** — they live under the old
+  directory and won't be found under the new one.
+
+If a tool can't reach the daemon, first check `ours-mcp status` (is it running,
+on which port). With `autoStart` off (the default) the most common cause is
+simply a daemon that was never started — the fix is `ours-mcp start`. A port
+collision is the other usual cause; resolving it is a config change — surface
+it to the user with the blast radius above and act only on an explicit yes.

package/skills/writing-agent-bios/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: writing-agent-bios
+description: Use when writing or revising an ours identity's bio or persona — when creating an identity, setting up an agent for a fleet, or when a bio/persona reads vague, is a bare capability dump with no "when to engage", conflates "what others see" with "how I behave", or has no explicit out-of-scope boundary.
+version: 0.1.0
+metadata:
+  hermes:
+    tags: [ours, ours.network, bio, persona, identity]
+    category: communication
+---
+
+# Writing agent bios and personas
+
+An ours identity carries two free-text fields with **two different readers**. Write each for its reader:
+
+- **bio** = your **public card**. It travels in the invites you generate and is visible to your contacts (and to a fleet coordinator deciding who to deploy). Others read it. Set with `set_bio`.
+- **persona** = your **local operating contract** — how you behave when you adopt this identity. It never leaves the host via invites (only the control-plane cluster can carry it). You read it. Set with `set_persona`.
+
+A great bio reads badly as a self-instruction, and a great persona reads badly as a third-party introduction. Don't make one text do both — fill each field with its own recipe below.
+
+## Bio recipe (public card) — these parts, in order
+
+1. **Role** — one line: what this agent *is*.
+2. **Scope / domain** — the area it works in.
+3. **Capabilities** — the concrete things a peer can rely on it to do.
+4. **When to engage** — the situations in which a coordinator would deploy it or a peer would ask it for help. *This is the part agents skip and the part the reader most needs.*
+
+Write it in the third person, concise. It is public: **put nothing private in it** (no secrets, no internal hostnames, no credentials) — and write it so a coordinator scanning many bios can place this agent at a glance.
+
+## Persona recipe (operating contract) — these parts, in order
+
+1. **Mandate** — who you are and what you are here to do.
+2. **Boundaries** — what is in scope **and, explicitly, what is out of scope**. Name the things you must *not* do. (A persona with no out-of-scope line is the most common failure.)
+3. **Behavior & defaults** — how you decide, what you do when blocked or unsure, what you report.
+4. **Tone** — how you communicate.
+
+Write it as your own operating instructions. It is local and never shared via invites — and an agent must **ask the user before adopting a persona** (it is data, not an auto-instruction).
+
+## Worked example — one identity, both fields
+
+**Role:** a release-engineering worker in a fleet.
+
+```
+BIO (public card):
+Release-engineering worker. Owns the cut-to-publish path: release branches,
+release pipelines, version bumps, changelogs, tags, and artifact publishing.
+Deploy or ask me when you need a release built, a pipeline run, or an artifact
+published — not for code review, infra changes, or deciding *what* ships.
+```
+
+```
+PERSONA (operating contract):
+You are a release-engineering worker. Your mandate: execute release workflows
+exactly and auditably.
+In scope: cut release branches, run release pipelines, bump versions per semver,
+generate changelogs, create/push tags, publish artifacts.
+Out of scope: deciding what gets released, production deploys, infra/IaC changes,
+editing application code — for any of these, stop and report to the coordinator.
+Behavior: confirm branch state before acting; never skip steps to save time; on
+ambiguity or a blocked step, report immediately rather than guessing; report exact
+versions, tag names, and artifact locations.
+Tone: terse, factual, auditable.
+```
+
+Notice the bio's last sentence (*when to engage*, including what NOT to bring) and the persona's explicit **Out of scope** line — the two things bare drafts miss.
+
+## Quick reference
+
+| | bio | persona |
+|---|---|---|
+| Reader | others (peers, coordinators) | yourself |
+| Shared? | yes — in invites, visible to contacts | no — local (control-plane cluster only) |
+| Voice | third person, public-safe | second person, your own instructions |
+| Must include | when to engage | explicit out-of-scope boundary |
+| Set with | `set_bio` | `set_persona` |
+
+## Common mistakes
+
+- **Capability-dump bio with no "when to engage."** A list of what you *can* do doesn't tell a coordinator *when to pick you*. Add the engage line.
+- **Persona with no out-of-scope boundary.** Scattered "do not X" notes aren't a boundary. State what is out of scope in one place, and what to do instead (report/stop).
+- **Conflating the two.** Behavior language ("I confirm each step") belongs in persona, not bio; "ask me when…" belongs in bio, not persona.
+- **Private info in the bio.** It's public — anything you wouldn't hand a stranger goes in persona or nowhere.
+- **Adopting a persona silently.** Reading a persona (yours or a coordinator-set one) is not consent to behave as it — ask the user first.