# Contributing

Thanks for helping improve Pi Toolbelt.

## Project goal

Pi Toolbelt makes local CLIs safe and useful for Pi agents. Contributions should preserve the core contract:

- provider credentials stay in local CLIs/auth stores
- Toolbelt rejects secret-shaped inputs
- Toolbelt redacts secret-shaped output
- read operations are easy
- mutations are approval-gated
- destructive operations are blocked or double-gated
- provider results are returned as structured JSON envelopes

## Good contributions

- Add a provider definition for a major official CLI.
- Improve install guidance for a provider.
- Add tests for redaction, approval gates, blocked operations, or registry validation.
- Improve docs and examples.
- Add support for safe custom provider features without weakening validation.

## Provider definition rules

Provider definitions must:

- use a simple executable name, not a shell expression
- classify every operation as `read`, `mutating`, or `blocked`
- avoid embedding credentials, tokens, secret names, or local absolute paths
- prefer JSON/machine-readable CLI output when available
- keep destructive operations blocked unless there is a strong reason
- include install guidance from official vendor documentation where possible

## Development

```bash
npm test
npm run smoke
npm run audit:secrets
npm pack --dry-run --json
```

Do not commit:

- `.env` files
- provider ledgers or runtime data
- provider auth stores
- generated caches with local paths
- API keys, tokens, cookies, private keys, or passwords

## Pull request checklist

- [ ] Tests pass.
- [ ] `npm run audit:secrets` reports zero findings.
- [ ] `npm pack --dry-run --json` contains only intended files.
- [ ] New provider definitions pass `catalog-check`.
- [ ] Docs are updated for user-visible behavior.