matimo-examples 0.1.0-alpha.12 → 0.1.0-alpha.13

package/QUICK_COMMANDS.md

@@ -0,0 +1,316 @@
+# Quick Command Reference
+
+Fast validation of all Matimo implementations.
+
+> ⚠️ **Important:** Matimo is a **pnpm monorepo**. Use `pnpm` commands, not `npm`. The `workspace:*` protocol is pnpm-specific and not supported by npm.
+
+## Test Everything (2-5 minutes)
+
+```bash
+cd /path/to/matimo
+
+# Build the project
+pnpm build
+
+# Change to examples directory
+cd examples/tools
+
+# Option A: Validate all implementations in batch
+pnpm validate:all   # Runs all examples with auto-approval
+pnpm validate:meta  # Only meta-tools
+pnpm validate:policy # Only policy
+pnpm validate:skills # Only skills
+
+# Option B: Run specific category examples
+# Meta/Demo Examples
+pnpm meta:flow      # Meta-tools integration (most comprehensive)
+pnpm policy:demo    # Policy engine focus
+pnpm skills:demo    # Skills system focus
+pnpm credentials:example # Credentials management
+
+# Option C: Run by provider (factory pattern is simplest to start, Please update provider api key in .env ref example.env)
+pnpm agent:factory          # Base agent example
+pnpm slack:factory          # Slack provider
+pnpm gmail:factory          # Gmail provider
+pnpm github:factory         # GitHub provider
+pnpm postgres:factory       # PostgreSQL provider
+pnpm notion:factory         # Notion provider
+pnpm hubspot:factory        # HubSpot provider
+pnpm mailchimp:factory      # Mailchimp provider
+pnpm twilio:factory         # Twilio provider
+
+# Option D: Run by core functionality (decorator pattern)
+pnpm execute:decorator      # Execute tool
+pnpm read:decorator         # Read tool
+pnpm edit:decorator         # Edit tool
+pnpm search:decorator       # Search tool
+pnpm web:decorator          # Web tool
+
+# Option E: Run LangChain integration examples
+pnpm agent:langchain        # Full LangChain agent
+pnpm agent:skills-policy        # LangChain with skills & policy
+pnpm slack:langchain        # Slack with LangChain
+pnpm execute:langchain      # Execute with LangChain
+```
+
+## Available Examples by Category
+
+### Meta/Demo Examples
+| Command | Purpose |
+|---------|---------|
+| `pnpm meta:flow` | Meta-tools integration demo (tool creation, policy, approvals) |
+| `pnpm policy:demo` | Policy engine validation & blocking scenarios |
+| `pnpm skills:demo` | Skills system creation and validation |
+| `pnpm credentials:example` | Credentials management patterns |
+
+### Provider Examples - Factory Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm agent:factory` | Base agent with factory pattern |
+| `pnpm slack:factory` | Slack tools via factory |
+| `pnpm gmail:factory` | Gmail tools via factory |
+| `pnpm github:factory` | GitHub tools via factory |
+| `pnpm postgres:factory` | PostgreSQL tools via factory |
+| `pnpm postgres:approval` | PostgreSQL with approval workflow |
+| `pnpm notion:factory` | Notion tools via factory |
+| `pnpm hubspot:factory` | HubSpot tools via factory |
+| `pnpm mailchimp:factory` | Mailchimp tools via factory |
+| `pnpm twilio:factory` | Twilio tools via factory |
+
+### Provider Examples - Decorator Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm agent:decorator` | Base agent with decorator pattern |
+| `pnpm slack:decorator` | Slack tools via decorators |
+| `pnpm gmail:decorator` | Gmail tools via decorators |
+| `pnpm github:decorator` | GitHub tools via decorators |
+| `pnpm postgres:decorator` | PostgreSQL tools via decorators |
+| `pnpm notion:decorator` | Notion tools via decorators |
+| `pnpm hubspot:decorator` | HubSpot tools via decorators |
+| `pnpm mailchimp:decorator` | Mailchimp tools via decorators |
+| `pnpm twilio:decorator` | Twilio tools via decorators |
+
+### Provider Examples - LangChain Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm agent:langchain` | Base agent with LangChain integration |
+| `pnpm agent:skills-policy` | LangChain agent with skills & policy |
+| `pnpm slack:langchain` | Slack tools via LangChain |
+| `pnpm gmail:langchain` | Gmail tools via LangChain |
+| `pnpm github:langchain` | GitHub tools via LangChain |
+| `pnpm github:approval` | GitHub with approval workflow |
+| `pnpm postgres:langchain` | PostgreSQL tools via LangChain |
+| `pnpm notion:langchain` | Notion tools via LangChain |
+| `pnpm hubspot:langchain` | HubSpot tools via LangChain |
+| `pnpm mailchimp:langchain` | Mailchimp tools via LangChain |
+| `pnpm twilio:langchain` | Twilio tools via LangChain |
+
+### Core Functionality Examples - Factory Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm execute:factory` | Execute commands via factory |
+| `pnpm read:factory` | Read files via factory |
+| `pnpm edit:factory` | Edit files via factory |
+| `pnpm search:factory` | Search files via factory |
+| `pnpm web:factory` | Web scraping via factory |
+
+### Core Functionality Examples - Decorator Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm execute:decorator` | Execute commands via decorators |
+| `pnpm read:decorator` | Read files via decorators |
+| `pnpm edit:decorator` | Edit files via decorators |
+| `pnpm search:decorator` | Search files via decorators |
+| `pnpm web:decorator` | Web scraping via decorators |
+
+### Core Functionality Examples - LangChain Pattern
+| Command | Purpose |
+|---------|---------|
+| `pnpm execute:langchain` | Execute commands via LangChain |
+| `pnpm read:langchain` | Read files via LangChain |
+| `pnpm edit:langchain` | Edit files via LangChain |
+| `pnpm search:langchain` | Search files via LangChain |
+| `pnpm web:langchain` | Web scraping via LangChain |
+
+### Validation Commands
+| Command | Purpose |
+|---------|---------|
+| `pnpm validate:all` | Run meta examples with auto-approval |
+| `pnpm validate:meta` | Only meta-tools example |
+| `pnpm validate:policy` | Only policy demo |
+| `pnpm validate:skills` | Only skills demo |
+| `pnpm validate:impl` | Implementation validation |
+
+
+```bash
+# From matimo root
+cd packages/cli
+
+# Validate all tools in a directory
+pnpm cli -- doctor packages/core/tools/
+
+# List pending and approved tools
+pnpm cli -- review list
+
+# Approve a tool (requires computed HMAC)
+pnpm cli -- review approve calculator --secret <hmac-hash>
+
+# Reject/revoke a tool
+pnpm cli -- review reject calculator
+```
+
+## Test Coverage
+
+```bash
+cd /path/to/matimo
+
+# Test policy engine (100% coverage expected)
+pnpm test -- packages/core/test/unit/policy/
+
+# Test skills system (100% coverage expected)
+pnpm test -- packages/core/test/unit/skills/
+
+# Test CLI commands (doctor, review, skills, etc.)
+pnpm test -- packages/cli/test/unit/commands/
+
+# Full project coverage
+pnpm test:coverage      # Shows summary and detailed report
+```
+
+## Quick Validation Checklist
+
+```bash
+# 1. Does meta-tools example run without errors?
+npx tsx examples/tools/meta-flow/meta-tools-integration.ts --help
+# Expected: Shows agent setup messages, or --help info
+
+# 2. Does policy engine block dangerous tools?
+cd examples/tools
+printf "y\ny\ny\ny\ny\ny\n" | npx tsx policy/policy-demo.ts 2>&1 | grep -i "blocked\|error" | head -10
+# Expected: Multiple "BLOCKED" messages for shell commands, SSRF, etc.
+
+# 3. Does skills system create valid SKILL.md files?
+printf "y\ny\ny\n" | npx tsx skills/skills-demo.ts 2>&1 | grep "skill" | grep -i "created\|pass"
+# Expected: Messages about skills being created and validated
+
+# 4. Can CLI doctor command validate tools?
+pnpm cli -- doctor packages/core/tools/ 2>&1 | grep -i "valid\|error\|pass" | head -10
+# Expected: Validation results for tools in directory
+
+# 5. Can review command manage approvals?
+pnpm cli -- review list 2>&1 | grep -i "pending\|approved\|tool"
+# Expected: Tool status listing (even if empty)
+```
+
+## What Each Component Validates
+
+For detailed validation details and expected outputs, see individual README files:
+
+### Meta-Tools Integration (`meta:flow`)
+📖 **Full details:** [meta-flow/README.md](./meta-flow/README.md)
+
+✓ Tool creation (matimo_create_tool)  
+✓ Policy validation (matimo_doctor)  
+✓ Human approval (matimo_review)  
+✓ Registry reload (matimo_reload_tools)  
+✓ Tool listing (matimo_list_user_tools)  
+✓ Tool execution after approval  
+✓ Agent learns from policy rejections  
+
+**Duration:** ~120s | **API Calls:** 12-15 | **Missions:** 5
+
+### Policy Demo (`policy:demo`)
+📖 **Full details:** [policy/README.md](./policy/README.md)
+
+✓ Safe tool validation passes  
+✓ Shell commands blocked  
+✓ SSRF attacks blocked  
+✓ Namespace hijacking blocked  
+✓ Human approval workflow  
+✓ Risk classification  
+
+**Duration:** ~90s | **API Calls:** 10-12 | **Missions:** 10
+
+### Skills Demo (`skills:demo`)
+📖 **Full details:** [skills/README.md](./skills/README.md)
+
+✓ Skill creation with YAML frontmatter  
+✓ Skill listing (Level 1 metadata)  
+✓ Skill content retrieval (Level 2)  
+✓ Spec validation  
+✓ Multi-skill application to code  
+
+**Duration:** ~60s | **API Calls:** 8-10 | **Missions:** 6
+
+### Credentials Management
+📖 **Full details:** [credentials/README.md](./credentials/README.md)
+
+✓ Environment variable loading  
+✓ Multi-provider credential setup  
+✓ Credential validation  
+✓ Best practices and patterns  
+
+---
+
+## Troubleshooting Quick Fixes
+
+| Problem | Fix |
+|---------|-----|
+| "OPENAI_API_KEY not set" | Add to examples/tools/.env |
+| "Agent loops indefinitely" | Increase MAX_ITERATIONS constant |
+| "No human prompt appears" | Ensure approval handler is set |
+| "Module not found: tsx" | `pnpm install -g tsx` or use `npx tsx` |
+| "Tools don't execute" | Verify matimo_reload_tools() called |
+| "Policy doesn't block" | Check PolicyConfig in init() |
+
+---
+
+## Performance Benchmarks
+
+| Example | Duration | API Calls | Missions |
+|---------|----------|-----------|----------|
+| meta:flow | ~120s | 12-15 | 5 |
+| policy:demo | ~90s | 10-12 | 10 |
+| skills:demo | ~60s | 8-10 | 6 |
+
+(Times depend on LLM latency; gpt-4o-mini is optimized for fast responses)
+
+---
+
+## Report All Results
+
+After running validations, check:
+
+```bash
+# cd to Matimo root folder from example/tools
+cd ../..
+# Test results
+pnpm test:coverage 2>&1 | tail -20
+
+# Meta-tools: created tools on disk
+ls -la /tmp/matimo-meta-flow-*/tools/*/definition.yaml
+
+# Skills: created SKILL.md files
+ls -la /tmp/matimo-skills-demo-*/skills/*/SKILL.md
+
+# Policy: validation logs show blocks
+grep -i "blocked\|invalid" /tmp/*.log
+```
+
+---
+
+## Next: Detailed Information
+
+For comprehensive information about each example including validation details, expected output patterns, troubleshooting, and performance metrics, see individual README files:
+
+| Example | Documentation |
+|---------|----------------|
+| **Meta-Tools** | [meta-flow/README.md](./meta-flow/README.md) — Tool creation, policy validation, approvals |
+| **Policy Engine** | [policy/README.md](./policy/README.md) — Policy validation, blocking scenarios, risk classification |
+| **Skills System** | [skills/README.md](./skills/README.md) — Skills creation, listing, validation, multi-skill application |
+| **Credentials** | [credentials/README.md](./credentials/README.md) — API key management, environment setup, best practices |
+| **All Examples** | [README.md](./README.md) — Overview of all 50+ examples |
+
+---
+
+**Quick tip: When in doubt, run: `pnpm meta:flow`** 🚀

