@aporthq/aport-agent-guardrails 1.0.8

package/docs/launch/ANNOUNCEMENT_GUIDE.md

@@ -0,0 +1,266 @@
+# OpenClaw + APort Announcement Guide
+
+**Ready to announce OpenClaw is secure!** This guide helps you create announcement materials.
+
+---
+
+## 🎯 Key Messages
+
+### Primary Message
+**"OpenClaw is now secure with APort - Pre-action authorization for commands and MCP tools. One command, no clone required."**
+
+### Supporting Points
+1. ✅ **One-command setup** - `npx @aporthq/aport-agent-guardrails` (no clone); optional hosted passport via `npx @aporthq/aport-agent-guardrails <agent_id>`
+2. ✅ **Local-first or API** - Works offline (bash) or with APort API (default in wizard) for full OAP
+3. ✅ **40+ built-in security patterns** - Protection against injection, path traversal, privilege escalation
+4. ✅ **4 OpenClaw policies** - Commands, MCP tools, sessions, tool registration
+5. ✅ **Sub-300ms performance** - Fast enough for real-time agent workflows
+
+---
+
+## 📝 Tweet Draft
+
+```
+🚀 OpenClaw is now secure with APort!
+
+✅ Pre-action authorization for commands & MCP tools
+✅ One command: npx @aporthq/aport-agent-guardrails (no clone)
+✅ 40+ built-in security patterns (injection, path traversal, etc.)
+✅ 5-minute setup • Hosted passport optional (use your agent_id)
+
+🔗 https://github.com/aporthq/aport-agent-guardrails
+📖 https://aport.io/openclaw
+
+#OpenClaw #AISecurity #PolicyEnforcement
+```
+
+---
+
+## 📝 Blog Post Outline
+
+### Title
+**"Securing OpenClaw with APort: Pre-Action Authorization in 5 Minutes"**
+
+### Structure
+
+1. **Introduction** (2 paragraphs)
+   - OpenClaw's security challenges
+   - APort's solution: pre-action authorization
+
+2. **The Problem** (3 paragraphs)
+   - TrustClaw addresses runtime security (OAuth, sandboxing)
+   - Missing: Pre-action policy enforcement
+   - Need for graduated controls (max amounts, daily caps)
+
+3. **The Solution** (4 paragraphs)
+   - APort's 4 OpenClaw policies
+   - Local-first approach (no cloud dependency)
+   - Built-in security patterns
+   - Easy integration
+
+4. **Quick Start** (5 paragraphs)
+   - One command: `npx @aporthq/aport-agent-guardrails` (no clone); optional `npx @aporthq/aport-agent-guardrails <agent_id>` for hosted passport
+   - 5-minute setup guide (wizard installs plugin, passport, smoke test)
+   - Code examples and test commands
+
+5. **Security Features** (3 paragraphs)
+   - 40+ built-in patterns
+   - Cannot be bypassed
+   - Defense-in-depth
+
+6. **Performance** (2 paragraphs)
+   - Sub-100ms API latency (~60–65 ms mean); local sub-300ms
+   - Fast enough for real-time workflows
+
+7. **Next Steps** (2 paragraphs)
+   - Try it locally
+   - Upgrade to cloud for team features
+
+---
+
+## 🎬 Demo Script
+
+### Video Script (2 minutes)
+
+**0:00 - 0:15: Introduction**
+- "OpenClaw is powerful, but needs security"
+- "APort adds pre-action authorization"
+- "Works locally, no cloud required"
+
+**0:15 - 0:45: Setup**
+- Run: `npx @aporthq/aport-agent-guardrails` (wizard: config dir, passport choice — hosted or wizard, mode API/local)
+- Show plugin installed; optional: show passport.json or hosted agent_id
+
+**0:45 - 1:15: Demo - Command Verification**
+- Show `~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'` (ALLOW)
+- Show `... '{"command":"rm -rf /"}'` (DENY - blocked pattern)
+- Show sudo / dangerous command (DENIED)
+
+**1:15 - 1:45: Demo - MCP Tool Verification**
+- Show github.pull_requests.create (ALLOWED)
+- Show evil-server.com (DENIED - server not allowed)
+
+**1:45 - 2:00: Wrap-up**
+- "40+ built-in security patterns"
+- "5-minute setup"
+- "Link in description"
+
+---
+
+## 📊 Code Examples for Announcement
+
+### Example 1: Command Verification
+
+```python
+from aport_guardrail import APortGuardrail
+
+guardrail = APortGuardrail()
+
+# This is ALLOWED
+guardrail.verify_command("npm", ["install"])
+
+# This is DENIED (blocked pattern)
+try:
+    guardrail.verify_command("rm", ["-rf", "/"])
+except PermissionError:
+    print("Dangerous command blocked!")
+```
+
+### Example 2: MCP Tool Verification
+
+```python
+# This is ALLOWED
+guardrail.verify_mcp_tool(
+    "https://mcp.github.com",
+    "github.pull_requests.create",
+    {"repo": "test/repo"}
+)
+
+# This is DENIED (server not allowed)
+try:
+    guardrail.verify_mcp_tool(
+        "https://evil-server.com",
+        "malicious.tool",
+        {}
+    )
+except PermissionError:
+    print("MCP tool blocked!")
+```
+
+---
+
+## 📈 Performance Metrics
+
+### Key Numbers to Highlight
+
+- **P95 Latency**: 268ms (generic evaluators)
+- **Mean Latency**: 178ms
+- **Success Rate**: 100%
+- **Security Patterns**: 40+ built-in patterns
+- **Setup Time**: 5 minutes
+- **Policies**: 4 OpenClaw-specific policies
+
+### Comparison
+
+| Metric | Manual Evaluators | Generic Evaluators | Target |
+|--------|------------------|-------------------|--------|
+| P95 Latency | 239ms | 268ms | <200ms |
+| Mean Latency | 165ms | 178ms | <150ms |
+| Success Rate | 100% | 100% | 100% |
+
+**Note**: Generic evaluators are 11.8% slower but provide:
+- ✅ Policy-driven (no hardcoded logic)
+- ✅ Easier to maintain
+- ✅ Consistent across all policies
+
+---
+
+## 🎨 Visual Assets
+
+### Screenshot Ideas
+
+1. **Terminal showing verification**
+   ```
+   ✅ npm install - ALLOWED
+   ❌ rm -rf / - DENIED (blocked pattern)
+   ❌ sudo apt update - DENIED (not in allowlist)
+   ```
+
+2. **Code example showing integration**
+   - Python code with APortGuardrail class
+   - Clean, readable, well-commented
+
+3. **Architecture diagram**
+   - OpenClaw → APort → Policy Evaluation → Allow/Deny
+
+---
+
+## 🔗 Links to Include
+
+- **GitHub Repo**: https://github.com/aporthq/aport-agent-guardrails
+- **Integration Guide**: docs/OPENCLAW_LOCAL_INTEGRATION.md
+- **Example Code**: examples/openclaw-integration-example.py
+- **Policy Docs**: policies/system.command.execute.v1/README.md
+- **Website**: https://aport.io
+- **OpenClaw quickstart**: https://aport.io/openclaw (one command: `npx @aporthq/aport-agent-guardrails`)
+
+---
+
+## 📋 Checklist Before Announcement
+
+- [ ] Local API server tested and working
+- [ ] Example scripts tested
+- [ ] Documentation reviewed
+- [ ] Performance metrics verified
+- [ ] Security patterns tested
+- [ ] Demo video recorded (optional)
+- [ ] Blog post written (optional)
+- [ ] Social media posts scheduled (optional)
+
+---
+
+## 🚀 Launch Day Checklist
+
+- [ ] Post on Twitter/X
+- [ ] Post on LinkedIn
+- [ ] Post on Reddit (r/MachineLearning, r/OpenSource)
+- [ ] Post on Hacker News
+- [ ] Update GitHub README
+- [ ] Send to OpenClaw community
+- [ ] Monitor for questions/feedback
+
+---
+
+## 💬 FAQ for Announcement
+
+### Q: Do I need cloud API?
+**A:** No! Works completely locally. Cloud API is optional for team features.
+
+### Q: How fast is it?
+**A:** Sub-100ms API (P95 ~70 ms); local sub-300ms — fast enough for real-time agent workflows.
+
+### Q: What's protected?
+**A:** Commands, MCP tools, agent sessions, and tool registration. 40+ built-in security patterns.
+
+### Q: Can I bypass the security?
+**A:** No. Built-in security patterns are always enforced, even if you add commands to allowlist.
+
+### Q: How do I upgrade to cloud?
+**A:** Sign up at aport.io, get API key, set environment variables. See docs/UPGRADE_TO_CLOUD.md.
+
+---
+
+## 🎉 Ready to Launch!
+
+You have everything you need:
+- ✅ Working implementation
+- ✅ Documentation
+- ✅ Examples
+- ✅ Performance metrics
+- ✅ Security features
+
+**Go ahead and announce! 🚀**
+
+---
+
+**Made with ❤️ by the APort team**

