# Wrkr

> Know what AI tools, agents, and MCP servers are configured on your machine and in your org before they become unreviewed access.

## Canonical
- https://github.com/Clyra-AI/wrkr
- https://clyra-ai.github.io/wrkr/

## Core Commands
- wrkr init --org <org> --github-api <url> --json
- wrkr --help
- wrkr help <command>
- wrkr scan --my-setup --json
- wrkr mcp-list --state ./.wrkr/last-scan.json --json
- wrkr scan --repo <owner/repo> --github-api <url> --json
- wrkr scan --org <org> --github-api <url> --json
- wrkr scan --github-org <org> --github-api <url> --json
- wrkr scan --path <dir> --sarif --json
- wrkr inventory --diff --baseline ./.wrkr/inventory-baseline.json --state ./.wrkr/last-scan.json --json
- wrkr inventory approve <agent-id> --owner <team> --evidence <ticket-or-url> --expires 90d --state ./.wrkr/last-scan.json --json
- wrkr inventory attach-evidence <agent-id> --control <control-id> --url <url> --state ./.wrkr/last-scan.json --json
- wrkr report --top <n> --json
- wrkr score --json
- wrkr evidence --frameworks eu-ai-act,soc2,pci-dss --state ./.wrkr/last-scan.json --output ./.wrkr/evidence --json
- wrkr verify --chain --json
- wrkr regress run --baseline ./.wrkr/inventory-baseline.json --state ./.wrkr/last-scan.json --json
- wrkr fix --top <n> --json

## When To Use
- You need a security/platform-led view of AI tooling posture across repos or orgs, with hosted org posture as the primary path and deterministic scenario/local fallbacks when hosted setup is not ready yet.
- You need deterministic inventory and evidence outputs for AI tooling declared across machines, repos, or org surfaces.
- You need compliance-ready evidence outputs with explicit verification workflows.
- You need CI gates for drift and regression with stable machine-readable reasons.
- You want posture and proof without moving scan data out of your environment.

## When Not To Use
- You need runtime traffic interception or live endpoint behavior control.
- You cannot provide required source acquisition inputs for repo/org scan modes.
- You need package or MCP-server vulnerability assessment rather than posture inventory.
- You need non-deterministic exploratory analysis instead of contract-stable outputs.

## Safety Model
- Fail-closed handling for unsafe output paths and missing required dependencies.
- Deterministic JSON contracts and stable exit-code semantics.
- No secret-value extraction; only risk context signals.
- Proof-chain verification support for evidence integrity checks; `wrkr evidence` now fails closed on malformed or tampered saved proof chains, while `verify --chain --json` remains the explicit machine gate and reports `chain.verification_mode` and `chain.authenticity_status`.
- Hosted org posture is the primary first-run path when prerequisites are ready; local `--my-setup`, repo-local `--path`, and the curated scenario remain deterministic fallback paths when hosted setup is not ready yet.
- The curated `./scenarios/wrkr/scan-mixed-org/repos` evaluator path is intentionally risky by design, so a low posture score or sparse first-run evidence is expected and demonstrates the detection/evidence model.
- Resumed hosted org scans revalidate checkpoint files and reused materialized repo roots before detector execution, so symlink-swapped resume state is blocked as unsafe.
- Low or zero `framework_coverage` reflects the controls currently evidenced in the scanned state, not missing parser support, and `wrkr evidence --json` emits additive `coverage_note` guidance with the same interpretation.
- Approval inventory mutations are local/file-based and append proof events; `wrkr evidence --json` and `wrkr verify --chain --json` may include additive `control_evidence` showing existing and missing proof for active backlog controls.
- `wrkr identity` and `wrkr inventory` mutations update saved state, manifest, lifecycle, and proof artifacts together, so `score`, `report`, and `regress` reflect approvals without a rescanning step.
- First discovery persists as `discovered`; `under_review` is reserved for explicit review and approval-expiry return-to-review flows.
- Evidence bundles include deterministic inventory artifacts: inventory.json, inventory-snapshot.json, inventory.yaml.
- Wrkr runs standalone; Gait is the optional control-layer counterpart.
- Wrkr does not replace vulnerability scanners such as Snyk.

## Canonical Docs
- /scan/
- /docs/map/
- /docs/start-here/
- /docs/commands/
- /docs/examples/quickstart/
- /docs/examples/site-assets/
- /docs/examples/personal-hygiene/
- /docs/examples/security-team/
- /docs/adopt_in_one_pr/
- /docs/integration_checklist/
- /docs/architecture/
- /docs/concepts/mental_model/
- /docs/policy_authoring/
- /docs/policy_builtin_rules/
- /docs/failure_taxonomy_exit_codes/
- /docs/threat_model/
- /docs/contracts/compatibility_matrix/
- /docs/positioning/
- /docs/intent/scan-org-repos-for-ai-agents-configs/
- /docs/intent/detect-headless-agent-risk/
- /docs/intent/detect-prompt-channel-and-attack-path-risk/
- /docs/intent/generate-compliance-evidence-from-scans/
- /docs/intent/gate-on-drift-and-regressions/
- /docs/trust/deterministic-guarantees/
- /docs/trust/detection-coverage-matrix/
- /docs/trust/mcp-enrich-quality-model/
- /docs/trust/proof-chain-verification/

## LLM Resources
- /llms-full.txt
- /llm/product.md
- /llm/quickstart.md
- /llm/security.md
- /llm/faq.md
- /llm/contracts.md
