docs: establish project documentation baseline

Provide installation, security, contribution, licensing, and release guidance while removing user-specific service configuration.
2026-07-27 15:15:56 +02:00
parent b7fea83ed6
commit 7cc15cca92
11 changed files with 529 additions and 5 deletions
@@ -0,0 +1,47 @@
+# 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
+```