@agenticmail/enterprise 0.3.2 → 0.4.0

package/ARCHITECTURE.md

@@ -1,183 +1,200 @@
 # AgenticMail Enterprise Architecture
 
 ## Vision
-Company installs `npx agenticmail-enterprise` → runs setup wizard → gets a cloud-hosted admin dashboard URL → manages AI agent identities, email, auth, compliance from that dashboard.
+Deploy and manage AI agents as employees within organizations. Companies configure agent skills, permissions, and deployment targets from a web dashboard. Agents run in Docker containers, VPS servers, or cloud platforms (Fly.io, Railway) — fully provisioned, monitored, and governed.
 
 ## Core Principles
-1. **Cloud-first**: No local servers. Deploys to user's cloud or our managed infra.
-2. **Bring your own database**: Support Postgres, MySQL, SQLite, MongoDB, DynamoDB, CockroachDB, PlanetScale, Turso, Supabase, Neon — anything.
-3. **Bring your own cloud**: Deploy to Fly.io, Railway, Render, AWS, GCP, Azure, Vercel, or managed by us.
-4. **Auto-provisioned URL**: Instant `<company>.agenticmail.cloud` subdomain, with custom domain support.
-5. **Admin UI**: Web dashboard for agent CRUD, audit logs, rules, compliance.
+1. **Bring your own database**: SQLite, Postgres, MySQL, MongoDB, DynamoDB, Turso — any SQL or NoSQL backend
+2. **Bring your own cloud**: Docker, VPS (SSH), Fly.io, Railway, or local development
+3. **Write-through persistence**: All engine state lives in memory for fast reads, with every mutation persisted to the database. On startup, state is hydrated from DB.
+4. **Single-file dashboard**: React 18 admin UI served as a single HTML file — no build step, no node_modules on the frontend
+5. **Hono API server**: Lightweight, fast HTTP framework with full middleware stack
 
-## User Journey
+## System Architecture
 
 ```
-$ npx agenticmail-enterprise
-
-🏢 AgenticMail Enterprise Setup
-
-? Company name: Acme Corp
-? Admin email: admin@acme.com
-? Database: (choose one)
-  ▸ PostgreSQL (connection string)
-    MySQL (connection string)
-    MongoDB (connection string)
-    SQLite (embedded)
-    Turso (LibSQL)
-    PlanetScale (MySQL-compatible)
-    Supabase (Postgres)
-    Neon (Postgres)
-    DynamoDB (AWS)
-    CockroachDB
-    
-? Database connection: postgresql://...
-? Deploy to: (choose one)
-  ▸ AgenticMail Cloud (managed, free tier)
-    Fly.io
-    Railway
-    Render
-    Docker (self-hosted)
-    
-? Custom domain (optional): mail.acme.com
-
-⏳ Provisioning...
-  ✓ Database schema created
-  ✓ Admin account created  
-  ✓ DKIM/SPF/DMARC configured
-  ✓ Deployed to agenticmail.cloud
-  
-🎉 Your dashboard is live!
-   URL: https://acme.agenticmail.cloud
-   Admin: admin@acme.com (check email for password)
-   
-   Add custom domain later:
-   CNAME mail.acme.com → acme.agenticmail.cloud
+┌──────────────────────────────────────────────────────────────┐
+│                    Dashboard (Web UI)                         │
+│              Single HTML · React 18 · CDN-loaded             │
+└─────────────────────────┬────────────────────────────────────┘
+                          │ HTTP/SSE
+┌─────────────────────────▼────────────────────────────────────┐
+│                   Hono API Server (server.ts)                 │
+│                                                               │
+│  ┌──────────┐  ┌───────────┐  ┌────────────────────────────┐ │
+│  │  Auth     │  │  Admin    │  │         Engine              │ │
+│  │  /auth/*  │  │  /api/*   │  │  /api/engine/*              │ │
+│  │          │  │           │  │                              │ │
+│  │  JWT     │  │  Users    │  │  Skills · PermissionEngine   │ │
+│  │  Login   │  │  Agents   │  │  AgentConfigGenerator        │ │
+│  │  Cookies │  │  Audit    │  │  DeploymentEngine            │ │
+│  │  API Keys│  │  Keys     │  │  ApprovalEngine (DB)         │ │
+│  │  SAML*   │  │  Settings │  │  AgentLifecycleManager (DB)  │ │
+│  │  OIDC*   │  │  Rules    │  │  KnowledgeBaseEngine (DB)    │ │
+│  └──────────┘  └───────────┘  │  TenantManager (DB)          │ │
+│                               │  ActivityTracker (DB)         │ │
+│                               │  Runtime Hooks               │ │
+│                               │  AgenticMail Bridge          │ │
+│                               └────────────────────────────┘ │
+│                                                               │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │               Middleware Stack                           │ │
+│  │  Request ID · CORS · Rate Limit · Security Headers      │ │
+│  │  Error Handler · Audit Logger · RBAC (requireRole)      │ │
+│  └─────────────────────────────────────────────────────────┘ │
+│                                                               │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │               Resilience Layer                           │ │
+│  │  CircuitBreaker · HealthMonitor · withRetry             │ │
+│  │  RateLimiter · KeyedRateLimiter                         │ │
+│  └─────────────────────────────────────────────────────────┘ │
+└─────────────────────────┬────────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          ▼               ▼               ▼
+┌─────────────┐  ┌──────────────┐  ┌──────────────┐
+│ Admin DB    │  │  Engine DB   │  │  Deployer    │
+│ (adapter.ts)│  │  (db-adapter) │  │              │
+│             │  │              │  │  Docker      │
+│ Users       │  │ 15 tables:   │  │  SSH/VPS     │
+│ Agents      │  │ managed_agents│  │  Fly.io      │
+│ API Keys    │  │ state_history │  │  Railway     │
+│ Audit Log   │  │ permission_   │  │              │
+│ Settings    │  │  profiles    │  │  execCommand  │
+│ Rules       │  │ organizations│  │  execSSH     │
+│             │  │ knowledge_   │  │              │
+│ 6 backends: │  │  bases       │  └──────────────┘
+│ SQLite      │  │ kb_documents │
+│ Postgres    │  │ kb_chunks    │
+│ MySQL       │  │ tool_calls   │
+│ MongoDB     │  │ activity_    │
+│ DynamoDB    │  │  events      │
+│ Turso       │  │ conversations│
+│             │  │ approval_    │
+└─────────────┘  │  requests    │
+                 │ approval_    │
+                 │  policies    │
+                 └──────────────┘
+
+* SAML/OIDC = stubs returning 501 (planned)
 ```
 
