fix plugin and docs

Author: ConnorWhelan11

docs/src/concepts/architecture.md

@@ -58,7 +58,7 @@ The intended integration is at the **tool boundary** (your agent runtime calls C
 |---------|-------------|
 | `@clawdstrike/sdk` | Crypto/receipts + a subset of guards + prompt-security utilities (no full policy engine) |
 | `@clawdstrike/adapter-core` | Framework-agnostic adapter interfaces |
-| `@clawdstrike/openclaw` | OpenClaw plugin |
+| `@clawdstrike/clawdstrike-security` | OpenClaw plugin (plugin id: `clawdstrike-security`) |
 | `@clawdstrike/vercel-ai` | Vercel AI SDK integration |
 | `@clawdstrike/langchain` | LangChain integration |
 | `@clawdstrike/hush-cli-engine` | Node.js bridge to Rust CLI |

docs/src/guides/openclaw-integration.md

@@ -1,17 +1,54 @@
-# OpenClaw Integration (experimental)
+# OpenClaw Integration
 
 This repository contains an OpenClaw plugin under `packages/clawdstrike-openclaw`.
 
 ## Enforcement boundaries (read this)
 
-The current OpenClaw plugin enforces policy at the **tool boundary**:
+The OpenClaw plugin enforces policy at the **tool boundary**:
 
 - **Preflight** via the `policy_check` tool (agents should call it before risky operations).
 - **Post-action** via the `tool_result_persist` hook (can block/redact what is persisted + record violations).
 
-This is **not** an OS sandbox and does not intercept syscalls. If an agent/runtime bypasses the OpenClaw tool layer, clawdstrike cannot stop it.
+This is **not** an OS sandbox and does not intercept syscalls. If an agent/runtime bypasses the OpenClaw tool layer, Clawdstrike cannot stop it.
 
-CI runs an **in-process simulated runtime** E2E (`npm run e2e` in `packages/clawdstrike-openclaw`) to verify wiring/behavior without starting OpenClaw itself.
+## Installation
+
+### From local development (alpha)
+
+```bash
+# Link the local package
+openclaw plugins install --link /path/to/hushclaw/packages/clawdstrike-openclaw
+
+# Enable the plugin
+openclaw plugins enable clawdstrike-security
+
+# Verify it's loaded
+openclaw plugins list | grep clawdstrike
+```
+
+### From npm (when published)
+
+```bash
+openclaw plugins install @clawdstrike/clawdstrike-security
+```
+
+## Quick verification
+
+```bash
+# Check plugin status
+openclaw clawdstrike status
+
+# Test policy checks
+openclaw clawdstrike check file_read ~/.ssh/id_rsa
+# → Denied by forbidden_path
+
+openclaw clawdstrike check file_read /tmp/test.txt
+# → Action allowed
+
+# Test with an agent
+openclaw agent --local --session-id test \
+  --message "Use policy_check to check if reading ~/.ssh/id_rsa is allowed"
+```
 
 ## Important: policy schema is different from Rust
 
@@ -21,23 +58,70 @@ If you paste a Rust policy into OpenClaw, it should fail closed (and it does): u
 
 See [Schema Governance](../concepts/schema-governance.md) for the repo-wide versioning/compat rules.
 
+## Configuration
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "clawdstrike-security": {
+        "enabled": true,
+        "config": {
+          "policy": "./.hush/policy.yaml",
+          "mode": "deterministic",
+          "logLevel": "info"
+        }
+      }
+    }
+  }
+}
+```
+
 ## Recommended flow
 
-- Use a built-in ruleset as a starting point: `clawdstrike:ai-agent-minimal` or `clawdstrike:ai-agent`.
-- Validate policies before running agents:
+1. Use a built-in ruleset as a starting point: `clawdstrike:ai-agent-minimal` or `clawdstrike:ai-agent`.
 
-```bash
-# The OpenClaw plugin ships its own Node CLI named `clawdstrike`.
-# Use `npx` to avoid confusion with the deprecated Rust `clawdstrike` binary.
-npx clawdstrike policy lint .hush/policy.yaml
+2. Test policy checks via CLI:
+   ```bash
+   openclaw clawdstrike check file_read ~/.ssh/id_rsa
+   openclaw clawdstrike check network api.github.com
+   ```
+
+3. Use `policy_check` tool for **preflight** decisions (before the agent attempts an action).
+
+4. Use the OpenClaw hook(s) for **post-action** defense-in-depth (e.g., block/strip tool outputs that contain secrets).
+
+## Agent tool: policy_check
+
+The plugin registers a `policy_check` tool that agents can use:
+
+```
+policy_check({ action: "file_read", resource: "~/.ssh/id_rsa" })
+→ {
+    "allowed": false,
+    "denied": true,
+    "guard": "forbidden_path",
+    "message": "Denied by forbidden_path: Access to forbidden path...",
+    "suggestion": "SSH keys are protected..."
+  }
 ```
 
