@aporthq/aport-agent-guardrails 1.0.8

package/docs/launch/FRAMEWORK_SUPPORT_PLAN.md

@@ -0,0 +1,1640 @@
+# APort Framework Support Strategy & Architecture
+
+**Version:** 2.0 (Comprehensive)
+**Last Updated:** 2026-02-18
+**Status:** Living Document (Public)
+
+> **Implementation aligned with v1.0.8:** Package renames (npm/PyPI), PyPI automation, security hardening, and docs are reflected in [CHANGELOG.md](../../CHANGELOG.md). This plan’s “Implementation status” table and DEPLOYMENT_READINESS are the source of truth for what is shipped.
+
+> **Vision:** One command (`npx @aporthq/aport-agent-guardrails` or `pip install aport-agent-guardrails`) that brings pre-action authorization to ANY AI agent framework—code, low-code, or no-code.
+
+---
+
+## Implementation status (current vs plan)
+
+**Use this section when assessing readiness.** The plan below describes the target architecture; this table reflects what is **actually implemented** as of the last doc update.
+
+| Plan pillar | Implemented? | Where to look |
+|-------------|---------------|---------------|
+| **Shared layer** (passport wizard, policy packs, guardrail scripts, config helpers) | ✅ Yes | `bin/aport-create-passport.sh`, `bin/aport-guardrail-*.sh`, `bin/lib/*.sh`, `external/aport-policies/`. Tests: `tests/unit`, `tests/test-*.sh`. |
+| **Single dispatcher CLI** | ✅ Yes | `bin/agent-guardrails` — detection, `--framework`, env overrides. Tests: `tests/frameworks/<name>/setup.sh`. Framework scripts run wizard + write config; they do **not** auto-install pip/npm packages (except OpenClaw full installer). |
+| **TypeScript core (evaluator, config, passport)** | ✅ Yes | `packages/core/src/core/evaluator.ts`, `config.ts`, `passport.ts`, `pathUtils.ts` — full implementation: API + local bash, native fetch in sync path, config YAML, passport loading. **Fail-closed by default** when passport/script missing (`fail_open_when_missing_config` or `APORT_FAIL_OPEN_WHEN_MISSING_CONFIG=1` for legacy). Jest: `packages/core/src/core/*.test.ts`. |
+| **Node LangChain adapter** | ✅ Yes | `packages/langchain/src/middleware.ts` — `APortGuardrailCallback`, `GuardrailViolationError`, uses core `Evaluator`. Jest: `middleware.test.ts`. |
+| **Node CrewAI adapter** | ✅ Yes | `packages/crewai/src/middleware.ts` — `beforeToolCall`, `registerAPortGuardrail`, `withAPortGuardrail`, uses core `verifySync`; module-level Evaluator reuse. Feature parity with Python. |
+| **Node Cursor package** | ✅ Yes | `packages/cursor` — `Evaluator`, `getHookPath()`. `activate()`/`deactivate()` are no-op stubs reserved for future VS Code extension. Runtime enforcement is bash hook from CLI. |
+| **Python LangChain/CrewAI adapters** | ✅ Yes | `python/langchain_adapter`, `python/crewai_adapter` — PyPI packages, CLIs, E2E in CI. |
+| **OpenClaw plugin** | ✅ Yes | `extensions/openclaw-aport/`, `bin/openclaw` — full installer + tests. |
+| **Cursor hook** | ✅ Yes | `bin/frameworks/cursor.sh`, `bin/aport-cursor-hook.sh` — unit + integration tests. |
+| **n8n custom node** | ❌ No | n8n is **coming soon**. Config/installer only; no custom node; `@aporthq/aport-agent-guardrails-n8n` not published. See `docs/frameworks/n8n.md`. |
+| **Release CI** | ✅ Yes | `.github/workflows/release.yml` — on tag push: publishes root + core, langchain, crewai, cursor to npm; Python to PyPI; GitHub Release. |
+
+**Single source of truth for deployability:** [DEPLOYMENT_READINESS.md](../DEPLOYMENT_READINESS.md). Production-ready today: OpenClaw, Cursor, Python LangChain/CrewAI, **and** the Node CLI + Node packages (root, core, langchain, crewai, cursor).
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Original Request & Goals](#original-request--goals)
+3. [Architecture Overview](#architecture-overview)
+4. [Framework Rankings & Justification](#framework-rankings--justification)
+5. [Technical Architecture](#technical-architecture)
+6. [Repository Structure](#repository-structure)
+7. [Shared Components Strategy](#shared-components-strategy)
+8. [Per-Framework Integration Patterns](#per-framework-integration-patterns)
+9. [Implementation Roadmap](#implementation-roadmap)
+10. [Success Metrics](#success-metrics)
+11. [Open Questions](#open-questions)
+
+---
+
+## Executive Summary
+
+### The Problem
+Every AI agent framework (LangChain, CrewAI, OpenClaw, AutoGen, etc.) needs pre-action authorization, but each has different:
+- Runtime architecture (Node, Python, Rust)
+- Hook mechanisms (middleware, decorators, callbacks)
+- Configuration patterns
+- Developer personas (code vs low-code vs no-code)
+
+### The Solution
+**Single unified installer** for each language ecosystem that:
+1. **Detects or prompts** for target framework
+2. **Runs shared passport creation flow** (same wizard, same OAP v1.0 format)
+3. **Installs framework-specific integration** (middleware, decorator, config)
+4. **Supports hosted or local** (agent_id-only or passport.json)
+
+### The Architecture
+```
+Common Layer (Shared):
+  - Passport wizard (OAP v1.0)
+  - Policy packs (JSON, SHIELD import)
+  - Verification logic (API client or local evaluator)
+  - Config management
+
+Framework Layer (Diverges):
+  - Node: npm packages with framework-specific hooks
+  - Python: pip packages with decorators/middleware
+  - Low/No-Code: HTTP/webhook integrations
+```
+
+### The Opportunity
+- **200K+ GitHub stars** across top frameworks
+- **1M+ developers** building AI agents
+- **94% of enterprises** plan to expand agent use in 2026
+- **Minimal APort adoption today** = greenfield opportunity
+
+---
+
+## Original Request & Goals
+
+### User Request (Verbatim)
+> "I want a single command:
+> - `npx @aporthq/aport-agent-guardrails` for Node agent frameworks
+> - Similar command for Python (deploy to PyPI?)
+>
+> The tool should:
+> 1. First ask for the framework
+> 2. Passport creation happens the same way
+> 3. Only divergence: how passport is saved and evaluator (if local)
+>
+> Possible: packages for each framework for SEO, then main command calls sub-packages
+>
+> Goal: Find common reusable tools and utils. Think like a Staff Developer with extensive backend, opensource, security experience."
+
+### Success Criteria
+1. ✅ **Single entry point** per language (npx, pip)
+2. ✅ **Maximum code reuse** across frameworks
+3. ✅ **Minimal maintenance burden** for new frameworks
+4. ✅ **SEO/discovery** via framework-specific packages
+5. ✅ **Production-ready** architecture that scales
+
+---
+
+## Architecture Overview
+
+### High-Level Flow
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e','primaryBorderColor':'#0284c7'}}}%%
+flowchart TB
+    Start([Developer runs install command]) --> Detect[Detect or prompt for framework]
+    Detect --> Wizard[Shared Passport Wizard<br/>OAP v1.0 format]
+    Wizard --> Choice{Hosted or Local?}
+    Choice -->|Hosted| HostedFlow[agent_id only<br/>API verification]
+    Choice -->|Local| LocalFlow[passport.json<br/>Local or API verification]
+    HostedFlow --> Install[Install framework integration]
+    LocalFlow --> Install
+    Install --> Configure[Write framework config]
+    Configure --> Test[Run smoke test]
+    Test --> Done([✅ Ready to use])
+
+    style Start fill:#0277bd,stroke:#01579b,color:#fff
+    style Wizard fill:#ff6f00,stroke:#bf360c,color:#fff
+    style Install fill:#2e7d32,stroke:#1b5e20,color:#fff
+    style Done fill:#388e3c,stroke:#1b5e20,color:#fff
+```
+
+### Core Principle: Shared + Divergent
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ SHARED LAYER (90% of code)                                  │
+├─────────────────────────────────────────────────────────────┤
+│  • Passport wizard (bin/aport-create-passport.sh)           │
+│  • Policy packs (external/aport-policies/*)                 │
+│  • Verification logic (src/evaluator.js, bin/*-bash.sh)     │
+│  • Config templates (lib/templates/*.yaml)                  │
+│  • Status/diagnostic tools (bin/aport-status.sh)            │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+        ┌────────────┴────────────┬──────────────┐
+        ▼                         ▼              ▼
+┌───────────────┐   ┌─────────────────┐   ┌──────────────┐
+│ NODE LAYER    │   │ PYTHON LAYER    │   │ HTTP LAYER   │
+├───────────────┤   ├─────────────────┤   ├──────────────┤
+│ • TypeScript  │   │ • Decorators    │   │ • Webhooks   │
+│   middleware  │   │ • Async context │   │ • REST API   │
+│ • Config:     │   │ • Config:       │   │ • Config:    │
+│   YAML/JSON   │   │   .aport/       │   │   URL + key  │
+└───────────────┘   └─────────────────┘   └──────────────┘
+```
+
+---
+
+## Framework Rankings & Justification
+
+### Ranking Methodology
+
+**Scoring Matrix (100 points total):**
+- **Estimated Users (30 pts):** GitHub stars, downloads, community size
+- **ROI vs Effort (25 pts):** Integration complexity vs adoption potential
+- **APort Adoption Potential (25 pts):** How well pre-action authorization fits use case
+- **Strategic Value (20 pts):** Ecosystem position, enterprise adoption, growth trajectory
+
+### Rankings Table
+
+| Rank | Framework | Category | Est. Users | Effort | ROI Score | APort Fit | Total | Status | Notes |
+|------|-----------|----------|------------|--------|-----------|-----------|-------|--------|-------|
+| **1** | **OpenClaw** | Code (Node) | 200K+ ⭐ | Low | 25/25 | 25/25 | **95/100** | ✅ Shipped | Already integrated; moving to OpenAI foundation |
+| **2** | **LangChain/LangGraph** | Code (Python) | 80K+ ⭐, massive enterprise | Medium | 24/25 | 24/25 | **92/100** | 🎯 Priority | Market leader, proven enterprise adoption |
+| **3** | **Cursor IDE** | IDE (Node/Electron) | 1M+ users, $500M ARR | Medium | 23/25 | 25/25 | **91/100** | 🎯 Priority | 50% Fortune 500 use it; pre-execution hooks needed |
+| **4** | **CrewAI** | Code (Python) | 20K+ ⭐, growing fast | Medium | 22/25 | 23/25 | **88/100** | 🎯 Priority | Multi-agent focus; strong community |
+| **5** | **n8n** | Low-Code (Node) | 50K+ ⭐, open-source | Low | 23/25 | 21/25 | **87/100** | 🚀 High | 70+ AI nodes; webhook integration simple |
+| **6** | **Microsoft AutoGen** | Code (Python) | 35K+ ⭐, MS backing | Medium | 21/25 | 22/25 | **86/100** | 🚀 High | Enterprise adoption; Microsoft ecosystem |
+| **7** | **Zapier AI Actions** | No-Code | 8000+ app integrations | Low | 20/25 | 20/25 | **83/100** | 🚀 High | Largest connector library; webhook integration |
+| **8** | **FlowiseAI** | Low-Code (Node) | 30K+ ⭐ | Low | 21/25 | 19/25 | **82/100** | 🟡 Medium | LangChain-based; visual builder |
+| **9** | **LlamaIndex Agents** | Code (Python) | 40K+ ⭐ | Medium | 19/25 | 20/25 | **81/100** | 🟡 Medium | RAG + agents; callback hooks |
+| **10** | **Semantic Kernel** | Code (C#/Python) | 22K+ ⭐, MS backing | High | 18/25 | 20/25 | **80/100** | 🟡 Medium | .NET ecosystem; enterprise focus |
+| **11** | **Goose CLI** | Code (Node) | Developer tool | Medium | 19/25 | 19/25 | **78/100** | 🟡 Medium | CLI-first; hook system exists |
+| **12** | **OpenAI Agents SDK** | Code (Python/Node) | Official OpenAI | Medium | 18/25 | 21/25 | **77/100** | ⏳ Future | SDK still evolving; wait for stable API |
+| **13** | **IronClaw** | Code (Rust/Node) | OpenClaw fork | Medium | 17/25 | 18/25 | **76/100** | ⏳ Future | Rust performance focus |
+| **14** | **Anthropic Tool Use** | Code (Python) | Official Claude | Medium | 17/25 | 19/25 | **75/100** | ⏳ Future | Tool use SDK; callback hooks |
+| **15** | **Windsurf IDE** | IDE (Node) | 100K+ users, growing | Medium | 16/25 | 18/25 | **74/100** | ⏳ Future | Cascades multi-file editing |
+| **16** | **Make (Integromat)** | No-Code | 500K+ users | Low | 18/25 | 16/25 | **73/100** | 🟡 Medium | Visual automation; HTTP modules |
+| **17** | **AutoGPT** | Code (Python) | 180K+ ⭐ (legacy) | High | 14/25 | 17/25 | **71/100** | 🔵 Backlog | Declining activity; watch for resurgence |
+| **18** | **Temporal Workflows** | Code (Go/TS) | Enterprise infra | High | 16/25 | 16/25 | **70/100** | 🔵 Backlog | Activity interceptors exist |
+| **19** | **AWS Bedrock Agents** | Cloud (Python) | AWS ecosystem | Medium | 15/25 | 17/25 | **69/100** | 🔵 Backlog | Lambda hooks; IAM integration |
+| **20** | **Langroid** | Code (Python) | 4K+ ⭐ | Medium | 14/25 | 15/25 | **67/100** | 🔵 Backlog | Actor-based; smaller community |
+| **21** | **PicoClaw** | Code (Go) | OpenClaw fork | High | 13/25 | 15/25 | **66/100** | 🔵 Backlog | Go ecosystem; smaller base |
+| **22** | **Google AI Studio** | Cloud (Python/Node) | Google ecosystem | Medium | 13/25 | 16/25 | **65/100** | 🔵 Backlog | Guardrail APIs exist |
+| **23** | **NanoClaw** | Code (Python) | OpenClaw fork | High | 12/25 | 14/25 | **64/100** | 🔵 Backlog | Python port; smaller base |
+| **24** | **Slack Bolt Framework** | Code (Node/Python) | Enterprise bots | Medium | 12/25 | 13/25 | **62/100** | 🔵 Backlog | Middleware hooks; bot focus |
+| **25** | **Microsoft Teams Bots** | Code (C#/Node) | Enterprise | Medium | 11/25 | 13/25 | **60/100** | 🔵 Backlog | Bot framework; Azure integration |
+
+### Category Breakdown
+
+#### Code Frameworks (Python) — 8 frameworks
+**Why prioritize:** Largest AI/ML developer community, established patterns (decorators, async middleware)
+
+**Top Picks:**
+1. LangChain/LangGraph (92/100) — Market leader
+2. CrewAI (88/100) — Multi-agent specialist
+3. Microsoft AutoGen (86/100) — Enterprise backing
+
+#### Code Frameworks (Node/TypeScript) — 6 frameworks
+**Why prioritize:** Web3, DevTools, IDE extensions; TypeScript = enterprise adoption
+
+**Top Picks:**
+1. OpenClaw (95/100) — Already shipped
+2. n8n (87/100) — Low-code + code hybrid
+3. FlowiseAI (82/100) — Visual LangChain
+
+#### IDE/Editor Extensions — 3 frameworks
+**Why prioritize:** Developers use daily; massive potential reach
+
+**Top Picks:**
+1. Cursor IDE (91/100) — $500M ARR, 50% Fortune 500
+2. Windsurf (74/100) — Growing Cascade competitor
+3. VS Code extensions (future)
+
+#### Low-Code/No-Code — 4 frameworks
+**Why prioritize:** Non-technical users; simple HTTP integration; massive TAM
+
+**Top Picks:**
+1. n8n (87/100) — Open-source; 70+ AI nodes
+2. Zapier AI (83/100) — 8000+ integrations
+3. Make (73/100) — 500K+ users
+
+#### Cloud Platforms — 3 frameworks
+**Why prioritize:** Enterprise budgets; compliance requirements
+
+**Top Picks:**
+1. AWS Bedrock Agents (69/100) — Lambda hooks
+2. Google AI Studio (65/100) — Guardrail APIs
+3. Azure (future)
+
+---
+
+## Technical Architecture
+
+### 1. Single Command, Multiple Entry Points
+
+#### Node Ecosystem
+
+```bash
+# Option 1: Main CLI (detects framework)
+npx @aporthq/aport-agent-guardrails
+
+# Option 2: Framework-specific (SEO)
+npx @aporthq/aport-agent-guardrails-langchain
+npx @aporthq/aport-agent-guardrails-crewai
+npx @aporthq/aport-agent-guardrails-n8n
+
+# Option 3: Direct framework argument
+npx @aporthq/aport-agent-guardrails --framework=langchain
+```
+
+#### Python Ecosystem
+
+```bash
+# Option 1: Main CLI
+pip install aport-agent-guardrails
+aport setup
+
+# Option 2: Framework-specific (SEO)
+pip install aport-agent-guardrails-langchain
+aport-langchain setup
+
+# Option 3: Python module
+python -m aport_guardrails --framework=crewai
+```
+
+### 2. Package Strategy: Monorepo + SEO Packages
+
+```
+Repository Structure:
+aport-agent-guardrails/
+  packages/
+    core/                    # @aporthq/aport-agent-guardrails (main)
+    langchain/               # @aporthq/aport-agent-guardrails-langchain
+    crewai/                  # @aporthq/aport-agent-guardrails-crewai
+    n8n/                     # @aporthq/aport-agent-guardrails-n8n
+  python/
+    aport_guardrails/        # aport-agent-guardrails (main)
+    langchain_adapter/       # aport-agent-guardrails-langchain
+    crewai_adapter/          # aport-agent-guardrails-crewai
+
+Strategy:
+  - Main package = full installer with all adapters
+  - Framework-specific = thin wrapper calling main package
+  - Benefits: SEO (appears in "langchain security"), discoverability
+```
+
+### 3. Shared Components (90% Reuse)
+
+#### Core Shared Logic
+
+```
+bin/
+  lib/
+    common.sh               # Shared bash functions
+    passport.sh             # Passport creation wizard
+    config.sh               # Config file management
+    allowlist.sh            # Command allowlisting
+  aport-create-passport.sh  # Main wizard (all frameworks use this)
+  aport-status.sh           # Status checker (all frameworks)
+
+src/
+  core/
+    evaluator.ts            # API verification client (Node)
+    passport.ts             # Passport schema validation
+    config.ts               # Config management
+  evaluators/
+    api.ts                  # API mode evaluator
+    local.ts                # Local bash evaluator wrapper
+
+python/
+  aport_guardrails/
+    core/
+      evaluator.py          # API verification client (Python)
+      passport.py           # Passport schema validation
+      config.py             # Config management
+    evaluators/
+      api.py                # API mode evaluator
+      local.py              # Local evaluator wrapper
+
+external/                   # Git submodules (shared policies)
+  aport-policies/
+    system.command.execute.v1/
+    mcp.tool.execute.v1/
+    [... other policy packs ...]
+```
+
+#### What's Shared (Same Code Everywhere)
+
+1. **Passport Creation** (bin/aport-create-passport.sh)
+   - OAP v1.0 wizard
+   - JSON schema validation
+   - Hosted vs local choice
+   - Credential storage
+
+2. **Policy Packs** (external/aport-policies/)
+   - JSON definitions
+   - SHIELD import
+   - Evaluation rules
+   - All frameworks reference same files
+
+3. **Verification Logic** (`packages/core/src/core/evaluator.ts`, `python/aport_guardrails/core/evaluator.py`)
+   - **Both implemented.** Node: API + local bash, native fetch in sync path; Python: API + local. Request/response handling, error handling, config/passport loading.
+
+4. **Config Management** (src/core/config.ts, python/aport_guardrails/core/config.py)
+   - Read/write config files
+   - Environment variable handling
+   - Credential management
+
+#### What Diverges (Framework-Specific)
+
+1. **Integration Hook** (where guardrail is called)
+   - LangChain: AsyncCallbackHandler
+   - CrewAI: Task decorator
+   - OpenClaw: before_tool_call plugin
+   - n8n: Custom HTTP node
+
+2. **Config File Location**
+   - OpenClaw: ~/.openclaw/aport-config.yaml
+   - LangChain: .aport/config.yaml or ~/.aport/langchain/
+   - n8n: n8n credentials store
+
+3. **Middleware/Decorator Pattern**
+   - Node: TypeScript classes
+   - Python: async decorators
+   - No-code: HTTP webhook
+
+### 4. Verification Flow (Identical Logic, Different Wrappers)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e'}}}%%
+sequenceDiagram
+    participant Framework as 🔧 Framework<br/>(LangChain/OpenClaw/n8n)
+    participant Adapter as 📦 APort Adapter<br/>(framework-specific)
+    participant Core as 🛡️ Core Evaluator<br/>(shared)
+    participant API as 🌐 APort API<br/>(or local script)
+
+    Framework->>Adapter: Tool call intercepted
+    Note over Adapter: Maps tool → OAP capability<br/>(framework-specific logic)
+    Adapter->>Core: evaluate(passport, policy, context)
+    Note over Core: Load config, prepare request<br/>(shared logic)
+    Core->>API: POST /api/verify
+    API-->>Core: Allow/Deny + reasons
+    Note over Core: Parse decision, log audit<br/>(shared logic)
+    Core-->>Adapter: Decision object
+    Note over Adapter: Format framework response<br/>(framework-specific)
+    Adapter-->>Framework: Allow or throw error
+```
+
+**Key Insight:** Only the adapter layer (10% of code) is framework-specific. 90% is shared.
+
+---
+
+## Repository Structure
+
+### Current State (OpenClaw-focused)
+
+```
+aport-agent-guardrails/
+├── bin/
+│   ├── openclaw                    # OpenClaw-specific setup
+│   ├── aport-create-passport.sh    # Shared wizard
+│   ├── aport-guardrail-bash.sh     # Local evaluator
+│   └── aport-guardrail-api.sh      # API evaluator
+├── src/
+│   ├── evaluator.js                # API client
+│   └── server/                     # Optional proxy
+├── extensions/
+│   └── openclaw-aport/             # OpenClaw plugin
+├── external/                       # Git submodules
+│   ├── aport-spec/
+│   └── aport-policies/
+├── docs/
+├── tests/
+└── package.json
+```
+
+### Target State (Multi-Framework)
+
+```
+aport-agent-guardrails/
+├── bin/
+│   ├── agent-guardrails            # 🆕 Main dispatcher
+│   ├── lib/
+│   │   ├── common.sh               # 🆕 Shared bash functions
+│   │   ├── passport.sh             # 🆕 Refactored wizard logic
+│   │   ├── config.sh               # 🆕 Config helpers
+│   │   └── templates/              # 🆕 Config templates
+│   ├── frameworks/                 # 🆕 Framework scripts
+│   │   ├── openclaw.sh
+│   │   ├── langchain.sh
+│   │   ├── crewai.sh
+│   │   └── n8n.sh
+│   ├── aport-create-passport.sh    # Now calls lib/passport.sh
+│   ├── aport-guardrail-bash.sh     # Local evaluator
+│   └── aport-guardrail-api.sh      # API evaluator
+├── packages/                       # 🆕 Monorepo packages
+│   ├── core/                       # @aporthq/aport-agent-guardrails
+│   │   ├── src/
+│   │   │   ├── index.ts            # Main CLI entry point
+│   │   │   ├── core/
+│   │   │   │   ├── evaluator.ts    # Shared evaluator
+│   │   │   │   ├── passport.ts     # Passport handling
+│   │   │   │   └── config.ts       # Config management
+│   │   │   ├── frameworks/         # Framework adapters
+│   │   │   │   ├── base.ts         # Base adapter class
+│   │   │   │   ├── openclaw.ts
+│   │   │   │   ├── langchain.ts
+│   │   │   │   └── n8n.ts
+│   │   │   └── cli.ts              # CLI logic
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   ├── langchain/                  # @aporthq/aport-agent-guardrails-langchain
+│   │   ├── src/
+│   │   │   ├── index.ts            # Exports middleware
+│   │   │   └── middleware.ts       # LangChain callback
+│   │   └── package.json            # Thin wrapper → core
+│   ├── crewai/                     # @aporthq/aport-agent-guardrails-crewai
+│   ├── n8n/                        # @aporthq/aport-agent-guardrails-n8n
+│   └── cursor/                     # @aporthq/aport-agent-guardrails-cursor
+├── python/                         # 🆕 Python packages
+│   ├── aport_guardrails/           # aport-agent-guardrails (main)
+│   │   ├── __init__.py
+│   │   ├── cli.py                  # Main CLI
+│   │   ├── core/
+│   │   │   ├── evaluator.py        # Shared evaluator
+│   │   │   ├── passport.py
+│   │   │   └── config.py
+│   │   ├── frameworks/
+│   │   │   ├── base.py
+│   │   │   ├── langchain.py
+│   │   │   └── crewai.py
+│   │   └── setup.py
+│   ├── langchain_adapter/          # aport-agent-guardrails-langchain
+│   │   ├── __init__.py             # Exports decorator
+│   │   ├── middleware.py           # LangChain async callback
+│   │   └── setup.py                # Depends on aport-agent-guardrails
+│   └── crewai_adapter/             # aport-agent-guardrails-crewai
+├── integrations/                   # 🆕 Framework-specific code
+│   ├── openclaw/
+│   │   └── extensions/             # Plugin code
+│   ├── langchain/
+│   │   ├── middleware.py           # Python middleware
+│   │   ├── middleware.ts           # Node middleware
+│   │   └── examples/
+│   ├── crewai/
+│   │   ├── decorator.py            # Task decorator
+│   │   └── examples/
+│   ├── n8n/
+│   │   ├── nodes/                  # Custom nodes
+│   │   └── credentials/
+│   └── cursor/
+│       └── extension/              # VS Code extension
+├── extensions/
+│   └── openclaw-aport/             # Keep for backward compat
+├── external/                       # Git submodules (unchanged)
+│   ├── aport-spec/
+│   └── aport-policies/
+├── docs/
+│   ├── frameworks/                 # 🆕 Per-framework docs
+│   │   ├── openclaw.md
+│   │   ├── langchain.md
+│   │   ├── crewai.md
+│   │   └── n8n.md
+│   └── FRAMEWORK_SUPPORT_PLAN.md   # This doc
+├── tests/
+│   ├── core/                       # Shared tests
+│   └── frameworks/                 # Framework-specific tests
+├── lerna.json                      # 🆕 Monorepo management
+├── package.json                    # Root package
+└── pyproject.toml                  # 🆕 Python monorepo
+```
+
+### Key Design Decisions
+
+1. **Monorepo Structure**
+   - ✅ **Pro:** Single source of truth; atomic changes across frameworks
+   - ✅ **Pro:** Shared CI/CD; easier version management
+   - ⚠️ **Con:** Larger repo size
+   - **Verdict:** Use Lerna (Node) + Poetry workspaces (Python)
+
+2. **Framework-Specific Packages**
+   - ✅ **Pro:** SEO (show up in "langchain security" searches)
+   - ✅ **Pro:** Lighter install for single-framework users
+   - ✅ **Pro:** Clear entry point per framework
+   - **Implementation:** Thin wrappers that depend on core package
+
+3. **Shared vs Separate Git Repos**
+   - ❌ **Separate:** Hard to keep passport wizard in sync
+   - ✅ **Single repo:** Easier to maintain shared logic
+   - **Verdict:** Single repo with clear boundaries
+
+---
+
+## Shared Components Strategy
+
+### What Must Be Shared (Non-Negotiable)
+
+#### 1. Passport Format (OAP v1.0)
+**Why:** Interoperability. Same passport works across all frameworks.
+
+**Shared Files:**
+- `external/aport-spec/oap/oap-spec.md` (submodule)
+- `bin/aport-create-passport.sh` (wizard)
+- Schema validation in evaluator
+
+**Framework Divergence:** Only storage location
+- OpenClaw: `~/.openclaw/passport.json`
+- LangChain: `~/.aport/langchain/passport.json`
+- Hosted: No file (agent_id only)
+
+#### 2. Policy Packs
+**Why:** Consistency. Same policy definitions across frameworks.
+
+**Shared Files:**
+- `external/aport-policies/` (submodule)
+- All JSON policy packs
+- SHIELD import adapter
+
+**Framework Divergence:** Policy → tool mapping
+- OpenClaw: `exec.run` → `system.command.execute.v1`
+- LangChain: `ShellTool` → `system.command.execute.v1`
+- Different tool names, same policy
+
+#### 3. Verification Logic
+**Why:** Security. Core authorization logic must be identical.
+
+**Shared Implementation:**
+```typescript
+// packages/core/src/core/evaluator.ts
+export class Evaluator {
+  async verify(
+    passport: Passport,
+    policy: PolicyPack,
+    context: ToolContext
+  ): Promise<Decision> {
+    // 1. Load config (API URL, agent_id)
+    // 2. Prepare request body
+    // 3. Call API or local script
+    // 4. Parse decision
+    // 5. Log audit trail
+    // 6. Return allow/deny
+  }
+}
+```
+
+**Python Mirror:**
+```python
+# python/aport_guardrails/core/evaluator.py
+class Evaluator:
+    async def verify(
+        self,
+        passport: Passport,
+        policy: PolicyPack,
+        context: ToolContext
+    ) -> Decision:
+        # Identical logic to TypeScript
+```
+
+**Framework Divergence:** Only the wrapper
+- LangChain: Calls evaluator from `AsyncCallbackHandler`
+- OpenClaw: Calls evaluator from plugin
+- n8n: Calls evaluator from HTTP node
+
+### What Can Diverge (Framework-Specific)
+
+#### 1. Integration Hook
+**Why:** Each framework has different extension APIs.
+
+**Examples:**
+- **LangChain:** `AsyncCallbackHandler.on_tool_start()`
+- **CrewAI:** `@task_wrapper` decorator
+- **OpenClaw:** `before_tool_call` plugin
+- **n8n:** Custom HTTP node
+
+#### 2. Config File Format
+**Why:** Match framework conventions.
+
+**Examples:**
+- **OpenClaw:** YAML in `~/.openclaw/aport-config.yaml`
+- **LangChain:** JSON in `.aport/config.json`
+- **n8n:** Stored in n8n credentials
+
+**Shared Logic:** All configs have same fields, just different serialization.
+
+#### 3. Installation Flow
+**Why:** Different frameworks have different setup steps.
+
+**Shared Steps (90%):**
+1. Prompt for framework
+2. Run passport wizard (shared)
+3. Choose hosted or local (shared)
+4. Write config (shared logic, different path)
+5. Run smoke test (shared)
+
+**Divergent Steps (10%):**
+- OpenClaw: Install plugin via `~/.openclaw/config.yaml`
+- LangChain: Add middleware import to user code
+- n8n: Install custom node via UI
+
+### Shared Utils Library
+
+```typescript
+// packages/core/src/utils/index.ts
+export class SharedUtils {
+  // Config management
+  static loadConfig(path: string): Config { }
+  static writeConfig(path: string, config: Config): void { }
+
+  // Passport handling
+  static loadPassport(pathOrAgentId: string): Passport { }
+  static validatePassport(passport: Passport): ValidationResult { }
+
+  // Policy management
+  static loadPolicy(capability: string): PolicyPack { }
+  static mapToolToCapability(frameworkName: string, toolName: string): string { }
+
+  // Verification
+  static async callVerifyAPI(req: VerifyRequest): Promise<VerifyResponse> { }
+  static parseDecision(response: VerifyResponse): Decision { }
+
+  // Audit
+  static logDecision(decision: Decision, context: Context): void { }
+}
+```
+
+**Why this works:**
+- All frameworks import `@aporthq/aport-agent-guardrails-core`
+- Framework adapters call `SharedUtils` methods
+- Changes to shared logic update all frameworks instantly
+
+---
+
+## Per-Framework Integration Patterns
+
+### Pattern Categories
+
+#### Category A: Code Frameworks (Middleware/Decorator)
+**Examples:** LangChain, CrewAI, AutoGen
+
+**Integration Pattern:**
+1. User imports middleware/decorator
+2. Middleware wraps tool execution
+3. Calls shared evaluator before tool runs
+4. Returns allow/deny
+
+**Code Example (LangChain):**
+```python
+from langchain.callbacks import AsyncCallbackHandler
+from aport_guardrails.core import Evaluator
+
+class APortGuardrailCallback(AsyncCallbackHandler):
+    def __init__(self, passport_path: str):
+        self.evaluator = Evaluator(passport_path)
+
+    async def on_tool_start(self, tool_name: str, input_str: str, **kwargs):
+        # Map tool name to OAP capability
+        capability = self._map_tool(tool_name)
+
+        # Load policy pack for capability
+        policy = self.evaluator.load_policy(capability)
+
+        # Prepare context
+        context = {"tool": tool_name, "input": input_str}
+
+        # Verify
+        decision = await self.evaluator.verify(
+            passport=self.passport,
+            policy=policy,
+            context=context
+        )
+
+        # Deny if not allowed
+        if not decision.allow:
+            raise PermissionError(decision.reasons[0].message)
+
+# User code:
+from langchain.agents import AgentExecutor
+agent = AgentExecutor(
+    callbacks=[APortGuardrailCallback("~/.aport/passport.json")]
+)
+```
+
+#### Category B: Plugin Architectures (Hooks)
+**Examples:** OpenClaw, Cursor, Windsurf
+
+**Integration Pattern:**
+1. User installs plugin via framework's plugin manager
+2. Plugin registers hooks (before_tool_call, etc.)
+3. Hook calls shared evaluator
+4. Hook returns block=true/false
+
+**Code Example (OpenClaw - already implemented):**
+```typescript
+// extensions/openclaw-aport/src/index.ts
+export async function before_tool_call(
+  tool: Tool,
+  params: ToolParams
+): Promise<{ block: boolean; blockReason?: string }> {
+  const evaluator = new Evaluator(config.passportPath);
+  const decision = await evaluator.verify(passport, policy, params);
+
+  if (!decision.allow) {
+    return { block: true, blockReason: decision.reasons[0].message };
+  }
+  return { block: false };
+}
+```
+
+#### Category C: Low-Code/No-Code (HTTP/Webhook)
+**Examples:** n8n, Zapier, Make, FlowiseAI
+
+**Integration Pattern:**
+1. User adds HTTP request node before action
+2. Node calls APort API (or self-hosted)
+3. Workflow branches on allow/deny
+4. Action executes only if allowed
+
+**Visual Flow (n8n):**
+```
+[Trigger] → [HTTP: APort Verify] → [IF: allow?]
+                                        ├─ Yes → [Action Node]
+                                        └─ No → [Send Error Notification]
+```
+
+**Implementation:**
+- Provide n8n custom node (TypeScript)
+- Node wraps evaluator.verify()
+- User drags node into workflow
+
+#### Category D: IDE Extensions
+**Examples:** Cursor, Windsurf, VS Code, JetBrains
+
+**Integration Pattern:**
+1. Extension hooks into IDE's agent API
+2. Before agent executes command, call evaluator
+3. Show approval dialog if required
+4. Block execution if denied
+
+**Code Example (Cursor):**
+```typescript
+// Extension: cursor_aport.ts
+import * as vscode from 'vscode';
+import { Evaluator } from '@aporthq/aport-agent-guardrails-core';
+
+export function activate(context: vscode.ExtensionContext) {
+  const evaluator = new Evaluator(/* config */);
+
+  // Hook into Cursor's agent API (pseudocode)
+  cursor.agent.onBeforeToolExecute(async (tool, params) => {
+    const decision = await evaluator.verify(passport, policy, params);
+    if (!decision.allow) {
+      vscode.window.showErrorMessage(decision.reasons[0].message);
+      return { cancel: true };
+    }
+  });
+}
+```
+
+### Framework-Specific Details
+
+#### 1. OpenClaw (Already Implemented) ✅
+
+**Current Integration:**
+- Plugin: `extensions/openclaw-aport/`
+- Hook: `before_tool_call`
+- Config: `~/.openclaw/aport-config.yaml`
+- Status: Shipped, in production
+
+**Refactor for Multi-Framework:**
+- Move to `integrations/openclaw/`
+- Extract shared logic to `packages/core/`
+- Keep `bin/frameworks/openclaw.sh` as installer
+
+#### 2. LangChain/LangGraph 🎯
+
+**Integration:**
+- Package: `aport-agent-guardrails-langchain` (Python)
+- Hook: `AsyncCallbackHandler.on_tool_start`
+- Config: `.aport/config.yaml` or `~/.aport/langchain/`
+
+**Installation Flow:**
+```bash
+pip install aport-agent-guardrails-langchain
+aport-langchain setup
+# → Runs passport wizard
+# → Writes .aport/config.yaml
+# → Prints code snippet
+```
+
+**User Code:**
+```python
+from langchain.agents import initialize_agent
+from aport_guardrails_langchain import APortCallback
+
+agent = initialize_agent(
+    tools=tools,
+    llm=llm,
+    callbacks=[APortCallback()]  # Auto-loads from .aport/config.yaml
+)
+```
+
+**Effort:** Medium (3-5 days)
+- AsyncCallbackHandler implementation
+- Tool name → capability mapping
+- Documentation + examples
+
+#### 3. CrewAI 🎯
+
+**Integration:**
+- Package: `aport-agent-guardrails-crewai` (Python)
+- Hook: Task decorator or crew-level middleware
+- Config: `.aport/config.yaml`
+
+**Installation Flow:**
+```bash
+pip install aport-agent-guardrails-crewai
+aport-crewai setup
+```
+
+**User Code:**
+```python
+from crewai import Task, Crew
+from aport_guardrails_crewai import with_aport_guardrail
+
+@with_aport_guardrail
+class MyTask(Task):
+    def execute(self, context):
+        # Task logic
+        pass
+
+crew = Crew(tasks=[MyTask()])
+```
+
+**Effort:** Medium (3-5 days)
+- Decorator implementation
+- Hook into CrewAI task execution
+- Multi-agent orchestration support
+
+#### 4. Cursor IDE 🎯
+
+**Integration:**
+- Package: `@aporthq/aport-agent-guardrails-cursor` (Node)
+- Hook: VS Code extension API
+- Config: VS Code settings.json
+
+**Installation Flow:**
+```bash
+npx @aporthq/aport-agent-guardrails cursor
+# → Runs passport wizard
+# → Installs VS Code extension
+# → Configures extension settings
+```
+
+**User Experience:**
+1. Cursor agent suggests command
+2. Extension intercepts before execution
+3. Shows inline approval UI if needed
+4. Blocks if denied
+
+**Effort:** Medium-High (5-7 days)
+- VS Code extension boilerplate
+- Hook into Cursor agent API (if available)
+- UI for approval dialogs
+- Marketplace submission
+
+#### 5. n8n 🚀
+
+**Integration:**
+- Package: `@aporthq/aport-agent-guardrails-n8n` (Node)
+- Hook: Custom node
+- Config: n8n credentials store
+
+**Installation Flow:**
+```bash
+npx @aporthq/aport-agent-guardrails n8n
+# → Runs passport wizard
+# → Installs custom node in ~/.n8n/custom/
+# → Adds credentials type
+```
+
+**User Experience:**
+1. User drags "APort Guardrail" node into workflow
+2. Node configured with agent_id or passport path
+3. Connect to action nodes
+4. Workflow routes on allow/deny
+
+**Effort:** Low-Medium (2-4 days)
+- n8n custom node (TypeScript)
+- Credentials type definition
+- Documentation + example workflows
+
+#### 6. Microsoft AutoGen 🚀
+
+**Integration:**
+- Package: `aport-agent-guardrails-autogen` (Python)
+- Hook: UserProxyAgent tool execution wrapper
+- Config: `.aport/config.yaml`
+
+**Installation Flow:**
+```bash
+pip install aport-agent-guardrails-autogen
+aport-autogen setup
+```
+
+**User Code:**
+```python
+from autogen import UserProxyAgent
+from aport_guardrails_autogen import APortProxyAgent
+
+agent = APortProxyAgent(
+    name="assistant",
+    # APort guardrail wraps tool execution
+)
+```
+
+**Effort:** Medium (3-5 days)
+- Wrap UserProxyAgent or extend
+- Hook into multi-agent conversations
+- Handle approval requests in chat
+
+#### 7. Zapier AI Actions 🚀
+
+**Integration:**
+- Package: None (HTTP only)
+- Hook: Webhook node
+- Config: Zapier Code step
+
+**Installation Flow:**
+```
+Documentation page with Zapier template:
+1. Add "Webhooks by Zapier" action
+2. POST to https://api.aport.io/api/verify
+3. Body: { agentId, capability, context }
+4. Branch on response.allow
+```
+
+**User Experience:**
+1. User imports Zapier template
+2. Configures agent_id in template
+3. Template checks permission before action
+4. Sends notification if denied
+
+**Effort:** Low (1-2 days)
+- Create Zapier template
+- Documentation
+- Video tutorial
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Weeks 1-2)
+
+**Goal:** Refactor existing codebase for multi-framework support
+
+**Tasks:**
+1. ✅ Create monorepo structure
+   - Set up Lerna for Node packages
+   - Set up Poetry for Python packages
+   - Migrate existing code to `packages/core/`
+
+2. ✅ Extract shared components
+   - Refactor `bin/aport-create-passport.sh` → `bin/lib/passport.sh`
+   - Create `bin/lib/common.sh` with shared functions
+   - Extract evaluator to `packages/core/src/core/evaluator.ts`
+
+3. ✅ Create framework dispatcher
+   - Implement `bin/agent-guardrails` (main entry point)
+   - Implement framework detection
+   - Implement framework selection prompt
+
+4. ✅ Migrate OpenClaw integration
+   - Move to `integrations/openclaw/`
+   - Create `bin/frameworks/openclaw.sh`
+   - Ensure backward compatibility
+
+**Deliverables:**
+- ✅ Monorepo structure
+- ✅ Shared components extracted
+- ✅ OpenClaw still works (no regression)
+- ✅ Foundation for new frameworks
+
+### Phase 2: Priority Frameworks (Weeks 3-6)
+
+**Goal:** Ship top 3 frameworks (LangChain, Cursor, CrewAI)
+
+**Current status:** ✅ Delivered. Node packages (`packages/core`, `langchain`, `crewai`, `cursor`) are implemented with real evaluator and adapters; Jest tests for core and langchain; CI publishes to npm on tag. Python adapters and Cursor hook were already shipped. See [Implementation status (current vs plan)](#implementation-status-current-vs-plan) above.
+
+#### Week 3: LangChain/LangGraph
+- ✅ Implement `packages/langchain/` (Node) — APortGuardrailCallback, Jest tests
+- ✅ Implement `python/langchain_adapter/` (Python)
+- Create `bin/frameworks/langchain.sh` installer
+- Write docs + examples
+- Test with real LangChain agents
+
+#### Week 4: Cursor IDE
+- Implement `packages/cursor/` (VS Code extension)
+- Create `bin/frameworks/cursor.sh` installer
+- Build approval UI
+- Submit to VS Code marketplace
+- Write docs + video tutorial
+
+#### Week 5: CrewAI
+- ✅ Implement `python/crewai_adapter/`
+- ✅ Implement `packages/crewai/` (Node) — beforeToolCall, withAPortGuardrail
+- ✅ Create `bin/frameworks/crewai.sh` installer
+- Test with multi-agent crews
+- Write docs + examples
+
+#### Week 6: Testing & Launch Prep
+- E2E tests for all frameworks
+- CI/CD for multi-package publishing
+- Update main README
+- Launch announcement prep
+
+**Deliverables:**
+- ✅ LangChain integration (Python + Node)
+- ✅ Cursor IDE integration (hook + Node package)
+- ✅ CrewAI integration (Python + Node)
+- ✅ TypeScript core (evaluator, config, passport) with Jest
+- ✅ Documentation for all three; release CI
+- ✅ Ready to announce
+
+### Phase 3: Low-Code/No-Code (Weeks 7-8)
+
+**Goal:** Ship n8n, Zapier, FlowiseAI
+
+#### Week 7: n8n
+- Implement `packages/n8n/` custom node
+- Create credentials type
+- Write installer + docs
+- Submit to n8n community nodes
+
+#### Week 8: Zapier + FlowiseAI
+- Create Zapier template
+- Write HTTP integration guide
+- FlowiseAI custom node (similar to n8n)
+- Video tutorials for all three
+
+**Deliverables:**
+- ✅ n8n custom node
+- ✅ Zapier template
+- ✅ FlowiseAI integration
+- ✅ No-code user docs
+
+### Phase 4: Expand & Optimize (Weeks 9-12)
+
+**Goal:** Add remaining high-value frameworks, optimize shared code
+
+#### Week 9: Microsoft AutoGen + Semantic Kernel
+- AutoGen Python adapter
+- Semantic Kernel (Python + C#)
+
+#### Week 10: LlamaIndex + OpenAI Agents SDK
+- LlamaIndex callback hooks
+- OpenAI Agents SDK (when stable)
+
+#### Week 11: Goose + IDE Extensions
+- Goose CLI integration
+- Windsurf extension
+
+#### Week 12: Optimization & Cloud Frameworks
+- Performance optimization
+- AWS Bedrock integration
+- Google AI Studio integration
+
+**Deliverables:**
+- ✅ 10+ frameworks supported
+- ✅ Performance benchmarks
+- ✅ Cloud platform integrations
+
+### Phase 5: Long Tail & Enterprise (Ongoing)
+
+**Goal:** Cover backlog frameworks, enterprise features
+
+**Backlog (as needed):**
+- IronClaw, PicoClaw, NanoClaw (OpenClaw forks)
+- Temporal Workflows
+- Slack/Teams bot frameworks
+- AutoGPT (if resurgence)
+- Langroid
+- Home automation (Home Assistant)
+- Custom serverless (Lambda, Cloud Run)
+
+**Enterprise Features:**
+- SSO integration
+- Team policy management
+- Compliance reporting dashboards
+- Custom policy pack builder UI
+
+---
+
+## Success Metrics
+
+### Adoption Metrics (Primary)
+
+| Metric | Target (6 months) | Measurement |
+|--------|-------------------|-------------|
+| **Total Installs** | 10,000+ | npm + pip downloads |
+| **Active Frameworks** | 10+ | Frameworks with >100 installs each |
+| **GitHub Stars** | 5,000+ | Main repo stars |
+| **Community Contributions** | 50+ | PRs from external contributors |
+
+### Framework-Specific Metrics
+
+| Framework | Target Installs (6mo) | Target Conversion | Notes |
+|-----------|----------------------|-------------------|-------|
+| OpenClaw | 2,000 | 1% of 200K stars | Already shipped; growth mode |
+| LangChain | 3,000 | 0.1% of 3M+ devs | Largest TAM; competitive |
+| Cursor | 5,000 | 0.5% of 1M users | High-value users; enterprise |
+| CrewAI | 1,000 | 5% of 20K stars | Strong community; multi-agent focus |
+| n8n | 1,500 | 3% of 50K stars | Low-code; visual appeal |
+| AutoGen | 800 | 2% of 35K stars | Enterprise; Microsoft ecosystem |
+
+### Technical Metrics (Secondary)
+
+| Metric | Target | Purpose |
+|--------|--------|---------|
+| **Shared Code %** | 85%+ | Measure reusability |
+| **Install Success Rate** | 95%+ | Measure setup quality |
+| **Verification Latency** | <300ms p99 | Measure performance |
+| **Framework Add Time** | <3 days | Measure scalability |
+
+### Business Metrics (Long-Term)
+
+| Metric | Target (12 months) | Impact |
+|--------|-------------------|--------|
+| **API Mode Adoption** | 40% | Drives APort Cloud revenue |
+| **Enterprise Leads** | 100+ | Cursor/Cursor users → enterprise deals |
+| **Marketplace Presence** | Top 10 in 3 categories | SEO + discoverability |
+
+---
+
+## Open Questions
+
+### Technical Questions
+
+1. **Q: Should we support framework version pinning?**
+   - **Context:** LangChain v0.1 vs v0.2 have different APIs
+   - **Options:**
+     - A) Maintain adapters for multiple versions
+     - B) Only support latest stable
+     - C) Let users specify version in config
+   - **Recommendation:** B for MVP, A for popular frameworks as needed
+
+2. **Q: How to handle framework-specific config schemas?**
+   - **Context:** Each framework has different tool names, params
+   - **Options:**
+     - A) Monolithic config file (all frameworks)
+     - B) Per-framework config files
+     - C) Shared config + framework overrides
+   - **Recommendation:** C (shared passport + framework-specific tool mappings)
+
+3. **Q: Local evaluator in Python?**
+   - **Context:** Currently bash-only
+   - **Options:**
+     - A) Keep bash, call from Python via subprocess
+     - B) Rewrite in Python
+     - C) Both (Python for speed, bash for portability)
+   - **Recommendation:** A for MVP, B if performance matters
+
+### Product Questions
+
+4. **Q: Pricing for framework-specific packages?**
+   - **Context:** Core package free, but framework packages?
+   - **Options:**
+     - A) All free (maximize adoption)
+     - B) Free for top 5, paid for enterprise frameworks
+     - C) Free packages, paid for hosted features
+   - **Recommendation:** C (aligns with current model)
+
+5. **Q: Support matrix?**
+   - **Context:** Which framework versions do we guarantee support for?
+   - **Proposal:**
+     - Tier 1 (OpenClaw, LangChain, Cursor): 100% coverage, <24h support
+     - Tier 2 (CrewAI, AutoGen, n8n): Best-effort, community support
+     - Tier 3 (Backlog): Community-driven, no official support
+   - **Recommendation:** Publish support tiers clearly
+
+### Strategic Questions
+
+6. **Q: Open-source everything?**
+   - **Context:** Framework adapters could be copied by competitors
+   - **Options:**
+     - A) Open-source all (maximize adoption)
+     - B) Core open, enterprise adapters closed
+     - C) Delay source release (binary-only npm packages)
+   - **Recommendation:** A (network effects > IP protection)
+
+7. **Q: Certification program for community adapters?**
+   - **Context:** Community might build adapters for niche frameworks
+   - **Proposal:**
+     - "APort Certified" badge for adapters that pass test suite
+     - Listed in official docs
+     - Quality signal for users
+   - **Recommendation:** Yes, implement in Phase 4
+
+8. **Q: Should we build a marketplace?**
+   - **Context:** Policy packs + framework adapters could be a marketplace
+   - **Vision:**
+     - Users browse "LangChain + AWS Bedrock" integrations
+     - Creators publish custom policy packs
+     - APort takes 20% cut
+   - **Recommendation:** Phase 5+ (after product-market fit)
+
+---
+
+## Appendix A: Example Installation Flows
+
+### Example 1: LangChain Developer
+
+```bash
+# Install
+pip install aport-agent-guardrails-langchain
+
+# Setup
+aport-langchain setup
+
+# Interactive prompts:
+# → Using LangChain framework
+# → Create new passport or use existing? [New]
+# → Agent name: my-research-assistant
+# → Owner: john@example.com
+# → Capabilities: [x] Command Execution  [x] Web Search  [ ] File Write
+# → Allowed commands: git, npm, python, curl
+# → Verification mode: API (recommended) or Local? [API]
+# → ✅ Passport created: ap_abc123...
+# → ✅ Config written to ~/.aport/langchain/config.yaml
+# → ✅ Test verification: PASSED
+
+# Copy this code to your agent:
+"""
+from langchain.agents import initialize_agent
+from aport_guardrails_langchain import APortCallback
+
+agent = initialize_agent(
+    tools=tools,
+    llm=llm,
+    callbacks=[APortCallback()]
+)
+"""
+```
+
+### Example 2: n8n User (No-Code)
+
+```bash
+# Install custom node
+npx @aporthq/aport-agent-guardrails n8n
+
+# Interactive prompts:
+# → Using n8n framework
+# → Create new passport or use existing? [Use existing]
+# → Paste agent_id from aport.io: ap_abc123...
+# → Verification mode: API (required for n8n)
+# → ✅ Custom node installed to ~/.n8n/custom/
+# → ✅ Restart n8n to see "APort Guardrail" node
+#
+# Next steps:
+# 1. Restart n8n (systemctl restart n8n)
+# 2. Open n8n editor
+# 3. Drag "APort Guardrail" node before any action
+# 4. Configure node with agent_id: ap_abc123...
+# 5. Connect to action nodes (Branch on allow/deny)
+```
+
+### Example 3: Cursor IDE Developer
+
+```bash
+# Install extension
+npx @aporthq/aport-agent-guardrails cursor
+
+# Interactive prompts:
+# → Using Cursor IDE framework
+# → Create new passport or use existing? [New]
+# → Agent name: cursor-coding-assistant
+# → Owner: jane@example.com
+# → Capabilities: [x] Command Execution  [x] File Write
+# → Allowed commands: git, node, npm, yarn, pnpm
+# → Verification mode: API (recommended) or Local? [API]
+# → ✅ Passport created: ap_def456...
+# → ✅ VS Code extension installed
+# → ✅ Extension configured in settings.json
+#
+# Restart Cursor IDE to activate guardrails.
+#
+# What happens next:
+# - Cursor agent suggests commands
+# - APort verifies before execution
+# - Denied commands show inline error
+# - Approved commands execute normally
+```
+
+---
+
+## Appendix B: Architecture Diagrams
+
+### System Architecture (All Frameworks)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e'}}}%%
+graph TB
+    subgraph "Developer Machine"
+        subgraph "Code Frameworks"
+            LC[LangChain Agent]
+            CC[CrewAI Agent]
+            AG[AutoGen Agent]
+        end
+
+        subgraph "IDE Frameworks"
+            CU[Cursor IDE]
+            WS[Windsurf]
+        end
+
+        subgraph "Low-Code Frameworks"
+            N8[n8n Workflow]
+            ZA[Zapier Workflow]
+        end
+
+        subgraph "APort Adapters"
+            ALC[LangChain Adapter]
+            ACC[CrewAI Adapter]
+            AAG[AutoGen Adapter]
+            ACU[Cursor Extension]
+            AN8[n8n Custom Node]
+        end
+
+        subgraph "Shared Core"
+            EVAL[Evaluator<br/>src/core/evaluator.ts]
+            PASS[Passport Loader]
+            POL[Policy Loader]
+        end
+
+        LC --> ALC
+        CC --> ACC
+        AG --> AAG
+        CU --> ACU
+        N8 --> AN8
+
+        ALC --> EVAL
+        ACC --> EVAL
+        AAG --> EVAL
+        ACU --> EVAL
+        AN8 --> EVAL
+
+        EVAL --> PASS
+        EVAL --> POL
+    end
+
+    subgraph "External"
+        API[APort API<br/>api.aport.io]
+        BASH[Local Evaluator<br/>bash script]
+    end
+
+    EVAL -->|API mode| API
+    EVAL -->|Local mode| BASH
+
+    subgraph "Policy Sources"
+        SPEC[aport-spec<br/>submodule]
+        POLS[aport-policies<br/>submodule]
+        SHIELD[SHIELD.md feeds]
+    end
+
+    POL --> POLS
+    POL --> SHIELD
+
+    style LC fill:#3b82f6,color:#fff
+    style CC fill:#3b82f6,color:#fff
+    style AG fill:#3b82f6,color:#fff
+    style CU fill:#8b5cf6,color:#fff
+    style WS fill:#8b5cf6,color:#fff
+    style N8 fill:#10b981,color:#fff
+    style ZA fill:#10b981,color:#fff
+    style EVAL fill:#f59e0b,color:#fff
+    style API fill:#ef4444,color:#fff
+```
+
+### Package Dependency Graph
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e'}}}%%
+graph LR
+    subgraph "Published Packages"
+        CORE[@aporthq/aport-agent-guardrails<br/>Core package]
+        LC[@aporthq/aport-agent-guardrails-langchain<br/>LangChain adapter]
+        CC[@aporthq/aport-agent-guardrails-crewai<br/>CrewAI adapter]
+        N8[@aporthq/aport-agent-guardrails-n8n<br/>n8n adapter]
+        CU[@aporthq/aport-agent-guardrails-cursor<br/>Cursor adapter]
+    end
+
+    subgraph "Python Packages"
+        PYCORE[aport-agent-guardrails<br/>Core package]
+        PYLC[aport-agent-guardrails-langchain<br/>LangChain adapter]
+        PYCC[aport-agent-guardrails-crewai<br/>CrewAI adapter]
+    end
+
+    LC --> CORE
+    CC --> CORE
+    N8 --> CORE
+    CU --> CORE
+
+    PYLC --> PYCORE
+    PYCC --> PYCORE
+
+    style CORE fill:#f59e0b,color:#fff
+    style PYCORE fill:#f59e0b,color:#fff
+    style LC fill:#3b82f6,color:#fff
+    style CC fill:#3b82f6,color:#fff
+    style N8 fill:#10b981,color:#fff
+    style CU fill:#8b5cf6,color:#fff
+    style PYLC fill:#3b82f6,color:#fff
+    style PYCC fill:#3b82f6,color:#fff
+```
+
+### Verification Flow (Shared Logic)
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#f0f9ff','primaryTextColor':'#0c4a6e'}}}%%
+sequenceDiagram
+    participant F as Framework<br/>(LangChain/OpenClaw/n8n)
+    participant A as Adapter<br/>(framework-specific)
+    participant E as Evaluator<br/>(shared core)
+    participant C as Config<br/>(shared)
+    participant V as Verifier<br/>(API or local)
+
+    F->>A: Tool call intercepted
+    activate A
+    Note over A: Map tool → capability<br/>(framework-specific)
+    A->>E: verify(capability, context)
+    activate E
+    E->>C: Load passport + policy
+    activate C
+    C-->>E: passport, policy
+    deactivate C
+    E->>V: POST /verify (or bash call)
+    activate V
+    V-->>E: Decision (allow/deny + reasons)
+    deactivate V
+    Note over E: Log audit trail<br/>(shared)
+    E-->>A: Decision object
+    deactivate E
+    Note over A: Format response<br/>(framework-specific)
+    A-->>F: Allow or throw error
+    deactivate A
+```
+
+---
+
+## Appendix C: Code Reuse Analysis
+
+### Current State (OpenClaw-only)
+
+```
+Total Lines of Code: ~3,500
+  - Shared:     ~2,000 (57%)
+    - Passport wizard: 500
+    - Policy packs: 800 (external submodule)
+    - Evaluator: 400
+    - Config: 300
+  - OpenClaw-specific: ~1,500 (43%)
+    - Plugin: 800
+    - Installer: 500
+    - Tests: 200
+```
+
+### Target State (10 Frameworks)
+
+```
+Total Lines of Code: ~12,000 (estimate)
+  - Shared:     ~5,000 (42% of total, but 90% reuse)
+    - Core evaluator: 1,200
+    - Passport wizard: 700
+    - Config management: 600
+    - Policy packs: 1,500 (external)
+    - Utils: 1,000
+  - Framework-specific: ~7,000 (58% of total, 10% unique per framework)
+    - 10 frameworks × 700 LOC each
+    - Each framework:
+      - Adapter: 400 LOC
+      - Installer: 200 LOC
+      - Tests: 100 LOC
+
+Reuse Factor: 90% of logic shared across frameworks
+Maintenance Burden: +700 LOC per new framework (2-3 days)
+```
+
+### Maintenance Cost Projection
+
+**Adding a new framework (after initial setup):**
+- Adapter implementation: 1-2 days
+- Installer script: 0.5 days
+- Documentation + examples: 0.5 days
+- Testing: 0.5-1 day
+- **Total: 2.5-4 days per framework**
+
+**Updating shared logic (benefits all frameworks):**
+- Passport format change: 1 update = 10 frameworks updated
+- Policy pack addition: 1 addition = 10 frameworks gain capability
+- Security fix: 1 fix = 10 frameworks patched
+
+**ROI of Shared Architecture:**
+- **Without shared code:** 10 frameworks × 10 days each = 100 days
+- **With shared code:** 20 days (core) + 10 × 3 days (adapters) = 50 days
+- **Savings: 50%** for initial implementation
+- **Ongoing: 90% savings** for updates
+
+---
+
+## Appendix D: FAQ for Framework Maintainers
+
+### Q: I maintain [Framework X]. How do I add APort support?
+
+**A:** We'd love to collaborate! Two options:
+
+1. **We build it:** Open an issue at [github.com/aporthq/aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails) with:
+   - Framework name + repo link
+   - Extension API docs (how to hook into tool execution)
+   - Estimated user base
+   - We'll prioritize based on our roadmap
+
+2. **You build it:** Follow our [Adapter Development Guide](docs/ADAPTER_DEVELOPMENT_GUIDE.md):
+   - Fork the repo
+   - Copy `packages/core/src/frameworks/base.ts` as template
+   - Implement 4 methods: `detect()`, `install()`, `verify()`, `test()`
+   - Submit PR with tests + docs
+   - We'll review and publish
+
+### Q: Does adding APort slow down my framework?
+
+**A:** Negligible impact:
+- **API mode:** <300ms p99 (network call)
+- **Local mode:** <50ms p99 (bash script)
+- **Overhead:** Adds one HTTP request or subprocess call per tool
+- **Comparison:** LLM inference (1-5s) >> APort verification (0.05-0.3s)
+
+### Q: Can users disable it?
+
+**A:** Yes, multiple ways:
+- **Framework level:** User doesn't install APort adapter = no guardrails
+- **Config level:** Set `APORT_ENABLED=false` in config
+- **Policy level:** Use `allowed_commands: ["*"]` + no blocked patterns = allow all
+
+APort is opt-in by design.
+
+### Q: What data does APort see?
+
+**A:** Only what's needed for authorization:
+- **API mode:** Tool name, parameters, passport (user's identity)
+- **NOT sent:** LLM prompts, responses, conversation history, API keys
+- **Retention:** Decisions logged for audit (30 days default, configurable)
+
+See [Privacy Policy](https://aport.io/privacy).
+
+### Q: Is this open-source?
+
+**A:** Mostly:
+- **Framework adapters:** Apache 2.0 (open-source)
+- **Core evaluator:** Apache 2.0 (open-source)
+- **APort API:** Proprietary (but self-hostable with enterprise license)
+
+Users can use local mode (100% open-source) or API mode (freemium SaaS).
+
+---
+
+## Document Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.0 | 2026-02-17 | Complete rewrite: rankings, architecture, roadmap |
+| 0.1 | 2026-02-17 | Initial draft (OpenClaw-focused) |
+
+---
+
+**Status:** Living Document (will be updated as we ship frameworks)
+
+**Feedback:** Open an issue at [github.com/aporthq/aport-agent-guardrails/issues](https://github.com/aporthq/aport-agent-guardrails/issues) with "Framework Support:" prefix
+
+**Contribute:** See [CONTRIBUTING.md](../CONTRIBUTING.md) for adapter development guide
+
+---
+
+<p align="center">
+<em>One command. Any framework. Pre-action authorization for all AI agents.</em>
+</p>