FAQ

Frequently Asked Questions

What is Wrkr in one sentence?

Wrkr evaluates your AI dev tool configurations across your GitHub repo/org against policy. Posture-scored, compliance-ready.

Is Wrkr deterministic?

Yes. Wrkr scan/risk/proof paths are deterministic by default for fixed inputs.

Does Wrkr need a hosted control plane?

No. Core operation is local and file-based by default.

Does Wrkr upload or retain private source code?

Wrkr does not upload source code by default. Hosted --repo and --org scans fetch required detector files from GitHub into a local managed workspace, emit logical repository locations in shareable artifacts, and remove the materialized source root after scan artifacts commit. Retention is explicit through --source-retention retain_for_resume or --source-retention retain; generic source-file fetching requires --mode deep or --allow-source-materialization.

Does Wrkr require setup for repo or org scans?

--path is the zero-integration first-value path. Hosted --repo and --org scans require explicit GitHub API configuration via --github-api, config github_api_base, or WRKR_GITHUB_API_BASE, and they usually also need a GitHub token for private repos or to avoid public API rate limits. Token resolution order is --github-token, config auth.scan.token, WRKR_GITHUB_TOKEN, then GITHUB_TOKEN.

wrkr init can now persist both the default hosted target and the hosted GitHub API base, so org-first onboarding can be:

wrkr init --non-interactive --org acme --github-api https://api.github.com --json
wrkr scan --config ~/.wrkr/config.json --json

For hosted org runs, the least-privilege fine-grained PAT recipe is: select only the target repositories, grant read-only repository metadata, and grant read-only repository contents. That matches the exact endpoints Wrkr calls: GET /orgs/{org}/repos, GET /repos/{owner}/{repo}, GET /repos/{owner}/{repo}/git/trees/{default_branch}?recursive=1, and GET /repos/{owner}/{repo}/git/blobs/{sha}.

What should I do if wrkr scan --json says no target was provided?

That failure remains fail closed with exit 6 and error.code=invalid_input, but the JSON error envelope now includes additive next_steps[] guidance. The three intended first-value paths are:

wrkr init --non-interactive --org acme --github-api https://api.github.com --json
wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --json
wrkr scan --my-setup --json

Use the hosted init path when GitHub prerequisites are ready, the curated scenario when they are not, and --my-setup when you want machine-local hygiene first.

Does Wrkr replace runtime enforcement?

No. Wrkr is discovery/posture. Runtime enforcement is a separate control layer.

Do I need Axym or Gait to run Wrkr?

No. Wrkr runs standalone for discovery, posture scoring, regress gates, and evidence generation. Axym and Gait are optional companion projects that interoperate through shared Clyra-AI/proof contracts.

Does wrkr mcp-list do vulnerability scanning?

No. mcp-list inventories saved MCP posture, transport, privilege surface, and optional local trust overlay state. Wrkr does not perform live MCP probing or package vulnerability assessment in this path. Use dedicated scanners such as Snyk for vulnerability workflows.

Should I start with wrkr scan --my-setup or wrkr scan --github-org?

For the current public launch, start with wrkr init --org ... --github-api ... --json, then run wrkr scan --config ... --json when the goal is org posture, shared inventory review, or compliance handoff. If hosted prerequisites are not ready yet, use wrkr scan --path ./your-repo --json as the zero-integration repo-local fallback or wrkr scan --my-setup --json for developer-machine hygiene. --path scans the selected directory itself when that directory is the repo root with signals such as .git, go.mod, AGENTS.md, or .codex/; it scans immediate child repos instead when you point it at a bundle root such as ./scenarios/wrkr/scan-mixed-org/repos. If you are evaluating Wrkr itself, start with the curated ./scenarios/wrkr/scan-mixed-org/repos bundle before scanning the repo root. That bundle is intentionally risky by design, so a low posture score or sparse first-run evidence is expected and useful. Developers doing only local checks can still start with wrkr scan --my-setup --json.

For larger orgs, prefer the opinionated path:

wrkr init --non-interactive --org acme --github-api https://api.github.com --json
wrkr scan --config ~/.wrkr/config.json --state ./.wrkr/last-scan.json --timeout 30m --json --json-path ./.wrkr/scan.json --report-md --report-md-path ./.wrkr/scan-summary.md --sarif --sarif-path ./.wrkr/wrkr.sarif

If the run is interrupted, rerun the same target with --resume. If partial_result, source_errors, or source_degraded is present, treat the result as incomplete until the hosted scan finishes cleanly.

Do I need Gait to use wrkr mcp-list?

No. Gait trust overlay data is optional. When no local trust registry is available, mcp-list degrades explicitly to trust_status=unavailable instead of failing.

How do I fail CI on posture drift?

Use wrkr regress init to establish a baseline and wrkr regress run in CI. Exit 5 indicates drift.

How do I produce compliance evidence?

Use wrkr evidence --frameworks ... --json and verify chain integrity with wrkr verify --chain --json.

Why can framework coverage be low on the first run?

framework_coverage reflects the controls and approvals currently evidenced in the scanned state. Low or zero coverage means more evidence work is needed; it does not mean Wrkr lacks support for that framework. wrkr evidence --json now emits additive coverage_note guidance with the same interpretation for automation and operator handoffs.