-- Use `policy_check` for **preflight** decisions (before the agent attempts an action).
-- Use the OpenClaw hook(s) for **post-action** defense-in-depth (e.g., block/strip tool outputs that contain secrets).
+**Actions:** `file_read`, `file_write`, `network`, `command`, `tool_call`
+
+## CLI commands
+
+```bash
+# Plugin status
+openclaw clawdstrike status
+
+# Check an action
+openclaw clawdstrike check <action> <resource>
+```
 
 ## Where to look
 
 - OpenClaw plugin docs: `packages/clawdstrike-openclaw/docs/`
 - OpenClaw plugin code: `packages/clawdstrike-openclaw/src/`
-- Example (minimal wiring): `examples/hello-secure-agent/`
-- Example (agentic EDR triage loop): `examples/bb-edr/`
+- Example (minimal wiring): `packages/clawdstrike-openclaw/examples/hello-secure-agent/`

examples/bb-edr/openclaw.json

@@ -25,7 +25,7 @@
 
   "plugins": {
     "entries": {
-      "@clawdstrike/openclaw": {
+      "clawdstrike-security": {
         "enabled": true,
         "config": {
           "policy": "./policy.yaml",

examples/hello-secure-agent/openclaw.json

@@ -23,24 +23,25 @@
     ]
   },
 
-  "plugins": [
-    {
-      "name": "@clawdstrike/openclaw",
-      "version": "^0.1.0",
-      "config": {
-        "policy": "./policy.yaml",
-        "mode": "deterministic",
-        "logLevel": "info",
-        "guards": {
-          "forbidden_path": true,
-          "egress": true,
-          "secret_leak": true,
-          "patch_integrity": true,
-          "mcp_tool": false
+  "plugins": {
+    "entries": {
+      "clawdstrike-security": {
+        "enabled": true,
+        "config": {
+          "policy": "./policy.yaml",
+          "mode": "deterministic",
+          "logLevel": "info",
+          "guards": {
+            "forbidden_path": true,
+            "egress": true,
+            "secret_leak": true,
+            "patch_integrity": true,
+            "mcp_tool": false
+          }
         }
       }
     }
-  ],
+  },
 
   "environment": {
     "HUSH_LOG_LEVEL": "info"

packages/clawdstrike-openclaw/docs/getting-started.md

@@ -13,9 +13,20 @@ This is **not** an OS sandbox. If an agent/runtime can access the filesystem/net
 
 ## Installation
 
+### From local development (recommended during alpha)
+
+```bash
+# Link the local package
+openclaw plugins install --link /path/to/hushclaw/packages/clawdstrike-openclaw
+
+# Enable the plugin
+openclaw plugins enable clawdstrike-security
+```
+
+### From npm (when published)
+
 ```bash
-npm install @clawdstrike/openclaw
-openclaw plugins enable @clawdstrike/openclaw
+openclaw plugins install @clawdstrike/clawdstrike-security
 ```
 
 ## Quick Start
@@ -46,72 +57,58 @@ on_violation: cancel
 
 ### 2. Configure OpenClaw
 
-Add to your `openclaw.json`:
+Add to your `~/.openclaw/openclaw.json`:
 
 ```json
 {
   "plugins": {
     "entries": {
-      "@clawdstrike/openclaw": {
+      "clawdstrike-security": {
         "enabled": true,
         "config": {
-          "policy": "./.hush/policy.yaml"
+          "policy": "./.hush/policy.yaml",
+          "mode": "deterministic"
         }
       }
     }
   }
 }
 ```
 
-### 3. Start OpenClaw
+### 3. Restart Gateway (if running)
 
 ```bash
-openclaw start
+openclaw gateway restart
 ```
 
 Clawdstrike is now configured for your OpenClaw runtime.
 
 ## Verify It Works
 
-Ask your agent: "Try to read ~/.ssh/id_rsa" (via whatever file-reading tool OpenClaw provides).
-
-Expected behavior: the tool result should be blocked/redacted and you should see a message indicating the `forbidden_path` guard denied it.
-
-## Using the CLI
-
-### Validate Your Policy
+### Using the CLI
 
 ```bash
-clawdstrike policy lint .hush/policy.yaml
-```
+# Check plugin status
+openclaw clawdstrike status
 
-### Test an Event
+# Test a policy check
+openclaw clawdstrike check file_read ~/.ssh/id_rsa
+# → Denied by forbidden_path: Access to forbidden path...
 
-Create `test-event.json`:
-```json
-{
-  "eventId": "example-1",
-  "eventType": "file_read",
-  "timestamp": "2026-02-02T00:00:00Z",
-  "data": { "type": "file", "path": "~/.ssh/id_rsa", "operation": "read" }
-}
+openclaw clawdstrike check file_read /tmp/test.txt
+# → Action allowed
 ```
 
-```bash
-clawdstrike policy test test-event.json --policy .hush/policy.yaml
-```
+### Using an Agent
 
-### Query Audit Log
+Ask your agent to use the policy_check tool:
 
 ```bash
-clawdstrike audit query --denied
+openclaw agent --local --session-id test \
+  --message "Use policy_check to check if reading ~/.ssh/id_rsa is allowed"
 ```
 
-### Explain a Block
-
-```bash
-clawdstrike why <event-id>
-```
+Expected: The agent uses `policy_check` and reports that access is denied by the `forbidden_path` guard.
 
 ## Agent Tools
 
@@ -120,15 +117,25 @@ clawdstrike why <event-id>
 Agents can use the `policy_check` tool to check permissions before attempting operations:
 
 ```
-policy_check({ action: "file_write", resource: "/etc/passwd" })
--> { allowed: false, denied: true, warn: false, guard: "forbidden_path", message: "Denied by forbidden_path: …" }
+policy_check({ action: "file_read", resource: "~/.ssh/id_rsa" })
+→ {
+    "allowed": false,
+    "denied": true,
+    "guard": "forbidden_path",
+    "message": "Denied by forbidden_path: Access to forbidden path...",
+    "suggestion": "SSH keys are protected. Consider using a different credential storage method."
+  }
 ```
 
-The tool provides:
+**Parameters:**
+- `action`: One of `file_read`, `file_write`, `network`, `command`, `tool_call`
+- `resource`: The resource to check (file path, domain/URL, command string, or tool name)
+
+**Response fields:**
 - `allowed`: Whether the action is permitted
 - `denied`: Whether the action is blocked
-- `reason` / `message`: Human-readable explanation
 - `guard`: Which guard made the decision
+- `reason` / `message`: Human-readable explanation
 - `suggestion`: Helpful alternative approaches
 
 ## Policy Reference
@@ -173,7 +180,7 @@ on_violation: cancel  # cancel | warn | log
 
 ## Built-in Rulesets
 
-Use predefined rulesets by extending them:
+Use predefined rulesets:
 
 ```yaml
 extends: clawdstrike:ai-agent-minimal
@@ -183,7 +190,34 @@ Available rulesets:
 - `clawdstrike:ai-agent-minimal` - Basic protection
 - `clawdstrike:ai-agent` - Standard development
 
+## Plugin Configuration Options
+
+```json
+{
+  "clawdstrike-security": {
+    "enabled": true,
+    "config": {
+      "policy": "./policy.yaml",
+      "mode": "deterministic",
+      "logLevel": "info",
+      "guards": {
+        "forbidden_path": true,
+        "egress": true,
+        "secret_leak": true,
+        "patch_integrity": true
+      }
+    }
+  }
+}
+```
+
+- `policy`: Path to policy YAML or built-in ruleset name
+- `mode`: `deterministic` (block), `advisory` (warn), or `audit` (log only)
+- `logLevel`: `debug`, `info`, `warn`, or `error`
+- `guards`: Enable/disable specific guards
+
 ## Next Steps
 
 - Check the [Examples](../examples/) directory
-- Run `clawdstrike --help` to explore the plugin CLI surface
+- Run `openclaw clawdstrike --help` to explore CLI commands
+- See the main [Clawdstrike documentation](../../../../docs/src/reference/guards/README.md) for guard details

packages/clawdstrike-openclaw/examples/hello-secure-agent/openclaw.json

@@ -1,7 +1,7 @@
 {
   "plugins": {
     "entries": {
-      "@clawdstrike/openclaw": {
+      "clawdstrike-security": {
         "enabled": true,
         "config": {
           "policy": "./policy.yaml",