package/README.md

@@ -1,65 +1,158 @@
-# Matimo + LangChain.js Agent Examples
+# Matimo Examples - All Patterns, Providers & Features
 
-Three complete, production-ready AI agent examples showing how to integrate **Matimo SDK** with **LangChain.js**.
+**Complete collection of production-ready examples** demonstrating Matimo SDK integration across:
+- **Three calling patterns** (LangChain Official, Decorator, Factory)
+- **10+ providers** (Slack, Gmail, GitHub, PostgreSQL, Notion, HubSpot, Mailchimp, Twilio, etc.)
+- **Core features** (Execute, Read, Edit, Search, Web scraping)
+- **Advanced capabilities** (Policy validation, Skills system, Meta-tools, Credentials)
 
 ## 🎯 What These Examples Demonstrate
 
 ✅ **Framework-Independent Tool Execution:**
-
 - Matimo loads and manages tools independently
 - Tools work the same way in any framework (LangChain, CrewAI, etc.)
 - No tool redefinition needed across frameworks
-- Simple adapter layer for LangChain integration
-
-✅ **Three SDK Calling Patterns:**
-
-1. **LangChain Official API** (Recommended): Use `createAgent()` with `tool()` function
-   - Simplest, fastest, most maintainable approach
-   - LangChain handles tool selection and calling automatically
-   - Use when: You want production-ready, framework-native integration
+- Simple adapter layer for any framework integration
 
