# Contributing

## Development Setup

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
```

Run:

```sh
PATH="$PWD/.venv/bin:$PATH" ./tools/check-local.sh
```

## Privacy

Use synthetic names, IDs, hosts, addresses, messages, and provider responses in
tests and documentation. Never contribute:

- populated config profiles or generated output;
- API keys, tokens, passwords, private keys, or signing keys;
- real SteamIDs, display names, person aliases, or group identifiers;
- OCR history, screenshots, debug payloads, incident archives, or SQLite;
- personal home paths, SSH aliases, hostnames, or network addresses.

Run `./tools/check-secrets.py` before every commit.

## Plugins

Use `tools/create-plugin.py`, declare the smallest capability set, and keep
registration static after startup. Plugins must return structured SDK plans and
must not access GUI, shell, environment, filesystem, raw sockets, raw ledger,
or unrestricted network.

Any command change must update the ownership inventory and pass:

```sh
./tools/sync-local-extensions.py --check
./tools/check-packages.sh
```

## Tests

Add focused tests proportional to risk. Changes to GUI sending must cover
primary send, fallback, and visual confirmation. Changes to routing or shared
contracts require parity and restart coverage.

## Pull Requests

Describe:

- user-visible behavior;
- trust boundaries and capabilities touched;
- config/schema changes;
- migration and rollback behavior;
- tests run.

Do not include generated artifacts or unrelated formatting churn.