@adaptic/maestro 1.0.1 → 1.1.1

package/README.md

@@ -1,162 +1,175 @@
-# Maestro
+# @adaptic/maestro
 
-**A production-grade framework for deploying autonomous AI agents on dedicated Mac minis.**
+[![npm](https://img.shields.io/npm/v/@adaptic/maestro)](https://www.npmjs.com/package/@adaptic/maestro)
 
-Maestro turns a Mac mini into a perpetually running AI employee. Each agent uses Claude Code as its reasoning engine, integrates with Slack, Gmail, Google Calendar, WhatsApp, SMS, and 25+ MCP-connected services, and operates autonomously around the clock -- observing events, executing tasks, communicating with humans, and maintaining institutional memory across sessions.
+A production-grade npm package for deploying autonomous AI agents on dedicated Mac minis.
 
 ---
 
 ## What is Maestro?
 
-Maestro is an autonomous AI agent operating system. It provides the complete infrastructure to deploy, run, and govern an AI agent that functions as a real member of your team -- with its own identity, responsibilities, communication channels, and institutional memory.
+Maestro is an autonomous AI agent operating system, distributed as an npm package. It provides the complete infrastructure to deploy, run, and govern an AI agent that functions as a real member of your team -- with its own identity, responsibilities, communication channels, and institutional memory.
 
-**What it does:**
-- Runs 24/7 on a dedicated Mac mini, polling Slack, Gmail, and Calendar for events
-- Reasons about incoming information and takes action autonomously
-- Sends messages, drafts documents, follows up on open loops, and coordinates work
-- Maintains persistent memory, decision logs, and strategic context across sessions
-- Spawns parallel sub-agents for complex, multi-track execution
-- Produces branded PDFs, executive briefs, and media assets
+Each agent lives in its own repository. You install `@adaptic/maestro` to scaffold that repo, and the package provides the framework: scripts, agent definitions, workflow templates, governance policies, macOS automation, and Claude Code integration. Your repo holds the agent's identity, configuration, secrets, and runtime data. The framework and the agent's state are cleanly separated, so framework upgrades never overwrite your agent's personality or operational history.
 
-**What it is NOT:**
-- Not a chatbot. The agent operates proactively, not just in response to prompts.
-- Not a demo or prototype. This is production infrastructure for real organisations.
-- Not a generic agent framework. It is opinionated about deployment (Mac mini), reasoning (Claude Code), and governance (audit trails, approval policies, rate limits).
+Maestro uses Claude Code as its reasoning engine and integrates with Slack, Gmail, Google Calendar, WhatsApp, SMS, and 25+ MCP-connected services. Agents run 24/7 on a dedicated Mac mini, polling for events, reasoning about incoming information, executing tasks autonomously, and maintaining persistent memory across sessions. They send messages, draft documents, follow up on open loops, spawn parallel sub-agents for complex work, and produce branded PDFs and media assets.
 
-**Who it is for:**
-Companies deploying AI employees -- autonomous agents that hold real roles, communicate with real people, and execute real work across real tools. If you need a Chief of Staff, a Head of Compliance, a quant researcher, or any other knowledge worker that runs continuously without human prompting, Maestro is the deployment framework.
+The package provides: framework scripts (poller, daemon, triggers, hooks, PDF and media generation), 31 agent definitions with mandates and prompts, workflow templates across daily/weekly/monthly/quarterly cadences, operational skills as a Claude Code plugin, slash commands for agent setup, macOS launchd configuration, and comprehensive documentation and runbooks.
 
 ---
 
-## Architecture
+## Quick Start
 
+```bash
+npx @adaptic/maestro create jacob-ai
+cd jacob-ai
+sudo npm run configure-macos    # Auto-login, disable sleep, Parsec, Slack CDP
+npm run init-agent              # Create directories, install launchd agents, configure Claude Code
+claude "/init-maestro"          # Interactive identity and services wizard
 ```
-┌─────────────────────────────────────────────────────┐
-│                   Your Agent                        │
-│              Executive Cortex (Tier 0)              │
-├──────────┬──────────┬──────────┬──────────┬─────────┤
-│ Briefing │ Strategic│ Domain   │ Comms    │ Task    │
-│          │ Planning │ Ops      │ Gov.     │ Exec.   │
-│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
-├──────────┴──────────┴──────────┴──────────┴─────────┤
-│              20+ Specialist Agents (Tier 2)         │
-│  Research · Product · Engineering · Legal · Ops ·   │
-│  Finance · Partnerships · Hiring · Market Intel ·   │
-│  Board Prep · Compliance · Writing · ...            │
-├─────────────────────────────────────────────────────┤
-│              Desktop Operations (Tier 3)            │
-│  Slack · Gmail · WhatsApp · Browser · Calendar      │
-├─────────────────────────────────────────────────────┤
-│              Governance & Memory (Tier 4)           │
-│  Decision Log · Risk Register · Knowledge Base      │
-└─────────────────────────────────────────────────────┘
-```
-
-**Tier 0 -- Executive Cortex:** The agent's core identity and reasoning loop. Reads dashboards, processes inbound events, makes decisions, and orchestrates lower tiers.
 
-**Tier 1 -- Domain Controllers:** Specialised reasoning modules for briefing, strategic planning, domain operations, communications governance, and task execution.
+### Prerequisites
 
-**Tier 2 -- Specialist Agents:** 20+ sub-agents that can be spawned in parallel for focused work -- research, document drafting, code review, legal analysis, hiring pipelines, and more.
+| Dependency        | Install                                                    | Purpose                        |
+|-------------------|------------------------------------------------------------|--------------------------------|
+| Node.js 20+      | `brew install node`                                        | Runtime for poller, triggers   |
+| Claude CLI        | `npm install -g @anthropic-ai/claude-code`                 | Agent reasoning engine         |
+| jq                | `brew install jq`                                          | Used by hook scripts           |
+| Pandoc + MacTeX   | `brew install pandoc && brew install --cask mactex-no-gui` | PDF generation (optional)      |
+| Anthropic API key | Set `ANTHROPIC_API_KEY` env var                            | Required for Claude CLI        |
 
-**Tier 3 -- Desktop Operations:** Integrations with external services via MCP servers, APIs, and local tooling. Slack, Gmail, Google Calendar, WhatsApp, SMS, browser automation.
+---
 
-**Tier 4 -- Governance & Memory:** Persistent state layer. Decision logs, risk registers, knowledge bases, interaction history, queue management, and audit trails.
+## What the Package Provides
+
+When you run `npx @adaptic/maestro create <name>`, the following framework files are copied into your new agent repo:
+
+| Directory                | Description                                                                 |
+|--------------------------|-----------------------------------------------------------------------------|
+| `scripts/`               | Poller, daemon, trigger runner, hooks, PDF generation, media generation, setup scripts, healthcheck, emergency stop |
+| `agents/`                | 31 specialist agent definitions with mandates, responsibilities, and prompts |
+| `workflows/`             | Workflow templates: continuous, daily, weekly, monthly, quarterly cadences   |
+| `policies/`              | Action classification, information barriers, prompt injection defence        |
+| `plugins/maestro-skills/`| Operational skills plugin for Claude Code (memory, comms, queue management)  |
+| `.claude/commands/`      | Slash commands including `/init-maestro` for identity setup                  |
+| `.claude/settings.json`  | Project-level Claude Code hooks and permissions                              |
+| `schedules/`             | Trigger prompt templates for launchd-scheduled sessions                      |
+| `teams/`                 | Agent team compositions and coordination definitions                         |
+| `docs/`                  | Architecture docs, governance policies, runbooks, workflow documentation      |
+| `public/assets/`         | Brand SVG assets (icon and logo, dark and light variants)                    |
+| `desktop-control/`       | macOS app control profiles for desktop automation                            |
+| `scaffold/`              | Template files for agent-specific config (CLAUDE.md, config/agent.ts)        |
 
 ---
 
-## Getting Started
+## What Lives in the Agent Repo (Not in the Package)
 
-### Prerequisites
+These files are specific to your agent and are never overwritten by framework upgrades:
 
-| Dependency          | Install                                                    | Purpose                          |
-|---------------------|------------------------------------------------------------|----------------------------------|
-| Node.js 25+        | `brew install node`                                        | Runtime for poller, triggers     |
-| Claude CLI          | `npm install -g @anthropic-ai/claude-code`                 | Agent reasoning engine           |
-| jq                  | `brew install jq`                                          | Used by hook scripts             |
-| Pandoc + MacTeX     | `brew install pandoc && brew install --cask mactex-no-gui` | PDF generation (optional)        |
-| Anthropic API key   | Set `ANTHROPIC_API_KEY` env var                            | Required for Claude CLI          |
+| File / Directory         | Purpose                                                          |
+|--------------------------|------------------------------------------------------------------|
+| `CLAUDE.md`              | The agent's behavioural charter -- identity, principles, communication rules, operating modes |
+| `config/agent.ts`        | Structured identity data: name, title, email, archetype, schedule, communication style |
+| `config/contacts.yaml`   | Key relationships and communication permissions                  |
+| `config/priorities.yaml` | Strategic focus areas and milestones                             |
+| `config/environment.yaml`| System-level settings: paths, scheduling, secrets references     |
+| `.env`                   | API keys and credentials (never committed to git)                |
+| `knowledge/`             | Sources, syntheses, entities, decisions, and memory              |
+| `memory/`                | Interaction history, user and channel profiles, precedents       |
+| `state/`                 | Queues, inbox, dashboards, polling cursors, locks                |
+| `logs/`                  | Audit trails, polling logs, workflow logs, session logs           |
+| `outputs/`               | Briefs, memos, drafts, research, and generated deliverables      |
 
-### Step 1: Clone and Install
+---
 
-```bash
-git clone git@github.com:your-org/maestro.git ~/your-agent
-cd ~/your-agent
-npm run init-agent
-```
+## CLI Reference
 
-The `init-agent` script handles all machine setup:
-- Installs npm dependencies
-- Creates all required `state/`, `logs/`, `memory/` directories
-- Installs global Claude Code settings with hook configuration
-- Generates and loads 12 macOS launchd agents (poller, inbox processor, backlog executor, meeting prep, weekly triggers, etc.)
-- Creates a `.env` template for API keys
-- Runs a health check
+### `npx @adaptic/maestro create <name>`
 
-### Step 2: Configure Your Agent
+Scaffolds a new agent repository. This command:
 
-```bash
-claude "/init-maestro"
-```
+1. Creates the target directory
+2. Copies all framework files (scripts, agents, workflows, policies, plugins, docs)
+3. Copies scaffold templates (CLAUDE.md and config/agent.ts stubs)
+4. Copies `.claude/` directory (settings and commands)
+5. Creates 30+ agent-specific directories (config, knowledge, memory, state, logs, outputs)
+6. Generates a `package.json` with all required scripts and dependencies
+7. Copies `.env.example` and `.gitignore`
+8. Initializes a git repository
+9. Runs `npm install`
 
-This launches an interactive Claude Code session that rewrites the repository for your agent's identity. You will be asked for:
+### `npx @adaptic/maestro upgrade`
 
-| Field                   | Example                                |
-|-------------------------|----------------------------------------|
-| Agent name              | "Jordan"                               |
-| Agent surname           | "Blake"                                |
-| Agent role/title        | "Chief of Staff"                       |
-| Directory name          | "jordan-ai"                            |
-| Mac mini hostname       | "jordan-mini"                          |
-| Key responsibilities    | 2-5 bullet points                      |
-| Reporting line          | "CEO" or specific person               |
-| Communication style     | Formal/casual, proactive/reactive      |
+Updates framework files in an existing agent repo. This command copies the latest versions of:
 
-The wizard updates `CLAUDE.md` (identity and principles), all script variables, launchd plist labels and paths, `package.json`, config files, trigger prompts, and agent definitions.
+- `scripts/` -- poller, daemon, hooks, PDF generation, setup scripts
+- `policies/` -- action classification, information barriers, prompt injection defence
+- `docs/` -- architecture, governance, runbooks
+- `public/assets/` -- brand assets
+- `.claude/commands/` -- slash commands
+- `plugins/maestro-skills/` -- operational skills
 
-See `docs/guides/agent-persona-setup.md` for the detailed persona configuration guide.
+Agent-specific files (`config/`, `CLAUDE.md`, `knowledge/`, `memory/`, `state/`, `logs/`) are never touched.
 
-### Step 3: Set Up Integrations
+### `npx @adaptic/maestro doctor`
 
-Copy `.env.example` to `.env` and fill in your API keys and tokens:
+Verifies the agent installation. Checks for:
+
+- Essential files: `config/agent.ts`, `CLAUDE.md`, `.claude/settings.json`, `package.json`, setup scripts
+- Environment variables: `ANTHROPIC_API_KEY` (required), `SLACK_USER_TOKEN`, `GMAIL_APP_PASSWORD` (optional)
+- `node_modules` installation
+- Claude CLI availability
+
+---
+
+## Updating the Framework
 
 ```bash
-cp .env.example .env
+npm update @adaptic/maestro   # Get the latest version from npm
+npm run upgrade               # Copy updated framework files into your repo
+git diff                      # Review what changed
+git add -A && git commit -m "Upgrade maestro framework"
 ```
 
-At minimum, configure Slack and Gmail credentials. See the Required Services table below for the full list.
+The `upgrade` command only updates framework infrastructure: scripts, policies, documentation, brand assets, commands, and plugins. It never modifies your agent's identity (`CLAUDE.md`, `config/agent.ts`), configuration (`config/*.yaml`), secrets (`.env`), or runtime data (`knowledge/`, `memory/`, `state/`, `logs/`, `outputs/`). Your agent's personality, relationships, and operational history remain intact.
 
-### Verifying the Setup
+---
 
-```bash
-# Check all launchd agents are loaded
-launchctl list | grep adaptic
+## The /init-maestro Wizard
 
-# Run health check
-npm run healthcheck
+After scaffolding, run `claude "/init-maestro"` to configure your agent's identity. The wizard runs in five phases:
 
-# Check poller is writing logs
-tail -f logs/polling/$(date +%Y-%m-%d)-poller.jsonl
-```
+1. **Identity gathering** -- Prompts for agent name, surname, title, archetype, email, phone, Mac mini hostname, principal (reporting line), responsibilities, communication style, and operating principles.
+
+2. **Parallel file rewriting** -- Rewrites `config/agent.ts` with structured identity data, generates `CLAUDE.md` with the full behavioural charter, updates `config/environment.yaml` with paths and schedule, and adapts `schedules/triggers/*.md` with the new identity.
+
+3. **macOS configuration** -- Updates launchd plist labels and paths, sets `package.json` name and description, and configures script variables.
+
+4. **Third-party services** -- Walks through Slack, Gmail, Calendar, and optional integrations, writing credentials to `.env`.
+
+5. **Verification** -- Runs a health check to confirm all components are correctly configured.
+
+See [docs/guides/agent-persona-setup.md](docs/guides/agent-persona-setup.md) for the full persona configuration guide, including archetype defaults, Control Tower selection, contact classification, and manual fine-tuning.
 
 ---
 
 ## Required Services and API Keys
 
-| Service            | Purpose                          | Required?   | Signup URL                                  | Tier / Pricing                          |
-|--------------------|----------------------------------|-------------|---------------------------------------------|-----------------------------------------|
-| Anthropic API      | Primary reasoning engine (Claude)| Required    | https://console.anthropic.com               | Pay-per-token or Max subscription       |
-| Slack              | Team communication               | Required    | https://api.slack.com/apps                  | Free (workspace needed)                 |
-| Gmail              | Email monitoring and sending     | Required    | https://myaccount.google.com/apppasswords   | Google Workspace or free Gmail          |
-| Google Calendar    | Meeting and schedule awareness   | Recommended | Via Google Workspace                        | Same account as Gmail                   |
-| Google Drive       | Document sharing                 | Recommended | Via Google Workspace                        | Same account as Gmail                   |
-| OpenAI             | Supplemental model access        | Optional    | https://platform.openai.com                | Pay-per-token                           |
-| Google Gemini      | Media generation (images, video) | Optional    | https://aistudio.google.com                | Free tier available                     |
-| Twilio             | SMS, voice, and WhatsApp         | Optional    | https://www.twilio.com                     | Pay-as-you-go (~$1/mo + usage)          |
-| Deepgram           | Speech-to-text transcription     | Optional    | https://deepgram.com                       | Free tier (200 hrs/yr)                  |
-| ElevenLabs         | Text-to-speech voice synthesis   | Optional    | https://elevenlabs.io                      | Free tier available                     |
-| Greptile           | Codebase search and indexing     | Optional    | https://greptile.com                       | Free tier available                     |
-
-Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more. See your Claude Code MCP configuration for the full list.
+| Service          | Purpose                            | Required?   | Signup URL                                | Tier / Pricing                    |
+|------------------|------------------------------------|-------------|-------------------------------------------|-----------------------------------|
+| Anthropic API    | Primary reasoning engine (Claude)  | Required    | https://console.anthropic.com             | Pay-per-token or Max subscription |
+| Slack            | Team communication                 | Required    | https://api.slack.com/apps                | Free (workspace needed)           |
+| Gmail            | Email monitoring and sending       | Required    | https://myaccount.google.com/apppasswords | Google Workspace or free Gmail    |
+| Google Calendar  | Meeting and schedule awareness     | Recommended | Via Google Workspace                      | Same account as Gmail             |
+| Google Drive     | Document sharing                   | Recommended | Via Google Workspace                      | Same account as Gmail             |
+| OpenAI           | Supplemental model access          | Optional    | https://platform.openai.com              | Pay-per-token                     |
+| Google Gemini    | Media generation (images, video)   | Optional    | https://aistudio.google.com              | Free tier available               |
+| Twilio           | SMS, voice, and WhatsApp           | Optional    | https://www.twilio.com                   | Pay-as-you-go (~$1/mo + usage)    |
+| Deepgram         | Speech-to-text transcription       | Optional    | https://deepgram.com                     | Free tier (200 hrs/yr)            |
+| ElevenLabs       | Text-to-speech voice synthesis     | Optional    | https://elevenlabs.io                    | Free tier available               |
+| Greptile         | Codebase search and indexing       | Optional    | https://greptile.com                     | Free tier available               |
+
+Additional services are available via MCP servers and can be configured separately. Supported integrations include Airtable, Linear, Figma, Notion, Jira, Calendly, and more.
 
 ### Environment Variables
 
@@ -192,253 +205,132 @@ GEMINI_API_KEY=...
 
 ---
 
-## Agent Configuration
-
-The central identity file is `config/agent.ts` (or the `CLAUDE.md` identity section, depending on your setup). This defines:
-
-- **Agent name, role, and title** -- who the agent is
-- **Operating principles** -- how the agent makes decisions
-- **Communication rules** -- voice modes, autonomy levels, escalation triggers
-- **Domain context** -- what the agent knows about the organisation
-- **Reporting line** -- who the agent escalates to
-
-Run `claude "/init-maestro"` for interactive setup, or see `docs/guides/agent-persona-setup.md` for manual configuration.
-
----
-
-## Directory Structure
+## Architecture
 
 ```
-maestro/
-├── README.md                    # This file
-├── CLAUDE.md                    # Claude Code operating instructions (identity + behaviour)
-├── .claude/
-│   ├── settings.json            # Project-level Claude Code hooks and permissions
-│   └── commands/
-│       └── init-agent.md        # /init-maestro command for identity setup
-├── docs/
-│   ├── architecture/            # System and agent architecture
-│   ├── governance/              # Approval models, communications policy, safety
-│   ├── runbooks/                # Mac mini bootstrap, perpetual ops, recovery
-│   ├── workflows/               # Cadence documentation
-│   └── prompts/                 # Output templates (briefs, memos, decisions)
-├── agents/                      # 30+ agent definitions with mandates and prompts
-├── teams/                       # Agent team compositions and responsibilities
-├── workflows/
-│   ├── continuous/              # Always-on inbound monitoring loop
-│   ├── daily/                   # Morning brief, evening wrap, comms triage
-│   ├── weekly/                  # Strategic memo, pipeline review
-│   ├── monthly/                 # Board readiness, risk refresh
-│   └── quarterly/               # Scenario analysis, board pack
-├── schedules/
-│   └── triggers/                # Trigger prompts for launchd-scheduled sessions
-├── scripts/
-│   ├── setup/
-│   │   └── init-agent.sh        # One-line machine setup script
-│   ├── local-triggers/
-│   │   ├── run-trigger.sh       # Trigger runner (invoked by launchd)
-│   │   ├── install-all.sh       # Install launchd plists
-│   │   └── plists/              # macOS launchd plist templates
-│   ├── daemon/                  # Main agent daemon
-│   ├── poller/                  # Event polling (Slack, Gmail, Calendar)
-│   ├── hooks/                   # Claude Code hook scripts
-│   ├── pdf-generation/          # Branded PDF generation (Pandoc + XeLaTeX)
-│   └── media-generation/        # AI illustration/video generation
-├── knowledge/                   # Sources, syntheses, memory, entities, decisions
-├── config/                      # Environment, priorities, contacts, repos, brand
-├── policies/                    # Action classification, approval rules
-├── state/                       # Queues, inbox, dashboards, polling cursors
-├── outputs/                     # Briefs, memos, drafts, research
-├── memory/                      # Interaction history, profiles, precedents
-└── logs/                        # Operational logs (audit, polling, workflows)
+┌─────────────────────────────────────────────────────┐
+│                   Your Agent                        │
+│              Executive Cortex (Tier 0)              │
+├──────────┬──────────┬──────────┬──────────┬─────────┤
+│ Briefing │ Strategic│ Domain   │ Comms    │ Task    │
+│          │ Planning │ Ops      │ Gov.     │ Exec.   │
+│ (Tier 1) │ (Tier 1) │ (Tier 1) │ (Tier 1) │(Tier 1)│
+├──────────┴──────────┴──────────┴──────────┴─────────┤
+│              20+ Specialist Agents (Tier 2)         │
+│  Research · Product · Engineering · Legal · Ops ·   │
+│  Finance · Partnerships · Hiring · Market Intel ·   │
+│  Board Prep · Compliance · Writing · ...            │
+├─────────────────────────────────────────────────────┤
+│              Desktop Operations (Tier 3)            │
+│  Slack · Gmail · WhatsApp · Browser · Calendar      │
+├─────────────────────────────────────────────────────┤
+│              Governance & Memory (Tier 4)           │
+│  Decision Log · Risk Register · Knowledge Base      │
+└─────────────────────────────────────────────────────┘
 ```
 
----
-
-## Operating Modes
+**Tier 0 -- Executive Cortex:** The agent's core identity and reasoning loop. Reads dashboards, processes inbound events, makes decisions, and orchestrates lower tiers.
 
-Maestro agents operate in three concurrent modes at all times.
+**Tier 1 -- Domain Controllers:** Specialised reasoning modules for briefing, strategic planning, domain operations, communications governance, and task execution.
 
-### Mode 1: Reactive -- Respond to Events
+**Tier 2 -- Specialist Agents:** 20+ sub-agents that can be spawned in parallel for focused work -- research, document drafting, code review, legal analysis, hiring pipelines, and more.
 
-The nervous system. Always on, always listening.
+**Tier 3 -- Desktop Operations:** Integrations with external services via MCP servers, APIs, and local tooling. Slack, Gmail, Google Calendar, WhatsApp, SMS, browser automation.
 
-- A lightweight poller checks Slack, Gmail, and Calendar for new events every 60 seconds
-- An inbox processor classifies and routes incoming items every 5 minutes
-- Priority events (CEO DMs, urgent tags, direct mentions) trigger immediate processing sessions
-- All inbound events land in `state/inbox/` as structured YAML before being routed to the appropriate queue
+**Tier 4 -- Governance & Memory:** Persistent state layer. Decision logs, risk registers, knowledge bases, interaction history, queue management, and audit trails.
 
-### Mode 2: Scheduled -- Run Cadence Workflows
+### Operating Modes
 
-The heartbeat. Ensures nothing falls through the cracks.
+All Maestro agents operate in three concurrent modes:
 
-- **Daily:** Morning brief, midday sweep, evening wrap, communications triage
-- **Weekly:** Strategic memo, pipeline review, hiring review, engineering health check, execution review
-- **Monthly:** Board readiness, risk register refresh, financial integration
-- **Quarterly:** Self-assessment, scenario analysis, board pack generation
+**Mode 1: Reactive** -- The nervous system. A lightweight poller checks Slack, Gmail, and Calendar every 60 seconds. An inbox processor classifies and routes incoming items every 5 minutes. Priority events trigger immediate processing.
 
-All scheduled workflows are defined in `workflows/` and triggered via macOS launchd agents.
+**Mode 2: Scheduled** -- The heartbeat. Daily morning brief, midday sweep, evening wrap. Weekly strategic memo, pipeline review, execution review. Monthly board readiness, risk refresh. Quarterly self-assessment and board pack. All triggered via macOS launchd.
 
-### Mode 3: Proactive -- Execute the Backlog
+**Mode 3: Proactive** -- The engine. The backlog executor runs every 10 minutes, reads all queues, selects the top actionable items by priority, and spawns parallel agents to execute them. Items move continuously from `open` to `in_progress` to `resolved` to `closed`.
 
-The engine. This is where the real work gets done.
+---
 
-- The backlog executor runs every 10 minutes via launchd
-- It reads all operational queues, selects the top 3-5 actionable items by priority
-- It spawns parallel background agents to execute each item independently
-- Agents do the actual work: draft documents, chase people, research topics, build deliverables
-- Results are reviewed, queues are updated, and the next batch is picked up
-- Items continuously move from `open` to `in_progress` to `resolved` to `closed`
+## Auto-Publishing
 
-The goal is continuous forward motion. Items should not sit in queues -- they should be getting done.
+Pushes to the `main` branch of the Maestro repository automatically publish to npm via GitHub Actions. Version bumps are handled automatically -- patch versions for fixes and minor changes, minor versions for new features. You do not need to manually publish or manage versions. When a new version is available, agent repos pick it up with `npm update @adaptic/maestro`.
 
 ---
 
-## Communication Governance
-
-All Maestro agents follow a structured governance framework for outbound communications.
+## Agent Roster (Example)
 
-| Action Level                     | Policy                                              |
-|----------------------------------|-----------------------------------------------------|
-| Observe                          | Always permitted                                    |
-| Draft                            | Always permitted                                    |
-| Recommend                        | Always permitted                                    |
-| Send (internal, routine)         | Pre-approved categories with full logging            |
-| Send (external)                  | Requires explicit approval from the agent's manager  |
-| Send (investor/regulator/board)  | Requires approval + confirmation                     |
+Maestro supports deploying any number of agents, each on its own Mac mini with a distinct role and domain focus:
 
-Additional safeguards:
+| Agent   | Role                        | Archetype            | Repo              |
+|---------|-----------------------------|----------------------|--------------------|
+| Sophie  | Chief of Staff              | executive-operator   | adapticai/sophie-ai |
+| Jacob   | Chief AI Scientist          | technical-leader     | adapticai/jacob-ai  |
+| Isla    | Head of Engineering         | technical-leader     | adapticai/isla-ai   |
+| Nadia   | Head of Compliance          | compliance-officer   | adapticai/nadia-ai  |
+| Luca    | Head of Product             | product-leader       | adapticai/luca-ai   |
+| Amara   | Head of Investor Relations  | commercial-leader    | adapticai/amara-ai  |
+| Kai     | Head of Fund Operations     | operations-leader    | adapticai/kai-ai    |
+| Rowan   | Head of Quant Engineering   | technical-leader     | adapticai/rowan-ai  |
 
-- **Pre-send audit hook** gates all outbound Slack and Gmail communications
-- **Rate limits** prevent runaway sending (configurable per channel)
-- **Duplicate detection** prevents the agent from replying to the same thread multiple times
-- **Information barriers** prevent confidential information from leaking across recipient boundaries
-- **Prompt injection defence** (5-layer) protects the agent from adversarial inbound messages
-
-Communication governance policies are defined in `policies/action-classification.yaml`.
+Each agent gets its own identity, operating principles, communication style, contact graph, priority stack, and specialist sub-agents -- all configured through the `/init-maestro` wizard.
 
 ---
 
-## Deploying Multiple Agents
-
-Maestro is designed to be forked for each AI agent in your organisation. Each agent runs on its own dedicated Mac mini with its own identity, domain focus, and operational context.
+## Tool Library (`lib/`)
 
-### Example: Multi-Agent Deployment
+Maestro provides a comprehensive library of 27+ reusable tools that agents can use during voice conversations, huddles, and autonomous operations. Tools are scoped by access level and executed via the Claude API `tool_use` protocol.
 
-| Agent   | Role                        | Mac Mini      | Repo            |
-|---------|-----------------------------|---------------|-----------------|
-| Jordan  | Chief of Staff              | jordan-mini   | jordan-ai       |
-| Alex    | Chief AI Scientist          | alex-mini     | alex-ai         |
-| Morgan  | Head of Quant Engineering   | morgan-mini   | morgan-ai       |
-| Riley   | Head of Engineering         | riley-mini    | riley-ai        |
-| Sam     | Head of Compliance          | sam-mini      | sam-ai          |
-| Taylor  | Head of Product             | taylor-mini   | taylor-ai       |
-| Casey   | Head of Investor Relations  | casey-mini    | casey-ai        |
-| Robin   | Head of Fund Operations     | robin-mini    | robin-ai        |
+### Categories
 
-### Setup: New Agent in 3 Steps
-
-**Step 1: Fork, clone, rename**
-
-```bash
-git clone git@github.com:your-org/maestro.git ~/alex-ai
-cd ~/alex-ai
-```
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Communication** | `slack_send`, `draft_email`, `whatsapp_send`, `sms_send` | Send messages across all channels |
+| **Search / RAG** | `search_email`, `search_calendar`, `search_files`, `search_meetings`, `search_slack`, `search_web`, `search_documents` | Real-time lookup via MCP-backed queries |
+| **Knowledge** | `search_decisions`, `lookup_person`, `search_regulatory`, `search_strategy`, `search_precedents` | Institutional memory and governance |
+| **Operations** | `queue_update`, `create_action_item`, `schedule_meeting`, `create_reminder` | Operational queue and calendar management |
+| **Analysis** | `search_financial`, `search_pipeline`, `search_engineering`, `search_hiring`, `search_risk` | Cross-functional health and pipeline data |
+| **Documents** | `generate_memo`, `generate_report` | Branded document generation |
 
-**Step 2: Run machine setup**
+### Usage
 
-```bash
-npm run init-agent
-```
+```js
+import { getToolsForAccessLevel, executeAction } from "@adaptic/maestro";
 
-**Step 3: Configure the agent identity**
+// Get tools for a Claude API call
+const tools = getToolsForAccessLevel("ceo"); // 27 tools
+const tools = getToolsForAccessLevel("leadership"); // 19 tools (no WhatsApp/SMS/memo)
+const tools = getToolsForAccessLevel("default"); // 17 tools (search/lookup only)
 
-```bash
-claude "/init-maestro"
+// Execute a tool call from Claude's response
+const result = await executeAction("search_email", { query: "DFSA update" }, callerInfo, sessionId);
 ```
 
-The `/init-maestro` wizard handles the full identity transformation:
+### RAG Architecture
 
-| What changes                         | Example                                          |
-|--------------------------------------|--------------------------------------------------|
-| `CLAUDE.md` identity and principles  | "Alex Park, Chief AI Scientist..."               |
-| Variable names in scripts            | `AGENT_DIR` updated to new paths                 |
-| Launchd plist labels                 | `ai.adaptic.agent-*` labels updated              |
-| `package.json` name and description  | `"alex-ai"`, `"Autonomous AI scientist for..."` |
-| `config/` files                      | Priorities, contacts, environment paths           |
-| `schedules/triggers/`               | Trigger prompts reference the new identity        |
-| `agents/` definitions               | Domain-specific agents adapted for the role       |
+Lookup tools use `claude --print --model haiku` under the hood, which leverages the agent's Max subscription and all configured MCP servers (Gmail, Calendar, Slack, filesystem, Granola, etc.). This means every agent automatically gets search capabilities across all connected services without additional API costs.
 
-### What Stays the Same
+### Agent-Specific Tools
 
-The following infrastructure is shared across all agents and does not need per-agent changes:
-
-- **Poller architecture** (`scripts/poller/`) -- Slack, Gmail, Calendar polling
-- **Trigger runner** (`scripts/local-triggers/run-trigger.sh`) -- launchd-to-Claude bridge
-- **Hook scripts** -- Pre/post tool hooks, session lifecycle
-- **Brand assets** (`public/assets/`) -- Organisation-wide branding
-- **PDF generation** (`scripts/pdf-generation/`) -- document templates
-- **Governance framework** (`policies/`, `docs/governance/`) -- same rules, different agent
-
----
+During `/init-maestro`, Sub-agent 8 generates role-specific tools based on the agent's archetype and responsibilities. These extend the base set — e.g., a compliance officer gets `licence_gap_check` and `regulatory_submission_status`, while an engineering leader gets `code_review_trigger` and `deployment_status`.
 
-## Commands Reference
+## Global vs Agent-Specific Features
 
-### Machine Setup
+When building new capabilities, decide where they belong:
 
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run init-agent`            | Full machine setup (deps, dirs, launchd, env)      |
-| `claude "/init-maestro"`        | Interactive agent identity wizard                  |
+| Push to `~/maestro` (global) | Keep agent-local |
+|-----|-----|
+| Role-agnostic tools any agent could use | Identity-specific configurations |
+| Communication primitives | Domain tools only this role needs |
+| Search/RAG capabilities | Custom MCP integrations for one agent |
+| Operational patterns | Hardcoded contacts, channels, API keys |
+| Infrastructure (audio, CDP, polling) | Agent-specific prompts and style |
+| Document generation templates | Workflow overrides |
+| Claude Code skills/plugins for dev experience | |
+| Governance patterns | |
 
-### Daemon Management
+**Decision rule:** Would another agent at Adaptic ever need this? **YES** → `~/maestro`. **NO** → agent repo only.
 
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run daemon`                | Run the main agent daemon (foreground)             |
-| `npm run daemon:start`          | Start daemon via launchd (background)              |
-| `npm run daemon:stop`           | Stop the launchd daemon                            |
-| `npm run daemon:status`         | Check daemon status and recent logs                |
-
-### Operations
-
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run healthcheck`           | Run system health check                            |
-| `npm run emergency-stop`        | Halt all autonomous operations immediately         |
-| `npm run resume`                | Resume operations after emergency stop             |
-
-### Slack Events
-
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run slack:events:start`    | Start the Slack events server                      |
-| `npm run slack:events:stop`     | Stop the Slack events server                       |
-| `npm run slack:events:status`   | Check Slack events server status                   |
-
-### PDF Generation
-
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run pdf:memo -- --input <file>`        | Generate internal memo PDF              |
-| `npm run pdf:board-pack -- --input <file>`  | Generate board pack with cover and TOC  |
-| `npm run pdf:letter -- --input <file>`      | Generate corporate correspondence PDF   |
-| `npm run pdf:investor -- --input <file>`    | Generate investor communication PDF     |
-
-### Media Generation
-
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run gen:illustration -- <slug>`  | Generate a single illustration via Gemini    |
-| `npm run gen:video -- <slug>`         | Generate a single video via Veo              |
-| `npm run gen:all-missing`             | Batch generate all missing illustrations     |
-| `npm run gen:list`                    | List available prompt specs                  |
-
-### Testing
-
-| Command                         | Purpose                                            |
-|---------------------------------|----------------------------------------------------|
-| `npm run test:daemon`           | Run daemon unit and integration tests              |
+After pushing to maestro: bump version → commit → push. Agent repos update via `npm update @adaptic/maestro`.
 
 ---
 
@@ -447,45 +339,29 @@ The following infrastructure is shared across all agents and does not need per-a
 - **Secrets management** -- All credentials via environment variables, never committed to the repository
 - **Full audit trail** -- Every action, communication, and decision is logged to `logs/`
 - **Approval policies** -- Outbound communications require appropriate approval levels based on risk classification
-- **Emergency stop** -- A single command halts all autonomous operations immediately
+- **Emergency stop** -- `npm run emergency-stop` halts all autonomous operations immediately
 - **Default-deny** -- Unclassified actions are blocked; only explicitly permitted actions proceed
 - **Rate limiting** -- Configurable limits on all communication channels (default: 3,000 sends/hour, 20,000/day)
 - **Prompt injection defence** -- 5-layer defence system: identity lock, sender privilege model, message classification, content isolation, anomaly detection
 - **Information barriers** -- Dynamic disclosure assessment prevents confidential information from crossing recipient boundaries
 - **Session logging** -- Every agent session is logged with start time, actions taken, and outcomes
+- **Communication governance** -- Pre-send audit hook gates all outbound Slack and Gmail; duplicate detection prevents replying to the same thread multiple times
 
 Security policies are defined in `policies/` and `docs/governance/`.
 
 ---
 
-## Troubleshooting
-
-| Symptom                                       | Cause                                        | Fix                                                    |
-|-----------------------------------------------|----------------------------------------------|--------------------------------------------------------|
-| `cb.apply is not a function` on every hook    | Legacy standalone `npx` package installed    | `npm uninstall -g npx`                                 |
-| `MODULE_NOT_FOUND` in poller logs             | Launchd plists point to wrong directory      | Re-run `npm run init-agent`                            |
-| Hook errors on every tool call                | Hook package not correctly installed         | Check `~/.claude/settings.json` uses correct package   |
-| Launchd agent exit code 78                    | Missing directories or config files          | Run `npm run init-agent` to recreate                   |
-| Poller rate limited                           | Too many Slack API calls                     | Increase `StartInterval` in the poller plist           |
-| Agent not responding to Slack messages        | Bot token missing or incorrect               | Verify `SLACK_BOT_TOKEN` in `.env`                     |
-| Gmail polling returns no results              | OAuth tokens expired                         | Refresh Gmail credentials and update `.env`            |
-| Daemon exits immediately on start             | Missing `ANTHROPIC_API_KEY`                  | Ensure the key is set in `.env` or shell environment   |
-| PDF generation fails                          | Pandoc or MacTeX not installed               | `brew install pandoc && brew install --cask mactex-no-gui` |
-| Launchd agents not visible                    | Plists not loaded                            | Run `scripts/local-triggers/install-all.sh`            |
-| Memory/state files corrupted                  | Concurrent write conflict                    | Check session locks; restart daemon                    |
-
----
-
-## Key Documents
+## Key Documentation
 
-- [System Architecture](docs/architecture/system-architecture.md)
-- [Agent Topology](docs/architecture/agent-topology.md)
-- [Action Approval Model](docs/governance/action-approval-model.md)
-- [Communications Policy](docs/governance/communications-policy.md)
-- [Mac Mini Bootstrap](docs/runbooks/mac-mini-bootstrap.md)
-- [Perpetual Operations](docs/runbooks/perpetual-operations.md)
-- [Recovery and Failover](docs/runbooks/recovery-and-failover.md)
+- [Agent Persona Setup Guide](docs/guides/agent-persona-setup.md) -- Detailed guide for configuring identity, operating charter, and behavioural policies
+- [System Architecture](docs/architecture/system-architecture.md) -- Full system design and component overview
+- [Agent Topology](docs/architecture/agent-topology.md) -- Sub-agent hierarchy and delegation model
+- [Action Approval Model](docs/governance/action-approval-model.md) -- Communication governance and approval levels
+- [Communications Policy](docs/governance/communications-policy.md) -- Voice modes, autonomy model, escalation rules
+- [Mac Mini Bootstrap](docs/runbooks/mac-mini-bootstrap.md) -- Hardware setup and initial configuration
+- [Perpetual Operations](docs/runbooks/perpetual-operations.md) -- Keeping the agent running 24/7
+- [Recovery and Failover](docs/runbooks/recovery-and-failover.md) -- Disaster recovery procedures
 
 ---
 
-Built with Maestro. Designed for autonomous AI workforces.
+Built by [Adaptic.ai](https://adaptic.ai)