+✅ **Three SDK Calling Patterns (Demonstrated Everywhere):**
+1. **LangChain Official API** (⭐ Recommended): Use `createAgent()` with `tool()` function
 2. **Decorator Pattern**: Use `@tool(toolName)` decorator on methods
-   - Decorator intercepts calls → executes via Matimo
-   - Use when: You want method-based calling style
-
 3. **Factory Pattern**: Direct `matimo.execute(toolName, params)` calls
-   - Call Matimo directly → tool executes
-   - Use when: You prefer functional style
 
-✅ **Full LangChain Integration:**
+✅ **10+ Provider Integrations:**
+- Slack, Gmail, GitHub, PostgreSQL, Notion, HubSpot, Mailchimp, Twilio (each with 3 patterns)
+- Approval workflows (PostgreSQL, GitHub)
 
-- Real OpenAI GPT-4 agent with multi-step reasoning
-- Tool orchestration with natural language understanding
-- Matimo stays independent of LangChain's details
+✅ **Core Functionality Examples:**
+- Execute system commands
+- Read files from disk
+- Edit/modify files
+- Search code/files
+- Web scraping & HTTP requests
 
-✅ **Production Ready:**
+✅ **Advanced Features:**
+- Meta-tools (tool creation, policy checking, approvals)
+- Policy validation & blocking  
+- Skills system (define reusable skill components)
+- Credentials management
+- Human-in-the-loop approval workflows
 
