docs: expand scanner accuracy and false-positive guidance

[affaan-m]

Summary\n- preserve the remaining hidden AgentShield delta as a reviewable PR\n- add scanner accuracy notes, runtime-confidence guidance, and false-positive triage workflow documentation\n\n## Verification\n- diff is documentation only\n

---

Summary by cubic

Expands the README with scanner accuracy and severity guidance, adds runtimeConfidence with updated scoring across all outputs, and documents a practical false‑positive triage workflow. Also adds JSON report schema, refreshed CLI flags/exit codes, and a new MiniClaw security/API overview.

• Documentation
  • Tightens severity scoring and reporter outputs: discounts by runtimeConfidence (template-example/docs-example 0.25x with 10‑pt per‑file cap, plugin-manifest 0.5x, project-local-optional 0.75x; secrets full weight). JSON/markdown/terminal/HTML now expose runtimeConfidence.
  • Adds MCP confidence notes and path handling; discovery now skips generated dirs (e.g., node_modules, build output, .dmux) and de‑emphasizes docs‑only examples and template catalogs.
  • Improves scanner accuracy: cross‑file hook‑manifest awareness; manifest‑resolved non‑shell hook-code signals; refined heuristics (pinned curl/wget, Node/Python wrappers, read‑only Docker); targeted severity downgrades for settings.local.json, specialist agents, and repo‑scoped filesystem MCP; role‑aware agent rules and effective prompt‑size measurement; suppresses example passwords in docs‑like paths.
  • Adds a false‑positive audit workflow with jq triage commands and links to false-positive-audit.md (taxonomy, worksheet, release gate).
  • Documents JSON report shape (including runtimeConfidence and score breakdown) and clarifies automation surfaces (CLI, JSON, ecc-agentshield/miniclaw), with packaging notes to prefer JSON over importing internals.
  • Adds a MiniClaw section with security model, HTTP endpoints, and basic library usage; renames MiniClaw “API” to “HTTP API”.
  • Expands CLI docs with new flags (--injection, --sandbox, --taint, --deep, --log, --log-format, --corpus) and exit codes.

^{Written for commit c43657f. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation

  • Added comprehensive API Reference covering CLI, JSON reports, and HTTP API; updated navigation (replaced Distribution with MiniClaw).
  • Expanded CLI docs with new flags and explicit exit codes.
  • Added JSON report shape, runtimeConfidence taxonomy, scoring/weighting/capping semantics, and scanner accuracy notes.
  • Added MCP Confidence Notes and discovery behavior guidance clarifying skipped generated/transient directories.

• New Features

  • Documented MiniClaw HTTP endpoint model, security layers, and library usage.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Note

.coderabbit.yaml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)

Validation error: Unrecognized key(s) in object: 'tools'

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0fe18494-4978-4a8d-b04c-3bf676d4e7ec

📥 Commits

Reviewing files that changed from the base of the PR and between be345e3 and c43657f.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

README substantially expanded: navigation updated (Distribution → API Reference, added MiniClaw), added Discovery notes, detailed JSON output (runtimeConfidence taxonomy and scoring), MCP/Scanner accuracy notes, JSON report shape example, and an enlarged CLI / MiniClaw HTTP API reference with new CLI flags and exit codes.

Changes

Cohort / File(s)

Summary

README Documentation README.md

Reworked top-level navigation (removed Distribution, added API Reference and MiniClaw). Added Discovery section (skipped generated/transient dirs). Introduced findings[].runtimeConfidence taxonomy, weighting/capping rules, MCP Confidence Notes, Scanner Accuracy Notes, JSON Report Shape with example, expanded CLI reference (new flags: --injection, --sandbox, --taint, --deep, --log, --log-format, --corpus and exit codes 0/1/2), and new MiniClaw HTTP API docs.

Sequence Diagram(s)

sequenceDiagram
  participant Client as Client (CLI/HTTP)
  participant MiniClaw as MiniClaw HTTP Server
  participant Scanner as AgentShield Scanner
  participant FS as Repository / Filesystem
  participant Report as JSON Report Output

  Client->>MiniClaw: HTTP request / start scan
  MiniClaw->>Scanner: invoke startMiniClaw / scan request
  Scanner->>FS: read repo, skip generated dirs (node_modules, build, .dmux, etc.)
  Scanner->>Scanner: analyze manifests, .claude/*, hooks, templates
  Scanner->>Report: emit findings with runtimeConfidence and scoring metadata
  MiniClaw->>Client: return JSON report / status (exit codes reflected)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: expanding documentation for scanner accuracy and false-positive guidance, which is the primary focus of the +236 lines of documentation additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/reporter-severity-refresh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 1 file

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 210: Update the README text in the sentence mentioning "fenced code
blocks and markdown tables" to capitalize "Markdown" (change "markdown tables"
to "Markdown tables") so the proper noun is used; locate the sentence that
describes the `agents-oversized-prompt` rule (the line referencing "fenced code
blocks and markdown tables" and the example agents `chief-of-staff.md` and
`planner.md`) and make the capitalization change there.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 76fe7293-ca32-416f-be38-b80c83748e05

📥 Commits

Reviewing files that changed from the base of the PR and between 6481553 and be345e3.

📒 Files selected for processing (1)

• README.md