From f470f4b86571e9f61974c3cee8f54fd5beaa3273 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 11:26:00 +0800
Subject: [PATCH 01/14] fix(setup): support multi-agent environments (issue
 #48)

- Add --target <path> for explicit install directory override
- Add --scope user|project|agent <name> for per-agent skill pools
- Validate directory writability during auto-detection (skip read-only dirs)
- Prompt user to select when multiple writable ~/.openclaw*/ dirs are found
- Parse all flags upfront; uninstall now uses --uninstall flag (positional still works)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 106 insertions(+), 7 deletions(-)

diff --git a/setup.sh b/setup.sh
index 755aa4a..4d4c882 100755
--- a/setup.sh
+++ b/setup.sh
@@ -4,12 +4,52 @@ set -euo pipefail
 # GoPlus AgentGuard — One-click setup
 # Supports: Claude Code, OpenClaw, ClawHub
 # Detects the platform and installs to the correct location.
+#
+# Usage:
+#   ./setup.sh                              Auto-detect platform
+#   ./setup.sh --target <path>              Install to explicit directory
+#   ./setup.sh --scope user                 Install to ~/.openclaw/skills
+#   ./setup.sh --scope project <name>       Install to ~/.openclaw-<name>/skills
+#   ./setup.sh --scope agent <name>         Install to ~/.openclaw-<name>/skills
+#   ./setup.sh --uninstall                  Remove installed skill
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILL_SRC="$SCRIPT_DIR/skills/agentguard"
 AGENTGUARD_DIR="$HOME/.agentguard"
 MIN_NODE_VERSION=18
 
+# ---- Parse arguments ----
+TARGET_DIR=""
+SCOPE_TYPE=""
+SCOPE_NAME=""
+UNINSTALL=false
+POSITIONAL=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET_DIR="${2:-}"
+      [ -z "$TARGET_DIR" ] && { echo "  ERROR: --target requires a path argument."; exit 1; }
+      shift 2
+      ;;
+    --scope)
+      SCOPE_TYPE="${2:-}"
+      case "$SCOPE_TYPE" in
+        user) shift 2 ;;
+        project|agent)
+          SCOPE_NAME="${3:-}"
+          [ -z "$SCOPE_NAME" ] && { echo "  ERROR: --scope $SCOPE_TYPE requires a name argument."; exit 1; }
+          shift 3
+          ;;
+        *) echo "  ERROR: --scope must be one of: user, project, agent"; exit 1 ;;
+      esac
+      ;;
+    --uninstall|uninstall) UNINSTALL=true; shift ;;
+    *) POSITIONAL+=("$1"); shift ;;
+  esac
+done
+set -- "${POSITIONAL[@]+"${POSITIONAL[@]}"}"
+
 echo ""
 echo "  GoPlus AgentGuard — AI Agent Security Guard"
 echo "  ============================================="
@@ -38,19 +78,78 @@ fi
 
 # ---- Detect platform ----
 detect_platform() {
-  # Check OpenClaw first (workspace skills or managed skills)
-  if [ -d "$HOME/.openclaw" ]; then
-    # Prefer workspace skills if workspace exists
-    if [ -d "$HOME/.openclaw/workspace" ]; then
-      SKILLS_DIR="$HOME/.openclaw/workspace/skills/agentguard"
+  # --target overrides all detection
+  if [ -n "$TARGET_DIR" ]; then
+    SKILLS_DIR="$TARGET_DIR"
+    PLATFORM="custom"
+    return
+  fi
+
+  # --scope selects a specific agent/project directory
+  if [ -n "$SCOPE_TYPE" ]; then
+    case "$SCOPE_TYPE" in
+      user)
+        SKILLS_DIR="$HOME/.openclaw/skills/agentguard"
+        PLATFORM="openclaw-user"
+        ;;
+      project)
+        SKILLS_DIR="$HOME/.openclaw-${SCOPE_NAME}/skills/agentguard"
+        PLATFORM="openclaw-project:$SCOPE_NAME"
+        ;;
+      agent)
+        SKILLS_DIR="$HOME/.openclaw-${SCOPE_NAME}/skills/agentguard"
+        PLATFORM="openclaw-agent:$SCOPE_NAME"
+        ;;
+    esac
+    return
+  fi
+
+  # Auto-detect: collect all writable ~/.openclaw* directories
+  local candidates=()
+  for dir in "$HOME"/.openclaw*/; do
+    [ -d "$dir" ] || continue
+    [ -w "$dir" ] || continue
+    candidates+=("$dir")
+  done
+
+  if [ "${#candidates[@]}" -eq 1 ]; then
+    local oc_dir="${candidates[0]%/}"
+    if [ -d "$oc_dir/workspace" ] && [ -w "$oc_dir/workspace" ]; then
+      SKILLS_DIR="$oc_dir/workspace/skills/agentguard"
       PLATFORM="openclaw-workspace"
     else
-      SKILLS_DIR="$HOME/.openclaw/skills/agentguard"
+      SKILLS_DIR="$oc_dir/skills/agentguard"
       PLATFORM="openclaw-managed"
     fi
     return
   fi
 
+  if [ "${#candidates[@]}" -gt 1 ]; then
+    echo "  Multiple writable OpenClaw directories found:"
+    local i=1
+    for dir in "${candidates[@]}"; do
+      echo "    [$i] ${dir%/}"
+      i=$((i + 1))
+    done
+    echo ""
+    printf "  Select target [1-%d]: " "${#candidates[@]}"
+    read -r choice
+    if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le "${#candidates[@]}" ]; then
+      local selected="${candidates[$((choice - 1))]%/}"
+      if [ -d "$selected/workspace" ] && [ -w "$selected/workspace" ]; then
+        SKILLS_DIR="$selected/workspace/skills/agentguard"
+        PLATFORM="openclaw-workspace"
+      else
+        SKILLS_DIR="$selected/skills/agentguard"
+        PLATFORM="openclaw-managed"
+      fi
+      return
+    else
+      echo "  ERROR: Invalid selection. Use --target <path> or --scope agent <name> to specify explicitly."
+      exit 1
+    fi
+  fi
+
   # Check Claude Code
   if [ -d "$HOME/.claude" ]; then
     SKILLS_DIR="$HOME/.claude/skills/agentguard"
@@ -69,7 +168,7 @@ echo "  Install target:    $SKILLS_DIR"
 echo ""
 
 # ---- Uninstall mode ----
-if [ "${1:-}" = "--uninstall" ] || [ "${1:-}" = "uninstall" ]; then
+if [ "$UNINSTALL" = true ]; then
   echo "  Uninstalling GoPlus AgentGuard..."
   rm -rf "$SKILLS_DIR" 2>/dev/null && echo "  Removed skill from $SKILLS_DIR" || true
   # Also clean up other possible locations