-## Package Structure
+## Engine Persistence Model
 
+All engine modules use a **write-through cache** pattern:
+
+1. **In-memory Maps** for fast reads (sub-millisecond)
+2. **Every write** also persists to the database via `EngineDatabase`
+3. **On startup**, `loadFromDb()` hydrates all Maps from the database
+4. **DB writes are fire-and-forget** for activity/events (non-blocking via `.catch(() => {})`)
+5. **DB writes are awaited** for agents/orgs/knowledge bases (data integrity)
+
+### Wiring Flow
 ```
-@agenticmail/enterprise
-├── src/
-│   ├── index.ts              # CLI entry point
-│   ├── setup/
-│   │   ├── wizard.ts         # Interactive setup flow
-│   │   ├── database.ts       # DB adapter factory
-│   │   └── deploy.ts         # Cloud deployment orchestrator
-│   ├── db/
-│   │   ├── adapter.ts        # Abstract DB interface
-│   │   ├── postgres.ts       # PostgreSQL adapter
-│   │   ├── mysql.ts          # MySQL adapter
-│   │   ├── mongodb.ts        # MongoDB adapter
-│   │   ├── sqlite.ts         # SQLite adapter (dev/small teams)
-│   │   ├── turso.ts          # Turso/LibSQL adapter
-│   │   ├── dynamodb.ts       # DynamoDB adapter
-│   │   └── migrations/       # Schema migrations (per adapter)
-│   ├── auth/
-│   │   ├── saml.ts           # SAML 2.0 SP
-│   │   ├── oidc.ts           # OAuth 2.0 / OpenID Connect
-│   │   ├── scim.ts           # SCIM provisioning
-│   │   ├── api-keys.ts       # API key management
-│   │   └── sessions.ts       # Session management
-│   ├── admin/
-│   │   ├── dashboard.ts      # Admin API routes
-│   │   ├── agents.ts         # Agent CRUD
-│   │   ├── audit.ts          # Audit log viewer
-│   │   ├── rules.ts          # Email rules management
-│   │   ├── compliance.ts     # DLP, retention policies
-│   │   └── billing.ts        # Usage tracking, plans
-│   ├── deploy/
-│   │   ├── fly.ts            # Fly.io deployment
-│   │   ├── railway.ts        # Railway deployment
-│   │   ├── render.ts         # Render deployment
-│   │   ├── docker.ts         # Docker/self-hosted
-│   │   └── managed.ts        # AgenticMail Cloud (our infra)
-│   ├── ui/                   # Admin dashboard (React/Next.js)
-│   │   ├── app/
-│   │   │   ├── layout.tsx
-│   │   │   ├── page.tsx          # Dashboard home
-│   │   │   ├── agents/           # Agent management
-│   │   │   ├── audit/            # Audit logs
-│   │   │   ├── settings/         # Company settings
-│   │   │   ├── auth/             # SSO config
-│   │   │   └── compliance/       # DLP, retention
-│   │   └── components/
-│   └── server.ts             # Express/Hono server (API + UI)
-└── package.json
+server.ts
+  └─ setEngineDb(engineDb)        // Called on first /api/engine/* request
+       ├─ lifecycle.setDb(db)      // Loads managed_agents into memory
+       ├─ approvals.setDb(db)      // Loads pending approval_requests
+       ├─ knowledgeBase.setDb(db)  // Loads knowledge_bases + documents + chunks
+       ├─ activity.setDb(db)       // Stores reference for fire-and-forget writes
+       ├─ tenants.setDb(db)        // Loads organizations into memory
+       └─ permissionEngine.setDb(db) // Stores reference for profile persistence
 ```
 
