docs: document AI configuration and usage [Draft]

[vinayada1]

Summary

Document how to enable and use AI-assisted checks in pvtr-github-repo-scanner.

This issue should cover user-facing configuration, supported provider examples, guidance on validating AI configuration without provider spend, and how [AI-Assisted] output should be interpreted.

Scope

• Add README documentation for AI configuration keys
• Document the supported providers (openai and anthropic)
• Explain how to validate AI configuration without incurring provider spend
• Explain timeout and token settings
• Explain how to interpret [AI-Assisted] results
• Update example-config.yml with commented AI variables

Acceptance Criteria

• README includes an AI configuration section
• example-config.yml includes commented AI-related variables
• Documentation includes provider configuration examples
• Documentation explains cost and operational considerations at a high level
• Documentation explains how to validate AI configuration without provider spend
• Documentation explains [AI-Assisted] result labeling

Note

This issue originally scoped "explain dry-run usage once supported by the SDK". AI dry-run was subsequently removed from privateer-sdk, so that bullet has been replaced. See the comment below for details.

[vinayada1]

Scope update: the "explain dry-run usage once supported by the SDK" bullet has been removed, because AI dry-run no longer exists in privateer-sdk.

History:

• privateerproj/privateer-sdk#227 (SDK v1.28.0) added AI dry-run: ai.Config.DryRun, ai/dryrun.go, the ai_dry_run config key, and a global --dry-run-ai flag.
• privateerproj/privateer-sdk#252 restructured the ai package into ai/provider, ai/openai, ai/anthropic, and ai/assist, and deleted ai/client.go, ai/dryrun.go, and ai/evidence.go in the process. ai_dry_run is no longer in the SDK's recognized config keys.

This scanner never implemented dry-run itself; it only calls ai.NewClient, so the capability disappeared purely as a result of the upstream SDK change. On the SDK version this repo currently pins (v1.32.2) there is nothing for the docs to describe.

Two other parts of the original scope were also written before that refactor and are updated accordingly:

• Provider examples now cover both openai and anthropic, not just an initial single-provider rollout.
• AI results are recorded as gemara.Evidence in the normal evaluation log rather than as separate on-disk evidence packets.

If AI dry-run is still wanted, it should be raised as a new feature request against privateerproj/privateer-sdk and documented here once it lands.