@aporthq/aport-agent-guardrails 1.0.8

package/docs/frameworks/crewai.md

@@ -0,0 +1,114 @@
+# APort Agent Guardrail — CrewAI
+
+CrewAI supports **tool call hooks** that run before (and after) every tool execution. The **APort Agent Guardrail for CrewAI** plugs into the **before tool call** hook: we verify the tool and parameters against your passport and policy; if the decision is deny, we return `False` and CrewAI blocks execution. This matches CrewAI’s [Tool Call Hooks](https://docs.crewai.com/en/learn/tool-hooks) model.
+
+## How CrewAI agent guardrails work
+
+- **Hooks:** CrewAI runs **before_tool_call** hooks before every tool execution. The hook receives a `ToolCallHookContext` (tool name, tool input, agent, task, crew). Returning `False` blocks execution; `True` or `None` allows it.
+- **Registration:** You can register a hook **globally** with `register_before_tool_call_hook()`, or use the `@before_tool_call` decorator, or use **crew-scoped** `@before_tool_call_crew` on a `@CrewBase` class.
+- **Multi-task crews:** The same hook runs for every tool call across all tasks and agents, so multi-task crews are supported by default.
+
+Our adapter provides a function that fits this API: it calls the APort evaluator (sync) and returns `False` on deny, `None` on allow. You register it once before running your crew.
+
+- **Integration:** CrewAI `before_tool_call` hook (global or crew-scoped)
+- **Config:** `~/.aport/crewai/config.yaml` or `.aport/config.yaml` (see [Verification methods](../VERIFICATION_METHODS.md))
+
+## Two ways to use APort
+
+| Use case | What it is | When to use it |
+|----------|------------|----------------|
+| **Guardrails (CLI/setup)** | One-line installer: runs the **passport wizard**, writes config, prints next steps. Does not run your app. | Getting started: create passport and config so the library can find them. |
+| **Core (library)** | The **evaluator** and **before-tool-call hook** in your code. Calls policy + passport to allow/deny each tool call. | Integrating into your app: register the hook so CrewAI blocks tool runs when policy denies. |
+
+You typically use **both**: run the CLI once to create passport and config, then use the library in your CrewAI app so every tool call is verified.
+
+---
+
+## Setup (Guardrails — create passport and config)
+
+**Python**
+
+```bash
+npx @aporthq/aport-agent-guardrails crewai   # wizard + config (optional)
+pip install aport-agent-guardrails-crewai
+aport-crewai setup
+```
+
+**Node**
+
+```bash
+npx @aporthq/aport-agent-guardrails crewai   # wizard + config
+npm install @aporthq/aport-agent-guardrails-crewai   # beforeToolCall, withAPortGuardrail (depends on -core)
+```
+
+`aport-crewai setup` (Python) writes config to `~/.aport/crewai/`, runs the passport wizard (or use `--ci` / `--no-wizard` for non-interactive), and prints next steps.
+
+## Using the library (Core) in your app
+
+**Python — Option 1: Register the hook before kickoff**
+
+```python
+from aport_guardrails_crewai import register_aport_guardrail
+
+register_aport_guardrail()
+crew.kickoff()
+```
+
+**Python — Option 2: Decorator on your entry point**
+
+```python
+from aport_guardrails_crewai import with_aport_guardrail
+
+@with_aport_guardrail
+def main():
+    crew.kickoff()
+
+main()
+```
+
+**Python — Option 3: Use the hook with `@before_tool_call`**
+
+```python
+from crewai.hooks import before_tool_call
+from aport_guardrails_crewai import aport_guardrail_before_tool_call
+
+@before_tool_call
+def my_guardrail(context):
+    return aport_guardrail_before_tool_call(context)
+```
+
+**Node:** Call `beforeToolCall` in your flow before each tool run (CrewAI Node SDK does not expose a global hook). Return `false` to block, `null` to allow. Or wrap your entry point with `withAPortGuardrail(fn)`.
+
+```ts
+import { beforeToolCall, withAPortGuardrail } from '@aporthq/aport-agent-guardrails-crewai';
+
+// In your tool-call flow, before executing a tool:
+const result = beforeToolCall({ tool_name: 'run_command', tool_input: { command: 'ls' } });
+if (result === false) {
+  // Block this tool call
+  return;
+}
+
+// Or wrap your crew kickoff so guardrail is in scope:
+withAPortGuardrail(() => {
+  crew.kickoff();
+});
+```
+
+## Config
+
+- **Config path:** `~/.aport/crewai/config.yaml`, or `.aport/config.yaml` in the project root.
+- **Mode:** `api` (default for production) or `local` (bash evaluator, no network). Same options as [LangChain](langchain.md) and OpenClaw.
+
+## Suspend (kill switch)
+
+Same as all frameworks: **passport is the source of truth**. Local: set passport `status` to `suspended` (or `active` to resume). API: suspend the passport in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+
+## Example and tests
+
+- **Example:** [examples/crewai/run_with_guardrail.py](../../examples/crewai/run_with_guardrail.py) — temp config, ALLOW then DENY, `register_aport_guardrail()`.
+- **Unit tests:** [python/crewai_adapter/tests/test_hook.py](../../python/crewai_adapter/tests/test_hook.py) — hook return value and context with mocked evaluator.
+
+## Status
+
+Implemented (Story D). **APort Agent Guardrail for CrewAI.** Package: `aport-agent-guardrails-crewai`; CLI: `aport-crewai setup`; hook: `aport_guardrail_before_tool_call` / `register_aport_guardrail` / `with_aport_guardrail`.

package/docs/frameworks/cursor.md

@@ -0,0 +1,159 @@
+# APort Agent Guardrail — Cursor (and VS Code Copilot / Claude Code)
+
+Cursor, VS Code with GitHub Copilot, and Claude Code support **config-driven hooks** that run before shell execution or tool use. The **APort hook script** reads JSON from stdin, calls the existing APort guardrail (policy + passport), and returns allow/deny; **exit 2** blocks the action. One script works across Cursor, Copilot, and Claude Code.
+
+## Two ways to use APort
+
+| Use case | What it is | When to use it |
+|----------|------------|----------------|
+| **Guardrails (CLI/setup)** | One-line installer: runs the **passport wizard**, writes **`~/.cursor/hooks.json`** with the path to the APort hook script. Does not run Cursor for you. | Getting started: create passport and install the hook so Cursor calls our script before the agent runs a command or tool. |
+| **Core (runtime)** | The **hook script** (`bin/aport-cursor-hook.sh`) and **evaluator** (bash or API): when the agent runs a command/tool, Cursor invokes the script; we verify and return allow/deny. Optionally, the **Node package** `@aporthq/aport-agent-guardrails-cursor` exposes `Evaluator` and `getHookPath()` if you need them in code. | Guardrails = after setup, the hook runs automatically. Use the Node package only if you're building tooling that needs the evaluator or hook path. |
+
+For Cursor, you almost always use **Guardrails (CLI)** once to install the hook; the **Core** behavior (the script + evaluator) then runs automatically whenever the agent uses the terminal or a tool.
+
+---
+
+## How it works
+
+- **Hooks:** Cursor uses `~/.cursor/hooks.json` (or `.cursor/hooks.json` in the project). Hooks such as `beforeShellExecution` and `preToolUse` run a command (our script). The host sends JSON to stdin and reads JSON from stdout; **exit code 2** = block.
+- **VS Code Copilot:** Agent hooks (Preview) use `~/.claude/settings.json` or `.github/hooks/*.json` with `PreToolUse`; same idea: command, stdin JSON, stdout JSON, exit 2 = block.
+- **Claude Code:** `~/.claude/settings.json`, same PreToolUse style.
+
+Our script accepts Cursor- and Copilot-style payloads (e.g. `command`, or `tool`/`input`), maps to the **system.command.execute** policy, calls the bash guardrail, and returns `permission: allow|deny` plus optional `agentMessage`. No VS Code extension is required for interception; hooks are the mechanism.
+
+**Hook script path:** The hook script (`aport-cursor-hook.sh`) resolves `bin/aport-guardrail-bash.sh` relative to its own directory (script dir → parent = package root). When you install via **npx**, the installer writes the path to the script inside the npx cache (e.g. `…/node_modules/@aporthq/aport-agent-guardrails/bin/aport-cursor-hook.sh`), so the guardrail script is found at `…/bin/aport-guardrail-bash.sh`. If you copy the hook script elsewhere, ensure `bin/aport-guardrail-bash.sh` exists at the same relative location or set `APORT_GUARDRAIL_SCRIPT` (or equivalent) so the hook can find the evaluator.
+
+## Setup
+
+```bash
+npx @aporthq/aport-agent-guardrails cursor
+# or
+npx @aporthq/aport-agent-guardrails --framework=cursor
+```
+
+This runs the **passport wizard** and writes **`~/.cursor/hooks.json`** with the path to the APort hook script. The wizard uses a **framework-specific default** for where to store the passport: for Cursor the default is **`~/.cursor/aport/passport.json`** (so passport and evaluation data live with Cursor’s own data). The **first question** in the wizard is “Passport file path [default]:” — press Enter to use that default or type a different path. In non-interactive mode you can pass **`--output /path/to/passport.json`** to choose the path. Restart Cursor (or reload the window) after setup so the hooks are loaded.
+
+## Is it installed? How to check
+
+- **No `~/.cursor/hooks.json`?** That file is **created when you run the installer**. If you get `No such file or directory`, the Cursor integration is not installed yet. Run:
+  ```bash
+  npx @aporthq/aport-agent-guardrails cursor
+  ```
+  (or `npx @aporthq/aport-agent-guardrails --framework=cursor`). The installer writes `~/.cursor/hooks.json` and runs the passport wizard.
+- **Hooks file:** After installing, open `~/.cursor/hooks.json` (user-level) or `.cursor/hooks.json` (project). You should see `beforeShellExecution` and/or `preToolUse` entries whose `command` is the path to `aport-cursor-hook.sh`.
+- **Restart required:** Cursor loads hooks at startup. After installing, **restart Cursor** (or **Reload Window** from the command palette) so the new hooks are active.
+- **Passport:** The hook uses the passport created by the wizard. The default path for Cursor is **`~/.cursor/aport/passport.json`** (each framework has its own default; see [Default paths](#config) below). The resolver probes `~/.cursor`, then `~/.openclaw`, etc., so the hook finds the passport without extra config.
+
+## What the guardrail applies to (and what it doesn’t)
+
+The guardrail only runs when the **Cursor agent** is about to run a shell command or use a tool. It does **not** run when **you** type commands in the terminal yourself.
+
+| Who runs the command | Hook runs? | Guardrail can block? |
+|----------------------|------------|------------------------|
+| **You** type `rm file` in the Cursor terminal | No | No — it’s your shell, not the agent. |
+| **The agent** runs a command (e.g. after you ask “run rm file”) | Yes (`beforeShellExecution`) | Yes — exit 2 blocks the agent’s command. |
+| **The agent** uses a tool that sends a command | Yes (`preToolUse`) | Yes. |
+| **The agent** uses a built-in “delete file” action (no shell) | No | No — direct file API, no hook. |
+
+So:
+
+- **Checked:** When the **agent** runs a command in the terminal (e.g. `rm file`, `npm install`) or uses a tool that goes through the hook → our script runs and can block (exit 2).
+- **Not checked:** (1) **You** typing in the terminal — the hook is never invoked. (2) The agent using a built-in “delete file” / “edit file” action (editor API) — no shell, so no hook.
+
+To **test that the guardrail is working**, ask the **agent** to run a terminal command your passport blocks (e.g. “Run in the terminal: `rm -rf /path/to/file`”). Do **not** type the command yourself in the terminal — that bypasses the hook.
+
+## Test the guardrail and inspect status/logs
+
+**Two ways to test:** (1) Run the hook from the terminal to verify the script and populate the audit log. (2) Ask the Cursor **agent** to run a command in chat to verify the full installation.
+
+### 1. Test the script (terminal)
+
+From the repo root (or wherever the hook script lives):
+
+```bash
+# Allow path (e.g. cat a file) — exit 0
+echo '{"command":"cat test.md"}' | bin/aport-cursor-hook.sh
+echo "Exit: $?"
+
+# Deny path (e.g. rm -rf) — exit 2
+echo '{"command":"rm -rf test.md"}' | bin/aport-cursor-hook.sh
+echo "Exit: $?"
+```
+
+### 2. Inspect status and audit log
+
+After running the hook (or after the agent runs a command), check the passport and decisions:
+
+```bash
+# From repo root: status (passport, capabilities, limits, latest decision, recent activity)
+bin/aport-status.sh
+
+# Audit log: one line per decision (timestamp, tool, decision_id, allow/deny, policy, context e.g. command)
+cat ~/.cursor/aport/audit.log
+
+# Last decision (full OAP JSON)
+cat ~/.cursor/aport/decision.json
+```
+
+If you used a different passport path during setup, the audit log and decision file are in that path’s `aport/` dir (e.g. `~/.openclaw/aport/` if you chose the OpenClaw default).
+
+### 3. Test the real installation (Cursor agent)
+
+In **Cursor chat**, ask the agent to run a command (do not type it in the terminal yourself):
+
+- **Should allow:** “Run in the terminal: `cat test.md`” — command runs; audit log gets an `allow=true` line.
+- **Should block:** “Run in the terminal: `rm -rf test.md`” — Cursor should block the command; audit log gets an `allow=false` line.
+
+Then run `bin/aport-status.sh` and `cat ~/.cursor/aport/audit.log` to confirm the new entries.
+
+## Config
+
+- **Hooks file:** `~/.cursor/hooks.json` (user) or `.cursor/hooks.json` (project). The installer writes the former by default.
+- **Passport and default paths:** Each framework stores passport and evaluation data in its own default location. For Cursor the default is **`~/.cursor/aport/passport.json`** (with `decision.json` and `audit.log` in `~/.cursor/aport/`). You can always choose a different path: in the wizard the first question is the passport path (default shown in brackets); in non-interactive mode use **`--output /path/to/passport.json`**. The Python evaluator and bash resolver use the same default-path map (e.g. `python/aport_guardrails/core/evaluator.py` → `DEFAULT_PASSPORT_PATHS`, `bin/lib/config.sh` → `get_default_passport_path`).
+- **Hook script:** `bin/aport-cursor-hook.sh` in this repo (or in the npm package when installed via npx). The installer puts its absolute path into `hooks.json`. The hook does not set a config dir; the path resolver probes `~/.cursor`, `~/.openclaw`, `~/.aport/langchain`, etc., and uses the first directory that contains `aport/passport.json`.
+
+## Status and logs
+
+- **Passport status:** Run `bin/aport-status.sh` (from repo) or the guardrail’s status script. It uses the same path resolution as the hook (probes `~/.cursor`, `~/.openclaw`, etc.), so it will show the passport under `~/.cursor/aport/` if that’s where you created it.
+- **Audit trail:** Allow/deny decisions are appended to the audit log in the same data dir as the passport (e.g. `~/.cursor/aport/audit.log` when using the Cursor default). Each line includes timestamp, tool, decision_id, allow/deny, policy id, and **context** (the actual command for `system.command.execute`, recipient for messaging, repo/branch for merge). `bin/aport-status.sh` shows this context in **Latest Decision** and **Recent Activity**.
+
+## Suspend (kill switch)
+
+Same as all frameworks: **passport is the source of truth**. Set passport `status` to `suspended` (or `active` to resume). The guardrail denies every call until the passport is active again.
+
+## Using the same script in VS Code (Copilot) and Claude Code
+
+- **VS Code + GitHub Copilot:** Add a PreToolUse hook in `~/.claude/settings.json` (or project `.claude/settings.json`, or `.github/hooks/*.json`) that runs the same script. See [Agent hooks (Preview)](https://code.visualstudio.com/docs/copilot/customization/hooks).
+- **Claude Code:** Configure `~/.claude/settings.json` to run the same APort hook script for PreToolUse.
+
+The script accepts multiple input shapes (e.g. `command`, `tool`/`input`) and returns the host-expected JSON; **exit 0** = allow, **exit 2** = block.
+
+## Using the Node package (optional)
+
+If you need the evaluator or hook path in your own Node/TypeScript code (e.g. custom tooling or scripts):
+
+```bash
+npm install @aporthq/aport-agent-guardrails-cursor   # or -core if you only need Evaluator
+```
+
+```ts
+import { Evaluator, getHookPath } from '@aporthq/aport-agent-guardrails-cursor';
+
+// Default path where the hook script is expected (~/.cursor/aport-cursor-hook.sh)
+const hookPath = getHookPath();
+
+// Use the evaluator programmatically (same as @aporthq/aport-agent-guardrails-core)
+const evaluator = new Evaluator(null, 'cursor');
+const decision = evaluator.verifySync({}, { capability: 'system.command.execute.v1' }, { tool: 'run_command', input: 'ls' });
+```
+
+Runtime enforcement in Cursor is done by the **hook script**, not by this package; the package is for programmatic use only.
+
+## Tests
+
+- **Unit:** Hook script with mock stdin — allow (exit 0, JSON `allowed: true`), deny (exit 2, `allowed: false`). See `tests/unit/test-cursor-hook.sh`.
+- **Integration:** Run script with sample Cursor-style JSON; assert output format and exit code. Cursor setup: `tests/frameworks/cursor/setup.sh` (writes hooks.json, config dir).
+
+## Status
+
+Implemented (Story E). **APort Agent Guardrail for Cursor.** Installer: `npx @aporthq/aport-agent-guardrails cursor`; hook script: `bin/aport-cursor-hook.sh`; config: `~/.cursor/hooks.json`. Same script usable for VS Code Copilot and Claude Code.

package/docs/frameworks/langchain.md

@@ -0,0 +1,72 @@
+# APort Agent Guardrail — LangChain / LangGraph
+
+**How the agent guardrail works:** LangChain’s callback system exposes `on_tool_start` (and related hooks) on `BaseCallbackHandler` / `AsyncCallbackHandler`. The **APort Agent Guardrail for LangChain** implements a callback that runs when a tool is about to execute; we call the APort evaluator and raise to block execution if denied. Note: in some agent setups, tool callbacks can be unreliable; register callbacks on the executor and test your flow.
+
+- **Integration:** `AsyncCallbackHandler` with `on_tool_start` (or equivalent)
+- **Config:** `~/.aport/langchain/` or `.aport/config.yaml`
+
+## Two ways to use APort
+
+| Use case | What it is | When to use it |
+|----------|------------|----------------|
+| **Guardrails (CLI/setup)** | One-line installer: runs the **passport wizard**, writes config, prints next steps. Does not run your app. | Getting started: create passport and config so the library can find them. |
+| **Core (library)** | The **evaluator** and **framework callback** in your code. Calls policy + passport to allow/deny each tool call. | Integrating into your app: add the callback so tool runs are checked before execution. |
+
+You typically use **both**: run the CLI once to create passport and config, then use the library in your LangChain app so every tool call is verified.
+
+---
+
+## Setup (Guardrails — create passport and config)
+
+**Python**
+
+```bash
+npx @aporthq/aport-agent-guardrails langchain   # wizard + config (optional)
+pip install aport-agent-guardrails-langchain
+aport-langchain setup
+```
+
+**Node**
+
+```bash
+npx @aporthq/aport-agent-guardrails langchain   # wizard + config
+npm install @aporthq/aport-agent-guardrails-langchain   # callback handler (depends on -core)
+```
+
+## Using the library (Core) in your app
+
+**Python:** Add `APortCallback()` to your agent's callbacks. Config is read from `~/.aport/langchain/` or `.aport/config.yaml`.
+
+```python
+from langchain.agents import initialize_agent
+from aport_guardrails_langchain import APortCallback
+
+agent = initialize_agent(
+    tools=tools,
+    llm=llm,
+    callbacks=[APortCallback()]
+)
+```
+
+**Node:** Add `APortGuardrailCallback` to your chain/agent callbacks. Config is read from `~/.aport/langchain/` or `.aport/config.yaml`.
+
+```ts
+import { APortGuardrailCallback } from '@aporthq/aport-agent-guardrails-langchain';
+
+const callback = new APortGuardrailCallback(); // optional: { configPath: '...', framework: 'langchain' }
+// Pass callback to your LangChain run (e.g. callbacks: [callback])
+// On deny, the callback throws GuardrailViolationError.
+```
+
+## Config
+
+- **Config:** `~/.aport/langchain/` or `.aport/config.yaml`
+- **Usage:** Add the callback to your agent (see above).
+
+## Suspend (kill switch)
+
+Same standard as all frameworks: **passport is the source of truth**—no separate file. Local: set passport `status` to `suspended` (or `active` to resume). Remote: use API mode and suspend in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+
+## Status
+
+Implemented. **APort Agent Guardrail for LangChain.** Package: `aport-agent-guardrails-langchain`; CLI: `aport-langchain setup`.

package/docs/frameworks/n8n.md

@@ -0,0 +1,40 @@
+# APort Guardrails — n8n
+
+**Coming soon.** n8n support is not yet available; custom node and runtime integration are in progress.
+
+**How guardrails work (planned):** n8n workflows run as a graph of nodes. We provide a custom **APort Guardrail** node that calls the evaluator (API or local); the node outputs allow/deny. You place it **before** action nodes and branch on the result (e.g. IF node on allow) so that only allowed actions run. No code; guardrail is enforced by workflow structure.
+
+- **Integration:** Custom node (or HTTP Request node to APort API) before action nodes; branch on allow/deny
+- **Config:** n8n credentials store (agent_id or passport)
+
+## Two ways to use APort (planned)
+
+| Use case | What it is | When to use it |
+|----------|------------|----------------|
+| **Guardrails (CLI/setup)** | Installer: runs the **passport wizard**, writes config; (when shipped) installs the **custom node** so workflows can use the APort Guardrail node. | Getting started: create passport and config; install the node so it appears in n8n. |
+| **Core (library / node)** | The **evaluator** and **custom node**: your workflow calls the node before an action; the node returns allow/deny so you can branch. The npm package `@aporthq/aport-agent-guardrails-n8n` is not published yet. | When available: add the APort Guardrail node before action nodes and branch on the result. |
+
+n8n support is **coming soon**; the custom node and npm package are not yet released.
+
+---
+
+## Setup
+
+```bash
+npx @aporthq/aport-agent-guardrails n8n
+# Runs passport wizard and writes config only. Custom node is NOT yet available.
+# When the node is released, it will install to ~/.n8n/custom/ and you will restart n8n.
+```
+
+## Config
+
+- **Credentials:** n8n credentials store (agent_id or passport)
+- **Workflow:** Drag "APort Guardrail" node before action; branch on allow/deny.
+
+## Suspend (kill switch)
+
+Same standard as all frameworks: **passport is the source of truth**—no separate file. Local: set passport `status` to `suspended` (or `active` to resume). Remote: use API mode and suspend in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+
+## Status
+
+High priority (Phase 3).

package/docs/frameworks/openclaw.md

@@ -0,0 +1,40 @@
+# APort Guardrails — OpenClaw
+
+**How guardrails work:** OpenClaw’s plugin API provides a `before_tool_call` hook that runs **before every tool execution**. The APort plugin registers this hook and calls the shared evaluator (API or local script); the platform blocks the tool if the evaluator returns deny. The model cannot skip it.
+
+- **Integration:** `before_tool_call` plugin (`extensions/openclaw-aport`)
+- **Config:** `~/.openclaw/aport-config.yaml`
+
+## Two ways to use APort
+
+| Use case | What it is | When to use it |
+|----------|------------|----------------|
+| **Guardrails (CLI/setup)** | Full installer: runs the **passport wizard**, writes config, installs the **OpenClaw plugin** so every tool call goes through the evaluator. | Getting started: one command sets up config, passport, and the plugin. |
+| **Core (runtime)** | The **evaluator** (bash script or API) that the plugin calls before each tool run. Same policy + passport as other frameworks. For **programmatic** use (e.g. custom scripts), you can use the **Python** (`aport_guardrails`) or **Node** (`@aporthq/aport-agent-guardrails-core`) library. | Guardrails = the plugin uses the evaluator automatically. Use the library only if you're building custom tooling. |
+
+For OpenClaw, you use **Guardrails (CLI)** once to install the plugin; the **Core** (evaluator) then runs automatically on every tool call.
+
+---
+
+## Setup
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw
+# or
+npx @aporthq/aport-agent-guardrails
+# then choose openclaw
+```
+
+## Config
+
+- **Config dir:** `~/.openclaw` (or `OPENCLAW_HOME`)
+- **Passport:** Created by wizard or use hosted `agent_id`
+- **Plugin:** `extensions/openclaw-aport`
+
+## Suspend (kill switch)
+
+Same standard as all frameworks: **passport is the source of truth**—no separate file. Local: set passport `status` to `suspended` (or `active` to resume). Remote: use API mode and suspend in [APort](https://aport.io); all agents using that passport deny within ≤30s.
+
+## Status
+
+Shipped; in production.

package/docs/launch/ADD_APORT_AWESOME_LISTS_INSTRUCTIONS.md

@@ -0,0 +1,146 @@
+# Add APort Agent Guardrails to Awesome Lists — Instructions
+
+Standard open-source workflow: **fork upstream → clone your fork → edit → push → open PR from your fork to upstream.**
+
+Use the script `docs/launch/scripts/add-aport-awesome-pr.sh`. Repo details from [README.md](../../README.md) and [package.json](../../package.json).
+
+**Standard entry (short):**
+- **Name:** APort Agent Guardrails  
+- **Repo:** https://github.com/aporthq/aport-agent-guardrails  
+- **npm:** https://www.npmjs.com/package/@aporthq/aport-agent-guardrails  
+- **Description:** Pre-action authorization for OpenClaw/agent frameworks. `before_tool_call` plugin, 40+ blocked patterns, local or API.  
+- **Setup:** `npx @aporthq/aport-agent-guardrails`
+
+---
+
+## 1. SamurAIGPT/awesome-openclaw
+
+- **Fork + clone:** Run the script (see workflow below). Your fork is cloned to `/tmp/aport-awesome-prs/SamurAIGPT-awesome-openclaw/`; `origin` = your fork.
+- **File:** `README.md`
+- **Section:** `## Security` → **Security Tools** table (after the aquaman row).
+- **Add this row** (after the line with `aquaman`):
+
+```markdown
+| [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) | - | Pre-action authorization for OpenClaw; `before_tool_call` plugin, allowlist + 40+ blocked patterns, local or API. Setup: `npx @aporthq/aport-agent-guardrails` |
+```
+
+- **Anchor:** Search for `### Security Tools` then the table with `| [aquaman]`. Add the new row after the aquaman row (before `### Security Resources`).
+
+---
+
+## 2. VoltAgent/awesome-openclaw-skills
+
+- **Fork + clone:** Run the script. Your fork is cloned to `/tmp/aport-awesome-prs/VoltAgent-awesome-openclaw-skills/`; `origin` = your fork.
+- **File:** `README.md`
+- **Section:** **### Security & Passwords** — add in alphabetical order with other skills (same bullet format as existing entries).
+- **Add** (match list format: `- [slug](url) - description`; alphabetically after amai-id, before audit-badge-demo):
+
+```markdown
+- [aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails) - Pre-action authorization for OpenClaw; before_tool_call plugin, 40+ blocked patterns, local or API. Setup: npx @aporthq/aport-agent-guardrails
+```
+
+- **Note:** This list only includes skills published in the OpenClaw skills repo; if APort is not there yet, the maintainers may ask you to publish the skill first. See CONTRIBUTING.md.
+
+---
+
+## 3. hesamsheikh/awesome-openclaw-usecases
+
+- **Fork + clone:** Script clones your fork to `/tmp/aport-awesome-prs/hesamsheikh-awesome-openclaw-usecases/`.
+- **File:** `README.md`
+- **Section:** Add a new section **## Security & Guardrails** (e.g. after `## Finance & Trading`, before `## 🤝 Contributing`).
+- **Add:**
+
+```markdown
+## Security & Guardrails
+
+| Name | Description |
+|------|-------------|
+| [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) | Pre-action authorization for OpenClaw; every tool call checked before it runs. Allowlist + 40+ blocked patterns, local or API. Setup: `npx @aporthq/aport-agent-guardrails` |
+```
+
+---
+
+## 4. Jenqyang/Awesome-AI-Agents
+
+- **Fork + clone:** Script clones your fork to `/tmp/aport-awesome-prs/Jenqyang-Awesome-AI-Agents/`.
+- **File:** `README.md`
+- **Section:** Find **Tools** or **Safety / Guardrails** (or similar). If there is a bullet list of tools, add:
+- **Add:**
+
+```markdown
+- [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) - Pre-action authorization for OpenClaw and agent frameworks. `before_tool_call` plugin, 40+ blocked patterns, local or API. Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+- **Note:** Open the README and place the entry in the most appropriate subsection (e.g. Tools or a guardrails/safety section). Match existing list style (dash vs table).
+
+---
+
+## 5. e2b-dev/awesome-ai-agents
+
+- **Fork + clone:** Script clones your fork to `/tmp/aport-awesome-prs/e2b-dev-awesome-ai-agents/`.
+- **File:** `README.md`
+- **Section:** Locate a Security / Guardrails / Tools section. Format may be minimal; match existing style.
+- **Add (bullet style):**
+
+```markdown
+- [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) - Pre-action authorization for OpenClaw and agent frameworks. `before_tool_call` plugin, 40+ blocked patterns. Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+---
+
+## 6. slavakurilyak/awesome-ai-agents
+
+- **Fork + clone:** Script clones your fork to `/tmp/aport-awesome-prs/slavakurilyak-awesome-ai-agents/`.
+- **File:** `README.md` (or the main list file; check repo structure).
+- **Section:** Find Guardrails / Safety / Security or Tools. Match existing entry format (often project name + stars + description).
+- **Add (adjust to match list style):**
+
+```markdown
+- [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) - Pre-action authorization for OpenClaw/agent frameworks; `before_tool_call` plugin, 40+ blocked patterns, local or API. Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+---
+
+## 7. TalEliyahu/Awesome-AI-Security
+
+- **Fork + clone:** Script clones your fork to `/tmp/aport-awesome-prs/TalEliyahu-Awesome-AI-Security/`.
+- **File:** `README.md`
+- **Section:** **Jailbreak & Policy Enforcement (Guardrails)** — add after the Guardrails entry (e.g. after the line with `guardrails-ai/guardrails`).
+- **Add** (match their format with GitHub stars badge if they use it):
+
+```markdown
+- **[APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails)** [![GitHub Repo stars](https://img.shields.io/github/stars/aporthq/aport-agent-guardrails?logo=github&label=&style=social)](https://github.com/aporthq/aport-agent-guardrails) - Pre-action authorization for OpenClaw/agent frameworks; `before_tool_call` hook, passport-driven, 40+ blocked patterns, local or API. Setup: `npx @aporthq/aport-agent-guardrails`
+```
+
+---
+
+## Repetitive workflow (per repo)
+
+1. **Fork and clone** (from this repo root). This forks the upstream repo to your GitHub account and clones your fork:
+   ```bash
+   ./docs/launch/scripts/add-aport-awesome-pr.sh <owner/repo>
+   ```
+   Example: `./docs/launch/scripts/add-aport-awesome-pr.sh SamurAIGPT/awesome-openclaw`  
+   Clone path: `/tmp/aport-awesome-prs/<owner>-<repo>/` (e.g. `SamurAIGPT-awesome-openclaw`). Remote `origin` is your fork.
+
+2. **Edit** the clone: open the file and section above, add the exact line(s) for that repo.
+
+3. **Push and open PR** (from your fork to upstream):
+   ```bash
+   ./docs/launch/scripts/add-aport-awesome-pr.sh <owner/repo> pr
+   ```
+
+**PR title (suggested):** `Add APort Agent Guardrails`  
+**PR body (suggested):**
+```markdown
+Adds [APort Agent Guardrails](https://github.com/aporthq/aport-agent-guardrails) — pre-action authorization for OpenClaw and compatible agent frameworks. Policy runs in the platform `before_tool_call` hook; 40+ blocked patterns, allowlist, local or API. Setup: `npx @aporthq/aport-agent-guardrails`.
+```
+
+---
+
+## Reference
+
+- **Repo:** https://github.com/aporthq/aport-agent-guardrails  
+- **npm:** https://www.npmjs.com/package/@aporthq/aport-agent-guardrails  
+- **Quick start:** https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md  
+- **package.json** name: `@aporthq/aport-agent-guardrails`, description: "Policy enforcement guardrails for OpenClaw-compatible agent frameworks"