-## Database Adapter Interface
-
-```typescript
-interface DatabaseAdapter {
-  // Connection
-  connect(config: DatabaseConfig): Promise<void>;
-  disconnect(): Promise<void>;
-  migrate(): Promise<void>;
-  
-  // Agents
-  createAgent(agent: AgentInput): Promise<Agent>;
-  getAgent(id: string): Promise<Agent | null>;
-  listAgents(filters?: AgentFilters): Promise<Agent[]>;
-  updateAgent(id: string, updates: Partial<Agent>): Promise<Agent>;
-  deleteAgent(id: string): Promise<void>;
-  archiveAgent(id: string): Promise<DeletionReport>;
-  
-  // Email
-  storeEmail(email: StoredEmail): Promise<void>;
-  getEmail(uid: number): Promise<StoredEmail | null>;
-  searchEmails(query: SearchQuery): Promise<StoredEmail[]>;
-  
-  // Audit
-  logEvent(event: AuditEvent): Promise<void>;
-  queryAuditLog(filters: AuditFilters): Promise<AuditEvent[]>;
-  
-  // Auth
-  createUser(user: UserInput): Promise<User>;
-  getUser(id: string): Promise<User | null>;
-  getUserByEmail(email: string): Promise<User | null>;
-  
-  // API Keys
-  createApiKey(key: ApiKeyInput): Promise<ApiKey>;
-  validateApiKey(key: string): Promise<ApiKey | null>;
-  revokeApiKey(id: string): Promise<void>;
-  
-  // Rules & Compliance
-  createRule(rule: RuleInput): Promise<Rule>;
-  getRules(): Promise<Rule[]>;
-  getRetentionPolicy(): Promise<RetentionPolicy>;
-  setRetentionPolicy(policy: RetentionPolicy): Promise<void>;
-}
+### Migration System
+- 15 engine tables defined in `db-schema.ts`
+- Versioned migrations with tracking table `engine_migrations`
+- Auto-converts SQLite DDL to Postgres/MySQL dialect
+- NoSQL support via optional `nosql()` migration callbacks for MongoDB/DynamoDB
+
+## Agent Lifecycle State Machine
+
 ```