+✅ **Production Ready:**
 - Independent npm package setup
-- Environment variable management
+- Environment variable management  
 - Proper TypeScript configuration
 - Clean imports from Matimo SDK
 
-## 📦 Quick Start
+## 🚀 Quick Start: Pick Your Path
+
+### Setup (All Examples)
+```bash
+# 1. Install dependencies
+pnpm install
+
+# 2. Setup environment
+cp .env.example .env
+echo "OPENAI_API_KEY=sk-your-key-here" >> .env  # From: https://platform.openai.com/api-keys
+```
 
-### 1. Install Dependencies
+### Choose Your Learning Path
 
+**👉 First time? Start here:**
 ```bash
-npm install
+pnpm agent:langchain      # ⭐ Simplest integration (recommended)
 ```
 
-This installs LangChain, Matimo SDK, and all required dependencies.
+**👉 Want to explore all examples?**
+```bash
+# See QUICK_COMMANDS.md for complete reference (50+ examples)
+# Or run batch validation:
+pnpm validate:all
+```
 
-### 2. Setup Environment
+**👉 Want to dive into providers?**
+```bash
+pnpm slack:factory        # Try any provider (factory/decorator/langchain)
+pnpm gmail:langchain
+pnpm github:decorator
+```
 
+**👉 Want to test core features?**
 ```bash
-# Copy environment template
-cp .env.example .env
+pnpm execute:factory      # Execute, read, edit, search, web
+pnpm search:langchain
+pnpm web:decorator
+```
+
+**👉 Want advanced features?**
+```bash
+pnpm meta:flow            # Meta-tools + policy + approvals
+pnpm policy:demo
+pnpm skills:demo
+```
+
+---
+
+## 📋 All Available Examples
+
+For complete reference of all 50+ examples, see [QUICK_COMMANDS.md](./QUICK_COMMANDS.md).
+
+Quick reference:
+
+### Meta/Demo Examples
+```bash
+pnpm meta:flow            # Meta-tools integration (most comprehensive)
+pnpm policy:demo             # Policy engine validation
+pnpm skills:demo             # Skills system
+pnpm credentials:example     # Credentials management
+```
+
+### Provider Examples (Pick Pattern)
+```bash
+# Slack (3 patterns):
+pnpm slack:factory | pnpm slack:decorator | pnpm slack:langchain
+
+# Gmail (3 patterns):
+pnpm gmail:factory | pnpm gmail:decorator | pnpm gmail:langchain
+
+# GitHub (3 patterns + approval workflow):
+pnpm github:factory | pnpm github:decorator | pnpm github:langchain | pnpm github:approval
+
+# PostgreSQL (3 patterns + approval workflow):
+pnpm postgres:factory | pnpm postgres:decorator | pnpm postgres:langchain | pnpm postgres:approval
+
+# Notion, HubSpot, Mailchimp, Twilio (same 3-pattern structure)
+```
+
+### Core Functionality Examples (3 patterns each)
+```bash
+# Execute system commands:
+pnpm execute:factory | pnpm execute:decorator | pnpm execute:langchain
+
+# Read files:
+pnpm read:factory | pnpm read:decorator | pnpm read:langchain
 
-# Add your OpenAI API key
-# Get key from: https://platform.openai.com/api-keys
-echo "OPENAI_API_KEY=sk-your-key-here" >> .env
+# Edit files:
+pnpm edit:factory | pnpm edit:decorator | pnpm edit:langchain
+
+# Search:
+pnpm search:factory | pnpm search:decorator | pnpm search:langchain
+
+# Web scraping:
+pnpm web:factory | pnpm web:decorator | pnpm web:langchain
 ```
 