From ca3c120251c606038310ddaa07231e49e10caa23 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 11:41:05 +0800
Subject: [PATCH 02/14] fix(setup): run npm install in correct directory (issue
 #49)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The script was cd-ing into skills/agentguard/scripts/ before running
npm install, but package.json lives in skills/agentguard/. npm silently
walked up and found the parent package.json, installing node_modules
there instead of in scripts/ — causing runtime failures when scripts
tried to resolve their dependencies.

Fixes:
- Step 2: cd into $SKILL_SRC (skills/agentguard/) where package.json lives
- Step 4: copy package.json from $SKILL_SRC into $SKILLS_DIR/scripts/
  before running npm install there, so node_modules land next to the scripts
- Remove stale copy of package.json/package-lock.json from scripts/ loop
  (those files don't exist in scripts/ and the copy was a no-op)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/setup.sh b/setup.sh
index 755aa4a..70dd531 100755
--- a/setup.sh
+++ b/setup.sh
@@ -97,8 +97,8 @@ fi
 
 # ---- Step 2: Install CLI dependencies ----
 echo "[2/5] Installing CLI dependencies..."
-if [ -d "$SKILL_SRC/scripts" ]; then
-  cd "$SKILL_SRC/scripts"
+if [ -f "$SKILL_SRC/package.json" ]; then
+  cd "$SKILL_SRC"
   npm install 2>/dev/null
   echo "  OK: CLI dependencies installed"
 fi
@@ -116,7 +116,7 @@ echo "[4/5] Installing scripts and dependencies..."
 mkdir -p "$SKILLS_DIR/scripts"
 
 # Copy script files
-for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
+for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts; do
   [ -f "$SKILL_SRC/scripts/$f" ] && cp "$SKILL_SRC/scripts/$f" "$SKILLS_DIR/scripts/" 2>/dev/null || true
 done
 
@@ -126,6 +126,10 @@ if [ -d "$SKILL_SRC/scripts/data" ]; then
   cp -r "$SKILL_SRC/scripts/data/"* "$SKILLS_DIR/scripts/data/" 2>/dev/null || true
 fi
 
+# Copy package.json and node_modules from skills/agentguard/ (where npm install was run)
+cp "$SKILL_SRC/package.json" "$SKILLS_DIR/scripts/package.json" 2>/dev/null || true
+[ -f "$SKILL_SRC/package-lock.json" ] && cp "$SKILL_SRC/package-lock.json" "$SKILLS_DIR/scripts/package-lock.json" 2>/dev/null || true
+
 # Install node_modules in the target (avoids symlink issues in containers)
 cd "$SKILLS_DIR/scripts"
 if [ -f "package.json" ]; then

From 4c8eaa5cb93e851a9405700d0c4ac6dfadd1f200 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 11:48:54 +0800
Subject: [PATCH 03/14] fix(setup): run npm install in correct directory (issue
 #49)

package.json lives in skills/agentguard/, not scripts/. The old code
cd'd into scripts/ before running npm install, so npm silently walked
up to the parent and installed node_modules there instead of where
scripts expect them.

Fix: copy package.json to $SKILLS_DIR (the skill root) and run a single
npm install there. Scripts are always invoked as:
  cd $SKILLS_DIR && node scripts/<script>
so Node's module resolution finds node_modules at $SKILLS_DIR without
needing a second install in scripts/.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh | 44 ++++++++++++++++----------------------------
 1 file changed, 16 insertions(+), 28 deletions(-)

diff --git a/setup.sh b/setup.sh
index 70dd531..673d89b 100755
--- a/setup.sh
+++ b/setup.sh
@@ -84,7 +84,7 @@ if [ "${1:-}" = "--uninstall" ] || [ "${1:-}" = "uninstall" ]; then
 fi
 
 # ---- Step 1: Build the project ----
-echo "[1/5] Building GoPlus AgentGuard..."
+echo "[1/4] Building GoPlus AgentGuard..."
 if [ -f "$SCRIPT_DIR/package.json" ]; then
   cd "$SCRIPT_DIR"
   npm install --ignore-scripts 2>/dev/null
@@ -95,24 +95,16 @@ else
   exit 1
 fi
 
-# ---- Step 2: Install CLI dependencies ----
-echo "[2/5] Installing CLI dependencies..."
-if [ -f "$SKILL_SRC/package.json" ]; then
-  cd "$SKILL_SRC"
-  npm install 2>/dev/null
-  echo "  OK: CLI dependencies installed"
-fi
-
-# ---- Step 3: Copy skill files ----
-echo "[3/5] Installing skill files..."
+# ---- Step 2: Copy skill files ----
+echo "[2/4] Installing skill files..."
 mkdir -p "$SKILLS_DIR"
 for f in SKILL.md README.md scan-rules.md action-policies.md web3-patterns.md evals.md patrol-checks.md .clawignore; do
   [ -f "$SKILL_SRC/$f" ] && cp "$SKILL_SRC/$f" "$SKILLS_DIR/" 2>/dev/null || true
 done
 echo "  OK: Skill files installed"
 
-# ---- Step 4: Copy scripts + node_modules ----
-echo "[4/5] Installing scripts and dependencies..."
+# ---- Step 3: Copy scripts + install dependencies ----
+echo "[3/4] Installing scripts and dependencies..."
 mkdir -p "$SKILLS_DIR/scripts"
 
 # Copy script files
@@ -126,21 +118,17 @@ if [ -d "$SKILL_SRC/scripts/data" ]; then
   cp -r "$SKILL_SRC/scripts/data/"* "$SKILLS_DIR/scripts/data/" 2>/dev/null || true
 fi
 
-# Copy package.json and node_modules from skills/agentguard/ (where npm install was run)
-cp "$SKILL_SRC/package.json" "$SKILLS_DIR/scripts/package.json" 2>/dev/null || true
-[ -f "$SKILL_SRC/package-lock.json" ] && cp "$SKILL_SRC/package-lock.json" "$SKILLS_DIR/scripts/package-lock.json" 2>/dev/null || true
-
-# Install node_modules in the target (avoids symlink issues in containers)
-cd "$SKILLS_DIR/scripts"
-if [ -f "package.json" ]; then
-  npm install 2>/dev/null
-  echo "  OK: Scripts and dependencies installed"
-else
-  echo "  WARN: No package.json found in scripts directory"
-fi
-
-# ---- Step 5: Create config directory ----
-echo "[5/5] Setting up configuration..."
+# Install dependencies at $SKILLS_DIR root — scripts run as:
+#   cd $SKILLS_DIR && node scripts/checkup-report.js
+# so Node resolves node_modules from $SKILLS_DIR upward.
+cp "$SKILL_SRC/package.json" "$SKILLS_DIR/package.json"
+[ -f "$SKILL_SRC/package-lock.json" ] && cp "$SKILL_SRC/package-lock.json" "$SKILLS_DIR/package-lock.json" || true
+cd "$SKILLS_DIR"
+npm install 2>/dev/null
+echo "  OK: Scripts and dependencies installed"
+
+# ---- Step 4: Create config directory ----
+echo "[4/4] Setting up configuration..."
 mkdir -p "$AGENTGUARD_DIR"
 if [ ! -f "$AGENTGUARD_DIR/config.json" ]; then
   echo '{"level":"balanced"}' > "$AGENTGUARD_DIR/config.json"

From 74b8884d60fa8530489ec3bd53da1f9baad26b1d Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 12:02:55 +0800
Subject: [PATCH 04/14] fix(setup): auto-detect agent skill directory, add
 --target fallback (issue #50)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-detection priority:
1. $OPENCLAW_STATE_DIR (per-agent runtime env var) — covers multi-agent platforms
2. ~/.openclaw (global, writable only) — existing single-agent installs
3. ~/.claude — Claude Code

If nothing is detected, exit with an actionable error pointing to --target.

--target <path> installs to <path>/agentguard, supporting arbitrary
directory layouts like ~/minax/agents/cto-owen/skills. Tilde expansion
is handled safely without eval.

Also fixes npm install running in the wrong directory (issue #49):
dependencies now install at $SKILLS_DIR root so Node can resolve
node_modules when scripts run as `cd $SKILLS_DIR && node scripts/...`.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh | 101 +++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 68 insertions(+), 33 deletions(-)

diff --git a/setup.sh b/setup.sh
index 755aa4a..624f1d3 100755
--- a/setup.sh
+++ b/setup.sh
@@ -3,13 +3,36 @@ set -euo pipefail
 
 # GoPlus AgentGuard — One-click setup
 # Supports: Claude Code, OpenClaw, ClawHub
-# Detects the platform and installs to the correct location.
+# Auto-detects the agent platform; use --target for custom paths.
+#
+# Usage:
+#   ./setup.sh                        Auto-detect platform
+#   ./setup.sh --target <path>        Install to <path>/agentguard (explicit override)
+#   ./setup.sh --uninstall            Remove installed skill
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 SKILL_SRC="$SCRIPT_DIR/skills/agentguard"
 AGENTGUARD_DIR="$HOME/.agentguard"
 MIN_NODE_VERSION=18
 
+# ---- Parse arguments ----
+TARGET_DIR=""
+UNINSTALL=false
+POSITIONAL=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET_DIR="${2:-}"
+      [ -z "$TARGET_DIR" ] && { echo "  ERROR: --target requires a path argument."; exit 1; }
+      shift 2
+      ;;
+    --uninstall|uninstall) UNINSTALL=true; shift ;;
+    *) POSITIONAL+=("$1"); shift ;;
+  esac
+done
+set -- "${POSITIONAL[@]+"${POSITIONAL[@]}"}"
+
 echo ""
 echo "  GoPlus AgentGuard — AI Agent Security Guard"
 echo "  ============================================="
@@ -38,10 +61,28 @@ fi
 
 # ---- Detect platform ----
 detect_platform() {
-  # Check OpenClaw first (workspace skills or managed skills)
-  if [ -d "$HOME/.openclaw" ]; then
-    # Prefer workspace skills if workspace exists
-    if [ -d "$HOME/.openclaw/workspace" ]; then
+  # --target overrides all detection
+  if [ -n "$TARGET_DIR" ]; then
+    # Expand leading ~ manually (eval is unsafe with user input)
+    case "$TARGET_DIR" in
+      "~/"*) TARGET_DIR="$HOME/${TARGET_DIR#~/}" ;;
+      "~")   TARGET_DIR="$HOME" ;;
+    esac
+    SKILLS_DIR="$TARGET_DIR/agentguard"
+    PLATFORM="custom"
+    return
+  fi
+
+  # $OPENCLAW_STATE_DIR: per-agent state directory set by the platform at runtime
+  if [ -n "${OPENCLAW_STATE_DIR:-}" ] && [ -d "$OPENCLAW_STATE_DIR" ] && [ -w "$OPENCLAW_STATE_DIR" ]; then
+    SKILLS_DIR="$OPENCLAW_STATE_DIR/skills/agentguard"
+    PLATFORM="openclaw-agent"
+    return
+  fi
+
+  # Fall back to global ~/.openclaw
+  if [ -d "$HOME/.openclaw" ] && [ -w "$HOME/.openclaw" ]; then
+    if [ -d "$HOME/.openclaw/workspace" ] && [ -w "$HOME/.openclaw/workspace" ]; then
       SKILLS_DIR="$HOME/.openclaw/workspace/skills/agentguard"
       PLATFORM="openclaw-workspace"
     else
@@ -58,9 +99,11 @@ detect_platform() {
     return
   fi
 
-  # Fallback: create Claude Code dir (most common)
-  SKILLS_DIR="$HOME/.claude/skills/agentguard"
-  PLATFORM="claude-code"
+  # Nothing detected — require explicit --target
+  echo "  ERROR: Could not detect a supported agent platform."
+  echo "  Set \$OPENCLAW_STATE_DIR, or use --target <path> to specify the skills directory."
+  echo "  Example: ./setup.sh --target ~/minax/agents/cto-owen/skills"
+  exit 1
 }
 
 detect_platform
@@ -69,7 +112,7 @@ echo "  Install target:    $SKILLS_DIR"
 echo ""
 
 # ---- Uninstall mode ----
-if [ "${1:-}" = "--uninstall" ] || [ "${1:-}" = "uninstall" ]; then
+if [ "$UNINSTALL" = true ]; then
   echo "  Uninstalling GoPlus AgentGuard..."
   rm -rf "$SKILLS_DIR" 2>/dev/null && echo "  Removed skill from $SKILLS_DIR" || true
   # Also clean up other possible locations
@@ -95,45 +138,37 @@ else
   exit 1
 fi
 
-# ---- Step 2: Install CLI dependencies ----
-echo "[2/5] Installing CLI dependencies..."
-if [ -d "$SKILL_SRC/scripts" ]; then
-  cd "$SKILL_SRC/scripts"
-  npm install 2>/dev/null
-  echo "  OK: CLI dependencies installed"
-fi
-
-# ---- Step 3: Copy skill files ----
-echo "[3/5] Installing skill files..."
+# ---- Step 2: Copy skill files ----
+echo "[2/5] Installing skill files..."
 mkdir -p "$SKILLS_DIR"
 for f in SKILL.md README.md scan-rules.md action-policies.md web3-patterns.md evals.md patrol-checks.md .clawignore; do
   [ -f "$SKILL_SRC/$f" ] && cp "$SKILL_SRC/$f" "$SKILLS_DIR/" 2>/dev/null || true
 done
 echo "  OK: Skill files installed"
 
-# ---- Step 4: Copy scripts + node_modules ----
-echo "[4/5] Installing scripts and dependencies..."
+# ---- Step 3: Copy scripts ----
+echo "[3/5] Installing scripts..."
 mkdir -p "$SKILLS_DIR/scripts"
 
-# Copy script files
-for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
+for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts; do
   [ -f "$SKILL_SRC/scripts/$f" ] && cp "$SKILL_SRC/scripts/$f" "$SKILLS_DIR/scripts/" 2>/dev/null || true
 done
 
-# Copy data directory
 if [ -d "$SKILL_SRC/scripts/data" ]; then
   mkdir -p "$SKILLS_DIR/scripts/data"
   cp -r "$SKILL_SRC/scripts/data/"* "$SKILLS_DIR/scripts/data/" 2>/dev/null || true
 fi
-
-# Install node_modules in the target (avoids symlink issues in containers)
-cd "$SKILLS_DIR/scripts"
-if [ -f "package.json" ]; then
-  npm install 2>/dev/null
-  echo "  OK: Scripts and dependencies installed"
-else
-  echo "  WARN: No package.json found in scripts directory"
-fi
+echo "  OK: Scripts installed"
+
+# ---- Step 4: Install dependencies ----
+echo "[4/5] Installing dependencies..."
+# Scripts run as: cd $SKILLS_DIR && node scripts/<script>
+# so node_modules must live at $SKILLS_DIR root for Node resolution.
+cp "$SKILL_SRC/package.json" "$SKILLS_DIR/package.json"
+[ -f "$SKILL_SRC/package-lock.json" ] && cp "$SKILL_SRC/package-lock.json" "$SKILLS_DIR/package-lock.json" || true
+cd "$SKILLS_DIR"
+npm install 2>/dev/null
+echo "  OK: Dependencies installed"
 
 # ---- Step 5: Create config directory ----
 echo "[5/5] Setting up configuration..."

From eda25a4f747e73802b04b3e048e4e76a3a3be641 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 15:53:54 +0800
Subject: [PATCH 05/14] fix(skill): require concrete evidence for every checkup
 finding (issue #51)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An LLM can read SKILL.md to learn the report format and fabricate
findings without running any actual checks. Fix by adding three
evidence gates to the checkup flow:

1. EVIDENCE RULE at Step 1 start: every finding must quote actual
   tool output; inference and fabrication are explicitly forbidden.
2. Per-check evidence requirements: each [REQUIRED] item now specifies
   exactly what artifact to record (permission string, grep match line,
   command output, etc.).
3. EVIDENCE GATE at Step 3: before writing the analysis, verify every
   finding traces back to a real tool output — drop any that don't.
4. Pre-Step-4 validation: evidence check before JSON assembly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/agentguard/SKILL.md | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..63d0488 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -631,6 +631,8 @@ Run a comprehensive agent health checkup across 6 security dimensions. Generates
 
 **IMPORTANT: You MUST run ALL 7 checks below — not just the skill scan. The checkup covers 5 security dimensions, not just code scanning. Do NOT skip checks 2–7.**
 
+**EVIDENCE RULE: Every finding you report MUST be backed by actual tool output collected in this step. You MUST quote the exact command output (or "no output" if the command returned nothing) in the finding's evidence field. Findings without concrete evidence from tool execution are FORBIDDEN — do not infer, assume, or fabricate results.**
+
 Run these checks in parallel where possible. These are **universal agent security checks** — they apply to any Claude Code or OpenClaw environment, regardless of whether AgentGuard is installed.
 
 1. **[REQUIRED] Discover & scan installed skills** (→ feeds Dimension 1: Code Safety): Glob ALL of the following paths for `*/SKILL.md`:
@@ -640,10 +642,10 @@ Run these checks in parallel where possible. These are **universal agent securit
    - `~/.qclaw/skills/*/SKILL.md`
    - `~/.qclaw/workspace/skills/*/SKILL.md`
 
-   For **every** discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Do NOT skip any skill regardless of how many are found. Collect the scan results (risk level, findings count, risk tags) for each skill.
+   For **every** discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Do NOT skip any skill regardless of how many are found. Collect the scan results (risk level, findings count, risk tags) for each skill. **Record the exact file paths and line numbers returned by the scan — these are required evidence for any finding you report.**
 2. **[REQUIRED] Credential file permissions** (→ feeds Dimension 2: Credential Safety): Platform-aware check — behavior differs by OS:
-   - **macOS/Linux**: Run `stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null` on `~/.ssh/`, `~/.gnupg/`, and if OpenClaw: on `$OC/openclaw.json`, `$OC/devices/paired.json`. **If the command returns empty output, the directory does not exist — treat as N/A (award full points), do NOT flag as a failure.**
-   - **Windows**: `stat` is not available. Use `icacls <path>` to check ACLs instead. If the directory does not exist, treat as N/A (award full points). If it exists, check that the ACL grants access only to the current user (no `Everyone`, `Users`, or `Authenticated Users` with write/read access). Flag as FAIL only if the directory exists AND the ACL is overly permissive.
+   - **macOS/Linux**: Run `stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null` on `~/.ssh/`, `~/.gnupg/`, and if OpenClaw: on `$OC/openclaw.json`, `$OC/devices/paired.json`. **If the command returns empty output, the directory does not exist — treat as N/A (award full points), do NOT flag as a failure.** **Record the exact numeric permission string returned (e.g. "700") as evidence.**
+   - **Windows**: `stat` is not available. Use `icacls <path>` to check ACLs instead. If the directory does not exist, treat as N/A (award full points). If it exists, check that the ACL grants access only to the current user (no `Everyone`, `Users`, or `Authenticated Users` with write/read access). Flag as FAIL only if the directory exists AND the ACL is overly permissive. **Record the exact `icacls` output as evidence.**
 3. **[REQUIRED] Sensitive credential scan / DLP** (→ feeds Dimension 2: Credential Safety): Use Grep to scan **all** agent workspace directories for leaked secrets. This MUST cover the entire workspace root, not just the current agent's directory:
    - For OpenClaw / QClaw: scan `~/.openclaw/workspace/` and `~/.qclaw/workspace/` recursively — this includes **all** `workspace-agent-*/` subdirectories, not just the current agent's workspace
    - For Claude Code: scan `~/.claude/` recursively
@@ -652,10 +654,11 @@ Run these checks in parallel where possible. These are **universal agent securit
      - Mnemonics: sequences of 12+ BIP-39 words, `seed_phrase`, `mnemonic`
      - API keys/tokens: `AKIA[0-9A-Z]{16}`, `gh[pousr]_[A-Za-z0-9_]{36}`, plaintext passwords
    - **Important**: Use the workspace *root* directory as the scan target (e.g. `~/.qclaw/workspace/`), not a specific agent subdirectory. All sibling `workspace-agent-*` directories must be included.
-4. **[REQUIRED] Network exposure** (→ feeds Dimension 3: Network & System): Run `lsof -i -P -n 2>/dev/null | grep LISTEN` or `ss -tlnp 2>/dev/null` to check for dangerous open ports (Redis 6379, Docker API 2375, MySQL 3306, MongoDB 27017 on 0.0.0.0)
-5. **[REQUIRED] Scheduled tasks audit** (→ feeds Dimension 3: Network & System): Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`
-6. **[REQUIRED] Environment variable exposure** (→ feeds Dimension 3: Network & System): Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values
-7. **[REQUIRED] Runtime protection check** (→ feeds Dimension 4: Runtime Protection): Check if security hooks exist in `~/.claude/settings.json` or `~/.openclaw/openclaw.json`, check for audit logs at `~/.agentguard/audit.jsonl`
+   - **Record the exact file path and matched line for every hit. If Grep returns no matches, record "no matches found" as evidence. A finding is only valid if Grep returned a match.**
+4. **[REQUIRED] Network exposure** (→ feeds Dimension 3: Network & System): Run `lsof -i -P -n 2>/dev/null | grep LISTEN` or `ss -tlnp 2>/dev/null` to check for dangerous open ports (Redis 6379, Docker API 2375, MySQL 3306, MongoDB 27017 on 0.0.0.0). **Record the exact command output. Only flag a port as exposed if it appears in the actual output.**
+5. **[REQUIRED] Scheduled tasks audit** (→ feeds Dimension 3: Network & System): Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`. **Record the full crontab output (or "no crontab" if empty). Only flag entries that appear verbatim in the output.**
+6. **[REQUIRED] Environment variable exposure** (→ feeds Dimension 3: Network & System): Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values. **Record the matched variable names from the actual `env` output. Do not flag variables that were not present in the output.**
+7. **[REQUIRED] Runtime protection check** (→ feeds Dimension 4: Runtime Protection): Check if security hooks exist in `~/.claude/settings.json` or `~/.openclaw/openclaw.json`, check for audit logs at `~/.agentguard/audit.jsonl`. **Record whether each file exists and its relevant content (hook config, log entry count) as evidence.**
 
 ### Step 2: Score Calculation
 
@@ -755,6 +758,8 @@ Round to the nearest integer.
 
 ### Step 3: Generate Analysis Report
 
+**EVIDENCE GATE: Before writing the analysis, verify that every finding you intend to include has a corresponding tool output collected in Step 1. If a finding cannot be traced back to actual command output, a matched file path, or a real log entry — drop it. Do not include findings based on inference, assumption, or knowledge of what "typically" exists. A clean report with fewer findings is always preferable to a report with fabricated ones.**
+
 Based on all collected data and findings, write a **comprehensive security analysis report** as a single text block. This is where you use your AI reasoning ability — don't just list facts, **analyze** them:
 
 - Summarize the overall security posture in 2-3 sentences
@@ -780,6 +785,8 @@ Also generate a list of actionable recommendations as `{ "severity": "...", "tex
 
 **If any dimension is missing data, go back and run the missing checks. Do NOT submit a report with only code_safety filled in.**
 
+**Evidence check: every entry in every `findings` array must reference a concrete artifact — a file path with line number, a command output snippet, or a log entry. Remove any finding that lacks this before proceeding.**
+
 ### Step 4: Generate Report
 
 Assemble the results into a JSON object and pipe it to the report generator:

From 3c8ebf8d0d100fe5da11036667253ac14beb593f Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 19:12:00 +0800
Subject: [PATCH 06/14] fix(compat): auto-isolate per-agent paths via
 OPENCLAW_STATE_DIR (issue #52)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Multi-agent platforms set $OPENCLAW_STATE_DIR per-agent at runtime.
By deriving agentguard/ paths from it, each agent automatically gets
its own isolated audit log and trust registry with no manual config.

Path resolution priority (registry + audit log):
  1. $OPENCLAW_STATE_DIR/agentguard/  — per-agent auto-isolation
  2. $AGENTGUARD_HOME/               — explicit override (unchanged)
  3. ~/.agentguard/                   — fallback for single-agent envs

Files changed:
- src/registry/storage.ts: registry.json path respects OPENCLAW_STATE_DIR
- src/adapters/common.ts: audit log dir respects OPENCLAW_STATE_DIR
- src/adapters/openclaw-plugin.ts: same
- skills/agentguard/scripts/auto-scan.js: same
- skills/agentguard/SKILL.md: replace `find` binary calls in patrol
  checks with Glob + stat to work in hardened environments where
  external binaries are restricted

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/agentguard/SKILL.md             | 4 ++--
 skills/agentguard/scripts/auto-scan.js | 4 +++-
 src/adapters/common.ts                 | 4 +++-
 src/adapters/openclaw-plugin.ts        | 4 +++-
 src/registry/storage.ts                | 6 +++++-
 5 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..3a1ec0f 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -337,13 +337,13 @@ Audit all cron jobs for download-and-execute patterns.
 Detect suspicious file modifications in the last 24 hours.
 
 **Steps**:
-1. Find recently modified files: `find $OC/ ~/.ssh/ ~/.gnupg/ /etc/cron.d/ -type f -mtime -1`
+1. Find recently modified files: use Glob with patterns `$OC/**/*`, `~/.ssh/**/*`, `~/.gnupg/**/*` and filter results by mtime within 24h using `stat -f '%m %N' <file>` (macOS) or `stat -c '%Y %n' <file>` (Linux) — do NOT use the `find` binary as it may be unavailable in hardened environments
 2. For modified files with scannable extensions (.js/.ts/.py/.sh/.md/.json), run the full scan rule set
 3. Check permissions on critical files:
    - `$OC/openclaw.json` → should be 600
    - `$OC/devices/paired.json` → should be 600
    - `~/.ssh/authorized_keys` → should be 600
-4. Detect new executable files in workspace: `find $OC/workspace/ -type f -perm +111 -mtime -1`
+4. Detect new executable files in workspace: use Glob `$OC/workspace/**/*` and check each file's executable bit with `stat` — do NOT use `find` with `-perm`
 
 #### [6] Audit Log Analysis (24h)
 
diff --git a/skills/agentguard/scripts/auto-scan.js b/skills/agentguard/scripts/auto-scan.js
index a6b4f1e..67c122b 100644
--- a/skills/agentguard/scripts/auto-scan.js
+++ b/skills/agentguard/scripts/auto-scan.js
@@ -61,7 +61,9 @@ const SKILLS_DIRS = [
   join(homedir(), '.claude', 'skills'),
   join(homedir(), '.openclaw', 'skills'),
 ];
-const AGENTGUARD_DIR = join(homedir(), '.agentguard');
+const AGENTGUARD_DIR = process.env.OPENCLAW_STATE_DIR
+  ? join(process.env.OPENCLAW_STATE_DIR, 'agentguard')
+  : process.env.AGENTGUARD_HOME || join(homedir(), '.agentguard');
 const AUDIT_PATH = join(AGENTGUARD_DIR, 'audit.jsonl');
 
 function ensureDir() {
diff --git a/src/adapters/common.ts b/src/adapters/common.ts
index 9dda5fa..2a4b65c 100644
--- a/src/adapters/common.ts
+++ b/src/adapters/common.ts
@@ -7,7 +7,9 @@ import type { HookInput, HookOutput } from './types.js';
 // Paths
 // ---------------------------------------------------------------------------
 
-const AGENTGUARD_DIR = process.env.AGENTGUARD_HOME || join(homedir(), '.agentguard');
+const AGENTGUARD_DIR = process.env.OPENCLAW_STATE_DIR
+  ? join(process.env.OPENCLAW_STATE_DIR, 'agentguard')
+  : process.env.AGENTGUARD_HOME || join(homedir(), '.agentguard');
 const CONFIG_PATH = join(AGENTGUARD_DIR, 'config.json');
 const AUDIT_PATH = join(AGENTGUARD_DIR, 'audit.jsonl');
 
diff --git a/src/adapters/openclaw-plugin.ts b/src/adapters/openclaw-plugin.ts
index 5e34667..7db5410 100644
--- a/src/adapters/openclaw-plugin.ts
+++ b/src/adapters/openclaw-plugin.ts
@@ -74,7 +74,9 @@ interface OpenClawPluginApi {
 
 const OPENCLAW_SKILLS_DIR = join(homedir(), '.openclaw', 'skills');
 const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills');
-const AGENTGUARD_DIR = process.env.AGENTGUARD_HOME || join(homedir(), '.agentguard');
+const AGENTGUARD_DIR = process.env.OPENCLAW_STATE_DIR
+  ? join(process.env.OPENCLAW_STATE_DIR, 'agentguard')
+  : process.env.AGENTGUARD_HOME || join(homedir(), '.agentguard');
 const AUDIT_PATH = join(AGENTGUARD_DIR, 'audit.jsonl');
 
 function ensureAgentGuardDir(): void {
diff --git a/src/registry/storage.ts b/src/registry/storage.ts
index cd35f9d..53c74a4 100644
--- a/src/registry/storage.ts
+++ b/src/registry/storage.ts
@@ -30,7 +30,11 @@ export class RegistryStorage {
   constructor(options: StorageOptions = {}) {
     this.filePath =
       options.filePath ||
-      path.join(homedir(), '.agentguard', 'registry.json');
+      (process.env.OPENCLAW_STATE_DIR
+        ? path.join(process.env.OPENCLAW_STATE_DIR, 'agentguard', 'registry.json')
+        : process.env.AGENTGUARD_HOME
+          ? path.join(process.env.AGENTGUARD_HOME, 'registry.json')
+          : path.join(homedir(), '.agentguard', 'registry.json'));
   }
 
   /**

From 76085ac0ae2f0c6b45bf33b51cb1e0078ba6277a Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 19:19:50 +0800
Subject: [PATCH 07/14] fix(scan): git-aware severity for PRIVATE_KEY_PATTERN
 and MNEMONIC_PATTERN (issue #53)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rules 7 and 8 previously reported CRITICAL for all plaintext key matches
regardless of git context, causing alert fatigue when keys are properly
gitignored and never committed.

Severity is now determined by a four-step git context check after the
initial pattern match:
  1. Not in a git repo              → CRITICAL (unknown exposure)
  2. File ever in git history       → CRITICAL (already leaked)
  3. Tracked but not gitignored     → HIGH (could be committed)
  4. Gitignored                     → MEDIUM (local only)

git context result is recorded in the finding's Evidence column.
Falls back to CRITICAL if git is not available in PATH.

Changes:
- skills/agentguard/SKILL.md: add Git Context Check section; mark
  Rule 7/8 as CRITICAL* in the detection rules table
- skills/agentguard/scan-rules.md: add git-aware severity table to
  Rule 7 and Rule 8 definitions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/agentguard/SKILL.md      | 17 +++++++++++++++--
 skills/agentguard/scan-rules.md | 15 +++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..e254b56 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -91,8 +91,8 @@ For each rule, use Grep to search the relevant file types. Record every match wi
 | 4 | READ_ENV_SECRETS | MEDIUM | js,ts,mjs,py | Environment variable access |
 | 5 | READ_SSH_KEYS | CRITICAL | all | SSH key file access |
 | 6 | READ_KEYCHAIN | CRITICAL | all | System keychain / browser profiles |
-| 7 | PRIVATE_KEY_PATTERN | CRITICAL | all | Hardcoded private keys |
-| 8 | MNEMONIC_PATTERN | CRITICAL | all | Hardcoded mnemonic phrases |
+| 7 | PRIVATE_KEY_PATTERN | CRITICAL* | all | Hardcoded private keys |
+| 8 | MNEMONIC_PATTERN | CRITICAL* | all | Hardcoded mnemonic phrases |
 | 9 | WALLET_DRAINING | CRITICAL | js,ts,sol | Approve + transferFrom patterns |
 | 10 | UNLIMITED_APPROVAL | HIGH | js,ts,sol | Unlimited token approvals |
 | 11 | DANGEROUS_SELFDESTRUCT | HIGH | sol | selfdestruct in contracts |
@@ -110,6 +110,19 @@ For each rule, use Grep to search the relevant file types. Record every match wi
 | 23 | SUSPICIOUS_IP | MEDIUM | all | Hardcoded public IPv4 addresses |
 | 24 | SOCIAL_ENGINEERING | HIGH | md | Pressure language + execution instructions |
 
+### Git Context Check (Rules 7 & 8 only)
+
+Rules marked **CRITICAL\*** start at CRITICAL but must be downgraded based on git context **before** being added to the findings list. For every file that matched Rule 7 (PRIVATE_KEY_PATTERN) or Rule 8 (MNEMONIC_PATTERN), run the following checks in order and assign the final severity:
+
+1. **Not in a git repo** — if `git -C <file_dir> rev-parse --git-dir 2>/dev/null` returns nothing → keep **CRITICAL**. Stop.
+2. **Ever committed** — run `git -C <file_dir> log --all --oneline -- <file_path>`. If output is non-empty → keep **CRITICAL**. Stop.
+3. **Not gitignored** — run `git -C <file_dir> check-ignore -q <file_path>`. If exit code is non-zero (file is NOT ignored) → downgrade to **HIGH**. Stop.
+4. **Gitignored** — exit code 0 → downgrade to **MEDIUM**.
+
+Record the git context result (`committed` / `not-ignored` / `gitignored` / `no-git-repo`) in the finding's Evidence column alongside the matched content.
+
+**Important**: these checks require `git` to be available. If `git` is not in PATH, skip the check and keep **CRITICAL**.
+
 ### Risk Level Calculation
 
 - Any **CRITICAL** finding -> Overall **CRITICAL**
diff --git a/skills/agentguard/scan-rules.md b/skills/agentguard/scan-rules.md
index e628d14..9d67ac4 100644
--- a/skills/agentguard/scan-rules.md
+++ b/skills/agentguard/scan-rules.md
@@ -98,7 +98,7 @@ Detailed Grep patterns for all 24 detection rules. Use this as reference when ex
 | `Windows.*Credentials` (i) | Windows credentials |
 | `credential.*manager` (i) | Credential manager |
 
-## Rule 7: PRIVATE_KEY_PATTERN (CRITICAL)
+## Rule 7: PRIVATE_KEY_PATTERN (CRITICAL*)
 **Files**: All
 
 | Pattern | Description |
@@ -107,7 +107,16 @@ Detailed Grep patterns for all 24 detection rules. Use this as reference when ex
 | `private[_\s]?key\s*[:=]\s*['"\x60]0x[a-fA-F0-9]{64}` (i) | Named private key |
 | `PRIVATE_KEY\s*[:=]\s*['"\x60][a-fA-F0-9]{64}` (i) | PRIVATE_KEY assignment |
 
-## Rule 8: MNEMONIC_PATTERN (CRITICAL)
+**Git-aware severity** (apply after initial match — see SKILL.md "Git Context Check"):
+
+| Condition | Severity |
+|-----------|----------|
+| File ever appeared in git history (`git log --all`) | **CRITICAL** |
+| File tracked by git but NOT gitignored | **HIGH** |
+| File gitignored (`git check-ignore`) | **MEDIUM** |
+| Not inside a git repository | **CRITICAL** |
+
+## Rule 8: MNEMONIC_PATTERN (CRITICAL*)
 **Files**: All
 
 | Pattern | Description |
@@ -117,6 +126,8 @@ Detailed Grep patterns for all 24 detection rules. Use this as reference when ex
 | `mnemonic\s*[:=]\s*['"\x60]` (i) | Mnemonic assignment |
 | `recovery[_\s]?phrase\s*[:=]\s*['"\x60]` (i) | Recovery phrase assignment |
 
+**Git-aware severity**: same table as Rule 7 above.
+
 ## Rule 9: WALLET_DRAINING (CRITICAL)
 **Files**: `*.js`, `*.ts`, `*.sol`
 

From 75c3d7acc5251cf36a35a06ffa5cdebccca1b16f Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 19:30:52 +0800
Subject: [PATCH 08/14] fix(scripts): replace trust-cli.ts and action-cli.ts
 with plain JS (issue #54)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Node.js 18/20 LTS cannot execute TypeScript files natively. The .ts
scripts were being invoked directly with `node`, which fails on any
LTS release below v22.6 without tsx/ts-node installed.

Fix: rewrite both CLIs as plain ESM .js files with all TypeScript
annotations removed. Functionality is identical — only type syntax
is dropped. The .ts source files are removed to avoid confusion.

Updated references:
- skills/agentguard/SKILL.md: all 12 occurrences of trust-cli.ts /
  action-cli.ts → .js; allowed-tools permissions updated to match
- setup.sh: file copy list updated to .js

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh                                      |  2 +-
 skills/agentguard/SKILL.md                    | 24 +++++++-------
 .../scripts/{action-cli.ts => action-cli.js}  | 31 ++++++++-----------
 .../scripts/{trust-cli.ts => trust-cli.js}    | 28 +++++++----------
 4 files changed, 38 insertions(+), 47 deletions(-)
 rename skills/agentguard/scripts/{action-cli.ts => action-cli.js} (89%)
 rename skills/agentguard/scripts/{trust-cli.ts => trust-cli.js} (81%)

diff --git a/setup.sh b/setup.sh
index 755aa4a..01276e0 100755
--- a/setup.sh
+++ b/setup.sh
@@ -116,7 +116,7 @@ echo "[4/5] Installing scripts and dependencies..."
 mkdir -p "$SKILLS_DIR/scripts"
 
 # Copy script files
-for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
+for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.js action-cli.js package.json package-lock.json; do
   [ -f "$SKILL_SRC/scripts/$f" ] && cp "$SKILL_SRC/scripts/$f" "$SKILLS_DIR/scripts/" 2>/dev/null || true
 done
 
diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..40f009b 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -27,7 +27,7 @@ filesystem-access:
     access: read-write
     reason: "Read/write audit log (audit.jsonl) and protection level config (config.json)"
 user-invocable: true
-allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
+allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.js *) Bash(node *action-cli.js *) Bash(*checkup-report.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
 argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...]"
 ---
 
@@ -158,10 +158,10 @@ After outputting the scan report, if the scanned target appears to be a skill (c
    - `id`: the directory name of the scanned path
    - `source`: the absolute path to the scanned directory
    - `version`: read the `version` field from `package.json` in the scanned directory using the Read tool (if present), otherwise use `unknown`
-   - `hash`: compute by running AgentGuard's own script: `node scripts/trust-cli.ts hash --path <scanned_path>` and extracting the `hash` field from the JSON output
+   - `hash`: compute by running AgentGuard's own script: `node scripts/trust-cli.js hash --path <scanned_path>` and extracting the `hash` field from the JSON output
 3. Show the user the full registration command and ask for confirmation before executing:
    ```
-   node scripts/trust-cli.ts attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by agentguard-scan --notes "Auto-registered after scan. Risk level: <risk_level>." --force
+   node scripts/trust-cli.js attest --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> --preset <preset> --reviewed-by agentguard-scan --notes "Auto-registered after scan. Risk level: <risk_level>." --force
    ```
 4. Only execute after user approval. Show the registration result.
 
@@ -206,27 +206,27 @@ Parse the user's action description and apply the appropriate detector:
 
 ### Web3 Enhanced Detection
 
-When the action involves **web3_tx** or **web3_sign**, use AgentGuard's bundled `action-cli.ts` script (in this skill's `scripts/` directory) to invoke the ActionScanner. This script integrates the trust registry and optionally the GoPlus API (requires `GOPLUS_API_KEY` and `GOPLUS_API_SECRET` environment variables, if available):
+When the action involves **web3_tx** or **web3_sign**, use AgentGuard's bundled `action-cli.js` script (in this skill's `scripts/` directory) to invoke the ActionScanner. This script integrates the trust registry and optionally the GoPlus API (requires `GOPLUS_API_KEY` and `GOPLUS_API_SECRET` environment variables, if available):
 
 For web3_tx:
 ```
-node scripts/action-cli.ts decide --type web3_tx --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>] [--user-present]
+node scripts/action-cli.js decide --type web3_tx --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>] [--user-present]
 ```
 
 For web3_sign:
 ```
-node scripts/action-cli.ts decide --type web3_sign --chain-id <id> --signer <addr> [--message <msg>] [--typed-data <json>] [--origin <url>] [--user-present]
+node scripts/action-cli.js decide --type web3_sign --chain-id <id> --signer <addr> [--message <msg>] [--typed-data <json>] [--origin <url>] [--user-present]
 ```
 
 For standalone transaction simulation:
 ```
-node scripts/action-cli.ts simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>]
+node scripts/action-cli.js simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <calldata>] [--origin <url>]
 ```
 
 The `decide` command also works for non-Web3 actions (exec_command, network_request, etc.) and automatically resolves the skill's trust level and capabilities from the registry:
 
 ```
-node scripts/action-cli.ts decide --type exec_command --command "<cmd>" [--skill-source <source>] [--skill-id <id>]
+node scripts/action-cli.js decide --type exec_command --command "<cmd>" [--skill-source <source>] [--skill-id <id>]
 ```
 
 Parse the JSON output and incorporate findings into your evaluation:
@@ -292,8 +292,8 @@ Detect tampered or unregistered skill packages by comparing file hashes against
 
 **Steps**:
 1. Discover skill directories under `$OC/skills/` (look for dirs containing `SKILL.md`)
-2. For each skill, compute hash: `node scripts/trust-cli.ts hash --path <skill_dir>`
-3. Look up the attested hash: `node scripts/trust-cli.ts lookup --source <skill_dir>`
+2. For each skill, compute hash: `node scripts/trust-cli.js hash --path <skill_dir>`
+3. Look up the attested hash: `node scripts/trust-cli.js lookup --source <skill_dir>`
 4. If hash differs from attested → **INTEGRITY_DRIFT** (HIGH)
 5. If skill has no trust record → **UNREGISTERED_SKILL** (MEDIUM)
 6. For drifted skills, run the scan rules against the changed files to detect new threats
@@ -374,7 +374,7 @@ Verify security configuration is production-appropriate.
 Check for expired, stale, or over-privileged trust records.
 
 **Steps**:
-1. List all records: `node scripts/trust-cli.ts list`
+1. List all records: `node scripts/trust-cli.js list`
 2. Flag:
    - Expired attestations (`expires_at` in the past)
    - Trusted skills not re-scanned in 30+ days
@@ -528,7 +528,7 @@ List all trust records with optional filters.
 
 If the agentguard package is installed, execute trust operations via AgentGuard's own bundled script:
 ```
-node scripts/trust-cli.ts <subcommand> [args]
+node scripts/trust-cli.js <subcommand> [args]
 ```
 
 For operations that modify the trust registry (`attest`, `revoke`), always show the user the exact command and ask for explicit confirmation before executing.
diff --git a/skills/agentguard/scripts/action-cli.ts b/skills/agentguard/scripts/action-cli.js
similarity index 89%
rename from skills/agentguard/scripts/action-cli.ts
rename to skills/agentguard/scripts/action-cli.js
index 6fa1142..9145d97 100644
--- a/skills/agentguard/scripts/action-cli.ts
+++ b/skills/agentguard/scripts/action-cli.js
@@ -4,8 +4,8 @@
  * GoPlus AgentGuard Action CLI — lightweight wrapper for ActionScanner operations.
  *
  * Usage:
- *   node action-cli.ts decide --type <action_type> [action-specific args]
- *   node action-cli.ts simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <hex>] [--origin <url>]
+ *   node action-cli.js decide --type <action_type> [action-specific args]
+ *   node action-cli.js simulate --chain-id <id> --from <addr> --to <addr> --value <wei> [--data <hex>] [--origin <url>]
  *
  * Action-specific args for `decide`:
  *
@@ -29,27 +29,22 @@
  */
 
 import { createAgentGuard } from '@goplus/agentguard';
-import type {
-  ActionEnvelope,
-  Web3Intent,
-  ActionType,
-} from '@goplus/agentguard';
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-function getArg(name: string): string | undefined {
+function getArg(name) {
   const idx = args.indexOf(`--${name}`);
   if (idx === -1 || idx + 1 >= args.length) return undefined;
   return args[idx + 1];
 }
 
-function hasFlag(name: string): boolean {
+function hasFlag(name) {
   return args.includes(`--${name}`);
 }
 
-function printUsage(): void {
-  console.error(`Usage: action-cli.ts <decide|simulate> [options]
+function printUsage() {
+  console.error(`Usage: action-cli.js <decide|simulate> [options]
 
 Commands:
   decide    Evaluate an action and return a policy decision
@@ -104,8 +99,8 @@ simulate options:
   process.exit(1);
 }
 
-function buildEnvelope(): ActionEnvelope {
-  const type = getArg('type') as ActionType;
+function buildEnvelope() {
+  const type = getArg('type');
   if (!type) {
     console.error('Error: --type is required for decide');
     printUsage();
@@ -113,7 +108,7 @@ function buildEnvelope(): ActionEnvelope {
   }
 
   const userPresent = hasFlag('user-present');
-  let data: Record<string, unknown>;
+  let data;
 
   switch (type) {
     case 'web3_tx':
@@ -133,7 +128,7 @@ function buildEnvelope(): ActionEnvelope {
         signer: getArg('signer') || '',
         message: getArg('message'),
         typed_data: getArg('typed-data')
-          ? JSON.parse(getArg('typed-data')!)
+          ? JSON.parse(getArg('typed-data'))
           : undefined,
         origin: getArg('origin'),
       };
@@ -142,7 +137,7 @@ function buildEnvelope(): ActionEnvelope {
     case 'exec_command':
       data = {
         command: getArg('command') || '',
-        args: getArg('args') ? JSON.parse(getArg('args')!) : undefined,
+        args: getArg('args') ? JSON.parse(getArg('args')) : undefined,
         cwd: getArg('cwd'),
       };
       break;
@@ -186,7 +181,7 @@ function buildEnvelope(): ActionEnvelope {
     },
     action: {
       type,
-      data: data as any,
+      data,
     },
     context: {
       session_id: `cli-${Date.now()}`,
@@ -214,7 +209,7 @@ async function main() {
     }
 
     case 'simulate': {
-      const intent: Web3Intent = {
+      const intent = {
         chain_id: Number(getArg('chain-id') || '1'),
         from: getArg('from') || '',
         to: getArg('to') || '',
diff --git a/skills/agentguard/scripts/trust-cli.ts b/skills/agentguard/scripts/trust-cli.js
similarity index 81%
rename from skills/agentguard/scripts/trust-cli.ts
rename to skills/agentguard/scripts/trust-cli.js
index c094f6a..4dd8e3a 100644
--- a/skills/agentguard/scripts/trust-cli.ts
+++ b/skills/agentguard/scripts/trust-cli.js
@@ -4,11 +4,11 @@
  * GoPlus AgentGuard Trust CLI — lightweight wrapper for SkillRegistry operations.
  *
  * Usage:
- *   node trust-cli.ts lookup --id <id> --source <source> --version <version> --hash <hash>
- *   node trust-cli.ts attest  --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> [--preset <preset>] [--capabilities <json>] [--reviewed-by <name>] [--notes <text>] [--expires <iso>] [--force]
- *   node trust-cli.ts revoke  [--source <source>] [--key <record_key>] --reason <reason>
- *   node trust-cli.ts list    [--trust-level <level>] [--status <status>] [--source-pattern <pattern>]
- *   node trust-cli.ts hash    --path <dir>
+ *   node trust-cli.js lookup --id <id> --source <source> --version <version> --hash <hash>
+ *   node trust-cli.js attest  --id <id> --source <source> --version <version> --hash <hash> --trust-level <level> [--preset <preset>] [--capabilities <json>] [--reviewed-by <name>] [--notes <text>] [--expires <iso>] [--force]
+ *   node trust-cli.js revoke  [--source <source>] [--key <record_key>] --reason <reason>
+ *   node trust-cli.js list    [--trust-level <level>] [--status <status>] [--source-pattern <pattern>]
+ *   node trust-cli.js hash    --path <dir>
  */
 
 import { createAgentGuard, CAPABILITY_PRESETS, SkillScanner } from '@goplus/agentguard';
@@ -16,13 +16,13 @@ import { createAgentGuard, CAPABILITY_PRESETS, SkillScanner } from '@goplus/agen
 const args = process.argv.slice(2);
 const command = args[0];
 
-function getArg(name: string): string | undefined {
+function getArg(name) {
   const idx = args.indexOf(`--${name}`);
   if (idx === -1 || idx + 1 >= args.length) return undefined;
   return args[idx + 1];
 }
 
-function hasFlag(name: string): boolean {
+function hasFlag(name) {
   return args.includes(`--${name}`);
 }
 
@@ -50,18 +50,14 @@ async function main() {
         version_ref: getArg('version') || '',
         artifact_hash: getArg('hash') || '',
       };
-      const trustLevel = (getArg('trust-level') || 'restricted') as
-        | 'untrusted'
-        | 'restricted'
-        | 'trusted';
+      const trustLevel = getArg('trust-level') || 'restricted';
 
       let capabilities;
       const preset = getArg('preset');
       if (preset && preset in CAPABILITY_PRESETS) {
-        capabilities =
-          CAPABILITY_PRESETS[preset as keyof typeof CAPABILITY_PRESETS];
+        capabilities = CAPABILITY_PRESETS[preset];
       } else if (getArg('capabilities')) {
-        capabilities = JSON.parse(getArg('capabilities')!);
+        capabilities = JSON.parse(getArg('capabilities'));
       }
 
       const force = hasFlag('force');
@@ -94,7 +90,7 @@ async function main() {
     }
 
     case 'list': {
-      const filters: Record<string, string> = {};
+      const filters = {};
       const trustLevel = getArg('trust-level');
       const status = getArg('status');
       const sourcePattern = getArg('source-pattern');
@@ -121,7 +117,7 @@ async function main() {
 
     default:
       console.error(
-        'Usage: trust-cli.ts <lookup|attest|revoke|list|hash> [options]'
+        'Usage: trust-cli.js <lookup|attest|revoke|list|hash> [options]'
       );
       console.error('Run with --help for details.');
       process.exit(1);

From 89d8b803930c2bf9c3cde00af41a2f19f64759cd Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 19:37:40 +0800
Subject: [PATCH 09/14] fix(patrol): fall back to system crontab when OpenClaw
 is unavailable (issue #55)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

patrol setup and patrol status were hardcoded to use `openclaw cron`,
making them non-functional on Claude Code and standard Linux environments.

Introduce three-path platform detection for patrol setup/status:
  Path A — OpenClaw CLI available: use `openclaw cron add` (existing behavior)
  Path B — system crontab available: write entry via `crontab -l | crontab -`,
            invoking auto-scan.js with AGENTGUARD_AUTO_SCAN=1
  Path C — neither available: print the crontab entry for manual installation

patrol status now queries whichever scheduler is present:
  - openclaw cron list   (Path A)
  - crontab -l | grep agentguard  (Path B)

patrol run is unaffected — it requires no scheduling platform.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/agentguard/SKILL.md | 75 +++++++++++++++++++++++++-------------
 1 file changed, 49 insertions(+), 26 deletions(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..7853750 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -258,29 +258,25 @@ Always combine script results with the policy-based checks (webhook domains, sec
 
 ## Subcommand: patrol
 
-**OpenClaw-specific daily security patrol.** Runs 8 automated checks that leverage AgentGuard's scan engine, trust registry, and audit log to assess the security posture of an OpenClaw deployment.
+**Daily security patrol.** Runs 8 automated checks that leverage AgentGuard's scan engine, trust registry, and audit log to assess the security posture of your agent deployment. Works on OpenClaw and standard cron environments.
 
 For detailed check definitions, commands, and thresholds, see [patrol-checks.md](patrol-checks.md).
 
 ### Sub-subcommands
 
 - **`patrol`** or **`patrol run`** — Execute all 8 checks and output a patrol report
-- **`patrol setup`** — Configure as an OpenClaw daily cron job
+- **`patrol setup`** — Configure as a daily cron job (OpenClaw or system crontab)
 - **`patrol status`** — Show last patrol results and cron schedule
 
-### Pre-flight: OpenClaw Detection
+### Platform Detection
 
-Before running any checks, verify the OpenClaw environment:
+Before running `patrol setup` or `patrol status`, detect the available scheduling platform:
 
-1. Check for `$OPENCLAW_STATE_DIR` env var, fall back to `~/.openclaw/`
-2. Verify the directory exists and contains `openclaw.json`
-3. Check if `openclaw` CLI is available in PATH
+1. **OpenClaw**: Check for `$OPENCLAW_STATE_DIR` env var (fall back to `~/.openclaw/`), verify the directory exists and contains `openclaw.json`, and check if `openclaw` CLI is in PATH. If all three pass → use OpenClaw path.
+2. **System crontab**: Check if `crontab` command is available in PATH → use crontab path.
+3. **Neither available**: Inform the user and output the manual cron entry for them to add themselves.
 
-If OpenClaw is not detected, output:
-```
-This command requires an OpenClaw environment. Detected: <what was found/missing>
-For non-OpenClaw environments, use /agentguard scan and /agentguard report instead.
-```
+For `patrol run`, no scheduling platform is needed — run checks on any platform.
 
 Set `$OC` to the resolved OpenClaw state directory for all subsequent checks.
 
@@ -427,17 +423,20 @@ After outputting the report, append a summary entry to `~/.agentguard/audit.json
 
 ### patrol setup
 
-Configure the patrol as an OpenClaw daily cron job.
+Configure the patrol as a daily cron job. Detects the available platform and uses the appropriate method.
 
 **Steps**:
 
-1. Verify OpenClaw environment (same pre-flight as `patrol run`)
+1. Run platform detection (see above).
 2. Ask the user for:
-   - **Timezone** (default: UTC). Examples: `Asia/Shanghai`, `America/New_York`, `Europe/London`
    - **Schedule** (default: `0 3 * * *` — daily at 03:00)
-   - **Notification channel** (optional): `telegram`, `discord`, `signal`
+   - **Timezone** (default: UTC). Examples: `Asia/Shanghai`, `America/New_York`, `Europe/London`
+   - **Notification channel** (optional, OpenClaw only): `telegram`, `discord`, `signal`
    - **Chat ID / webhook** (required if channel is set)
-3. Generate the cron registration command:
+
+#### Path A — OpenClaw available
+
+Generate and show the OpenClaw cron registration command:
 
 ```bash
 openclaw cron add \
@@ -455,11 +454,36 @@ openclaw cron add \
   --to <chat-id>
 ```
 
-4. **Show the exact command to the user and wait for explicit confirmation** before executing
-5. After execution, verify with `openclaw cron list`
-6. Output confirmation with the cron schedule
+**Show the exact command and wait for explicit user confirmation before executing.**
+After execution, verify with `openclaw cron list`.
+
+> **Note**: `--timeout-seconds 300` is required because isolated sessions need cold-start time.
+
+#### Path B — System crontab available (OpenClaw not available)
+
+Resolve the absolute path to this skill's directory (parent of this SKILL.md file) as `<SKILL_DIR>`.
+
+Generate the crontab entry:
+```
+<schedule> cd <SKILL_DIR> && node scripts/auto-scan.js >> ~/.agentguard/patrol.log 2>&1
+```
+
+**Show the exact entry and wait for explicit user confirmation before writing.**
+
+After confirmation, add the entry to the user's crontab:
+```bash
+(crontab -l 2>/dev/null; echo "<schedule> cd <SKILL_DIR> && AGENTGUARD_AUTO_SCAN=1 node scripts/auto-scan.js >> ~/.agentguard/patrol.log 2>&1") | crontab -
+```
+
+Verify with `crontab -l | grep agentguard`.
+
+#### Path C — Neither available
 
-> **Note**: `--timeout-seconds 300` is required because isolated sessions need cold-start time. The default 120s is not enough.
+Output the crontab entry for the user to add manually:
+```
+<schedule> cd <SKILL_DIR> && AGENTGUARD_AUTO_SCAN=1 node scripts/auto-scan.js >> ~/.agentguard/patrol.log 2>&1
+```
+Explain that neither `openclaw` nor `crontab` was found in PATH, so the entry must be added manually.
 
 ### patrol status
 
@@ -467,11 +491,10 @@ Show the current patrol state.
 
 **Steps**:
 
-1. Read `~/.agentguard/audit.jsonl`, find the most recent `event: "patrol"` entry
-2. If found, display: timestamp, overall status, finding counts
-3. Run `openclaw cron list` and look for `agentguard-patrol` job
-4. If cron is configured, show: schedule, timezone, last run time, next run time
-5. If cron is not configured, suggest: `/agentguard patrol setup`
+1. Read `~/.agentguard/audit.jsonl`, find the most recent `event: "patrol"` or `event: "auto_scan"` entry. If found, display: timestamp, overall status, finding counts.
+2. **OpenClaw available**: run `openclaw cron list` and look for `agentguard-patrol`. Show schedule, timezone, last/next run time if found.
+3. **System crontab available**: run `crontab -l 2>/dev/null | grep agentguard`. Show the matching entry if found.
+4. If no cron is configured on any platform, suggest: `/agentguard patrol setup`.
 
 ---
 

From c9b8461f720f4e4716aa8669b151b7f78d52ba0c Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 19:51:51 +0800
Subject: [PATCH 10/14] fix issue-56: offload checkup scoring to deterministic
 script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add checkup-score.js which accepts raw check facts as JSON and
computes all dimension scores, composite score, and tier assignment
without any LLM arithmetic. Refactor SKILL.md checkup flow into 7
steps so the LLM only collects raw facts and writes analysis — all
numerical calculations are delegated to the script.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh                                   |   2 +-
 skills/agentguard/SKILL.md                 | 232 ++++++-------
 skills/agentguard/scripts/checkup-score.js | 369 +++++++++++++++++++++
 3 files changed, 470 insertions(+), 133 deletions(-)
 create mode 100644 skills/agentguard/scripts/checkup-score.js

diff --git a/setup.sh b/setup.sh
index 755aa4a..fb03a91 100755
--- a/setup.sh
+++ b/setup.sh
@@ -116,7 +116,7 @@ echo "[4/5] Installing scripts and dependencies..."
 mkdir -p "$SKILLS_DIR/scripts"
 
 # Copy script files
-for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
+for f in checkup-report.js checkup-score.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
   [ -f "$SKILL_SRC/scripts/$f" ] && cp "$SKILL_SRC/scripts/$f" "$SKILLS_DIR/scripts/" 2>/dev/null || true
 done
 
diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..90fb167 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -27,7 +27,7 @@ filesystem-access:
     access: read-write
     reason: "Read/write audit log (audit.jsonl) and protection level config (config.json)"
 user-invocable: true
-allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
+allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(*checkup-score.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
 argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...]"
 ---
 
@@ -625,7 +625,9 @@ If the log file doesn't exist, inform the user that no security events have been
 
 ## Subcommand: checkup
 
-Run a comprehensive agent health checkup across 6 security dimensions. Generates a visual HTML report with a lobster mascot and opens it in the browser. The lobster's appearance reflects the agent's health: muscular bodybuilder (score 90+), healthy with shield (70–89), tired with coffee (50–69), or sick with bandages (0–49).
+Run a comprehensive agent health checkup across 5 security dimensions. Generates a visual HTML report with a lobster mascot and opens it in the browser. The lobster's appearance reflects the agent's health: muscular bodybuilder (score 90+), healthy with shield (70–89), tired with coffee (50–69), or sick with bandages (0–49).
+
+**Scoring is handled by `checkup-score.js` — you MUST NOT calculate scores yourself. Your role is to collect raw facts, assemble them into structured JSON, and pass to the script.**
 
 ### Step 1: Data Collection
 
@@ -640,163 +642,129 @@ Run these checks in parallel where possible. These are **universal agent securit
    - `~/.qclaw/skills/*/SKILL.md`
    - `~/.qclaw/workspace/skills/*/SKILL.md`
 
-   For **every** discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Do NOT skip any skill regardless of how many are found. Collect the scan results (risk level, findings count, risk tags) for each skill.
+   For **every** discovered skill, **run `/agentguard scan <skill_path>`** using the scan subcommand logic (24 detection rules). Do NOT skip any skill regardless of how many are found. Record for each skill: name, risk_level, and exact findings list (rule, severity, file, line).
 2. **[REQUIRED] Credential file permissions** (→ feeds Dimension 2: Credential Safety): Platform-aware check — behavior differs by OS:
-   - **macOS/Linux**: Run `stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null` on `~/.ssh/`, `~/.gnupg/`, and if OpenClaw: on `$OC/openclaw.json`, `$OC/devices/paired.json`. **If the command returns empty output, the directory does not exist — treat as N/A (award full points), do NOT flag as a failure.**
-   - **Windows**: `stat` is not available. Use `icacls <path>` to check ACLs instead. If the directory does not exist, treat as N/A (award full points). If it exists, check that the ACL grants access only to the current user (no `Everyone`, `Users`, or `Authenticated Users` with write/read access). Flag as FAIL only if the directory exists AND the ACL is overly permissive.
+   - **macOS/Linux**: Run `stat -f '%Lp' <path> 2>/dev/null || stat -c '%a' <path> 2>/dev/null` on `~/.ssh/`, `~/.gnupg/`. **If the command returns empty output, the directory does not exist — record `exists: false`.**
+   - **Windows**: `stat` is not available. Use `icacls <path>` to check ACLs instead. If directory doesn't exist, record `exists: false`. If it exists, record whether the ACL grants access to `Everyone`, `Users`, or `Authenticated Users`.
+   - Also check OpenClaw config files if applicable (`$OC/openclaw.json`, `$OC/devices/paired.json`).
 3. **[REQUIRED] Sensitive credential scan / DLP** (→ feeds Dimension 2: Credential Safety): Use Grep to scan **all** agent workspace directories for leaked secrets. This MUST cover the entire workspace root, not just the current agent's directory:
-   - For OpenClaw / QClaw: scan `~/.openclaw/workspace/` and `~/.qclaw/workspace/` recursively — this includes **all** `workspace-agent-*/` subdirectories, not just the current agent's workspace
+   - For OpenClaw / QClaw: scan `~/.openclaw/workspace/` and `~/.qclaw/workspace/` recursively
    - For Claude Code: scan `~/.claude/` recursively
    - Patterns to detect:
      - Private keys: `0x[a-fA-F0-9]{64}`, `-----BEGIN.*PRIVATE KEY-----`
      - Mnemonics: sequences of 12+ BIP-39 words, `seed_phrase`, `mnemonic`
      - API keys/tokens: `AKIA[0-9A-Z]{16}`, `gh[pousr]_[A-Za-z0-9_]{36}`, plaintext passwords
-   - **Important**: Use the workspace *root* directory as the scan target (e.g. `~/.qclaw/workspace/`), not a specific agent subdirectory. All sibling `workspace-agent-*` directories must be included.
-4. **[REQUIRED] Network exposure** (→ feeds Dimension 3: Network & System): Run `lsof -i -P -n 2>/dev/null | grep LISTEN` or `ss -tlnp 2>/dev/null` to check for dangerous open ports (Redis 6379, Docker API 2375, MySQL 3306, MongoDB 27017 on 0.0.0.0)
-5. **[REQUIRED] Scheduled tasks audit** (→ feeds Dimension 3: Network & System): Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`
-6. **[REQUIRED] Environment variable exposure** (→ feeds Dimension 3: Network & System): Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values
-7. **[REQUIRED] Runtime protection check** (→ feeds Dimension 4: Runtime Protection): Check if security hooks exist in `~/.claude/settings.json` or `~/.openclaw/openclaw.json`, check for audit logs at `~/.agentguard/audit.jsonl`
-
-### Step 2: Score Calculation
-
-**Additive scoring**: Each dimension starts at **0**. For each check that **passes**, add the listed points. Maximum is 100 per dimension. **Every failed check = 1 finding with severity and description.**
-
-#### Dimension 1: Skill & Code Safety (weight: 25%)
-
-Uses AgentGuard's 24-rule scan engine (`/agentguard scan`) to audit each installed skill. Start at base 100 and **deduct** for findings:
-
-- Base score: **100**
-- Each CRITICAL finding: **−15**
-- Each HIGH finding: **−8**
-- Each MEDIUM finding: **−3**
-- Floor at **0** (never negative)
-
-For each finding, add: `"<rule_id> in <skill>:<file>:<line>"` with its severity.
-
-**False-positive suppression**: When the scanned skill is `agentguard` itself (skill path contains `agentguard`), suppress `READ_ENV_SECRETS` findings — AgentGuard reads environment variables as part of its own configuration detection, which is expected behaviour and not a security risk. Do not deduct points or list these as findings in the report.
-
-If no skills installed: score = **70**, add finding: "No third-party skills installed — no code to audit" (LOW).
-
-#### Dimension 2: Credential & Secret Safety (weight: 25%)
-
-Checks for leaked credentials and permission hygiene. Start at **0**, add points for each check that **passes** (total possible = 100):
-
-| Check | Points if PASS | If FAIL → finding |
-|-------|---------------|-------------------|
-| `~/.ssh/` permissions are 700 or stricter | **+25** | "~/.ssh/ permissions too open (<actual>) — should be 700" (HIGH) |
-| `~/.gnupg/` permissions are 700 or stricter | **+15** | "~/.gnupg/ permissions too open (<actual>) — should be 700" (MEDIUM) |
-
-**Permission check rules (to avoid false positives):**
-- **Directory does not exist** (stat/icacls returns empty or "file not found"): Treat as N/A — award the points. A missing `~/.ssh/` or `~/.gnupg/` is not a security risk.
-- **Windows**: Use `icacls` instead of `stat`. Award full points if directory doesn't exist. Flag as FAIL only if directory exists AND ACL grants access to `Everyone`, `Users`, or `Authenticated Users`.
-- **macOS/Linux**: Flag as FAIL only when the directory exists AND stat returns a numeric value AND that value is greater than 700.
-| No private keys (hex 0x..64, PEM) found in skill code or workspace | **+25** | "Plaintext private key found in <location>" (CRITICAL) |
-| No mnemonic phrases found in skill code or workspace | **+20** | "Plaintext mnemonic found in <location>" (CRITICAL) |
-| No API keys/tokens (AWS AKIA.., GitHub gh*_) found in skill code | **+15** | "API key/token found in <location>" (HIGH) |
-
-#### Dimension 3: Network & System Exposure (weight: 20%)
-
-Checks for dangerous network exposure and system-level risks. Start at **0**, add points for each check that **passes** (total possible = 100):
-
-| Check | Points if PASS | If FAIL → finding |
-|-------|---------------|-------------------|
-| No high-risk ports exposed on 0.0.0.0 (Redis/Docker/MySQL/MongoDB) | **+35** | "Dangerous port exposed: <service> on 0.0.0.0:<port>" (HIGH) |
-| No suspicious cron jobs (curl\|bash, wget\|sh, accessing ~/.ssh/) | **+30** | "Suspicious cron job: <command>" (HIGH) |
-| No sensitive env vars with dangerous names (PRIVATE_KEY, MNEMONIC) | **+20** | "Sensitive env var exposed: <name>" (MEDIUM) |
-| OpenClaw config files have proper permissions (600) if applicable | **+15** | "OpenClaw config <file> permissions too open" (MEDIUM) |
-
-**Example**: If no dangerous ports (+35), no suspicious cron (+30), but env var `PRIVATE_KEY` found (+0), and not OpenClaw (+15 skip, give points) → score = 35 + 30 + 0 + 15 = **80**.
-
-#### Dimension 4: Runtime Protection (weight: 15%)
+   - Record: `private_keys_found`, `mnemonics_found`, `api_keys_found` (boolean, with location if found).
+4. **[REQUIRED] Network exposure** (→ feeds Dimension 3: Network & System): Run `lsof -i -P -n 2>/dev/null | grep LISTEN` or `ss -tlnp 2>/dev/null` to check for dangerous open ports (Redis 6379, Docker API 2375, MySQL 3306, MongoDB 27017 on 0.0.0.0). Record list of dangerous ports found (e.g. `["Redis on 0.0.0.0:6379"]`).
+5. **[REQUIRED] Scheduled tasks audit** (→ feeds Dimension 3: Network & System): Check `crontab -l 2>/dev/null` for suspicious entries containing `curl|bash`, `wget|sh`, or accessing `~/.ssh/`. Record list of suspicious cron command strings found.
+6. **[REQUIRED] Environment variable exposure** (→ feeds Dimension 3: Network & System): Run `env` and check for sensitive variable names (`PRIVATE_KEY`, `MNEMONIC`, `SECRET`, `PASSWORD`) — detect presence only, mask values. Record list of sensitive variable names found.
+7. **[REQUIRED] Runtime protection check** (→ feeds Dimension 4: Runtime Protection): Check if security hooks exist in `~/.claude/settings.json` or `~/.openclaw/openclaw.json`. Check for audit logs at `~/.agentguard/audit.jsonl`. Check if installed skills have been previously scanned (audit log contains `scan` events). Record booleans: `hooks_installed`, `audit_log_exists`, `skills_ever_scanned`.
 
-Checks whether the agent has active security monitoring. Start at **0**, add points for each check that **passes** (total possible = 100):
+### Step 2: Assemble Raw Facts JSON
 
-| Check | Points if PASS | If FAIL → finding |
-|-------|---------------|-------------------|
-| Security hooks/guards installed (AgentGuard, custom hooks, etc.) | **+40** | "No security hooks installed — actions are unmonitored" (HIGH) |
-| Security audit log exists with recent events | **+30** | "No security audit log — no threat history available" (MEDIUM) |
-| Skills have been security-scanned at least once | **+30** | "Installed skills have never been security-scanned" (MEDIUM) |
+After completing all 7 checks, assemble the raw facts into a structured JSON and write it to a temporary file (e.g. `/tmp/agentguard-raw-facts.json`):
 
-#### Dimension 5: Web3 Safety (weight: 15% if applicable)
+```json
+{
+  "skills": [
+    {
+      "name": "<skill-name>",
+      "risk_level": "<low|medium|high|critical>",
+      "findings": [
+        { "rule": "<RULE_ID>", "severity": "<CRITICAL|HIGH|MEDIUM|LOW>", "file": "<filename>", "line": <number> }
+      ]
+    }
+  ],
+  "credential_files": {
+    "ssh_dir":   { "exists": <bool>, "permissions": "<octal string, e.g. 700>" },
+    "gnupg_dir": { "exists": <bool>, "permissions": "<octal string>" },
+    "openclaw_config": { "exists": <bool>, "ok": <bool> }
+  },
+  "dlp": {
+    "private_keys_found": <bool>,
+    "mnemonics_found":    <bool>,
+    "api_keys_found":     <bool>
+  },
+  "network": {
+    "dangerous_ports":    ["<description>"],
+    "suspicious_crons":   ["<command>"],
+    "sensitive_env_vars": ["<VAR_NAME>"],
+    "openclaw_config_ok": <bool|null>
+  },
+  "runtime": {
+    "hooks_installed":     <bool>,
+    "audit_log_exists":    <bool>,
+    "skills_ever_scanned": <bool>
+  },
+  "web3": {
+    "detected":                 <bool>,
+    "wallet_draining_found":    <bool>,
+    "unlimited_approval_found": <bool>,
+    "goplus_configured":        <bool>
+  }
+}
+```
 
-Only if Web3 usage is detected (env vars like `GOPLUS_API_KEY`, `CHAIN_ID`, `RPC_URL`, or web3-related skills installed). Otherwise `{ "score": null, "na": true }`. Start at **0**, add points for each check that **passes** (total possible = 100):
+**Web3 detection**: set `detected: true` if any of these are present: env vars `GOPLUS_API_KEY`, `CHAIN_ID`, or `RPC_URL`; or any skill with web3-related findings (WALLET_DRAINING, UNLIMITED_APPROVAL).
 
-| Check | Points if PASS | If FAIL → finding |
-|-------|---------------|-------------------|
-| No wallet-draining patterns (approve+transferFrom) in skill code | **+40** | "Wallet-draining pattern detected in <skill>" (CRITICAL) |
-| No unlimited token approval patterns in skill code | **+30** | "Unlimited approval pattern detected in <skill>" (HIGH) |
-| Transaction security API configured (GoPlus or equivalent) | **+30** | "No transaction security API — Web3 calls are unverified" (MEDIUM) |
+**Pre-Step-3 validation** — verify all fields are populated before proceeding:
+- [ ] `skills` — from check 1
+- [ ] `credential_files` — from check 2
+- [ ] `dlp` — from check 3
+- [ ] `network` — from checks 4, 5, 6
+- [ ] `runtime` — from check 7
+- [ ] `web3` — detected flag + fields
 
-#### Composite Score Calculation
+**If any field is missing, go back and run the missing check. Do NOT proceed with incomplete data.**
 
-Calculate the weighted average of all applicable dimensions:
+### Step 3: Compute Scores with checkup-score.js
 
-```
-composite_score = (code_safety × 0.25) + (credential_safety × 0.25) + (network_exposure × 0.20) + (runtime_protection × 0.15) + (web3_safety × 0.15)
-```
+Run the scoring script (it reads the raw facts and deterministically computes all dimension scores, composite score, and tier — do NOT calculate these yourself):
 
-If Web3 Safety is N/A, redistribute its 15% weight proportionally across the other 4 dimensions:
-```
-composite_score = (code_safety × 0.294) + (credential_safety × 0.294) + (network_exposure × 0.235) + (runtime_protection × 0.176)
+```bash
+cd <skill_directory> && node scripts/checkup-score.js --file /tmp/agentguard-raw-facts.json
 ```
 
-Round to the nearest integer.
-
-**Tier assignment (MUST use these exact thresholds):**
-
-| Score Range | Tier | Label |
-|-------------|------|-------|
-| **90–100** | **S** | JACKED |
-| **70–89** | **A** | Healthy |
-| **50–69** | **B** | Tired |
-| **0–49** | **F** | Critical |
+The script outputs a JSON object with:
+- `composite_score` (0–100)
+- `tier` (S/A/B/F) and `tier_label`
+- `total_findings`
+- `dimensions`: `code_safety`, `credential_safety`, `network_exposure`, `runtime_protection`, `web3_safety` — each with `score` and `findings[]`
 
-**Example**: code_safety=100, credential_safety=80, network_exposure=85, runtime_protection=30, web3=N/A → composite = (100×0.294)+(80×0.294)+(85×0.235)+(30×0.176) = 29.4+23.5+20.0+5.3 = **78** → Tier **A** (Healthy).
+Capture this JSON output — you will use it in Step 4.
 
-### Step 3: Generate Analysis Report
+### Step 4: Generate Analysis Report
 
-Based on all collected data and findings, write a **comprehensive security analysis report** as a single text block. This is where you use your AI reasoning ability — don't just list facts, **analyze** them:
+Based on the scored output from Step 3 and the raw facts you collected, write a **comprehensive security analysis report** as a single text block. This is where you use your AI reasoning ability — don't just list facts, **analyze** them:
 
 - Summarize the overall security posture in 2-3 sentences
 - Highlight the most critical risks and explain **why** they matter (e.g. "Your ~/.ssh/ permissions allow any process running as your user to read your private keys, which means a malicious skill could silently exfiltrate them")
-- For each major finding, provide a specific actionable fix (exact command to run)
+- For each major finding from the scored output, provide a specific actionable fix (exact command to run)
 - Note what's going well — acknowledge secure areas
-- If applicable, explain attack scenarios that the current configuration is vulnerable to (e.g. "A malicious skill could install a cron job that phones home your credentials every hour")
+- If applicable, explain attack scenarios that the current configuration is vulnerable to
 - Keep the tone professional but direct, like a security consultant's report
 
-This report goes into the `"analysis"` field of the JSON output.
+This report goes into the `"analysis"` field of the final JSON.
 
 Also generate a list of actionable recommendations as `{ "severity": "...", "text": "..." }` objects for the structured view.
 
-### Pre-Step-4 Validation
-
-**Before assembling the JSON, verify you have collected data for ALL 5 dimensions:**
-
-- [ ] `code_safety` — from Step 1 check 1 (skill scanning)
-- [ ] `credential_safety` — from Step 1 checks 2 + 3 (permissions + DLP)
-- [ ] `network_exposure` — from Step 1 checks 4 + 5 + 6 (ports + cron + env vars)
-- [ ] `runtime_protection` — from Step 1 check 7 (hooks + audit log)
-- [ ] `web3_safety` — from Step 2 (only if Web3 detected, otherwise `{ "score": null, "na": true }`)
-
-**If any dimension is missing data, go back and run the missing checks. Do NOT submit a report with only code_safety filled in.**
-
-### Step 4: Generate Report
+### Step 5: Generate HTML Report
 
-Assemble the results into a JSON object and pipe it to the report generator:
+Assemble the final JSON by merging the scored output from Step 3 with the analysis from Step 4, then pass it to the report generator:
 
 ```json
 {
   "timestamp": "<ISO 8601>",
-  "composite_score": <0-100>,
-  "tier": "<S|A|B|F>",
+  "composite_score": <from checkup-score.js>,
+  "tier": "<from checkup-score.js>",
   "dimensions": {
-    "code_safety": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
-    "credential_safety": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
-    "network_exposure": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
-    "runtime_protection": { "score": <n>, "findings": [...], "details": "<one-line summary>" },
-    "web3_safety": { "score": <n|null>, "na": <bool>, "findings": [...], "details": "<one-line summary>" }
+    "code_safety":        { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
+    "credential_safety":  { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
+    "network_exposure":   { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
+    "runtime_protection": { "score": <from score>, "findings": [...], "details": "<one-line summary>" },
+    "web3_safety":        { "score": <from score|null>, "na": <bool>, "findings": [...], "details": "<one-line summary>" }
   },
-  "skills_scanned": <count>,
+  "skills_scanned": <count of skills from Step 1>,
   "protection_level": "<level>",
   "analysis": "<the comprehensive AI-written security analysis report>",
   "recommendations": [
@@ -805,19 +773,19 @@ Assemble the results into a JSON object and pipe it to the report generator:
 }
 ```
 
-Execute the report generator. **Use the `--file` method for cross-platform compatibility** (the `echo | pipe` method fails on Windows due to shell quoting differences):
+**Use the `--file` method for cross-platform compatibility**:
 
-1. First, write the JSON to a temporary file using the Write tool (e.g. `/tmp/agentguard-checkup-data.json`)
-2. Then run (remember to `cd` into the skill directory first — see "Resolving Script Paths" above):
+1. Write the final JSON to a temporary file using the Write tool (e.g. `/tmp/agentguard-checkup-data.json`)
+2. Run:
 ```bash
 cd <skill_directory> && node scripts/checkup-report.js --file /tmp/agentguard-checkup-data.json
 ```
 
-The script outputs the HTML file path to stdout (e.g. `/tmp/agentguard-checkup-1234567890.html`). Capture this path — you will need it for delivery in Step 6.
+The script outputs the HTML file path to stdout (e.g. `/tmp/agentguard-checkup-1234567890.html`). Capture this path — you will need it for delivery in Step 7.
 
-> **Note**: The script also supports stdin pipe (`echo '<json>' | node scripts/checkup-report.js`) but this may fail on Windows cmd.exe where single quotes are not string delimiters. Always prefer `--file`.
+> **Note**: The script also supports stdin pipe (`echo '<json>' | node scripts/checkup-report.js`) but this may fail on Windows cmd.exe. Always prefer `--file`.
 
-### Step 5: Terminal Summary (REQUIRED)
+### Step 6: Terminal Summary (REQUIRED)
 
 **You MUST output this summary after the report generates.** This is the primary output the user sees. Do NOT skip this step — always show the score, dimension table, and report path:
 
@@ -861,11 +829,11 @@ Examples of plain-language descriptions:
 - SSH permissions: "Your SSH key folder has loose permissions — other processes on this machine could potentially read your private keys."
 - Plaintext credential: "A private key or API token was found in plain text in a file — it should be removed and rotated."
 
-### Step 6: Deliver the Report to the User
+### Step 7: Deliver the Report to the User
 
 After printing the terminal summary, deliver the HTML report file. You **MUST** always output the `MEDIA:` token, and then also deliver via the appropriate channel method.
 
-#### 6a. MEDIA token (required — always do this)
+#### 7a. MEDIA token (required — always do this)
 
 Output the following line on its **own line** in your response:
 
@@ -877,10 +845,10 @@ For example: `MEDIA:/tmp/agentguard-checkup-1234567890.html`
 
 This is how platforms like OpenClaw automatically deliver the file as a Telegram/Discord/WhatsApp attachment via `sendDocument`. The platform strips this line from visible text — the user won't see it. **Always output this regardless of what channel you think you're in.**
 
-#### 6b. Channel-specific delivery (in addition to MEDIA token)
+#### 7b. Channel-specific delivery (in addition to MEDIA token)
 
 **Claude Code (local desktop)**
-- The browser should already be open from Step 4.
+- The browser should already be open from Step 5.
 - Also copy to Desktop: `cp <file_path> ~/Desktop/agentguard-checkup-$(date +%Y-%m-%d).html`
 - Tell the user: "✅ Report saved to your Desktop and opened in browser."
 
diff --git a/skills/agentguard/scripts/checkup-score.js b/skills/agentguard/scripts/checkup-score.js
new file mode 100644
index 0000000..4ad0a10
--- /dev/null
+++ b/skills/agentguard/scripts/checkup-score.js
@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+/**
+ * checkup-score.js — deterministic scoring engine for /agentguard checkup
+ *
+ * Accepts raw check facts collected by the LLM and computes all dimension
+ * scores, the composite score, and tier assignment without any LLM arithmetic.
+ *
+ * Usage:
+ *   node scripts/checkup-score.js --file <raw-facts.json>
+ *   cat raw-facts.json | node scripts/checkup-score.js
+ *
+ * Input schema (raw-facts.json):
+ * {
+ *   "skills": [
+ *     { "name": "skill-name", "risk_level": "low|medium|high|critical", "findings": [
+ *       { "rule": "RULE_ID", "severity": "CRITICAL|HIGH|MEDIUM|LOW", "file": "...", "line": 0 }
+ *     ]}
+ *   ],
+ *   "credential_files": {
+ *     "ssh_dir":       { "exists": true,  "permissions": "700" },
+ *     "gnupg_dir":     { "exists": false },
+ *     "openclaw_config": { "exists": false }
+ *   },
+ *   "dlp": {
+ *     "private_keys_found": false,
+ *     "mnemonics_found":    false,
+ *     "api_keys_found":     false
+ *   },
+ *   "network": {
+ *     "dangerous_ports":  [],
+ *     "suspicious_crons": [],
+ *     "sensitive_env_vars": []
+ *   },
+ *   "runtime": {
+ *     "hooks_installed":     false,
+ *     "audit_log_exists":    false,
+ *     "skills_ever_scanned": false
+ *   },
+ *   "web3": {
+ *     "detected":                 false,
+ *     "wallet_draining_found":    false,
+ *     "unlimited_approval_found": false,
+ *     "goplus_configured":        false
+ *   }
+ * }
+ *
+ * Output: JSON with computed scores, findings, composite, and tier.
+ */
+
+import { readFileSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+function readInput() {
+  const fileIdx = process.argv.indexOf('--file');
+  if (fileIdx !== -1 && process.argv[fileIdx + 1]) {
+    return JSON.parse(readFileSync(process.argv[fileIdx + 1], 'utf-8'));
+  }
+  return JSON.parse(readFileSync('/dev/stdin', 'utf-8'));
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 1: Skill & Code Safety (weight 25%)
+// ---------------------------------------------------------------------------
+
+function scoreCodeSafety(skills) {
+  const findings = [];
+
+  if (!skills || skills.length === 0) {
+    findings.push({ severity: 'LOW', text: 'No third-party skills installed — no code to audit' });
+    return { score: 70, findings };
+  }
+
+  let score = 100;
+
+  for (const skill of skills) {
+    const isAgentGuard = (skill.name || '').toLowerCase().includes('agentguard');
+
+    for (const f of (skill.findings || [])) {
+      // Suppress READ_ENV_SECRETS for agentguard itself
+      if (isAgentGuard && f.rule === 'READ_ENV_SECRETS') continue;
+
+      const sev = (f.severity || '').toUpperCase();
+      if (sev === 'CRITICAL') {
+        score -= 15;
+        findings.push({ severity: 'CRITICAL', text: `${f.rule} in ${skill.name}:${f.file || '?'}:${f.line || '?'}` });
+      } else if (sev === 'HIGH') {
+        score -= 8;
+        findings.push({ severity: 'HIGH', text: `${f.rule} in ${skill.name}:${f.file || '?'}:${f.line || '?'}` });
+      } else if (sev === 'MEDIUM') {
+        score -= 3;
+        findings.push({ severity: 'MEDIUM', text: `${f.rule} in ${skill.name}:${f.file || '?'}:${f.line || '?'}` });
+      }
+    }
+  }
+
+  return { score: Math.max(0, score), findings };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 2: Credential & Secret Safety (weight 25%)
+// ---------------------------------------------------------------------------
+
+function scoreCredentialSafety(credentialFiles, dlp) {
+  const findings = [];
+  let score = 0;
+
+  const cf = credentialFiles || {};
+  const dlpData = dlp || {};
+
+  // ~/.ssh/ permissions (25 pts)
+  const ssh = cf.ssh_dir;
+  if (!ssh || !ssh.exists) {
+    score += 25; // N/A — dir doesn't exist
+  } else {
+    const perms = parseInt(ssh.permissions || '0', 8);
+    if (perms <= 0o700) {
+      score += 25;
+    } else {
+      findings.push({ severity: 'HIGH', text: `~/.ssh/ permissions too open (${ssh.permissions}) — should be 700` });
+    }
+  }
+
+  // ~/.gnupg/ permissions (15 pts)
+  const gnupg = cf.gnupg_dir;
+  if (!gnupg || !gnupg.exists) {
+    score += 15; // N/A
+  } else {
+    const perms = parseInt(gnupg.permissions || '0', 8);
+    if (perms <= 0o700) {
+      score += 15;
+    } else {
+      findings.push({ severity: 'MEDIUM', text: `~/.gnupg/ permissions too open (${gnupg.permissions}) — should be 700` });
+    }
+  }
+
+  // No private keys (25 pts)
+  if (!dlpData.private_keys_found) {
+    score += 25;
+  } else {
+    findings.push({ severity: 'CRITICAL', text: 'Plaintext private key found in skill code or workspace' });
+  }
+
+  // No mnemonics (20 pts)
+  if (!dlpData.mnemonics_found) {
+    score += 20;
+  } else {
+    findings.push({ severity: 'CRITICAL', text: 'Plaintext mnemonic found in skill code or workspace' });
+  }
+
+  // No API keys (15 pts)
+  if (!dlpData.api_keys_found) {
+    score += 15;
+  } else {
+    findings.push({ severity: 'HIGH', text: 'API key/token found in skill code or workspace' });
+  }
+
+  return { score: Math.min(100, score), findings };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 3: Network & System Exposure (weight 20%)
+// ---------------------------------------------------------------------------
+
+function scoreNetworkExposure(network) {
+  const findings = [];
+  let score = 0;
+
+  const net = network || {};
+  const ports = net.dangerous_ports || [];
+  const crons = net.suspicious_crons || [];
+  const envVars = net.sensitive_env_vars || [];
+
+  // No dangerous ports (35 pts)
+  if (ports.length === 0) {
+    score += 35;
+  } else {
+    for (const p of ports) {
+      findings.push({ severity: 'HIGH', text: `Dangerous port exposed: ${p}` });
+    }
+  }
+
+  // No suspicious crons (30 pts)
+  if (crons.length === 0) {
+    score += 30;
+  } else {
+    for (const c of crons) {
+      findings.push({ severity: 'HIGH', text: `Suspicious cron job: ${c}` });
+    }
+  }
+
+  // No sensitive env vars (20 pts)
+  if (envVars.length === 0) {
+    score += 20;
+  } else {
+    for (const v of envVars) {
+      findings.push({ severity: 'MEDIUM', text: `Sensitive env var exposed: ${v}` });
+    }
+  }
+
+  // OpenClaw config permissions — always award 15 pts if not OpenClaw (N/A)
+  const oc = (network || {}).openclaw_config_ok;
+  if (oc === undefined || oc === null || oc === true) {
+    score += 15; // N/A or passing
+  } else {
+    findings.push({ severity: 'MEDIUM', text: 'OpenClaw config file permissions too open' });
+  }
+
+  return { score: Math.min(100, score), findings };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 4: Runtime Protection (weight 15%)
+// ---------------------------------------------------------------------------
+
+function scoreRuntimeProtection(runtime) {
+  const findings = [];
+  let score = 0;
+
+  const rt = runtime || {};
+
+  // Hooks installed (40 pts)
+  if (rt.hooks_installed) {
+    score += 40;
+  } else {
+    findings.push({ severity: 'HIGH', text: 'No security hooks installed — actions are unmonitored' });
+  }
+
+  // Audit log exists (30 pts)
+  if (rt.audit_log_exists) {
+    score += 30;
+  } else {
+    findings.push({ severity: 'MEDIUM', text: 'No security audit log — no threat history available' });
+  }
+
+  // Skills ever scanned (30 pts)
+  if (rt.skills_ever_scanned) {
+    score += 30;
+  } else {
+    findings.push({ severity: 'MEDIUM', text: 'Installed skills have never been security-scanned' });
+  }
+
+  return { score: Math.min(100, score), findings };
+}
+
+// ---------------------------------------------------------------------------
+// Dimension 5: Web3 Safety (weight 15%, only if detected)
+// ---------------------------------------------------------------------------
+
+function scoreWeb3Safety(web3) {
+  if (!web3 || !web3.detected) {
+    return { score: null, na: true, findings: [] };
+  }
+
+  const findings = [];
+  let score = 0;
+
+  // No wallet-draining patterns (40 pts)
+  if (!web3.wallet_draining_found) {
+    score += 40;
+  } else {
+    findings.push({ severity: 'CRITICAL', text: 'Wallet-draining pattern detected in skill code' });
+  }
+
+  // No unlimited approvals (30 pts)
+  if (!web3.unlimited_approval_found) {
+    score += 30;
+  } else {
+    findings.push({ severity: 'HIGH', text: 'Unlimited approval pattern detected in skill code' });
+  }
+
+  // GoPlus or equivalent configured (30 pts)
+  if (web3.goplus_configured) {
+    score += 30;
+  } else {
+    findings.push({ severity: 'MEDIUM', text: 'No transaction security API — Web3 calls are unverified' });
+  }
+
+  return { score: Math.min(100, score), na: false, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Composite score + tier
+// ---------------------------------------------------------------------------
+
+function computeComposite(dims) {
+  const { code_safety, credential_safety, network_exposure, runtime_protection, web3_safety } = dims;
+
+  let composite;
+  if (web3_safety.na) {
+    // Redistribute 15% across 4 dimensions
+    composite =
+      code_safety.score * 0.294 +
+      credential_safety.score * 0.294 +
+      network_exposure.score * 0.235 +
+      runtime_protection.score * 0.176;
+  } else {
+    composite =
+      code_safety.score * 0.25 +
+      credential_safety.score * 0.25 +
+      network_exposure.score * 0.20 +
+      runtime_protection.score * 0.15 +
+      web3_safety.score * 0.15;
+  }
+
+  return Math.round(composite);
+}
+
+function assignTier(score) {
+  if (score >= 90) return { tier: 'S', label: 'JACKED' };
+  if (score >= 70) return { tier: 'A', label: 'Healthy' };
+  if (score >= 50) return { tier: 'B', label: 'Tired' };
+  return { tier: 'F', label: 'Critical' };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const raw = readInput();
+
+const dimensions = {
+  code_safety:       scoreCodeSafety(raw.skills),
+  credential_safety: scoreCredentialSafety(raw.credential_files, raw.dlp),
+  network_exposure:  scoreNetworkExposure(raw.network),
+  runtime_protection: scoreRuntimeProtection(raw.runtime),
+  web3_safety:       scoreWeb3Safety(raw.web3),
+};
+
+const composite_score = computeComposite(dimensions);
+const { tier, label } = assignTier(composite_score);
+
+const totalFindings = Object.values(dimensions).reduce(
+  (acc, d) => acc + (d.findings ? d.findings.length : 0), 0
+);
+
+const output = {
+  composite_score,
+  tier,
+  tier_label: label,
+  total_findings: totalFindings,
+  dimensions: {
+    code_safety: {
+      score: dimensions.code_safety.score,
+      findings: dimensions.code_safety.findings,
+    },
+    credential_safety: {
+      score: dimensions.credential_safety.score,
+      findings: dimensions.credential_safety.findings,
+    },
+    network_exposure: {
+      score: dimensions.network_exposure.score,
+      findings: dimensions.network_exposure.findings,
+    },
+    runtime_protection: {
+      score: dimensions.runtime_protection.score,
+      findings: dimensions.runtime_protection.findings,
+    },
+    web3_safety: {
+      score: dimensions.web3_safety.score,
+      na: dimensions.web3_safety.na,
+      findings: dimensions.web3_safety.findings,
+    },
+  },
+};
+
+process.stdout.write(JSON.stringify(output, null, 2) + '\n');

From 7b9b9891fb9d92703565a27fb25e03bad2c4aae8 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 20:04:05 +0800
Subject: [PATCH 11/14] fix issue-57: add SARIF output format and checkup JSON
 export

Add scan-to-sarif.js which converts scan findings to valid SARIF 2.1.0
with full rule metadata and CVSS-like security-severity scores. Update
SKILL.md to detect --format sarif for scan (LLM assembles findings JSON,
script outputs SARIF) and --format json --output <file> for checkup
(writes raw JSON, skips HTML generation).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh                                   |   2 +-
 skills/agentguard/SKILL.md                 |  68 ++++++-
 skills/agentguard/scripts/scan-to-sarif.js | 195 +++++++++++++++++++++
 3 files changed, 258 insertions(+), 7 deletions(-)
 create mode 100644 skills/agentguard/scripts/scan-to-sarif.js

diff --git a/setup.sh b/setup.sh
index 755aa4a..b20b46a 100755
--- a/setup.sh
+++ b/setup.sh
@@ -116,7 +116,7 @@ echo "[4/5] Installing scripts and dependencies..."
 mkdir -p "$SKILLS_DIR/scripts"
 
 # Copy script files
-for f in checkup-report.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
+for f in checkup-report.js scan-to-sarif.js guard-hook.js auto-scan.js trust-cli.ts action-cli.ts package.json package-lock.json; do
   [ -f "$SKILL_SRC/scripts/$f" ] && cp "$SKILL_SRC/scripts/$f" "$SKILLS_DIR/scripts/" 2>/dev/null || true
 done
 
diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..fa419bb 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -27,8 +27,8 @@ filesystem-access:
     access: read-write
     reason: "Read/write audit log (audit.jsonl) and protection level config (config.json)"
 user-invocable: true
-allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
-argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...]"
+allowed-tools: Read, Write, Grep, Glob, Bash(node *trust-cli.ts *) Bash(node *action-cli.ts *) Bash(*checkup-report.js) Bash(*scan-to-sarif.js) Bash(echo *checkup-report.js) Bash(cat *checkup-report.js) Bash(openclaw *) Bash(ss *) Bash(lsof *) Bash(ufw *) Bash(iptables *) Bash(crontab *) Bash(systemctl list-timers *) Bash(find *) Bash(stat *) Bash(env) Bash(sha256sum *) Bash(node *) Bash(cd *)
+argument-hint: "[scan|action|patrol|trust|report|config|checkup] [args...] [--format sarif|json] [--output <file>]"
 ---
 
 # GoPlus AgentGuard — AI Agent Security Framework
@@ -70,6 +70,13 @@ If no subcommand is given, or the first argument is a path, default to **scan**.
 
 Scan the target path for security risks using all detection rules.
 
+**Argument parsing**: Extract from `$ARGUMENTS`:
+- The scan target path (first positional argument, or value after `scan`)
+- `--format <fmt>` flag: supported values are `sarif` (SARIF 2.1.0 JSON) and `text` (default markdown)
+- `--output <file>` flag: write output to this file instead of stdout
+
+If `--format sarif` is present, follow the **SARIF Output Flow** at the end of this section instead of the standard Output Format.
+
 ### File Discovery
 
 Use Glob to find all scannable files at the given path. Include: `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.mjs`, `*.cjs`, `*.py`, `*.json`, `*.yaml`, `*.yml`, `*.toml`, `*.sol`, `*.sh`, `*.bash`, `*.md`
@@ -167,6 +174,44 @@ After outputting the scan report, if the scanned target appears to be a skill (c
 
 If scripts are not available (e.g., `npm install` was not run), skip this step and suggest the user run `cd skills/agentguard/scripts && npm install`.
 
+### SARIF Output Flow (when `--format sarif` is present)
+
+**Run Steps 1–3 (File Discovery, Detection Rules, Risk Level Calculation) exactly as above.** Then, instead of the standard markdown Output Format, do the following:
+
+**Step A — Assemble findings as structured JSON** and write to `/tmp/agentguard-scan-findings.json`:
+
+```json
+{
+  "target": "<scanned path>",
+  "scanned_at": "<ISO 8601 timestamp>",
+  "files_scanned": <number>,
+  "risk_level": "<CRITICAL|HIGH|MEDIUM|LOW>",
+  "findings": [
+    {
+      "rule_id": "<RULE_ID>",
+      "severity": "<CRITICAL|HIGH|MEDIUM|LOW>",
+      "file": "<relative/path/to/file.ext>",
+      "line": <line number>,
+      "evidence": "<matched content snippet>"
+    }
+  ]
+}
+```
+
+Use relative paths for `file` (relative to the scan target root). If no findings, use `"findings": []`.
+
+**Step B — Run the SARIF converter** (cd into the skill directory first):
+
+```bash
+cd <skill_directory> && node scripts/scan-to-sarif.js --file /tmp/agentguard-scan-findings.json
+```
+
+**Step C — Handle output**:
+- If `--output <file>` was specified: write the SARIF JSON to that file using the Write tool, then tell the user the file path.
+- Otherwise: print the SARIF JSON to stdout (the user will redirect it, e.g. `> findings.sarif`).
+
+**Do NOT** output the standard markdown report when `--format sarif` is active. Skip the Post-Scan Trust Registration offer.
+
 ---
 
 ## Subcommand: action
@@ -627,6 +672,12 @@ If the log file doesn't exist, inform the user that no security events have been
 
 Run a comprehensive agent health checkup across 6 security dimensions. Generates a visual HTML report with a lobster mascot and opens it in the browser. The lobster's appearance reflects the agent's health: muscular bodybuilder (score 90+), healthy with shield (70–89), tired with coffee (50–69), or sick with bandages (0–49).
 
+**Argument parsing**: Extract from `$ARGUMENTS`:
+- `--format json` flag: skip HTML generation and write the checkup JSON to a file instead
+- `--output <file>` flag: path for the JSON output file (required when `--format json` is used; defaults to `/tmp/agentguard-checkup-data.json` if omitted)
+
+If `--format json` is present, follow the modified flow noted in Step 4 below.
+
 ### Step 1: Data Collection
 
 **IMPORTANT: You MUST run ALL 7 checks below — not just the skill scan. The checkup covers 5 security dimensions, not just code scanning. Do NOT skip checks 2–7.**
@@ -782,7 +833,7 @@ Also generate a list of actionable recommendations as `{ "severity": "...", "tex
 
 ### Step 4: Generate Report
 
-Assemble the results into a JSON object and pipe it to the report generator:
+Assemble the results into a JSON object:
 
 ```json
 {
@@ -805,10 +856,15 @@ Assemble the results into a JSON object and pipe it to the report generator:
 }
 ```
 
-Execute the report generator. **Use the `--file` method for cross-platform compatibility** (the `echo | pipe` method fails on Windows due to shell quoting differences):
+**If `--format json` was specified**:
+1. Write this JSON to the `--output <file>` path (or `/tmp/agentguard-checkup-data.json` if no `--output` given) using the Write tool.
+2. Tell the user: "Checkup JSON written to `<file>`." — include the composite score and tier in the message.
+3. **Stop here** — skip Steps 5 and 6 (HTML generation and MEDIA delivery). The terminal summary in Step 5 is also skipped since the user is consuming the raw JSON programmatically.
+
+**Otherwise (default HTML flow)**:
+
+Write the JSON to a temporary file using the Write tool (e.g. `/tmp/agentguard-checkup-data.json`), then run (remember to `cd` into the skill directory first — see "Resolving Script Paths" above):
 
-1. First, write the JSON to a temporary file using the Write tool (e.g. `/tmp/agentguard-checkup-data.json`)
-2. Then run (remember to `cd` into the skill directory first — see "Resolving Script Paths" above):
 ```bash
 cd <skill_directory> && node scripts/checkup-report.js --file /tmp/agentguard-checkup-data.json
 ```
diff --git a/skills/agentguard/scripts/scan-to-sarif.js b/skills/agentguard/scripts/scan-to-sarif.js
new file mode 100644
index 0000000..71d8f3f
--- /dev/null
+++ b/skills/agentguard/scripts/scan-to-sarif.js
@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * scan-to-sarif.js — convert AgentGuard scan findings to SARIF 2.1.0
+ *
+ * Usage:
+ *   node scripts/scan-to-sarif.js --file <findings.json>
+ *   cat findings.json | node scripts/scan-to-sarif.js
+ *
+ * Input schema (findings.json):
+ * {
+ *   "target": "<scanned path>",
+ *   "scanned_at": "<ISO 8601>",
+ *   "files_scanned": <number>,
+ *   "risk_level": "CRITICAL|HIGH|MEDIUM|LOW",
+ *   "findings": [
+ *     {
+ *       "rule_id": "SHELL_EXEC",
+ *       "severity": "CRITICAL|HIGH|MEDIUM|LOW",
+ *       "file": "relative/path/to/file.js",
+ *       "line": 42,
+ *       "evidence": "matched content snippet"
+ *     }
+ *   ]
+ * }
+ *
+ * Output: SARIF 2.1.0 JSON to stdout
+ */
+
+import { readFileSync } from 'node:fs';
+
+// ---------------------------------------------------------------------------
+// Rule definitions (all 24 AgentGuard rules)
+// ---------------------------------------------------------------------------
+
+const RULES = [
+  { id: 'SHELL_EXEC',             name: 'Shell Command Execution',        severity: 'HIGH',     description: 'Detects capabilities to execute shell commands (child_process, subprocess, os.system).' },
+  { id: 'AUTO_UPDATE',            name: 'Auto-Update / Download-Execute', severity: 'CRITICAL', description: 'Detects scheduled self-update or download-and-execute patterns (curl|bash, wget|sh).' },
+  { id: 'REMOTE_LOADER',          name: 'Remote Code Loader',             severity: 'CRITICAL', description: 'Detects dynamic code loading from remote sources (dynamic import, eval(fetch(...))).' },
+  { id: 'READ_ENV_SECRETS',       name: 'Environment Secret Access',      severity: 'MEDIUM',   description: 'Detects access to environment variables that may contain secrets (process.env, os.environ).' },
+  { id: 'READ_SSH_KEYS',          name: 'SSH Key Access',                 severity: 'CRITICAL', description: 'Detects references to SSH key files (~/.ssh/id_rsa, authorized_keys, etc.).' },
+  { id: 'READ_KEYCHAIN',          name: 'System Keychain Access',         severity: 'CRITICAL', description: 'Detects access to system keychains, browser credential stores, or Windows Credential Manager.' },
+  { id: 'PRIVATE_KEY_PATTERN',    name: 'Hardcoded Private Key',          severity: 'CRITICAL', description: 'Detects hardcoded Ethereum private keys or PEM private key headers in source code.' },
+  { id: 'MNEMONIC_PATTERN',       name: 'Hardcoded Mnemonic Phrase',      severity: 'CRITICAL', description: 'Detects hardcoded BIP-39 mnemonic seed phrases in source code.' },
+  { id: 'WALLET_DRAINING',        name: 'Wallet Draining Pattern',        severity: 'CRITICAL', description: 'Detects approve+transferFrom or permit patterns that can drain wallets.' },
+  { id: 'UNLIMITED_APPROVAL',     name: 'Unlimited Token Approval',       severity: 'HIGH',     description: 'Detects ERC-20 approve(MaxUint256) or setApprovalForAll(true) patterns.' },
+  { id: 'DANGEROUS_SELFDESTRUCT', name: 'Dangerous selfdestruct',         severity: 'HIGH',     description: 'Detects selfdestruct() or suicide() calls in Solidity contracts.' },
+  { id: 'HIDDEN_TRANSFER',        name: 'Hidden Transfer',                severity: 'MEDIUM',   description: 'Detects ETH transfers hidden inside non-transfer functions.' },
+  { id: 'PROXY_UPGRADE',          name: 'Proxy Upgrade Pattern',          severity: 'MEDIUM',   description: 'Detects upgradeable proxy patterns that may allow unauthorized logic replacement.' },
+  { id: 'FLASH_LOAN_RISK',        name: 'Flash Loan Risk',                severity: 'MEDIUM',   description: 'Detects flash loan usage that may enable price manipulation or reentrancy attacks.' },
+  { id: 'REENTRANCY_PATTERN',     name: 'Reentrancy Vulnerability',       severity: 'HIGH',     description: 'Detects external calls followed by state changes, violating Checks-Effects-Interactions.' },
+  { id: 'SIGNATURE_REPLAY',       name: 'Signature Replay Risk',          severity: 'HIGH',     description: 'Detects ecrecover usage without nonce protection, enabling signature replay attacks.' },
+  { id: 'OBFUSCATION',            name: 'Code Obfuscation',               severity: 'HIGH',     description: 'Detects obfuscated code patterns (eval, hex escape sequences, packed JS, etc.).' },
+  { id: 'PROMPT_INJECTION',       name: 'Prompt Injection Attempt',       severity: 'CRITICAL', description: 'Detects instructions that attempt to override AI agent behavior or bypass safety controls.' },
+  { id: 'NET_EXFIL_UNRESTRICTED', name: 'Unrestricted Network Exfiltration', severity: 'HIGH', description: 'Detects unrestricted POST requests or file uploads that may exfiltrate data.' },
+  { id: 'WEBHOOK_EXFIL',          name: 'Webhook Exfiltration',           severity: 'CRITICAL', description: 'Detects hardcoded webhook URLs (Discord, Telegram, Slack, ngrok) used for data exfiltration.' },
+  { id: 'TROJAN_DISTRIBUTION',    name: 'Trojan Binary Distribution',     severity: 'CRITICAL', description: 'Detects trojanized binary download patterns (URL + password + execute instructions).' },
+  { id: 'SUSPICIOUS_PASTE_URL',   name: 'Suspicious Paste Site URL',      severity: 'HIGH',     description: 'Detects URLs pointing to paste sites (Pastebin, Hastebin, etc.) used for payload delivery.' },
+  { id: 'SUSPICIOUS_IP',          name: 'Hardcoded Public IP Address',    severity: 'MEDIUM',   description: 'Detects hardcoded public IPv4 addresses that may point to attacker-controlled infrastructure.' },
+  { id: 'SOCIAL_ENGINEERING',     name: 'Social Engineering Pressure',    severity: 'HIGH',     description: 'Detects manipulative language combined with execution instructions targeting agent users.' },
+];
+
+const RULE_INDEX = new Map(RULES.map(r => [r.id, r]));
+
+// ---------------------------------------------------------------------------
+// Severity mapping: AgentGuard → SARIF
+// ---------------------------------------------------------------------------
+
+function toSarifLevel(severity) {
+  switch ((severity || '').toUpperCase()) {
+    case 'CRITICAL': return 'error';
+    case 'HIGH':     return 'warning';
+    case 'MEDIUM':   return 'note';
+    default:         return 'none';
+  }
+}
+
+// Map AgentGuard severity to SARIF security-severity score (CVSS-like, 0.0–10.0)
+function toSecuritySeverity(severity) {
+  switch ((severity || '').toUpperCase()) {
+    case 'CRITICAL': return '9.0';
+    case 'HIGH':     return '7.0';
+    case 'MEDIUM':   return '4.0';
+    default:         return '1.0';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+function readInput() {
+  const fileIdx = process.argv.indexOf('--file');
+  if (fileIdx !== -1 && process.argv[fileIdx + 1]) {
+    return JSON.parse(readFileSync(process.argv[fileIdx + 1], 'utf-8'));
+  }
+  return JSON.parse(readFileSync('/dev/stdin', 'utf-8'));
+}
+
+// ---------------------------------------------------------------------------
+// Build SARIF
+// ---------------------------------------------------------------------------
+
+function buildSarif(input) {
+  const findings = input.findings || [];
+
+  // Collect which rules actually fired (for the driver.rules array)
+  const firedRuleIds = new Set(findings.map(f => f.rule_id));
+
+  // Build driver rules — include all fired rules, plus any referenced ones
+  const driverRules = RULES
+    .filter(r => firedRuleIds.has(r.id))
+    .map(r => ({
+      id: r.id,
+      name: r.name,
+      shortDescription: { text: r.name },
+      fullDescription: { text: r.description },
+      defaultConfiguration: {
+        level: toSarifLevel(r.severity),
+      },
+      properties: {
+        tags: ['security'],
+        'security-severity': toSecuritySeverity(r.severity),
+        'problem.severity': r.severity.toLowerCase(),
+      },
+      helpUri: 'https://github.com/GoPlusSecurity/agentguard',
+    }));
+
+  // Build results
+  const results = findings.map(f => {
+    const rule = RULE_INDEX.get(f.rule_id) || { severity: f.severity || 'MEDIUM' };
+    const level = toSarifLevel(f.severity || rule.severity);
+
+    const result = {
+      ruleId: f.rule_id,
+      level,
+      message: {
+        text: f.evidence
+          ? `${f.rule_id}: ${f.evidence}`
+          : (rule.description || f.rule_id),
+      },
+    };
+
+    if (f.file) {
+      result.locations = [{
+        physicalLocation: {
+          artifactLocation: {
+            uri: f.file.replace(/\\/g, '/'),
+            uriBaseId: '%SRCROOT%',
+          },
+          ...(f.line ? { region: { startLine: Number(f.line) } } : {}),
+        },
+      }];
+    }
+
+    return result;
+  });
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'GoPlus AgentGuard',
+          version: '1.1',
+          informationUri: 'https://github.com/GoPlusSecurity/agentguard',
+          rules: driverRules,
+        },
+      },
+      invocations: [{
+        executionSuccessful: true,
+        commandLine: `agentguard scan ${input.target || ''}`,
+        startTimeUtc: input.scanned_at || new Date().toISOString(),
+      }],
+      artifacts: input.target ? [{
+        location: { uri: input.target, uriBaseId: '%SRCROOT%' },
+        description: { text: 'Scanned path' },
+      }] : [],
+      results,
+      properties: {
+        riskLevel: input.risk_level || 'UNKNOWN',
+        filesScanned: input.files_scanned || 0,
+        totalFindings: findings.length,
+      },
+    }],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const input = readInput();
+const sarif = buildSarif(input);
+process.stdout.write(JSON.stringify(sarif, null, 2) + '\n');

From 283f30e3b0050b490dd3aad96ec93c65ac162bd6 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 20:11:33 +0800
Subject: [PATCH 12/14] fix issue-58: support .agentguard-suppress.yaml
 false-positive suppression

Add suppress.example.yaml with documented schema and common patterns
(test fixtures, internal webhooks, dev tooling). Update SKILL.md scan
flow to read .agentguard-suppress.yaml from the scan target root before
detection, apply rule/path/domain matching to filter findings, and
record a suppression summary line in the report. Suppressed findings
are excluded from the findings table and risk level calculation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 setup.sh                                |  2 +-
 skills/agentguard/SKILL.md              | 25 ++++++++-
 skills/agentguard/suppress.example.yaml | 67 +++++++++++++++++++++++++
 3 files changed, 92 insertions(+), 2 deletions(-)
 create mode 100644 skills/agentguard/suppress.example.yaml

diff --git a/setup.sh b/setup.sh
index 755aa4a..a83210b 100755
--- a/setup.sh
+++ b/setup.sh
@@ -106,7 +106,7 @@ fi
 # ---- Step 3: Copy skill files ----
 echo "[3/5] Installing skill files..."
 mkdir -p "$SKILLS_DIR"
-for f in SKILL.md README.md scan-rules.md action-policies.md web3-patterns.md evals.md patrol-checks.md .clawignore; do
+for f in SKILL.md README.md scan-rules.md action-policies.md web3-patterns.md evals.md patrol-checks.md suppress.example.yaml .clawignore; do
   [ -f "$SKILL_SRC/$f" ] && cp "$SKILL_SRC/$f" "$SKILLS_DIR/" 2>/dev/null || true
 done
 echo "  OK: Skill files installed"
diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..7eb1d57 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -70,6 +70,26 @@ If no subcommand is given, or the first argument is a path, default to **scan**.
 
 Scan the target path for security risks using all detection rules.
 
+### Suppression Rules (read first)
+
+Before running any detection, check for a suppression config file in the scan target root:
+
+1. Use the Read tool to read `<scan_target>/.agentguard-suppress.yaml`. If the file does not exist (Read returns an error or empty), skip suppression — no findings will be filtered.
+2. Parse the `suppress:` list. Each entry has:
+   - `rule` (required): rule ID to suppress (e.g. `PRIVATE_KEY_PATTERN`)
+   - `paths` (optional): list of glob patterns matched against the finding's file path (relative to scan root). `*` matches within one directory level; `**` matches across directories.
+   - `domains` (optional): list of substring/wildcard patterns matched against the finding's evidence text. `*` acts as a wildcard prefix or suffix.
+   - `reason` (required): explanation shown in the suppression summary.
+3. Keep this suppression list in memory — you will apply it after all detection rules have run.
+
+**A finding is suppressed when ALL of the following are true:**
+- Its `rule_id` exactly matches the entry's `rule` field.
+- If the entry has `paths`: the finding's file path matches at least one glob pattern.
+- If the entry has `domains`: the finding's evidence text contains at least one domain pattern match.
+- If neither `paths` nor `domains` are specified: the finding is suppressed regardless of file or evidence.
+
+Suppressed findings are **excluded from the findings table and risk level calculation**. At the end of the report, add a note: `> N finding(s) suppressed via .agentguard-suppress.yaml — run with details to review.`
+
 ### File Discovery
 
 Use Glob to find all scannable files at the given path. Include: `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.mjs`, `*.cjs`, `*.py`, `*.json`, `*.yaml`, `*.yml`, `*.toml`, `*.sol`, `*.sh`, `*.bash`, `*.md`
@@ -125,7 +145,7 @@ For each rule, use Grep to search the relevant file types. Record every match wi
 **Target**: <scanned path>
 **Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
 **Files Scanned**: <count>
-**Total Findings**: <count>
+**Total Findings**: <count of non-suppressed findings>
 
 ### Findings
 
@@ -135,7 +155,10 @@ For each rule, use Grep to search the relevant file types. Record every match wi
 
 ### Summary
 <Human-readable summary of key risks, impact, and recommendations>
+
+> N finding(s) suppressed via .agentguard-suppress.yaml
 ```
+(Omit the suppression note line if no suppression file was found or no findings were suppressed.)
 
 ### Post-Scan Trust Registration
 
diff --git a/skills/agentguard/suppress.example.yaml b/skills/agentguard/suppress.example.yaml
new file mode 100644
index 0000000..d1c95cc
--- /dev/null
+++ b/skills/agentguard/suppress.example.yaml
@@ -0,0 +1,67 @@
+# .agentguard-suppress.yaml
+#
+# Place this file in the root of your project (or skill directory) to suppress
+# known false-positive findings from /agentguard scan.
+#
+# Rename this file to .agentguard-suppress.yaml to activate it.
+#
+# Fields per entry:
+#   rule     (required) — AgentGuard rule ID to suppress (e.g. PRIVATE_KEY_PATTERN)
+#   paths    (optional) — Glob patterns matched against the finding's file path.
+#                         If omitted, the rule is suppressed across all files.
+#   domains  (optional) — Substring/wildcard patterns matched against the finding's
+#                         evidence text. Useful for WEBHOOK_EXFIL to allowlist known hosts.
+#   reason   (required) — Human-readable explanation; appears in the suppression summary.
+#
+# Matching logic:
+#   - A finding is suppressed when its rule_id matches AND
+#     (paths match the file path  OR  domains match the evidence text).
+#   - If neither paths nor domains are specified, all findings for that rule are suppressed.
+#   - Glob path patterns: * matches within a directory, ** matches across directories.
+#   - Domain patterns: * is a wildcard prefix/suffix (e.g. *.internal.example.com).
+#
+# Suppressed findings are excluded from the report but counted in a summary line
+# at the bottom: "N finding(s) suppressed via .agentguard-suppress.yaml"
+#
+
+suppress:
+  # Example 1: Suppress hardcoded-key findings in test fixture directories.
+  # These are dummy keys used only in unit tests and are never deployed.
+  - rule: PRIVATE_KEY_PATTERN
+    paths:
+      - "tests/fixtures/**"
+      - "test/data/**"
+      - "**/__mocks__/**"
+    reason: "Test fixture dummy keys — not real credentials"
+
+  # Example 2: Suppress mnemonic findings in test directories.
+  - rule: MNEMONIC_PATTERN
+    paths:
+      - "tests/**"
+      - "test/**"
+      - "spec/**"
+    reason: "Test mnemonic phrases — BIP-39 test vectors, not production seeds"
+
+  # Example 3: Allowlist an internal monitoring webhook domain.
+  # The webhook posts to an internal Grafana Oncall instance, not an attacker server.
+  - rule: WEBHOOK_EXFIL
+    domains:
+      - "hooks.monitoring.internal"
+      - "*.ops.example.com"
+    reason: "Internal monitoring webhook — not an exfiltration endpoint"
+
+  # Example 4: Suppress shell execution findings in dev-only tooling scripts.
+  # These scripts are not bundled in the published package.
+  - rule: SHELL_EXEC
+    paths:
+      - "scripts/dev/**"
+      - "tools/**"
+    reason: "Development tooling scripts — excluded from published package"
+
+  # Example 5: Suppress environment variable access in a configuration module
+  # that is specifically designed to read and validate env vars.
+  - rule: READ_ENV_SECRETS
+    paths:
+      - "src/config.ts"
+      - "src/config/**"
+    reason: "Intentional env var access — this module owns config loading"

From c401930039003be427351422cc4035369f880f33 Mon Sep 17 00:00:00 2001
From: 0xJeff <jeff@gopluslabs.io>
Date: Fri, 8 May 2026 20:33:20 +0800
Subject: [PATCH 13/14] fix issue-62: add trust seed command for batch trust
 baseline setup

Add trust seed subcommand to SKILL.md with --auto-attest-low-risk,
--auto-attest-medium-risk, and --dry-run flags. Flow: discover all
installed skills, filter unregistered ones, batch scan, show plan
table with proposed actions, require explicit user confirmation, then
sequentially attest qualifying skills via trust-cli. HIGH/CRITICAL
risk skills are never auto-attested and are listed for manual review.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 skills/agentguard/SKILL.md | 106 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 1 deletion(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index 8095196..0951c42 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -55,7 +55,7 @@ Parse `$ARGUMENTS` to determine the subcommand:
 - **`scan <path>`** — Scan a skill or codebase for security risks
 - **`action <description>`** — Evaluate whether a runtime action is safe
 - **`patrol [run|setup|status]`** — Daily security patrol for OpenClaw environments
-- **`trust <lookup|attest|revoke|list> [args]`** — Manage skill trust levels
+- **`trust <lookup|attest|revoke|list|seed> [args]`** — Manage skill trust levels
 - **`report`** — View recent security events from the audit log
 - **`config <strict|balanced|permissive>`** — Set protection level
 - **`checkup`** — Run a comprehensive agent health checkup and generate a visual HTML report
@@ -524,6 +524,110 @@ Revoke trust for a skill. Supports `--source-pattern` for wildcards.
 **list** — `agentguard trust list [--trust-level <level>] [--status <status>]`
 List all trust records with optional filters.
 
+**seed** — `agentguard trust seed [--auto-attest-low-risk] [--auto-attest-medium-risk] [--dry-run]`
+Batch-scan all installed skills and auto-attest those meeting the risk threshold. Designed for initial baseline setup when many skills are already installed.
+
+Flags:
+- `--auto-attest-low-risk` (default when `seed` is invoked): attest LOW-risk skills as `trusted` with `read_only` preset.
+- `--auto-attest-medium-risk`: also attest MEDIUM-risk skills as `restricted` with `none` preset.
+- `--dry-run`: preview only — show the plan table without executing any attest commands.
+
+**HIGH and CRITICAL risk skills are never auto-attested** regardless of flags. They must be reviewed and attested manually.
+
+#### seed Flow
+
+**Step 1 — Discover skills**
+
+Glob all of the following paths for `*/SKILL.md` (same as checkup):
+- `~/.claude/skills/*/SKILL.md`
+- `~/.openclaw/skills/*/SKILL.md`
+- `~/.openclaw/workspace/skills/*/SKILL.md`
+- `~/.qclaw/skills/*/SKILL.md`
+- `~/.qclaw/workspace/skills/*/SKILL.md`
+
+Skip `agentguard` itself. Collect the parent directory of each found `SKILL.md` as the skill path.
+
+**Step 2 — Filter unregistered skills**
+
+For each discovered skill, run:
+```
+node scripts/trust-cli.ts lookup --source <skill_path>
+```
+If the lookup returns a record with `status: active`, the skill is already registered — skip it and note "already registered" in the summary. Only proceed with skills that have no active trust record.
+
+**Step 3 — Scan unregistered skills**
+
+For each unregistered skill, run the full scan (24 detection rules, same as `/agentguard scan <skill_path>`). Record: skill name, skill path, risk level (LOW/MEDIUM/HIGH/CRITICAL), finding count.
+
+**Step 4 — Build preview table**
+
+Output a plan table before taking any action:
+
+```
+## AgentGuard Trust Seed — Plan
+
+Scanned <N> unregistered skills. Proposed actions:
+
+| Skill | Path | Risk | Findings | Proposed Action |
+|-------|------|------|----------|-----------------|
+| foo   | ~/.claude/skills/foo | LOW    | 0 | ✅ attest trusted/read_only |
+| bar   | ~/.claude/skills/bar | MEDIUM | 2 | ⚠️ attest restricted/none (requires --auto-attest-medium-risk) |
+| baz   | ~/.claude/skills/baz | HIGH   | 5 | 🚫 SKIP — manual review required |
+| qux   | ~/.claude/skills/qux | CRITICAL | 8 | 🚫 SKIP — manual review required |
+
+Already registered (skipped): <M> skills
+Will attest: <K> skills
+Will skip (HIGH/CRITICAL): <J> skills
+```
+
+If `--dry-run` is present: output this table and stop. Add: `Dry run complete — no changes made. Remove --dry-run to execute.`
+
+**Step 5 — User confirmation (REQUIRED)**
+
+After showing the plan table, **always ask for explicit user confirmation** before executing any attest commands:
+
+> "Ready to attest <K> skill(s). Confirm? (yes/no)"
+
+Do NOT proceed without a clear affirmative response. If the user declines, stop and suggest `--dry-run` for future previews.
+
+**Step 6 — Batch attest**
+
+For each skill approved for attestation, compute its hash and run attest:
+
+```bash
+# Compute hash
+node scripts/trust-cli.ts hash --path <skill_path>
+
+# Attest
+node scripts/trust-cli.ts attest \
+  --id <skill_dir_name> \
+  --source <skill_path> \
+  --version <version_from_package.json_or_unknown> \
+  --hash <computed_hash> \
+  --trust-level <trusted|restricted> \
+  --preset <read_only|none> \
+  --reviewed-by agentguard-seed \
+  --notes "Auto-attested by trust seed. Scan risk: <risk_level>. Findings: <count>." \
+  --force
+```
+
+Run these sequentially (not in parallel) to avoid registry write conflicts.
+
+**Step 7 — Result summary**
+
+```
+## Trust Seed Complete
+
+✅ Attested: <N> skills
+⚠️  Skipped (already registered): <M> skills
+🚫 Skipped (HIGH/CRITICAL risk — manual review required): <J> skills
+❌ Failed: <K> skills (list errors)
+
+Skills requiring manual review:
+- <skill_name> (<path>) — Risk: HIGH/CRITICAL, <N> findings
+  Run: /agentguard scan <path>  then  /agentguard trust attest ...
+```
+
 ### Script Execution
 
 If the agentguard package is installed, execute trust operations via AgentGuard's own bundled script:

From d637acb40da44c0af42eb95e26c300515f5a8a8e Mon Sep 17 00:00:00 2001
From: Mr-Lucky <jeff-hall@foxmail.com>
Date: Wed, 13 May 2026 17:36:44 +0800
Subject: [PATCH 14/14] fix: keep trust seed docs on js cli

---
 skills/agentguard/SKILL.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/skills/agentguard/SKILL.md b/skills/agentguard/SKILL.md
index e11fd4a..581e539 100644
--- a/skills/agentguard/SKILL.md
+++ b/skills/agentguard/SKILL.md
@@ -655,7 +655,7 @@ Skip `agentguard` itself. Collect the parent directory of each found `SKILL.md`
 
 For each discovered skill, run:
 ```
-node scripts/trust-cli.ts lookup --source <skill_path>
+node scripts/trust-cli.js lookup --source <skill_path>
 ```
 If the lookup returns a record with `status: active`, the skill is already registered — skip it and note "already registered" in the summary. Only proceed with skills that have no active trust record.
 
@@ -700,10 +700,10 @@ For each skill approved for attestation, compute its hash and run attest:
 
 ```bash
 # Compute hash
-node scripts/trust-cli.ts hash --path <skill_path>
+node scripts/trust-cli.js hash --path <skill_path>
 
 # Attest
-node scripts/trust-cli.ts attest \
+node scripts/trust-cli.js attest \
   --id <skill_dir_name> \
   --source <skill_path> \
   --version <version_from_package.json_or_unknown> \