@cohortapp/agent-sdk 2.3.0

package/docs/guides/telegram-setup.md

@@ -0,0 +1,227 @@
+# Telegram Setup Guide
+
+How to enable Telegram messaging for a Maestro agent: creating a bot with
+BotFather, wiring the token, the in-daemon grammY long-poll adapter, inbound event
+mapping (DMs, groups, forum topics, reactions, media, voice→STT), default-deny DM
+pairing, and outbound sending.
+
+**Prerequisites**: A working agent repo (`maestro create` + `maestro setup`
+identity done) and a Telegram account to talk to BotFather.
+
+---
+
+## Architecture Overview
+
+Unlike WhatsApp/SMS (which use Twilio webhooks behind a Cloudflare tunnel),
+Telegram runs entirely **inside the daemon** via grammY long-polling — there is
+**no relay, no tunnel, and no extra process**:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  INBOUND                                                         │
+│                                                                   │
+│  Telegram user ──▶ Telegram Bot API                             │
+│                         │  (long-poll: getUpdates)               │
+│                         ▼                                        │
+│           lib/channels/telegram/adapter.mjs  (grammY)           │
+│                         │  _toEvent → MessageEvent              │
+│                         ▼                                        │
+│              writeInboxItem → state/inbox/telegram/*.yaml       │
+│              (classifier / dispatcher route — unchanged)        │
+├─────────────────────────────────────────────────────────────────┤
+│  OUTBOUND                                                        │
+│                                                                   │
+│  adapter._send ──▶ Telegram Bot API ──▶ Telegram user          │
+│  (typing heartbeat via sendChatAction while a session runs)     │
+├─────────────────────────────────────────────────────────────────┤
+│  PAIRING (default-deny)                                          │
+│                                                                   │
+│  Unknown DM ──▶ "pair <code>" gate ──▶ config/allowlist.yaml   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+grammY is a **dynamic dependency** (like Baileys): the package installs without
+it, and the daemon only loads the Telegram adapter when `config/telegram.yaml`
+exists. Flip the gate file off to disable the channel.
+
+---
+
+## 1. Create a Bot with BotFather
+
+1. Open Telegram and message **@BotFather**.
+2. Send `/newbot`. Choose a display name and a username ending in `bot`.
+3. BotFather replies with an HTTP API token like `123456789:ABCdef...`. Keep it secret.
+
+### (Optional) Let the bot read all group messages
+
+By default a bot only sees `@mentions`, replies, and commands in groups. To let it
+read every message in a group:
+
+1. @BotFather → `/setprivacy` → pick your bot → **Disable**.
+
+Leave privacy **enabled** if you only want the agent to react when addressed.
+
+---
+
+## 2. Wire the Token and Activate the Channel
+
+Run the idempotent init script (mirrors `init-whatsapp-baileys.mjs`):
+
+```bash
+node scripts/setup/init-telegram.mjs
+```
+
+It will:
+
+1. Walk you through the BotFather steps above.
+2. Prompt for the token and append `TELEGRAM_BOT_TOKEN=...` to `.env` (never
+   overwriting an existing value; it skips the prompt when stdin is non-interactive).
+3. **Validate the token** via the Telegram `getMe` API (no grammY needed) and print
+   the resolved bot username.
+4. Activate `config/telegram.yaml` from the scaffold example (the gate file).
+5. Check for the optional `grammy` npm package and print an install hint if missing.
+
+Install grammY in the agent repo so the daemon can load the adapter:
+
+```bash
+npm i grammy
+```
+
+You can also set the token by hand in `.env`:
+
+```bash
+# Telegram (grammY long-poll, in-daemon)
+TELEGRAM_BOT_TOKEN=123456789:ABCdef...
+```
+
+### Wiring through `maestro setup`
+
+The `comms` section of the setup wizard wires Telegram alongside the other
+channels and verifies it:
+
+```bash
+maestro setup comms
+```
+
+It runs the same init flow, confirms `config/telegram.yaml` is present, and
+includes Telegram in the capability table (the verify probe checks `getMe`).
+
+---
+
+## 3. Inbound — Event Mapping
+
+The adapter's `_toEvent` translates each grammY update into the unified
+`MessageEvent` contract (`lib/channels/contract.mjs`). Mapping:
+
+| Telegram update | `MessageEvent` |
+|---|---|
+| Private message (DM) | `kind: "message"`, `source: telegram`, thread keyed to the DM |
+| Group / supergroup message | `kind: "message"` with the chat as the conversation |
+| Forum **topic** (`message_thread_id`) | `kind: "message"` with `thread_context` set to the topic |
+| Reaction (`message_reaction`) | `kind: "reaction"` (resolves the target message text) |
+| Photo / document / audio | `kind: "message"` with the media attached |
+| **Voice note** | `kind: "voice_note"` — audio is run through STT and the transcript becomes the message body |
+
+Because `MessageEvent` is serialized to the same on-disk inbox-item bytes as the
+legacy poller (`lib/channels/inbox-item.mjs`), the classifier, directed-gate, and
+dispatcher handle Telegram items with no special-casing.
+
+---
+
+## 4. DM Pairing (default-deny)
+
+Telegram DMs are **default-deny**: an unknown sender cannot reach the agent until
+they pair. Pairing is enforced in `BaseAdapter` (so every channel inherits it) via
+`lib/channels/pairing.mjs` and the cross-channel allowlist `config/allowlist.yaml`.
+
+- An unknown DM is intercepted **before** the classifier; the agent does not act on it.
+- The sender pairs by sending exactly `pair <code>` (matched by `^pair <code>$`).
+- Once redeemed, their Telegram id is added to the allowlist and subsequent messages flow normally.
+- You can also seed allowlisted ids ahead of time under the `telegram:` key in `config/allowlist.yaml`.
+
+Groups follow the bot's privacy setting (see §1); pairing applies to direct
+messages.
+
+---
+
+## 5. Outbound — Sending and Typing
+
+Outbound goes through the adapter's `_send`. While a session is working on a
+Telegram conversation, `BaseAdapter`'s typing heartbeat calls `sendChatAction`
+(`typing`) every few seconds so the user sees the agent "typing…" until the reply
+lands — the same holding behaviour as Slack/WhatsApp. SMS/Gmail have no typing
+capability and are no-ops there.
+
+Outbound messages pass through the standard pre-send pipeline (content-hash dedup,
+factual validation, audit logging) like every other channel.
+
+---
+
+## 6. Testing
+
+| # | Test | How to Verify |
+|---|---|---|
+| 1 | Token valid | `node scripts/setup/init-telegram.mjs` prints `token valid — bot is @yourbot` |
+| 2 | Gate file present | `config/telegram.yaml` exists |
+| 3 | grammY installed | `ls node_modules/grammy` |
+| 4 | Daemon loads adapter | Start the daemon; check logs for the Telegram adapter connecting |
+| 5 | Inbound DM | DM the bot; check `state/inbox/telegram/` for a YAML item |
+| 6 | Pairing blocks unknown | DM from an unpaired account → no agent action until `pair <code>` |
+| 7 | Group mention | @mention the bot in a group; verify it's captured |
+| 8 | Reaction captured | React to a message the bot can see; verify `kind: reaction` |
+| 9 | Voice note → STT | Send a voice note; verify the transcript appears as the message body |
+| 10 | Verify probe | `maestro setup comms` (or `maestro doctor`) shows Telegram passing |
+
+---
+
+## 7. Troubleshooting
+
+### `getMe` validation fails
+
+1. Re-copy the token from BotFather — a trailing space or missing digits breaks it.
+2. The token format is `digits:alphanumerics` (e.g. `123456789:ABCdef...`).
+3. If you regenerated the token via `/revoke`, update `TELEGRAM_BOT_TOKEN` in `.env`.
+
+### Bot doesn't see group messages
+
+1. Privacy mode is **enabled** by default — the bot only sees mentions/replies/commands.
+2. @BotFather → `/setprivacy` → your bot → **Disable**, then re-add the bot to the group.
+
+### Daemon starts but Telegram never connects
+
+1. Confirm `config/telegram.yaml` exists (the gate file) — without it the adapter never loads.
+2. Confirm `grammy` is installed in the **agent** repo: `npm i grammy`.
+3. Check the daemon logs for a token or network error from `getUpdates`.
+
+### Unknown sender can't reach the agent
+
+That's the default-deny pairing working as designed. Have them send `pair <code>`,
+or seed their id under `telegram:` in `config/allowlist.yaml`.
+
+### Conflict: "terminated by other getUpdates request"
+
+Two processes are long-polling the same bot token. Telegram allows only one. Make
+sure you aren't running a second daemon (or a stray script) with the same
+`TELEGRAM_BOT_TOKEN`.
+
+---
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `lib/channels/telegram/adapter.mjs` | grammY long-poll adapter (`_connect/_toEvent/_send/_react/_setTyping`) |
+| `scripts/setup/init-telegram.mjs` | Idempotent init: BotFather walkthrough, token → `.env`, `getMe` validation, gate-file activation |
+| `config/telegram.yaml` | Channel gate file (activated from the scaffold example) |
+| `config/allowlist.yaml` | Cross-channel default-deny DM allowlist (the `telegram:` key) |
+| `lib/channels/contract.mjs` | The unified `MessageEvent` contract `_toEvent` maps onto |
+| `lib/channels/base-adapter.mjs` | Session-keying, typing heartbeat, and pairing gate inherited by the adapter |
+
+---
+
+## Related Documents
+
+- [Setup Wizard](setup-wizard.md) — the `comms` section that wires Telegram
+- [Channel bus](channel-bus.md) — the unified messaging layer and `MessageEvent` contract
+- [WhatsApp Setup](whatsapp-setup.md) — the Baileys channel this guide mirrors
+- [Poller & Daemon Setup](poller-daemon-setup.md) — how channel events integrate with the event loop

package/docs/guides/twilio-subaccounts-setup.md

@@ -0,0 +1,223 @@
+# Twilio Sub-Accounts Setup Guide
+
+How to create a dedicated Twilio sub-account for each Maestro agent under a single parent Twilio account. This is required for per-agent WhatsApp segregation because the **Twilio WhatsApp Sandbox webhook is account-wide** — only one URL per Twilio account.
+
+**Prerequisites**: A parent Twilio account already exists (the company's root account). You have its `Account SID` and `Auth Token`.
+
+---
+
+## Why sub-accounts?
+
+Each agent runs as a separate identity (one per principal) and needs:
+
+- Its own phone number (for SMS)
+- Its own WhatsApp sandbox webhook URL (the constraint)
+- Its own auth token (so the agent's webhook relay can verify Twilio HMAC signatures independently)
+- Its own usage logs and cost attribution
+
+Sub-accounts give you all of this while still rolling up to the parent account for billing.
+
+| Constraint | Sharing parent account | Per-agent sub-account |
+|---|---|---|
+| WhatsApp sandbox webhook | One URL for ALL agents — only the latest agent's webhook works | Each agent has their own sandbox + webhook |
+| Phone numbers | Mixed across agents on one account | Each agent has their own |
+| Auth Token | Shared — every agent's relay can verify everything (security risk) | Per-agent token, isolated verification |
+| Cost attribution | Aggregated — hard to attribute to a specific agent | Sub-account usage rolls up but is separately reportable |
+| Suspension | Suspending the parent kills all agents | Suspend just the affected agent |
+
+---
+
+## 1. Create the sub-account
+
+Run from the agent's repo (or anywhere with `TWILIO_PARENT_ACCOUNT_SID` and `TWILIO_PARENT_AUTH_TOKEN` set):
+
+```bash
+TWILIO_PARENT_ACCOUNT_SID=AC...         # parent
+TWILIO_PARENT_AUTH_TOKEN=...            # parent
+AGENT_NAME="jordan-lee-northwind"       # whatever friendly name you want
+
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts.json" \
+  --data-urlencode "FriendlyName=$AGENT_NAME" \
+  | python3 -m json.tool
+```
+
+Capture from the response:
+
+- `sid` — the new sub-account SID (starts with `AC...`)
+- `auth_token` — the sub-account's auth token (use this for HMAC verification on the agent's webhook relay)
+- `owner_account_sid` — confirms it's a child of the parent account
+
+Save both to the agent's `.env`:
+
+```bash
+# Jordan's dedicated Twilio sub-account
+TWILIO_ACCOUNT_SID=ACf2...               # the new sub-account SID
+TWILIO_AUTH_TOKEN=c1da...                # the new sub-account auth token
+
+# Parent account — only used for sub-account management API calls
+TWILIO_PARENT_ACCOUNT_SID=AC36...
+TWILIO_PARENT_AUTH_TOKEN=af86...
+```
+
+---
+
+## 2. Buy a phone number under the sub-account
+
+Search for available numbers:
+
+```bash
+source .env
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?AreaCode=628&SmsEnabled=true&VoiceEnabled=true&PageSize=5"
+```
+
+Buy one (irreversible — costs ~$1.15/mo + per-message charges):
+
+```bash
+PHONE="+16283454599"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
+  --data-urlencode "PhoneNumber=$PHONE" \
+  --data-urlencode "FriendlyName=Jordan Lee - Northwind"
+```
+
+Save the returned `sid` (starts with `PN...`) to `.env` as `TWILIO_PHONE_SID`.
+
+### Transferring an existing number from the parent
+
+If the agent already has a number under the parent account that you want to move to the sub-account:
+
+```bash
+PARENT_SID="AC36..."          # parent account SID
+PARENT_AUTH="af86..."         # parent account auth token
+PHONE_SID="PN1eb30e..."       # the number to move
+SUBACCOUNT_SID="ACf2..."      # destination sub-account
+
+curl -s -u "$PARENT_SID:$PARENT_AUTH" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$PARENT_SID/IncomingPhoneNumbers/$PHONE_SID.json" \
+  --data-urlencode "AccountSid=$SUBACCOUNT_SID"
+```
+
+The number, all its webhook configuration, and message history move to the sub-account in one API call.
+
+---
+
+## 3. Configure the SMS webhook
+
+After the sub-account owns the number, configure the SMS webhook to point at the agent's Railway webhook relay:
+
+```bash
+source .env
+RELAY_URL="https://${AGENT_FIRSTNAME_LOWER}-webhook-relay-production.up.railway.app"
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  --data-urlencode "SmsUrl=$RELAY_URL/sms" \
+  --data-urlencode "SmsMethod=POST"
+```
+
+---
+
+## 4. Configure the WhatsApp sandbox
+
+This is the whole reason we use sub-accounts. Each sub-account has its own independent WhatsApp sandbox.
+
+**Important**: WhatsApp sandbox webhook configuration is **UI-only** — Twilio does not expose an API for this. You must use Playwright or the user must configure it manually.
+
+1. Log in to the Twilio Console (the sandbox UI uses a different login session than the API)
+2. **Switch to the sub-account** via the account selector top-left (the dropdown shows all sub-accounts under the parent)
+3. Navigate to: `https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn?frameUrl=%2Fconsole%2Fsms%2Fwhatsapp%2Flearn`
+4. Click **Sandbox settings** tab
+5. Set the inbound webhook URL: `https://{firstname}-webhook-relay-production.up.railway.app/whatsapp`
+6. Set the status callback URL: `https://{firstname}-webhook-relay-production.up.railway.app/whatsapp/status`
+7. Set both methods to HTTP POST
+8. Save
+
+Note the **sandbox join code** shown on the page (e.g. `join follow-arm`). Users must send `join {code}` from their WhatsApp to `+1 415 523 8886` to enroll their number for testing with this agent's sandbox.
+
+### Production WhatsApp (post-sandbox)
+
+For production WhatsApp (real WABA business number, not the shared sandbox number), each sub-account can register its own WABA. This requires Facebook Business verification per sub-account — Twilio provides a self-sign-up flow at https://www.twilio.com/docs/whatsapp/self-sign-up. Same pattern: each agent's sub-account → its own WABA → its own webhook URL.
+
+---
+
+## 5. Update the Railway webhook relay
+
+The agent's relay verifies Twilio HMAC signatures using the sub-account's auth token (NOT the parent's). After creating the sub-account, update the Railway env var:
+
+```bash
+source .env
+cd services/webhook-relay
+railway variables --service ${AGENT_FIRSTNAME_LOWER}-webhook-relay \
+  --set "TWILIO_AUTH_TOKEN=$TWILIO_AUTH_TOKEN"
+railway up --service ${AGENT_FIRSTNAME_LOWER}-webhook-relay --detach
+```
+
+Wait until `/health` reports `twilio_signature: true` again.
+
+---
+
+## 6. Add to init-maestro Phase 4
+
+When `/init-maestro` runs Phase 4 Service Configuration, the Twilio step should:
+
+1. Check whether `TWILIO_PARENT_ACCOUNT_SID` is set in `.env` (from a previous agent's setup or org config)
+2. If yes: create a sub-account for this agent via the API (Step 1 above), then bypass the "buy new account" flow
+3. If no: this is the first agent in the org — use `TWILIO_ACCOUNT_SID` as both parent and main, and document that future agents will need sub-accounts under it
+4. Buy a phone number under the sub-account
+5. Configure SMS webhook → Railway
+6. (Manual or Playwright) Configure WhatsApp sandbox → Railway
+
+---
+
+## Verification
+
+```bash
+# 1. Sub-account exists and is active
+source .env
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json" \
+  | python3 -m json.tool
+
+# 2. Phone number is owned by the sub-account
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json"
+
+# 3. SMS webhook points at Railway
+curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers/$TWILIO_PHONE_SID.json" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print('SMS URL:', d.get('sms_url'))"
+
+# 4. Send a test SMS using the sub-account credentials
+bash scripts/send-sms.sh --to "+1...your_test_number" --body "Sub-account test from {AgentName}"
+
+# 5. Send a WhatsApp message after joining the sandbox
+bash scripts/send-whatsapp.sh --to "whatsapp:+1...your_number" --body "WhatsApp test from {AgentName}"
+```
+
+---
+
+## Closing / suspending a sub-account
+
+When an agent is decommissioned:
+
+```bash
+source .env
+curl -s -u "$TWILIO_PARENT_ACCOUNT_SID:$TWILIO_PARENT_AUTH_TOKEN" -X POST \
+  "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json" \
+  --data-urlencode "Status=closed"
+```
+
+Closing is irreversible. Use `Status=suspended` for temporary suspension (can be reactivated).
+
+Before closing, decide what to do with the agent's phone number:
+- Transfer back to the parent account (if you want to retain the number for re-use)
+- Release it (Twilio will free up the number, you stop being charged)
+
+---
+
+## Related guides
+
+- [Webhook Relay Setup](webhook-relay-setup.md) — How the Railway relay uses `TWILIO_AUTH_TOKEN` to verify HMAC signatures
+- [Voice & SMS Setup](voice-sms-setup.md) — End-to-end SMS pipeline
+- [WhatsApp Setup](whatsapp-setup.md) — Sandbox vs production WhatsApp

package/docs/guides/verification.md

@@ -0,0 +1,128 @@
+# Verifying Maestro
+
+How to prove the framework works — from the zero-credential automated suite to a
+full live agent. Use the fast path for every change; use the live sections when
+you've wired real channel/model credentials.
+
+## 1. Fast path — automated suite (no credentials, ~7s)
+
+From the framework checkout (`~/maestro`):
+
+```bash
+npm install            # once
+npm test               # full suite — 862 tests across every subsystem
+npm run check          # 6 zero-dependency guards (conflict markers, exports,
+                       # files-exist, no-confidential, unresolved tokens, identity)
+```
+
+`npm test` is the single source of truth for the logic of all four workstreams
+(it runs hermetically — every channel socket, `claude --print`, and `os`-stat is
+injected, so there's no network or real spawn). Green here means the wizard,
+channel contract, learning loop, governor, rate-guard, budget-guard, cadence bus,
+and recovery paths all behave.
+
+Scoped subsets (all defined in `package.json`):
+
+```bash
+npm run test:setup     # the maestro setup wizard (lib/setup/*)
+npm run test:channels  # channel abstraction
+npm run test:cadence   # cadence bus + consumer + enqueue
+npm run test:voice     # voice
+npm run test:cli       # bin/maestro.mjs
+```
+
+Run one file directly while iterating:
+
+```bash
+node --test lib/learning/curator-consolidate.test.mjs
+node --test lib/channels/whatsapp/baileys-typing.test.mjs
+```
+
+## 2. The setup wizard (deterministic — safe to dry-run anywhere)
+
+```bash
+node bin/maestro.mjs setup --help        # command + flag reference
+```
+
+Inside an **agent instance repo** (one created by `maestro create`):
+
+```bash
+maestro setup --status     # per-section detect(): unconfigured / partial / complete
+maestro setup --dry-run    # show what each section would do; writes nothing
+maestro setup --only comms # (re)run a single section
+```
+
+Unattended / CI config (no prompts, no LLM unless you drop `--no-enrich`):
+
+```bash
+maestro setup --headless --answers answers.json
+```
+
+`lib/setup/integration.test.mjs` already exercises this end-to-end: it copies the
+`scaffold/`, runs the wizard headless on a fixture answers file, asserts a green
+completeness gate, and re-runs to prove idempotency. That test is the canonical
+"the wizard actually configures an agent" proof.
+
+## 3. `maestro doctor` — runtime health of a configured agent
+
+```bash
+maestro doctor          # identity + operating-model completeness, channels,
+                        # cadence-bus arch, watchdog heartbeat, .emergency-stop
+                        # (human-only now), governor ceiling vs RAM, open rate
+                        # breaker, pmset autorestart, resume-pending strikes,
+                        # today's budget band
+maestro doctor --fix    # apply the auto-fixable findings
+```
+
+## 4. Live, per-subsystem (needs the relevant credentials)
+
+### Messaging (real-time)
+- **Telegram** — set `TELEGRAM_BOT_TOKEN`, then `node scripts/setup/init-telegram.mjs`
+  (validates via `getMe`, writes `config/telegram.yaml`). DM the bot; unknown DMs
+  are default-denied → reply `pair <code>` to pair. Long-poll runs inside the
+  daemon (no relay/tunnel).
+- **Slack** — `node scripts/setup/init-slack-socket-mode.mjs`; enable reactions /
+  thread-context / CC'd channels via `config/slack.yaml`. The dedicated launchd
+  socket process is the single owner (do **not** also set the daemon adapter).
+- **WhatsApp (Baileys)** — `npm i baileys` in the agent repo, scan the QR
+  (`state/whatsapp/auth/pending-qr.txt`); the agent now shows a real "typing…"
+  presence while it composes a reply.
+- **Verify inbound actually works** — `maestro setup comms` runs a per-channel
+  probe that drops a sentinel and asserts a matching inbox-item / connect-log
+  appears within a timeout (it prints the `tail -f` command on failure).
+
+### Self-learning loop
+- End a Claude Code session in an agent repo → the global `Stop` hook spawns the
+  detached reflect worker. Confirm:
+  - `plugins/agent-skills/skills/<id>.md` — any newly authored skill (live on disk
+    immediately; the next session loads it).
+  - `logs/audit/skills.jsonl` — every create/patch/abort/consolidate row.
+  - `state/learning/counters.json` — the nudge counters.
+- **Verbatim recall** — invoke the `session-search` skill (discovery / scroll /
+  read / browse) over `state/learning/sessions.db`.
+- **Skill curator** — `node scripts/learning/consolidate-skills.mjs` runs the LLM
+  umbrella consolidation on demand (no-op below `consolidation.minSkills`); it
+  otherwise fires as a detached worker from the `skill-curator` cadence when due.
+
+### Recovery & resource governance
+- **Governor** — `lib/resource-governor.test.mjs` drives ADMIT/QUEUE/DEFER with
+  injected `os` stats; in production it gates every `dispatcher.spawnSession`.
+- **Never-brick watchdog** — `bash -n scripts/watchdog/memory-watchdog.sh`; the
+  tiers are SOFT (`state/throttle.json`) → HARD (kill youngest) → CRITICAL (clean
+  restart) → graceful reboot. OOM never writes `.emergency-stop`.
+- **At-most-once cron / outage** — `lib/cadence-bus-schedule.test.mjs` proves a
+  simulated multi-period outage yields exactly one catch-up tick.
+
+## 5. Full end-to-end on a scratch agent
+
+```bash
+npx @cohortapp/agent-sdk create test-agent
+cd test-agent
+npm install
+maestro setup --headless --answers answers.json   # or run it interactively
+maestro doctor                                     # confirm green
+npm install -g baileys   # (optional) per channel you enable
+```
+
+This goes from an empty directory to a configured, self-verifying agent using the
+same code the suite covers.