pi-gui/CONTRIBUTING.md

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 and the relevant document under 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

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

npm test && npm run check