+draft → configuring → ready → provisioning → deploying → starting → running
+                                                                      ↕
+                                                                   degraded
+                                                                      ↓
+                                         stopped ← error ← destroying
+```
+
+- **12 states**: draft, configuring, ready, provisioning, deploying, starting, running, degraded, stopped, error, updating, destroying
+- **Health check loop**: 30-second interval when running/degraded
+- **Auto-recovery**: Restarts after 5 consecutive health failures
+- **Budget enforcement**: Auto-stop when monthly token/cost budget exceeded
+- **State transitions persisted** to `agent_state_history` table
+
+## File Structure
+
+```
+enterprise/src/
+├── cli.ts                      # CLI entry point (npx @agenticmail/enterprise)
+├── server.ts                   # Hono server: middleware, auth, route mounting
+├── index.ts                    # Public API exports
+│
+├── auth/
+│   └── routes.ts               # JWT login, cookies, refresh, SAML/OIDC stubs
+│
+├── admin/
+│   └── routes.ts               # Users, Agents, API Keys, Audit, Settings, Rules CRUD
+│
+├── middleware/
+│   └── index.ts                # Rate limiter, security headers, audit logger, RBAC, error handler
+│
+├── lib/
+│   └── resilience.ts           # CircuitBreaker, HealthMonitor, withRetry, RateLimiter
+│
+├── db/                         # Admin database adapters (6 backends)
+│   ├── adapter.ts              # Abstract DatabaseAdapter interface
+│   ├── factory.ts              # createAdapter() factory
+│   ├── sql-schema.ts           # Shared DDL + migrations
+│   ├── sqlite.ts               # SQLite (better-sqlite3)
+│   ├── postgres.ts             # PostgreSQL (pg)
+│   ├── mysql.ts                # MySQL (mysql2)
+│   ├── mongodb.ts              # MongoDB
+│   ├── dynamodb.ts             # DynamoDB (@aws-sdk)
+│   └── turso.ts                # Turso/LibSQL (@libsql/client)
+│
+├── engine/                     # Agent management platform (11 subsystems)
+│   ├── index.ts                # Public re-exports
+│   ├── routes.ts               # All engine REST endpoints (50+)
+│   ├── skills.ts               # 38 skills, 5 presets, PermissionEngine (DB-persisted)
+│   ├── agent-config.ts         # AgentConfigGenerator: workspace files, gateway, docker-compose, systemd
+│   ├── deployer.ts             # DeploymentEngine: Docker, VPS/SSH, Fly.io, Railway
+│   ├── lifecycle.ts            # AgentLifecycleManager: state machine, health checks (DB-persisted)
+│   ├── approvals.ts            # ApprovalEngine: policies, requests, decisions (DB-persisted)
+│   ├── knowledge.ts            # KnowledgeBaseEngine: docs, chunking, embeddings, RAG (DB-persisted)
+│   ├── tenant.ts               # TenantManager: orgs, plans, limits, usage (DB-persisted)
+│   ├── activity.ts             # ActivityTracker: events, tool calls, conversations, SSE (DB-persisted)
+│   ├── tool-catalog.ts         # 167 tool IDs mapped to skills
+│   ├── runtime/                # Runtime hooks and plugin integration
+│   ├── agenticmail-bridge.ts   # Bridge to AgenticMail API
+│   ├── db-adapter.ts           # EngineDatabase wrapper (682 lines, all CRUD implemented)
+│   └── db-schema.ts            # Engine DDL: 15 tables, versioned migrations, dialect converters
+│
+├── deploy/                     # Cloud deployment
+│   ├── fly.ts                  # Fly.io Machines API
+│   └── managed.ts              # Managed cloud provisioning
+│
+├── setup/                      # CLI setup wizard
+│   ├── index.ts                # Wizard orchestrator
+│   ├── company.ts              # Company info prompts
+│   ├── database.ts             # Database selection
+│   ├── deployment.ts           # Deployment target
+│   ├── domain.ts               # Custom domain
+│   └── provision.ts            # Provisioning logic
+│
+└── dashboard/
+    └── index.html              # Admin UI (single HTML, React 18 from CDN)
+```
+
+## Key Design Decisions
+
+1. **Single HTML dashboard**: No build step. React 18 + ReactDOM loaded from CDN. All components defined inline. Served at `/dashboard`. This keeps the package small and eliminates frontend toolchain complexity.
+
+2. **Lazy engine initialization**: Engine routes and EngineDatabase are initialized on first `/api/engine/*` request (not at server startup). This avoids blocking startup and allows the admin DB to be ready first.
+
+3. **Two database layers**: Admin DB (DatabaseAdapter) handles users/agents/audit/settings. Engine DB (EngineDatabase) handles lifecycle/approvals/knowledge/activity/tenants. Both can use the same underlying database connection, but the Engine DB has its own tables and migration system.
+
+4. **Write-through + fire-and-forget**: Critical data (agents, orgs, knowledge bases) uses `await db.upsert()`. High-volume data (activity events, tool calls) uses `db.insert().catch(() => {})` to avoid blocking the request path.
 
-## Deployment Architecture
-
-### AgenticMail Cloud (Managed)
-- Fly.io multi-region (us-east, eu-west, ap-southeast)
-- Customer gets `<company>.agenticmail.cloud` subdomain
-- Wildcard TLS via Fly.io
-- Shared Fly.io org, isolated apps per customer
-- Customer can add custom domain (CNAME → our subdomain)
-
-### Self-Hosted
-- Single Docker image: `docker run -p 3000:3000 agenticmail/enterprise`
-- Or via CLI: `npx agenticmail-enterprise start`
-- Env vars for DB connection, SMTP, domain
-
-## Admin Dashboard Pages
-
-1. **Dashboard** — Overview: active agents, emails sent/received, health
-2. **Agents** — Create, edit, archive, delete. Role assignment. Email config per agent.
-3. **Audit Log** — Who did what, when. Filterable, exportable.
-4. **Authentication** — SAML/OIDC setup, user management, API keys
-5. **Compliance** — DLP rules, retention policies, outbound guards
-6. **Email Rules** — Server-side rules (auto-tag, auto-move, auto-reply)
-7. **Settings** — Company info, domain, SMTP config, billing
-8. **Integrations** — Slack, Teams, Discord notifications
-
-## Pricing Tiers (Future)
-- **Free**: 3 agents, 1K emails/mo, community support
-- **Team**: 25 agents, 50K emails/mo, SSO, audit logs — $49/mo
-- **Enterprise**: Unlimited, SCIM, DLP, retention, SLA, dedicated support — $299/mo
-- **Self-Hosted**: Unlimited, your infra — $99/mo license
+5. **Module-level singletons with late binding**: Engine modules are instantiated at module load time (top of routes.ts) as singletons. Database is injected later via `setDb()` when `setEngineDb()` is called. This allows routes to be defined before the DB is ready.

package/CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md — Enterprise Repository Rules
+
+## CRITICAL: This is a DEDICATED REPO
+
+**Repo:** `github.com/agenticmail/enterprise`  
+**Origin:** `https://github.com/agenticmail/enterprise.git`
+
+### DO NOT:
+- Push code from the monorepo (`agentic-mail/packages/enterprise`) directly — sync first
+- Force push to `main`
+- Commit `node_modules/`, `dist/`, `.env`, `*.db`, `*.sqlite` files
+- Change the git remote origin
+- Merge code from other packages into this repo
+
+### DO:
+- Work in this directory for enterprise-specific changes
+- Run `npm run build` before committing to verify compilation
+- Run `node live-test.mjs` to verify 33+ E2E tests pass
+- Update `README.md` when changing API endpoints or features
+- Update `CHANGELOG.md` for every version bump
+
+### Sync Process (monorepo → dedicated repo)
+If changes were made in `agentic-mail/packages/enterprise/`:
+```bash
+rsync -av --delete \
+  --exclude='node_modules' --exclude='dist' --exclude='.git' --exclude='*.db' --exclude='*.sqlite' \
+  ../agentic-mail/packages/enterprise/ .
+```
+
+### Key Files
+- `src/dashboard/index.html` — Single-file React dashboard (entire UI)
+- `src/server.ts` — Hono server entry point
+- `src/auth/routes.ts` — Authentication (cookies + JWT)
+- `src/admin/routes.ts` — Admin API endpoints
+- `src/engine/routes.ts` — Engine API endpoints
+- `live-test.mjs` — E2E test runner (33 tests)
+- `test-integration.mjs` — Integration tests (94 tests)
+
+### Current Version
+Check `package.json` for current version. Published to npm as `@agenticmail/enterprise`.

package/CONTRIBUTING.md

@@ -0,0 +1,254 @@
+# Contributing Community Skills to AgenticMail Enterprise
+
+AgenticMail Enterprise has an open skill marketplace powered by Git. Anyone can build a skill for any application and submit it as a pull request.
+
+> **All skill submissions require manual review and approval from a maintainer.**
+> Automated CI validates the manifest format, but a human reviews every skill
+> for accuracy, safety, and quality before it can be merged. No skill goes live
+> without maintainer sign-off.
+
+## Quick Start
+
+```bash
+# 1. Create your skill directory
+mkdir community-skills/my-skill
+
+# 2. Create the manifest
+cp community-skills/_template/agenticmail-skill.json community-skills/my-skill/
+
+# 3. Edit the manifest with your skill details
+# (see Specification below)
+
+# 4. Validate
+agenticmail-enterprise validate community-skills/my-skill/
+
+# 5. Submit a PR
+agenticmail-enterprise submit-skill community-skills/my-skill/
+```
+
+Or use the AI-assisted builder:
+
+```bash
+agenticmail-enterprise build-skill
+```
+
+## agenticmail-skill.json Specification
+
+Every community skill is defined by an `agenticmail-skill.json` manifest in its own directory under `community-skills/`.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier. Lowercase alphanumeric, hyphens, underscores. 3-64 chars. |
+| `name` | string | Human-readable name. Max 100 chars. |
+| `description` | string | What the skill does. 20-500 chars. |
+| `version` | string | Semantic version (e.g. `1.0.0`). |
+| `author` | string | Your GitHub username. |
+| `repository` | string | URL to the skill's source repository. |
+| `license` | string | SPDX license identifier (e.g. `MIT`, `Apache-2.0`). |
+| `category` | string | One of the valid categories (see below). |
+| `risk` | string | `low`, `medium`, `high`, or `critical`. |
+| `tools` | array | At least one tool definition (see below). |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `icon` | string | Emoji or URL for display. |
+| `tags` | string[] | Up to 20 lowercase tags for search. |
+| `configSchema` | object | Configuration fields needed by the skill. |
+| `minEngineVersion` | string | Minimum engine version required. |
+| `homepage` | string | URL to documentation. |
+
+### Tool Definition
+
+Each tool in the `tools` array describes one action the skill provides:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique tool ID. Lowercase with underscores. **Must not conflict with existing tools.** |
+| `name` | string | Yes | Human-readable name. |
+| `description` | string | Yes | What this tool does. |
+| `category` | string | No | `read`, `write`, `execute`, `communicate`, or `destroy`. |
+| `riskLevel` | string | No | `low`, `medium`, `high`, or `critical`. |
+| `sideEffects` | string[] | No | What external effects this tool causes. |
+| `parameters` | object | No | Input parameters the tool accepts. |
+
+### Naming Convention for Tool IDs
+
+Use a prefix based on your skill ID to avoid collisions:
+
+```
+skill ID:  github-issues
+tool IDs:  github_create_issue, github_update_issue, github_list_issues
+```
+
+## Valid Categories (27)
+
+| Category | Description |
+|----------|-------------|
+| `communication` | Email, SMS, messaging |
+| `development` | GitHub, coding, git |
+| `productivity` | Calendar, notes, reminders, tasks |
+| `research` | Web search, web fetch, summarize |
+| `media` | Image gen, TTS, video, audio |
+| `automation` | Browser, shell, scripting |
+| `smart-home` | IoT, Hue, Sonos, cameras |
+| `data` | Files, databases, storage |
+| `security` | Passwords, healthcheck, IAM |
+| `social` | Twitter/X, LinkedIn |
+| `platform` | Core AgenticMail platform internals |
+| `collaboration` | Slack, Teams, Zoom, chat |
+| `crm` | Salesforce, HubSpot, Dynamics |
+| `project-management` | Jira, Asana, Monday, Linear |
+| `cloud-infrastructure` | AWS, Azure, GCP |
+| `devops` | Docker, K8s, Terraform, CI/CD |
+| `finance` | Stripe, QuickBooks, Xero |
+| `analytics` | Tableau, Power BI, Mixpanel |
+| `design` | Figma, Canva, Adobe |
+| `ecommerce` | Shopify, WooCommerce |
+| `marketing` | Mailchimp, SendGrid, ads |
+| `hr` | BambooHR, Workday, Gusto |
+| `legal` | DocuSign, compliance |
+| `customer-support` | Zendesk, Intercom, Freshdesk |
+| `storage` | Dropbox, Box, OneDrive |
+| `database` | MongoDB, Redis, Snowflake |
+| `monitoring` | Datadog, PagerDuty, Sentry |
+
+## Valid Tool Categories (5)
+
+| Category | Description |
+|----------|-------------|
+| `read` | Read-only, no side effects |
+| `write` | Creates or modifies data |
+| `execute` | Runs code or commands |
+| `communicate` | Sends messages externally |
+| `destroy` | Deletes data |
+
+## Risk Levels
+
+| Level | When to use |
+|-------|-------------|
+| `low` | Read-only operations, no sensitive data |
+| `medium` | Creates/modifies data, sends messages |
+| `high` | Handles sensitive data, financial operations, destructive actions |
+| `critical` | Full system access, admin operations, irreversible actions |
+
+## Side Effects (11)
+
+| Effect | Description |
+|--------|-------------|
+| `sends-email` | Sends an email |
+| `sends-message` | Sends a chat/SMS message |
+| `sends-sms` | Sends an SMS specifically |
+| `posts-social` | Posts to social media |
+| `runs-code` | Executes code or commands |
+| `modifies-files` | Creates or modifies files |
+| `deletes-data` | Deletes data permanently |
+| `network-request` | Makes external HTTP requests |
+| `controls-device` | Controls IoT/smart devices |
+| `accesses-secrets` | Reads passwords, tokens, keys |
+| `financial` | Processes payments or financial data |
+
+## CLI Commands
+
+### Validate a Skill
+
+```bash
+# Validate a single skill
+agenticmail-enterprise validate community-skills/my-skill/
+
+# Validate all community skills
+agenticmail-enterprise validate --all
+
+# Machine-readable output (for CI)
+agenticmail-enterprise validate --all --json
+```
+
+### Build a Skill (AI-Assisted)
+
+```bash
+agenticmail-enterprise build-skill
+```
+
+This interactive command:
+1. Asks what application/service the skill should integrate with
+2. Asks what operations it should support
+3. Uses an AI agent (if agent runtime is running) to generate the manifest
+4. Falls back to template-based generation otherwise
+5. Validates the output
+6. Offers to submit as a PR
+
+### Submit a Skill
+
+```bash
+agenticmail-enterprise submit-skill community-skills/my-skill/
+```
+
+This automates the entire PR flow:
+1. Validates the manifest
+2. Forks the repo (if needed)
+3. Creates a branch
+4. Commits and pushes
+5. Opens a pull request
+
+**Requires:** [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated.
+
+## Review Process
+
+**Every community skill requires maintainer approval before it can be merged.**
+
+When you open a PR, the following happens automatically:
+
+1. CI runs `agenticmail-enterprise validate` on your manifest
+2. The bot posts a validation report and a **maintainer review checklist** on your PR
+3. The PR is labeled `community-skill` + `needs-maintainer-review`
+4. A maintainer from `@agenticmail/skill-reviewers` is auto-assigned via CODEOWNERS
+
+**The PR cannot be merged until a maintainer explicitly approves it.**
+
+### What Maintainers Check
+
+Automated validation only checks the manifest format. A human reviewer checks:
+
+1. **Tool IDs are sensibly named** — follow `prefix_action` convention, no misleading names
+2. **Descriptions are accurate** — clearly explain what each tool does
+3. **Risk levels are appropriate** — destructive actions must be `high`/`critical`
+4. **Side effects are correctly declared** — `sends-email`, `deletes-data`, `financial`, etc.
+5. **No malicious or deceptive definitions** — tool names must match their actual behavior
+6. **Category fits the application** — not miscategorized to gain visibility
+7. **Config schema is reasonable** — no unnecessary secrets or permissions requested
+8. **README documents everything** — all tools, configuration, and usage examples
+9. **License is valid** — must be an open-source SPDX license
+
+### After Approval
+
+Once a maintainer approves and merges your PR:
+
+1. CI automatically rebuilds `community-skills/index.json`
+2. All deployed AgenticMail instances pick up the new skill within 6 hours (via periodic sync)
+3. Admins can also trigger an immediate sync from the dashboard
+4. Your skill appears in the Community Skills marketplace for all users
+
+## Directory Structure
+
+```
+community-skills/
+  _template/                    # Template for new skills
+    agenticmail-skill.json
+    README.md
+  github-issues/                # Example: GitHub Issues skill
+    agenticmail-skill.json
+    README.md
+  slack-notifications/          # Example: Slack skill
+    agenticmail-skill.json
+    README.md
+  your-skill/                   # Your contribution
+    agenticmail-skill.json
+    README.md
+```
+
+## License
+
+By contributing a community skill, you agree that your contribution is licensed under the license specified in your manifest (defaulting to MIT).