# Contributing to Pi Status Bridge

## Reason for existence

Keep contributions reviewable and preserve the bridge's worktree isolation, local-only transport, and Pi-owned approval policy.

## Before coding

1. Create a focused branch; do not develop directly on `main`.
2. Read [`DESIGN.md`](DESIGN.md) and the relevant document under [`specs/`](specs/).
3. State which boundary changes: bridge protocol, Pi RPC adapter, desktop UI, or Noctalia adapter.
4. Add or update the narrowest test that proves the behavior.

## Development workflow

```bash
npm --prefix ui ci
npm test
npm run check
```

Use Node.js 20+ and Rust/Tauri tooling for UI work. Keep generated directories untracked: `ui/node_modules/`, `ui/dist/`, `ui/src-tauri/target/`, and `ui/src-tauri/gen/schemas/`.

## Required invariants

- **Never** expose a TCP listener in v1.
- **Never** route a request to a worktree other than the explicitly selected agent.
- **Never** let the bridge, desktop client, or Noctalia adapters decide an extension approval.
- **Never** commit runtime sockets, sessions, logs, build outputs, secrets, or agent artifacts.

## Pull requests

1. Use a Conventional Commit-style title, for example `fix(protocol): reject malformed frames`.
2. Explain the user-visible behavior and the invariant protected.
3. Include tests for the changed contract; include manual verification steps for desktop or Noctalia changes.
4. Run `npm test` and `npm run check` before requesting review.
5. Push the feature branch and merge through the forge workflow; do not directly push `main`.

## Documentation changes

Update the closest authoritative document when behavior, setup, security boundaries, or test coverage changes. Keep the root README concise and link detailed design material rather than duplicating it.

## Verification

```bash
npm test && npm run check
```