docs: surface Claude Code plugin

README.md

@@ -110,7 +110,16 @@ curl -fsSL https://foxguard.dev/install.sh | sh          # prebuilt binary (macO
 cargo install foxguard                                   # crates.io
 ```
 
-**Editor:** [VS Code extension](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard) scans on save and shows findings inline.
+**Editors and agents:**
+
+- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard) scans on save and shows findings inline.
+- [Claude Code plugin](./plugins/claude-code) auto-scans files after Claude writes or edits them, adds `/foxguard:*` scan/triage/PQ/secrets skills, and injects secure-coding defaults into agent sessions.
+
+```sh
+claude --plugin-dir ./plugins/claude-code
+```
+
+Run `/foxguard:setup` inside Claude Code to verify the scanner is available. See [Claude Code integration](docs/claude-code-integration.md) for local plugin loading, hook behavior, and marketplace status.
 
 ## CI integration
 
@@ -132,7 +141,7 @@ jobs:
           upload-sarif: "true"
 ```
 
-Findings land in **Security → Code Scanning**. On any other CI: `npx foxguard@latest --format sarif . > out.sarif`. For Claude Code and other editor hooks, see [docs/claude-code-integration.md](docs/claude-code-integration.md).
+Findings land in **Security → Code Scanning**. On any other CI: `npx foxguard@latest --format sarif . > out.sarif`. For Claude Code and other agent/editor hooks, see [docs/claude-code-integration.md](docs/claude-code-integration.md).
 
 **Pre-commit:**
 

docs/claude-code-integration.md

@@ -1,90 +1,85 @@
 # Claude Code Integration
 
-foxguard can run as a [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) to scan agent-written code before each commit. When findings are detected, the commit is blocked and Claude sees the output — giving it a chance to fix the issue before retrying.
-
-## Setup
-
-Add the following to `.claude/settings.json` in your project root:
-
-```json
-{
-  "hooks": {
-    "PreCommit": [
-      {
-        "command": "npx foxguard --changed --severity high .",
-        "description": "foxguard security scan"
-      }
-    ]
-  }
-}
+foxguard ships a Claude Code plugin in [`plugins/claude-code`](../plugins/claude-code). It is the recommended Claude Code integration path because it runs automatically during an agent session instead of waiting until commit time.
+
+## What The Plugin Does
+
+- Runs a `PostToolUse` hook after `Write`, `Edit`, `MultiEdit`, and `NotebookEdit` so files Claude changes are scanned immediately.
+- Emits medium-and-above findings back to Claude so the agent can fix them before the issue lands in the repo.
+- Adds a `SessionStart` secure-coding preamble covering command execution, SQL, SSRF, path traversal, secrets, randomness, crypto, and deserialization.
+- Provides namespaced `/foxguard:*` skills for setup, full scans, diff scans, PQ audits, secrets scans, and TUI triage.
+
+## Local Install
+
+Install foxguard first:
+
+```sh
+curl -fsSL https://foxguard.dev/install.sh | sh
+# or: npm i -g foxguard
+# or: cargo install foxguard
+```
+
+Then load the plugin from this repo:
+
+```sh
+claude --plugin-dir ./plugins/claude-code
 ```
 
-That's it. Claude Code will run foxguard before every commit.
+Inside Claude Code, run:
 
-## What happens when findings are detected
+```text
+/foxguard:setup
+```
 
-1. Claude writes code and attempts to commit.
-2. foxguard scans the changed files.
-3. If any findings at or above the configured severity are found, foxguard exits non-zero.
-4. Claude Code blocks the commit and shows foxguard's output to the agent.
-5. The agent sees the finding (rule ID, file, line, description) and can fix it.
-6. On the next commit attempt, foxguard runs again.
+That verifies the `foxguard` binary is available and explains the active hook severity threshold.
 
-## Customizing severity threshold
+## Hook Behavior
 
-The `--severity` flag controls the minimum severity that causes a non-zero exit:
+The auto-scan hook reads the Claude Code hook JSON from stdin, extracts `tool_input.file_path` or `tool_input.path`, and runs:
 
-```json
-{ "command": "npx foxguard --changed --severity critical ." }
+```sh
+foxguard --format json --severity medium <edited-file>
 ```
 
-Valid values: `low`, `medium`, `high`, `critical`.
+If findings are present, the hook exits `2` and prints a compact finding summary to stderr. Missing binaries, unreadable files, invalid hook input, and clean scans exit `0` so plugin machinery does not block Claude by itself.
 
-- `critical` — only block on critical findings (SQL injection, command injection, etc.)
-- `high` — block on high and critical (recommended default)
-- `medium` — block on medium and above
-- `low` — block on everything
-
-## Adding secrets scanning
-
-To also catch leaked credentials, add a second hook entry:
-
-```json
-{
-  "hooks": {
-    "PreCommit": [
-      {
-        "command": "npx foxguard --changed --severity high .",
-        "description": "foxguard security scan"
-      },
-      {
-        "command": "npx foxguard secrets --changed .",
-        "description": "foxguard secrets scan"
-      }
-    ]
-  }
-}
+Tune the threshold with:
+
+```sh
+export FOXGUARD_HOOK_SEVERITY=high
 ```
 
-## Combining with the VS Code extension
+Valid values: `low`, `medium`, `high`, `critical`.
+
+## Commands And Skills
 
-For a full agentic security loop:
+Claude Code plugin skills are namespaced by the plugin name:
 
-1. **VS Code extension** — scans on save, shows findings as inline underlines while the agent is editing.
-2. **Claude Code hook** — catches anything missed before commit.
+- `/foxguard:setup` verifies installation and configuration.
+- `/foxguard:scan [path]` runs a full scan and summarizes findings.
+- `/foxguard:diff-scan [base]` reports findings introduced by the current branch.
+- `/foxguard:pq-audit [path]` runs post-quantum crypto and CNSA 2.0 checks.
+- `/foxguard:secrets [path]` scans for leaked credentials and private keys.
+- `/foxguard:triage [args]` opens or explains the interactive TUI triage flow.
 
-Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard), then add the hook config above. The two complement each other: the extension gives real-time feedback, the hook is the final gate.
+The plugin also includes a model-invoked `secure-coding` skill so Claude can pull in foxguard-aligned remediation guidance while writing security-sensitive code.
 
-## Pinning a version
+## Pre-commit Still Helps
 
-To avoid network fetches on every commit, pin the version:
+The plugin is live feedback. A pre-commit hook is still useful as a final gate for human edits, other agents, or terminal changes outside Claude Code:
 
-```json
-{ "command": "npx foxguard@0.6.2 --changed --severity high ." }
+```sh
+foxguard init
 ```
 
-Or install foxguard globally (`curl -fsSL https://foxguard.dev/install.sh | sh`) and reference the binary directly:
+Or configure your own hook to run:
 
-```json
-{ "command": "foxguard --changed --severity high ." }
+```sh
+npx foxguard --changed --severity high .
 ```
+
+## Publishing Status
+
+The plugin can be loaded locally today with `--plugin-dir`. Publishing to an official Claude plugin marketplace is an external release step: it requires final marketplace metadata, a release/versioning decision, local plugin smoke testing in Claude Code, and submission through Anthropic's plugin form.
+
+Track the publishing checklist in the GitHub issue linked from the README/PR queue rather than treating it as part of the scanner binary release.