+### Agent Examples
+```bash
+pnpm agent:factory        # Factory pattern agent
+pnpm agent:decorator      # Decorator pattern agent
+pnpm agent:langchain      # LangChain Official API (⭐ recommended)
+pnpm agent:skills-policy  # LangChain with skills & policy
+```
+
+---
+
+## 🌟 Deep Dive: Three Calling Patterns
+
 ### 3. Run LangChain Official API Agent (⭐ Recommended)
 
 ```bash
@@ -195,32 +288,57 @@ Result returned to LangChain
 
 ## 🔀 Patterns Compared
 
-| Aspect               | LangChain Official         | Decorator                           | Factory                  |
-| -------------------- | -------------------------- | ----------------------------------- | ------------------------ |
-| **Call Style**       | `createAgent()` + `tool()` | `await agent.method()`              | `await matimo.execute()` |
-| **Complexity**       | ~100 lines                 | ~200 lines (with dynamic dispatch)  | ~150 lines               |
-| **Schema**           | Automatic from Zod         | Inferred from method signature      | Manual mapping           |
-| **Tool Binding**     | Native LangChain           | Decorator intercept with reflection | Direct call              |
-| **Scalability**      | ✅ Great                   | ✅ Excellent (no routing code)      | ✅ Great                 |
-| **Type Safety**      | ✅ Yes                     | ✅ Yes (full TS support)            | ✅ Yes                   |
-| **Recommended**      | ⭐ **For frameworks**      | ⭐ **For class-based agents**       | For functional style     |
-| **Production Ready** | ✅ Yes                     | ✅ Yes                              | ✅ Yes                   |
+| Aspect                | LangChain Official         | Decorator                            | Factory                  |
+| --------------------- | -------------------------- | ------------------------------------ | ------------------------ |
+| **Call Style**        | `createAgent()` + `tool()` | `await agent.method()`               | `await matimo.execute()` |
+| **Complexity**        | ~100 lines                 | ~200 lines (with dynamic dispatch)   | ~150 lines               |
+| **Schema**            | Automatic from Zod         | Inferred from method signature       | Manual mapping           |
+| **Tool Binding**      | Native LangChain           | Decorator intercept + reflection     | Direct call              |
+| **Scalability**       | ✅ Great                   | ✅ Excellent (no routing code)       | ✅ Great                 |
+| **Type Safety**       | ✅ Yes                     | ✅ Yes (full TS support)             | ✅ Yes                   |
+| **Best For**          | Framework integration      | Class-based agents                   | Functional style         |
+| **Recommended**       | ⭐ **Start here**          | ⭐ **For class apps**                | For direct calls         |
+| **Production Ready**  | ✅ Yes                     | ✅ Yes                               | ✅ Yes                   |
+| **Works With**        | All providers & features   | All providers & features             | All providers & features |
 
 ## 📁 Project Structure
 
-````
+```
 examples/tools/
