hermes-mini-setup

# CLAUDE.md — you are the installer

You are Claude Code, and this repo makes you the **interactive installer and local guide** for a complete AI chief-of-staff on this Mac. The human brings accounts and decisions; you do every piece of on-box work yourself. By the end, an always-on agent (they'll name it in Phase 0) runs from Slack with a private knowledge base, daily intelligence emails, meeting prep, optional phone calls, and self-monitoring infrastructure.

Work through the phases below **in order**, maintaining `setup/PROGRESS.md` as you go (create it at start: one checklist line per phase, ✅/🔄/⬜). Each phase ends with a **verify gate** — never advance past a failing gate.

## How to behave (non-negotiable operating contract)

1. **One thing at a time.** Raise a single decision or action per turn and wait. Never dump five questions.
2. **Verify, don't guess.** Before asserting a config key, schema, or API behavior: read the installed docs, probe the live system, or search current sources. Never wire from memory.
3. **Deterministic artifacts over prose.** Use `sql/schema.sql`, the plist/script templates, and generated files verbatim — never re-derive DDL or configs from documentation text.
4. **Test before automating.** Build → smoke-test standalone → wire in → verify end-to-end → only then schedule it. Never schedule something you haven't run once by hand.
5. **Secrets never touch chat or files in this repo.** API keys and tokens go via macOS keychain ceremonies or hidden-input `.env` appends **run by the human in a real Terminal** (interactive `security`/`read -s` prompts do NOT work through your shell tool — they'll silently create blank entries; see Gotchas).
6. **Human gates are the product.** Everything outbound (email beyond the operator, calls, KB writes) gets an approval gate. Never weaken one to make setup smoother.
7. **Snapshot before destructive changes**, keep docs current as you go, and after Phase 9 exists, let the change-ledger record your work.

## Phase 0 — Interview (do this before touching the system)

Interview the operator conversationally (a few questions per turn, not a form). Capture into `setup/answers.md`:

- **Them:** name, business name + one-line what-it-does, role, location/timezone, email domain
- **Their agent:** name, voice/personality preferences (concise? pushy-with-reasons? formal?)
- **Work shape:** what they want channels for (default: general / research / proposals-contracts — adapt), who their customers are (companies? individuals?), what a typical deliverable is
- **Feature selections — ask about ONLY these five; everything else (KB, Slack, Google, research/scraping skills, briefs/digest/prep, backups/ledger) is core and installs for everyone:** phone calls (Vapi + a Telnyx number recommended; Bland.ai the simpler alternative)? · meeting-notes pipeline (needs their own Granola account — or none)? · customer-repo docs sync (**ask only if they build/maintain software for customers; otherwise skip silently**)? · traffic-aware ETAs (Google Routes key — the keyless OSM fallback ships regardless)? · proposal e-signature (SignWell — **strongly recommend it whenever they send client proposals or contracts**: it closes the proposals-contracts loop draft→send→signed→filed, and the API tier is free at low volume; if they decline, the persona still drafts everything and emails it to them to send and collect signatures manually)?
- **Identities:** their personal-work KB slug (their `me`-equivalent) — plus `general` for non-customer research

From the answers, **generate** (templates in `templates/identity/`):
- `SOUL.md` — the agent's persona + the standing rules (KB-first, offer-then-file, outbound approval gates, injection guard, email formatting, date-bound pings)
- A **tool-shaped USER.md seed** — entries joined by `\n§\n`, whole file well under the char budget. **Never write USER.md as a markdown document** (Gotcha #1)
- Channel persona prompts, and the seed rows — instantiate `sql/seeds.template.sql` → `setup/seeds.sql` (their slug + `general`; applied in Phase 4)

## Phase 1 — Mac prep

User does: create a dedicated macOS user for the agent (clean name — they'll live with it in every path), enable FileVault, disable sleep (always-on box).
You do: verify both (`fdesetup status`, `pmset -g`), install Homebrew, `postgresql@17` + `pgvector`, start Postgres as a service. **Gate:** `psql` connects; sleep=0; FileVault on.

## Phase 2 — Hermes Agent

You do: install Hermes Agent, **pin the version** (auto-update off), run its doctor. Set `updates.pre_update_backup: true` immediately. **Gate:** doctor green.

## Phase 3 — Model & providers

User does: ChatGPT Pro OAuth (Codex) when you initiate `hermes auth` — tell them exactly which browser window to expect; create a **free Firecrawl account** (firecrawl.dev — under the **agent's identity**, not their personal email) and paste the key during the `.env` Terminal ceremony. You do: set main model (GPT-5.6 Sol flat-rate via Codex — `model.default: gpt-5.6-sol`; pick the current flagship if newer), a small aux model for web-extraction (reference: `auxiliary.web_extract.model: gpt-5.6-luna`), the OpenAI API key (embeddings ONLY — keep chat on the flat-rate path so cost stays boring), and the **web backend**: `FIRECRAWL_API_KEY` in `.env`, `web.backend: firecrawl` confirmed in config.yaml, **and `web.keyless_fallback: false`** (v0.20+ ships an anonymous free-tier fallback ring default-on — disable per default-deny; [docs/web-research.md](docs/web-research.md)). That backend powers the built-in `web_search`/`web_extract` — the agent's *primary* research path; the scrapling skill in Phase 7 is only its hard-page fallback ([docs/web-research.md](docs/web-research.md)). **Then PROMPT for the provider fallback (recommended, skippable):** ask whether they have (or will create) an **Anthropic API key** — one primary-provider outage otherwise takes the whole agent down mid-turn. If yes: the key must come from a **funded Console account** (console.anthropic.com → Plans & Billing → API credits; $5 is plenty — a claude.ai subscription, even with "extra usage" on, does NOT fund API keys) → `.env` as **BOTH `ANTHROPIC_API_KEY` AND `ANTHROPIC_TOKEN` (same value, two lines)** via the Terminal ceremony — the platform resolves Anthropic credentials `ANTHROPIC_TOKEN` first / `ANTHROPIC_API_KEY` LAST, behind Claude Code's own login, so on the very box Claude Code is installing from, the API key alone loses to CC's consumer OAuth and every fallback call 400s ("extra usage"); `sk-ant-api*` keys pass priority 1 untouched. Then then `fallback_providers: [{provider: anthropic, model: claude-sonnet-5}]` in config.yaml (recommend **claude-sonnet-5** — strong, pay-per-use, costs pennies and only when the primary fails; fallback is turn-scoped so every new message retries the primary first). **Force-test it:** `hermes -m <nonexistent-model> -z "which model family are you?"` — the answer must come from Claude. If they skip, note it in `setup/answers.md` so the digest's by-model table isn't expected to show a fallback row ([docs/architecture.md](docs/architecture.md) Models section). **Gate:** a headless `hermes -z "say ok"` returns, AND a web probe ("search the web for <something current> and quote one source") comes back with a real fetched quote — that proves search + extract end to end. If the fallback was wired: the force-test answered from the fallback model.

## Phase 4 — Knowledge base

You do: `createdb`, apply `sql/schema.sql` **verbatim**, apply generated seeds, install the `mcp-rag` server (templates in `templates/mcp-rag/`), wire it in `config.yaml` `mcp_servers`, restart, verify the `mcp_rag_*` tools exist and a store→search round-trip works. Teach the scoping rule into SOUL: **every store names an explicit identity; unscoped defaults are a misfile.** **Gate:** store + semantic search round-trip under a test identity, then delete the test row.

## Phase 5 — Slack (the daily driver)

User does: create the Slack app **from the shipped manifest template** (`templates/slack-manifest.agentview.json.template` — you substitute `{{AGENT_NAME}}` and hand them the JSON; NEVER the raw `hermes slack manifest` output, which carries all 50 built-in commands including `/update` = an unpinned platform update from chat; curation rationale + cut list in [docs/slack-gateway.md](docs/slack-gateway.md)), enable Socket Mode, install to workspace, create the persona channels, and copy two tokens when you say so. You do: `.env` wiring (via Terminal ceremony), **allowlist their member ID before first message**, channel→persona prompts from Phase 0, gateway as a login service, inline replies, **`slack.free_response_channels` set to the persona channel IDs** (the platform default requires an @-mention in channels — the gate below must pass WITHOUT mentioning the bot), and `stt.local.model: small` in config.yaml (voice transcription — the reference build runs whisper `small` over the platform-default `base` for accuracy; still seconds per note on Apple silicon). **Plus the broadcast-only ops channel:** operator creates `#system-messages` + invites the bot; you pin its ID as `SYSTEM_NOTIFY_CHANNEL` in `.env` (NOT in free_response_channels), install `templates/scripts/system_notify.sh` + the `templates/hooks/system-notify/` gateway hook (→ `~/.hermes/hooks/`), and set `slack.gateway_restart_notification: false` (the hook's startup line replaces the platform's in-session restart pings — note: with the platform notice off, the hook is the ONLY restart announcement). The nightly-script templates already carry their failure pings + the digest headline. **Gate:** a test `system_notify.sh "ping"` lands in the channel, and a gateway restart posts exactly one "⚙️ gateway started" there with #general silent. **Gate:** they message each channel and get in-persona replies; voice note transcribes.

## Phase 6 — Google (two-account model)

The pattern that matters: **their account reads, the agent's account acts.** User does: create the agent's Workspace user (`<agent-slug>@their-domain`), share their calendar to it, create a GCP project with **Internal** OAuth consent, and complete two browser auths when you initiate them. **Batch the console trip:** if traffic-aware ETAs was selected in Phase 0, have them also enable the **Routes API** in this same project while they're in the console — link billing (gotcha #8), create an API key **restricted to Routes API only**, and capture it now via the `.env` ceremony as `GOOGLE_ROUTES_API_KEY` (Phase 8 just wires it). You do: token setup for both lanes — operator token (`gmail.readonly`, `gmail.compose`, `tasks.readonly` — compose exists ONLY for the email-triage drafts lane; drafts-only is enforced in `google_api.py`, which implements no send op on this account), agent token (`gmail.send`, `calendar.readonly`, **`calendar.events`**, `drive.file` — events is what makes REAL calendar invites possible; see the invite lane below) — and per-op routing, by applying the modified scripts in `templates/google-workspace/` (they ARE the two-account routing, the drafts lane, the invite lane, and both signature hooks; don't re-derive any of it).

**Then finish the three lanes those scripts expect** (all documented in [docs/google-workspace.md](docs/google-workspace.md)):
- **Signature files** — create `~/.hermes/operator-signature.txt` + `.html` (the operator's real signature: pull the exact wording/links from one of their own recent sent emails, don't reconstruct it) and `~/.hermes/agent-signature.txt` + `.html` (the agent's identity block: name, "AI Assistant to <operator>", company, "sent on their behalf (they're copied)", operator's direct address). The scripts append these automatically — operator's on drafts they'll send, agent's on any email reaching someone other than the operator. Files live in `HERMES_HOME`, outside the skill dir, so platform updates never touch them.
- **Agent-inbox lane** — the agent lane's `gmail.readonly` lets the agent read its OWN mailbox (`--account send gmail search …`); nobody opens that account by hand, so schedule `templates/scripts/agent_inbox.py.template` hourly in Phase 8 or vendor mail and replies to the agent's outbound go unseen. Report-only: replies still go through the gated send path.
- **Drafts lane** — `gmail draft-create` files a draft in the operator's own Drafts folder; `gmail draft-update --draft-id` revises it **in place** (never a second create — that litters the folder). Nothing on this account can send: that's the whole guarantee.
- **Invite lane** — `gmail`/`calendar create --calendar primary` puts the event on the AGENT's own calendar as organizer, with the operator + guests as `--attendees`, and passes `sendUpdates="all"` so Google actually emails real invitations (without it the event exists and nobody is notified). Cancellations go through `calendar delete`, same flag.

**SOUL rules to write in the same session** (Phase 5's SOUL work, or amend it now — the scripts guarantee the mechanics, SOUL governs the behavior): "draft me an email" composes in chat first, then OFFERS to file it in Drafts (nothing lands in Gmail unasked) and revisions use draft-update · never type a signature (it's automatic — you'd double it), but do identify as an AI in prose when introducing yourself · calendar invites have ONE canonical path (agent's own calendar as organizer; never hand-build an "invitation email" or .ics; report failures instead of falling back to email; non-operator attendees are approval-gated) · who-responded questions read `attendees[].responseStatus` off the organizer copy.

**Operator side-task:** rename the agent's account display name in the Workspace Admin console to include its AI nature (e.g. "Atlas (Alex's AI Assistant)") — that fixes the From-name on every email AND the organizer name on every invite, everywhere. Send policy: **email the operator only; anyone else is approval-gated — and approved external sends/replies auto-CC the operator (enforced in `_ensure_owner_cc`).** **Gate:** read their inbox subject line · send a test email operator-ward · list today's calendar · **create a test draft and update it in place** (one draft in the folder, operator's signature appended once) · **send a test calendar invite to the operator and one outside address** — a REAL invitation with an RSVP chip must arrive, then read back `responseStatus` and cancel it. (Auth gotchas #4/#5. **Invite-delivery gotcha:** if an invite email doesn't arrive somewhere, check the RECIPIENT's per-calendar "Other notifications → New events" setting before suspecting the sender — set to None, that account gets no invitation emails from anyone while the event still lands silently on their calendar.)

## Phase 7 — Skills, default-deny

You do: audit installed skills, then `skills.disabled` in config.yaml down to the working set (the operator's rule to adopt: *not discussed = not enabled, especially third-party connectors*). The bundled keep-set: `google-workspace`, `scrapling` (stealth scraping — the hard-page **fallback** to the built-in web tools wired in Phase 3, not the primary research path; [docs/web-research.md](docs/web-research.md)), `maps` (travel ETAs), `grounded-citations` (bundled since v0.20 — numbered inline citations whose url→[n] mapping comes from retrieval rather than model memory, plus a verbatim-quote fact-check chain; worth enabling for any research-heavy operator), the **document trio `docx`/`pdf`/`xlsx`** (Anthropic-authored, bundled since platform v0.19 — edit client Word docs, merge/split/fill PDF forms, create/read spreadsheets; turns "here's a file, fix it and send it back" into a one-message ask alongside deliverable-export's md→branded-doc lane), plus `telephony` only if Phase 10 is selected — everything else disabled. **The doc trio ships with missing python deps** — install into the platform venv: `pip install --only-binary :all: openpyxl pdf2image pdfplumber pypdf`, then **run `pip check`** — if it reports a Pillow version conflict, re-pin to the platform's required version (`pip install --only-binary :all: "pillow==<required>"`); `brew install poppler` if `pdftoppm` is absent (the pdf skill's image lane needs it). Smoke each: xlsx round-trip via openpyxl + its `recalc.py`; pdf create→`convert_pdf_to_images.py` e2e; docx `office/validate.py --help` from its own dir. **Pre-arm scrapling now, don't leave it lazy:** install the skill from the hub if not already present (`hermes skills install scrapling`), then `pip install "scrapling[all]"` on the platform venv + `scrapling install` (~1GB of Playwright browsers, one-time) + symlink the CLI into the agent's PATH (`ln -s <venv>/bin/scrapling ~/.local/bin/scrapling`, same pattern as the python symlink), then smoke-test all three strategies against a benign page (`extract get` / `fetch` / `stealthy-fetch`) — otherwise the first real fallback stalls mid-research on a browser download. Install the local skill templates (`templates/skills/`): customer-onboarding, contact-onboarding, customer-brief (read-only "where are we with X" account snapshot — its `brief_data.py` needs `{{KB_DB_NAME}}`), deliverable-export, file-to-kb, email-triage (on-demand inbox triage → gated reply drafts into the operator's own Gmail Drafts; needs the `gmail.compose` scope, the `draft-create`/`draft-update` ops, and the operator signature file — all from Phase 6 — plus `{{KB_DB_NAME}}`) — personalized from Phase 0. **Reference config parity** — while in config.yaml, set the eight non-default values the reference build carries: `sessions.auto_prune: true` (session hygiene), `agent.max_turns: 60` (runaway guard, default 90), `session_reset: {mode: both, idle_minutes: 1440, at_hour: 4}` (fresh session every morning — persona/SOUL edits land daily), `approvals.destructive_slash_confirm: false` (gates exist for the AGENT's actions; the operator's own slash commands aren't gated), `approvals.mcp_reload_confirm: false` (MCP reload is routine ops), `agent.disabled_toolsets: [image_gen, tts, computer_use, homeassistant, kanban, project, video, video_gen, a2a, desktop_ui, browser-use, browser-cdp, bfl]` (toolset default-deny — rationale + keep-list in [docs/security.md](docs/security.md); the last five arrived with platform v0.20, the prior three with v0.19 — all harmless to list on older pins; the reminder capability's `cronjob` tool stays enabled on purpose), `skills.write_approval: true` (agent skill writes stage for `/skills approve` — **flip the existing `write_approval: false` line in the `skills:` block; adding the key elsewhere creates a silent YAML duplicate that keeps it off**; smoke-test: have the agent patch a skill, verify it STAGES, view `/skills diff`, reject, confirm the file is untouched), and `skills.creation_nudge_interval: 0` (the background skill-creation nudge otherwise DRAFTS WHOLE SKILLS silently into the approval queue — two field boxes each found ~9 staged writes nobody had ever seen; with the gate on, staged items get one mention at best and no follow-up ever, so pair the gate with: this nudge off, the `pending_watch.py` template scheduled q5m via launchd (pings the ops channel the moment anything lands in `~/.hermes/pending/*/`), and the ops digest's staged-writes section, which renders whenever the queue is non-empty. Known platform trap: `/skills approve` refuses patches to a skill's root files — only `assets/ references/ scripts/ templates/` apply — but staging accepts them, so a staged root-file patch can never be approved; apply those as direct operator edits instead). (The `fallback_providers` chain was already prompted and wired in Phase 3 — just confirm it's still in config.yaml.) **Gate:** skills list shows only the deliberate set; one skill smoke-tested.

## Phase 8 — Daily intelligence (crons)

You do, one at a time (build → hand-test → schedule from `templates/launchd/`): **morning brief** (gather + synthesize + HTML email), **ops digest** (deterministic all-systems health: gateway, every cron, memory-store drift checks, repo push state — *silence is never success*), **meeting prep** (15-min poll, ~2h window; poll, never a calendar webhook — no public endpoints, ever), **email triage** (15-min poll of the operator's inbox — `templates/scripts/email_triage_cron.py.template` reuses the skill's gather; new real-person mail gets a reply draft auto-placed in THEIR Drafts + one home-channel summary; nothing new ⇒ zero tokens, no post — install the `email-triage` skill first, Phase 7), **agent inbox** (hourly, `templates/scripts/agent_inbox.py.template` — new mail in the agent's own mailbox summarized to the home channel; needs the agent lane's `gmail.readonly`, Phase 6). Optional per Phase 0: meeting-notes pipeline (`templates/skills/granola-meeting-reports/` — MCP wiring + TTY-login note in `templates/skills/README.md`), customer-docs sync (`templates/mcp-rag/github_docs_sync.py.template` — install notes in `templates/mcp-rag/README.md`), traffic-aware "leave by" (`GOOGLE_ROUTES_API_KEY` was already captured during the Phase 6 console trip — run that ceremony now only if it was skipped; OSM keyless fallback ships regardless). Space the schedule; avoid colliding minutes. **Gate:** each job's first scheduled run verified in its log + the inbox. **Audio brief (standard — free, fully local):** the morning brief ships with a spoken m4a version (commute-friendly). Set up Kokoro local TTS — `python3.11 -m venv ~/.hermes/kokoro-venv` + `pip install mlx-audio "misaki[en]"`, smoke a sample line, let them pick a voice (54 ship with the model), set `KOKORO_VOICE` in the brief script. The audio path is a soft dependency in code — any TTS failure means `audio=skipped` in the log and no attachment, never a failed brief — so verify the brief's first run logs `audio=yes` ([docs/briefs-and-digest.md](docs/briefs-and-digest.md)).

## Phase 9 — Backups, ledger, self-push (do NOT skip)

You do: nightly **encrypted** backup from `templates/scripts/backup.py.template` (KB dump + sqlite snapshots + config/secrets + **the `~/Library/LaunchAgents` plists** — restore = untar, never rebuild jobs from docs; gpg AES-256, passphrase in keychain) → their Drive via the agent token · `git init` the agent home as a **local-only change ledger** (secrets gitignored — plus churny run-state like `cron/output/` and `cron/ticker_*`, so the reminder job store `cron/jobs.json` stays tracked as change-signal; no remote, ever) · docs repo auto-push from `templates/scripts/git_backup.py.template` to **their own private GitHub repo** (fine-grained single-repo PAT, keychain credential helper, its own 3:10 launchd job — this is Layer 2 in [docs/backups-and-dr.md](docs/backups-and-dr.md); do not skip it because the Drive bundle "already covers" the repo — two layers is the design). **The passphrase gets an off-box copy the same day it's created** — a keychain-only passphrase means box loss destroys every backup. **Gate — prove CONTENTS, not just that it ran** (a field install shipped a bundle that silently omitted the docs repo because a `{{PLACEHOLDER}}` was left unfilled): `grep -rn "{{" ~/.hermes/scripts/` must be empty; decrypt + `tar -t` the first bundle and confirm it lists the KB dump, config, **the docs-repo dir incl. `.git`**, and the CC-memory dir; then a full restore drill into a scratch DB; ledger diff appears in the next digest; the git-backup log shows `pushed OK`.

## Phase 10 — Optional: outbound AI calls

If selected: **Vapi (recommended) + a Telnyx number** — Vapi can't dial out from its own free numbers and sells none, so outbound needs a carrier number imported into Vapi; Telnyx verifies automatically after email confirmation, a US local number is ~$1/mo, and Vapi imports it first-class. Bland.ai is the simpler alternative (one key, sells its own $15/mo numbers, weaker voice, no BYO voice) — same skill, `PHONE_PROVIDER=bland`. Steps, in order ([docs/telephony.md](docs/telephony.md)): Telnyx account → buy a number → API v2 key; Vapi account → $10 credits (auto-reload on — no balance API) → private key; import the number into Vapi (Telnyx credential, then phone-number; save the id as `VAPI_PHONE_NUMBER_ID`); **attach the Telnyx call-control app named "Vapi" to an outbound voice profile whitelisting the destination country — outbound is dead without it**; optional ElevenLabs key registered in Vapi as an `11labs` credential (their own or cloned voice, billed to their ElevenLabs plan, $0 from Vapi — keep the identify-as-AI disclosure); `.env` keys via the Terminal ceremony (`VAPI_API_KEY`, `VAPI_PHONE_NUMBER_ID`, `VAPI_VOICE_PROVIDER=11labs`, `VAPI_VOICE_ID`, `VAPI_MODEL=gpt-4.1`, `TELNYX_API_KEY`, `TELNYX_PHONE_NUMBER`, `ELEVENLABS_API_KEY`, `PHONE_PROVIDER=vapi`); install the official skill and apply `templates/telephony-mods/PATCHES.md` (Cloudflare UA fix, the Vapi payload/defaults/status hunks, rules 7–8) + instantiate the call-reporter template (MP3 + transcript + synthesized breakdown emailed on every terminal state, 3-line Slack summary, never a file prompt); **neuter the number's inbound side — no assistant, a `call.ringing` say-hook that announces a redirect and hangs up** (outbound-only is a security property); per-call approval as a hard skill rule; register the number at freecallerregistry.com (business category: *Informational*). **Gate:** validate the payload without dialing (`POST /assistant` with the same body, read it back, `DELETE`), then a live test call to the operator's own cell — immediate greeting, clean line, three-step closing — with the report email and Slack summary received.

## Phase 10b — Strongly recommended: proposal/contract e-signature (SignWell)

If selected (strongly recommended for anyone sending client proposals or contracts — it's what closes the proposals-contracts channel's loop; declining just means the persona emails finished drafts to the operator to send and collect signatures manually): the operator creates a **SignWell account under their own business email** (Google sign-in is fine — this is THEIR legal-document identity, not the agent's; deliberate exception to the agent-identity rule) and configures dashboard branding (Settings → Branding: logo — coach them to a **300×60 self-backgrounded lockup bar**, icon + wordmark on a dark rounded bar, since a transparent logo fails on either light webmail or dark-mode mobile; company From-name; return email; signature). **Warn them about the tier gate up front:** the logo banner + email signature only persist on the **Business** web plan — the trial shows them, then they vanish on Free/Light (the reference build hit this). The skill's `custom_requester_*` API fields keep the from-name + reply-to on any plan, and the sending address is always `signwelldocs@signwell.com` regardless of tier — they should decide whether the banner is worth the Business price before polishing it. You do: `SIGNWELL_API_KEY` → `.env` via the Terminal ceremony (`read -s`, never through chat), install `templates/skills/proposal-esign/` personalized from Phase 0 (including `references/contract-skeleton.md` — the generic services-agreement skeleton: set `{{BUSINESS_LEGAL_NAME}}`/`{{STATE}}`, confirm the operator's IP stance and payment defaults; recommend a one-time attorney review), add the signature-block tags to the operator's proposal flow (they live IN the template markdown — white-on-white SignWell text tags), instantiate the **`ai.hermes.signwell-poll`** launchd job (every 15 min, `signwell.py poll --notify` — no-op when nothing is pending; posts the signed-doc file-ask to the proposals channel via `hermes send`, @-mentioning the operator; set `SIGNWELL_NOTIFY_CHANNEL` in `.env` to the channel **ID** so channel renames never break it). The ops digest's SignWell row ships in the digest template already, gated on the skill dir — installing the skill lights it up. **The send gate is a hard skill rule** (send-card echo + confirm before every live send). **Gate:** a `test_mode` send to the operator's own email (banner-wrapped preview arrives, fields auto-placed from the text tags), then a live send to themselves — sign it, watch the poller's Slack file-ask appear, file it, and verify the KB doc's links. First 25 API docs/month are free (card on file); PAYG after.

## Phase 11 — Sign-off

Run the full green-board check: next morning's ops digest shows every row OK. Walk the operator through a day-in-the-life (message each channel, file a doc via the gate, check the brief). Hand them `docs/operations.md` as their runbook. Done.

## Gotchas appendix (all hit for real — believe them)

1. **Memory files are tool-owned**: `USER.md`/`MEMORY.md` are `\n§\n`-delimited entry lists with a whole-file char budget. A hand-written doc-style profile silently breaks every memory write with "drift" errors, forever. Seed entries in the tool's format only.
2. **Interactive prompts need a real Terminal**: `security add-generic-password -w` / `read -s` through an agent shell get empty input and create *blank* keychain entries — which then block the real attempt with "already exists" (delete the blank, retry in Terminal).
3. **macOS TCC**: you can't read Downloads/Desktop/Documents. Have the user move files to `~` or the repo.
4. **Google Internal consent** rejects personal Gmail logins ("Access blocked") — auth as the Workspace account, in the right browser profile.
5. **Never hand-copy OAuth URLs from a wrapped terminal line** — invisible line-break junk → `Error 400: invalid_request`. Let commands open the browser.
6. **Cloudflare blocks Python's default user-agent** on some APIs (403/error 1010) — send a custom UA; curl passing while urllib fails is the tell.
7. **Apple's `/usr/bin/python3` fails TLS to some hosts** (OSM among them) — run helper scripts on the venv python, always.
8. **GCP billing accounts have a small linked-projects quota** — "cannot enable billing" usually means unlink idle projects (check the account's 30-day spend is $0 first), not a new billing account.
9. **iPhone unknown-caller silencing** sends new outbound-agent numbers straight to voicemail — have the operator save the number to Contacts before judging a "failed" call.
10. **Platform updates revert local patches** — keep a patch list in the ops doc, re-apply after every update, and check that newly-bundled skills didn't seed themselves enabled.
11. **The agent can't remember its own memory is broken** (the mechanism it would use is the broken one) — which is why the ops digest checks the memory stores from *outside* the agent, daily.

## Repo map

`sql/schema.sql` (apply verbatim) + `sql/seeds.template.sql` (instantiate in Phase 0) · `templates/` (identity generators, launchd, all production scripts, the mcp-rag server, five skills, google-workspace mods, telephony mods — instantiate by replacing `{{PLACEHOLDERS}}` from `setup/answers.md`; registry in `templates/README.md`) · **`docs/` — read [architecture](docs/architecture.md) first (the system map), then the matching deep-dive before each phase** ([index](docs/README.md)): web tools→[web-research](docs/web-research.md) · KB→[knowledge-base](docs/knowledge-base.md) · Slack→[slack-gateway](docs/slack-gateway.md) · Google→[google-workspace](docs/google-workspace.md) · skills→[skills](docs/skills.md) · crons→[briefs-and-digest](docs/briefs-and-digest.md)+[meeting-pipeline](docs/meeting-pipeline.md) · backups→[backups-and-dr](docs/backups-and-dr.md) · phone→[telephony](docs/telephony.md) · e-sign→[proposal-esign](docs/proposal-esign.md) · memory→[memory-system](docs/memory-system.md) · posture→[security](docs/security.md) · hand-off→[operations](docs/operations.md) · `setup/` (your working state — gitignored)