package/docs/launch/AWESOME_REPOS.md

@@ -0,0 +1,53 @@
+# Awesome Repos: Discovery & Backlinks
+
+**Goal:** Get APort Agent Guardrails (or OpenClaw guardrails) listed in curated awesome lists for visibility and SEO. Do **after** guardrail post is live and repo is public.
+
+**Suggested timing:** Day 2–3 after launch (once GitHub repo link works and you have a live post to reference).
+
+---
+
+## Repos to Submit To
+
+| # | Repo | Focus | Suggested section / placement | Entry idea |
+|---|-----|--------|-------------------------------|------------|
+| 1 | [e2b-dev/awesome-ai-agents](https://github.com/e2b-dev/awesome-ai-agents) | AI autonomous agents list | Security / guardrails or integrations | APort Agent Guardrails — pre-action policy enforcement for OpenClaw |
+| 2 | [Jenqyang/Awesome-AI-Agents](https://github.com/Jenqyang/Awesome-AI-Agents) | Autonomous agents (LLM) | Tools or Security | APort Guardrails — authorization layer for OpenClaw agents |
+| 3 | [VoltAgent/awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills) | OpenClaw skills | **Security & Passwords** (guardrails fit here) | guardrails — Pre-action policy enforcement; blocks dangerous commands, 40+ patterns |
+| 4 | [rohitg00/awesome-openclaw](https://github.com/rohitg00/awesome-openclaw) | OpenClaw resources | Security or Integrations | APort Guardrails — pre-action authorization for OpenClaw |
+| 5 | [hesamsheikh/awesome-openclaw-usecases](https://github.com/hesamsheikh/awesome-openclaw-usecases) | OpenClaw use cases | New category or Infrastructure | Security / guardrails use case |
+| 6 | [SamurAIGPT/awesome-openclaw](https://github.com/SamurAIGPT/awesome-openclaw) | OpenClaw resources, tools, skills | Security or Community Projects | APort Guardrails — deterministic policy enforcement for OpenClaw |
+
+---
+
+## Suggested entry text (copy-paste for PRs)
+
+**Short (for most lists):**
+```markdown
+- [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) — Pre-action guardrails for OpenClaw (`before_tool_call` plugin, 40+ blocked patterns, local or API). Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+**With one line of detail:**
+```markdown
+- [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) — Deterministic policy enforcement for OpenClaw (passport + plugin). Allowlist commands, block `rm -rf`, cap messaging; local-first with optional API mode. Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+---
+
+## Checklist (use with QUICK_LAUNCH_CHECKLIST)
+
+- [ ] e2b-dev/awesome-ai-agents — open PR (check their CONTRIBUTING for format)
+- [ ] Jenqyang/Awesome-AI-Agents — open PR
+- [ ] VoltAgent/awesome-openclaw-skills — open PR (Security & Passwords section)
+- [ ] rohitg00/awesome-openclaw — open PR
+- [ ] hesamsheikh/awesome-openclaw-usecases — open PR or new use case doc
+- [ ] SamurAIGPT/awesome-openclaw — open PR
+
+**Note:** Each repo has its own CONTRIBUTING and format. Read the README and existing entries before submitting.
+
+---
+
+## Links (for PR descriptions)
+
+- **Repo:** https://github.com/aporthq/aport-agent-guardrails  
+- **npm:** https://www.npmjs.com/package/@aporthq/aport-agent-guardrails  
+- **QuickStart:** https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md  

package/docs/launch/CURSOR_VSCODE_HOOKS_RESEARCH.md

@@ -0,0 +1,77 @@
+# Cursor vs VS Code: Hooks, Extensions, and ROI
+
+**Purpose:** Decide how to support Cursor and VS Code (Copilot) with maximum traction and minimum effort.
+
+---
+
+## 1. Can we use a VS Code extension for “before execution” hooks?
+
+**Short answer: No for vanilla VS Code; not needed for Copilot/Cursor.**
+
+| Environment | Before shell/tool execution? | How? |
+|-------------|------------------------------|------|
+| **VS Code (no Copilot)** | **No** | The VS Code extension API has no way to intercept terminal commands before they run. `Terminal.onDidWriteData` is after the fact. You cannot build an extension that “hooks before every shell execution” in plain VS Code. |
+| **VS Code + GitHub Copilot (agent)** | **Yes** | Via **agent hooks** (Preview in VS Code 1.109.3+). Hooks are **config-driven**, not extension API–driven: JSON config files point to **shell scripts**. |
+| **Cursor** | **Yes** | Native **hooks** (e.g. `beforeShellExecution`, `preToolUse`). Same idea: config file + script. Cursor can also load **Claude Code** hook config from `~/.claude/settings.json`. |
+
+So “before execution” is available only where an **agent** runs (Copilot, Cursor, Claude Code), and in those cases it’s done via **hooks + scripts**, not via a VS Code extension API.
+
+---
+
+## 2. Common thing in the VS Code ecosystem that adds the most value with least effort
+
+**Recommendation: One hook script + one installer that writes the right config for each host. No VS Code extension required for the core behavior.**
+
+### Why hooks (script + config) beat an extension here
+
+1. **Same mechanism everywhere**  
+   - **VS Code (Copilot):** [Agent hooks (Preview)](https://code.visualstudio.com/docs/copilot/customization/hooks) — config in `~/.claude/settings.json`, `.claude/settings.json`, or `.github/hooks/*.json`. `PreToolUse` runs a command (our script).  
+   - **Cursor:** [Hooks](https://cursor.com/docs/agent/hooks) — config in `~/.cursor/hooks.json` or `.cursor/hooks.json`. `beforeShellExecution` / `preToolUse` run a command.  
+   - **Claude Code:** `~/.claude/settings.json`, same PreToolUse style.  
+   All of them: **JSON config → shell script → stdin JSON in, stdout JSON out, exit 2 = block.**
+
+2. **One script, many editors**  
+   A single APort hook script can:
+   - Read JSON from stdin (tool name + input; e.g. `runTerminalCommand` / `command` for shell).
+   - Map to our policy (e.g. `system.command.execute.v1`).
+   - Call the existing guardrail (bash or API).
+   - Emit the host’s expected JSON (e.g. VS Code: `permissionDecision: allow|deny|ask`, Cursor: allow/deny + exit code).
+   - Use **exit 2** to block (both Cursor and VS Code use exit 2 for “block”).
+
+3. **Extension adds little for interception**  
+   - Vanilla VS Code: extension **cannot** intercept shell execution (no API).  
+   - Copilot/Cursor: interception is already done by **hooks**, not by extensions. An extension would at best **write** the same hook config and maybe add a “Install APort guardrails” command. That’s optional UX; the core value is the **script + config**.
+
+### What to build (high value, low effort)
+
+| Deliverable | Effort | Value |
+|-------------|--------|--------|
+| **One hook script** (e.g. `aport-hook.sh`) that parses stdin (Cursor/Copilot/Claude format), calls existing guardrail, returns allow/deny + exit 0/2 | Low | High — works in Cursor, VS Code Copilot, Claude Code |
+| **Installer** (`npx @aporthq/aport-agent-guardrails cursor` or `--framework=cursor`) that runs passport wizard and writes `~/.cursor/hooks.json` (and optionally `~/.claude/settings.json`) pointing at the script | Low | High — one command to enable guardrails |
+| **Docs** for Cursor, VS Code+Copilot, and Claude Code (where to put config, example `PreToolUse` / `beforeShellExecution` snippet) | Low | High — reuse same script everywhere |
+| **VS Code extension** that only writes hook config + “Install guardrails” command | Medium | Low–medium — nicer discoverability, same behavior as script+installer |
+
+So the **common thing** that adds the most value with least effort is: **one script + config for PreToolUse / beforeShellExecution**, shared across Cursor, VS Code (Copilot), and Claude Code. A VS Code extension is optional polish, not required for “works in VS Code (Copilot) and other flavours.”
+
+---
+
+## 3. PreToolUse / beforeShellExecution availability
+
+| Platform | PreToolUse / beforeShellExecution | Config location |
+|----------|-----------------------------------|------------------|
+| **VS Code (Copilot)** | Yes — `PreToolUse` (Preview) | `~/.claude/settings.json`, `.claude/settings.json`, `.github/hooks/*.json` |
+| **Cursor** | Yes — `preToolUse`, `beforeShellExecution` | `~/.cursor/hooks.json`, `.cursor/hooks.json` |
+| **Claude Code** | Yes — `PreToolUse` | `~/.claude/settings.json`, `.claude/settings.json` |
+| **VS Code (no agent)** | N/A | No agent → no tool/shell interception in the first place |
+
+So **PreToolUse / beforeShellExecution is available** exactly where we care: Cursor, VS Code+Copilot, and Claude Code. It’s not available in “plain VS Code” because there’s no agent running tools/shell there.
+
+---
+
+## 4. ROI vs effort: summary
+
+- **Implement:** One **hook script** + **installer** that writes the right **hooks config** for Cursor (and optionally for VS Code/Claude via `~/.claude/settings.json`). Document for Cursor, VS Code+Copilot, and Claude Code.
+- **Skip for MVP:** A VS Code extension whose only job is to install guardrails. Same outcome can be achieved with `npx @aporthq/aport-agent-guardrails cursor` (or a `copilot` framework flag) and one script; extension can be added later if we want marketplace discoverability.
+- **Do not rely on:** A VS Code extension to “intercept shell execution” in vanilla VS Code — the API doesn’t support it; interception only exists in agent-based products and is done via hooks.
+
+This keeps effort low and ROI high: one script, one installer, one set of docs, and it works on Cursor, VS Code (Copilot), and other flavours that use the same hook format (e.g. Claude Code).

package/docs/launch/DEMO_TERMINAL_OUTPUT.txt

@@ -0,0 +1,48 @@
+# Demo terminal output (for screenshot / evidence)
+
+Use this as reference for what to show in the guardrail launch post. The guardrail script itself only exits 0 (ALLOW) or 1 (DENY) and writes JSON to the decision file; it does not print "ALLOW"/"DENY" to the terminal. To get the output below, run the commands and then echo the result (or use the one-liners at the end).
+
+---
+
+## Option A: With decision JSON (full)
+
+$ aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'
+✅ ALLOW
+{"allow":true,"assurance_level":"L2","decision_id":"...","policy_id":"system.command.execute.v1","reasons":[{"code":"oap.allowed","message":"All policy checks passed"}],...}
+
+$ aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'
+❌ DENY
+{"allow":false,...,"reasons":[{"code":"oap.command_not_allowed","message":"Command 'rm -rf /' is not in allowed list"}],...}
+
+---
+
+## Option B: Short (ALLOW/DENY only — best for screenshot)
+
+$ aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'
+✅ ALLOW
+
+$ aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'
+❌ DENY - Blocked pattern: rm -rf /
+
+---
+
+## Commands to run (from repo with fixture passport)
+
+# ALLOW
+OPENCLAW_PASSPORT_FILE=tests/fixtures/passport.oap-v1.json ./bin/aport-guardrail-bash.sh system.command.execute '{"command":"mkdir test"}'
+echo "✅ ALLOW (exit $?)"
+
+# DENY
+OPENCLAW_PASSPORT_FILE=tests/fixtures/passport.oap-v1.json ./bin/aport-guardrail-bash.sh system.command.execute '{"command":"rm -rf /"}' || true
+echo "❌ DENY (exit 1) - Blocked pattern: rm -rf /"
+
+---
+
+## If using installed ~/.openclaw/.skills/aport-guardrail.sh
+
+Ensure ~/.openclaw/.aport-repo points to your repo and ~/.openclaw/passport.json exists. Then:
+
+~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"mkdir test"}' && echo '✅ ALLOW' || echo '❌ DENY'
+~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}' && echo '✅ ALLOW' || echo '❌ DENY'
+
+Second line will print ❌ DENY (script exits 1).

package/docs/launch/DRY_AND_PLAN_CHECKLIST.md

@@ -0,0 +1,47 @@
+# DRY and FRAMEWORK_SUPPORT_PLAN alignment checklist
+
+This doc confirms the codebase follows the structure, conventions, and best practices in [FRAMEWORK_SUPPORT_PLAN.md](FRAMEWORK_SUPPORT_PLAN.md). Use it to keep the repo DRY and aligned with the plan.
+
+## Repository structure (plan vs actual)
+
+| Plan | Actual | Status |
+|------|--------|--------|
+| `bin/lib/` common, passport, config, allowlist | `bin/lib/common.sh`, `passport.sh`, `config.sh`, `allowlist.sh`, `detect.sh`, `templates/` | ✅ |
+| `bin/frameworks/<name>.sh` thin scripts | `bin/frameworks/openclaw.sh`, `langchain.sh`, `crewai.sh`, `n8n.sh` (<50 lines each) | ✅ |
+| Shared wizard: `bin/aport-create-passport.sh` | All frameworks use it via `lib/passport.sh` or delegate (OpenClaw) | ✅ |
+| Config locations: OpenClaw `~/.openclaw`, LangChain `~/.aport/langchain/`, etc. | `lib/config.sh` `get_config_dir()` + `write_config_template()` | ✅ |
+| `integrations/<framework>/` | `integrations/openclaw/`, `langchain/`, `crewai/`, `n8n/` (README, examples) | ✅ |
+| `python/aport_guardrails/` core | `core/evaluator.py`, `config.py`, `passport.py`, `exceptions.py` | ✅ |
+| `python/.../langchain` adapter | `langchain_adapter/` + `aport_guardrails_langchain` import package | ✅ |
+
+## Shared vs divergent (DRY)
+
+- **Shared (no duplication):** Passport wizard, policy packs (`external/aport-policies`), tool→pack_id mapping (bash, Node, Python share same semantics), config read/write, kill switch = passport status only (no file).
+- **Divergent (per-framework only):** Integration hook (callback vs decorator vs plugin), config file location, CLI entry (`aport-langchain` vs `bin/openclaw`).
+
+## Verification: two passport options, two policy options
+
+Per agent-passport API `POST /api/verify/policy/{pack_id}` (see agent-passport `functions/api/verify/policy/[pack_id].ts`):
+
+- **Passport:** (1) **agent_id** in context → API fetches passport (cloud). (2) **passport** in body → API uses it directly (local via API).
+- **Policy:** (1) **pack_id** in URL path → policy from registry. (2) **policy** in body when `pack_id=IN_BODY` → policy from request.
+
+| Layer | agent_id | passport in body | pack_id in path | policy in body (API) |
+|-------|----------|------------------|-----------------|----------------------|
+| **Node (src/evaluator.js)** | ✅ context.agent_id | ✅ body.passport | ✅ URL | ✅ options.policyInBody → IN_BODY + body.policy |
+| **Bash (aport-guardrail-api.sh)** | ✅ APORT_AGENT_ID | ✅ via Node (passport loaded and passed) | ✅ via Node | N/A (uses Node) |
+| **Python (core/evaluator.py)** | ✅ context.agent_id | ✅ body.passport (from passport_path) | ✅ URL _tool_to_pack_id | ✅ full OAP pack → IN_BODY + body.policy |
+
+**Note:** Local verification with policy-in-body (e.g. passing a policy object to the bash guardrail or a future local evaluator) is planned and not implemented yet.
+
+## Test coverage (Story C and general)
+
+- **Unit:** `aport_guardrails/frameworks/langchain.py` (LangChainAdapter) — pytest in core or adapter; callback deny → `GuardrailViolation` covered in `langchain_adapter/tests/test_callback.py`.
+- **Integration:** Example under `examples/langchain/` with temp config/passport; ALLOW/DENY flows in `run_with_guardrail.py`.
+- **E2E:** GH Action installs package, `aport-langchain setup --ci`, runs sample agent or example, expects ALLOW log (see `.github/workflows/e2e-langchain.yml` or equivalent).
+
+## Doc references
+
+- [FRAMEWORK_SUPPORT_PLAN.md](FRAMEWORK_SUPPORT_PLAN.md) — architecture, shared vs divergent, per-framework patterns.
+- [USER_STORIES.md](USER_STORIES.md) — acceptance criteria and implementation status.
+- [ADDING_A_FRAMEWORK.md](../ADDING_A_FRAMEWORK.md) — how to add a framework without copying passport/config logic.

package/docs/launch/EVIDENCE_README.md

@@ -0,0 +1,61 @@
+# Launch evidence
+
+**Before publishing the guardrail launch post:**
+
+1. **Repo public:** In GitHub repo settings, set the repository to **Public**. Verify https://github.com/aporthq/aport-agent-guardrails does not 404.
+
+2. **Evidence captured:** Terminal ALLOW/DENY transcript is in ** [EVIDENCE_TERMINAL_CAPTURE.txt](EVIDENCE_TERMINAL_CAPTURE.txt)** (guardrail exit 0 = ALLOW, exit 1 = DENY). For the post, use a screenshot of that output—or run the same commands and capture. Save as **`evidence-allow-deny.png`** in this folder if you want a dedicated image. See **`DEMO_TERMINAL_OUTPUT.txt`** for one-liner variants.
+
+DENY:
+aport-guardrail.sh system.command.execute '{"command":"rm -rf /"}'
+❌ DENY
+{
+   "allow":false,
+   "assurance_level":"L2",
+   "decision_id":"A0A4C0DE-D6AB-4F9E-A5ED-7002919C0375",
+   "expires_at":"2026-02-16T18:49:22Z",
+   "issued_at":"2026-02-16T17:49:22Z",
+   "kid":"oap:local:dev-key",
+   "owner_id":"user@example.com",
+   "passport_digest":"sha256:2c8368260593935ff699b5223d4101458881e3678e9b4ef992ad522bdabe198b",
+   "passport_id":"CDE60F4E-49DC-4D97-AC05-190E693C202C",
+   "policy_id":"system.command.execute.v1",
+   "prev_content_hash":"sha256:8bb0fd773e38bb412fa79e9857392b746d891dde929764ddbaca76235d45b0c8",
+   "prev_decision_id":"3E79C583-3A42-413C-830D-DA2480AD25C9",
+   "reasons":[
+      {
+         "code":"oap.command_not_allowed",
+         "message":"Command 'rm -rf /' is not in allowed list"
+      }
+   ],
+   "signature":"ed25519:local-unsigned",
+   "content_hash":"sha256:5d61ab149eb0e86e1c1d9d5822ba6714eb7b7a6ddc823130595132cd29974270"
+}
+
+
+ALLOW:
+aport-guardrail.sh system.command.execute '{"command":"mkdir test"}'
+✅ ALLOW
+
+{
+   "allow":true,
+   "assurance_level":"L2",
+   "decision_id":"3E79C583-3A42-413C-830D-DA2480AD25C9",
+   "expires_at":"2026-02-16T18:49:18Z",
+   "issued_at":"2026-02-16T17:49:18Z",
+   "kid":"oap:local:dev-key",
+   "owner_id":"user@example.com",
+   "passport_digest":"sha256:2c8368260593935ff699b5223d4101458881e3678e9b4ef992ad522bdabe198b",
+   "passport_id":"CDE60F4E-49DC-4D97-AC05-190E693C202C",
+   "policy_id":"system.command.execute.v1",
+   "prev_content_hash":"sha256:9572913a7cc9595629ba07ed8cf91868889987e655d69445d52bdbfc0961b827",
+   "prev_decision_id":"A5CA49E4-849D-4ED8-BB68-177F1784726C",
+   "reasons":[
+      {
+         "code":"oap.allowed",
+         "message":"All policy checks passed"
+      }
+   ],
+   "signature":"ed25519:local-unsigned",
+   "content_hash":"sha256:8bb0fd773e38bb412fa79e9857392b746d891dde929764ddbaca76235d45b0c8"
+}

package/docs/launch/EVIDENCE_TERMINAL_CAPTURE.txt

@@ -0,0 +1,10 @@
+# Actual capture — guardrail ALLOW/DENY (run with fixture passport)
+# Generated: 2026-02-16T19:15:11Z
+
+$ OPENCLAW_PASSPORT_FILE=tests/fixtures/passport.oap-v1.json ./bin/aport-guardrail-bash.sh system.command.execute '{"command":"mkdir test"}'
+Exit: 0
+✅ ALLOW
+
+$ OPENCLAW_PASSPORT_FILE=tests/fixtures/passport.oap-v1.json ./bin/aport-guardrail-bash.sh system.command.execute '{"command":"rm -rf /"}'
+Exit: 1
+❌ DENY - Blocked pattern: rm -rf /