-├── agents/
+├── agents/                             # Agent examples (3 patterns)
 │   ├── langchain-agent.ts              # ⭐ LangChain Official API (recommended)
 │   ├── decorator-pattern-agent.ts      # Uses @tool decorator with MatimoInstance
-│   └── factory-pattern-agent.ts        # Uses matimo.execute() with MatimoInstance
-├── package.json                        # Standalone dependencies (LangChain, Matimo, etc.)
+│   ├── factory-pattern-agent.ts        # Uses matimo.execute() with MatimoInstance
+│   └── langchain-skills-policy-agent.ts # LangChain with skills & policy
+├── slack/                              # Slack provider (3 patterns)
+├── gmail/                              # Gmail provider (3 patterns)
+├── github/                             # GitHub provider (3 patterns + approval)
+├── postgres/                           # PostgreSQL provider (3 patterns + approval)
+├── notion/                             # Notion provider (3 patterns)
+├── hubspot/                            # HubSpot provider (3 patterns)
+├── mailchimp/                          # Mailchimp provider (3 patterns)
+├── twilio/                             # Twilio provider (3 patterns)
+├── execute/                            # Execute/run commands (3 patterns)
+├── read/                               # Read files (3 patterns)
+├── edit/                               # Edit files (3 patterns)
+├── search/                             # Search files (3 patterns)
+├── web/                                # Web scraping (3 patterns)
+├── meta-flow/                          # Meta-tools integration demo
+├── policy/                             # Policy engine demo
+├── skills/                             # Skills system demo
+├── credentials/                        # Credentials management
+├── package.json                        # Dependencies (LangChain, Matimo, etc.)
 ├── tsconfig.json                       # TypeScript configuration
-├── .env.example                        # Environment template (OPENAI_API_KEY)
-├── test-agents.ts                      # Testing script for tool verification
+├── .env.example                        # Environment template
+├── QUICK_COMMANDS.md                   # Complete reference (50+ examples)
 └── README.md                           # This file
 
-All agents load tools from: `../../tools/` (parent project's tool definitions)
+**Key:** All examples load tools from: `../../tools/` (parent project's tool definitions)
+**Pattern:** Each category (provider, feature) has 3 file variants:
+- `*-factory.ts` — Use MatimoInstance.execute()
+- `*-decorator.ts` — Use @tool() decorators
+- `*-langchain.ts` — Use LangChain Official API
+```
 
 ## 🔄 SDK Patterns Explained
 
@@ -500,11 +618,20 @@ npm run agent:langchain   # or agent:decorator, agent:factory
 
 ## 📚 Next Steps
 
-1. **Try all three agents** - compare patterns: `npm run agent:langchain`, `agent:decorator`, `agent:factory`
-2. **Modify agent queries** in `agents/*.ts` - change the example prompts
-3. **Add custom tools** to `../../tools/` - they auto-appear in all agents
-4. **Extend the agents** - add memory, streaming, custom system prompts
-5. **Deploy to production** - use Matimo REST API or MCP server
+### Beginner
+1. **Run all three agent patterns** — compare approaches: `npm run agent:langchain`, `agent:decorator`, `agent:factory`
+2. **Try a provider** — pick Slack/Gmail/GitHub: `npm run slack:factory`, `npm run github:langchain`, etc.
+3. **Test core features** — execute, read, edit: `npm run execute:factory`, `npm run read:langchain`, etc.
+
+### Intermediate
+4. **Modify example prompts** — edit `agents/*.ts` or provider files to change queries
+5. **Add custom tools** — create `../../tools/custom-tool/definition.yaml`, they auto-appear in all examples
+6. **Extend agents** — add memory, streaming, custom system prompts, better error handling
+
+### Advanced
+7. **Use advanced features** — try `npm run meta:flow` (meta-tools), `pnpm policy:demo` (validation), `pnpm skills:demo` (reusable skills)
+8. **Implement approvals** — try PostgreSQL/GitHub approval workflows: `npm run postgres:approval`, `npm run github:approval`
+9. **Deploy to production** — use Matimo REST API (Phase 2) or MCP server for Claude integration
 
 ## 🔗 Related Documentation
 
@@ -516,10 +643,26 @@ npm run agent:langchain   # or agent:decorator, agent:factory
 
 ## 💡 Key Takeaway
 
-This example proves Matimo's core value proposition:
+These examples prove Matimo's core value proposition:
 
 **Define tools ONCE in YAML** ↓  
-**Use them EVERYWHERE**: LangChain (3 patterns), SDK, CrewAI, MCP, REST, CLI ↓  
+**Use them with THREE calling patterns** (LangChain, Decorator, Factory) ↓  
+**Use them with TEN+ providers** (Slack, Gmail, GitHub, PostgreSQL, Notion, HubSpot, Mailchimp, Twilio, etc.) ↓  
+**Use them with FIVE core features** (Execute, Read, Edit, Search, Web) ↓  
+**Use them with advanced capabilities** (Meta-tools, Policy, Skills, Approvals) ↓  
+**Use them EVERYWHERE**: LangChain, SDK, CrewAI, MCP, REST API, CLI ↓  
+
 **Zero duplication. Pure productivity.**
 
-All three agents use the exact same Matimo tools with different SDK patterns. That's the Matimo difference.
+All examples use the exact same Matimo tools with different patterns, providers, and frameworks. **That's the Matimo difference.**
+
+---
+
+### 📖 For Complete Reference
+
+See [QUICK_COMMANDS.md](./QUICK_COMMANDS.md) for:
+- All 50+ example commands organized by category
+- Complete provider list with all three patterns
+- Core functionality examples (execute, read, edit, search, web)
+- Meta/demo examples (meta-tools, policy, skills, credentials)
+- Validation & testing commands