docs: welcome open-source contributors

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: Bug report
+description: Report a reproducible problem with BarKeep
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve BarKeep. Do not include passwords, tokens,
+        private notifications, calendar details, or signing credentials.
+        Security vulnerabilities should be reported privately.
+  - type: input
+    id: version
+    attributes:
+      label: BarKeep version
+      description: Shown at the bottom-right of the BarKeep menu.
+      placeholder: "1.0.13"
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: Installation method
+      options:
+        - Homebrew cask
+        - GitHub release
+        - Built from source
+    validations:
+      required: true
+  - type: input
+    id: macos
+    attributes:
+      label: macOS version
+      placeholder: "macOS 15.5"
+    validations:
+      required: true
+  - type: input
+    id: firmware
+    attributes:
+      label: Busy Bar firmware version
+      placeholder: "1.0.2"
+    validations:
+      required: true
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Connection
+      options:
+        - USB
+        - Wi-Fi
+        - Both
+        - Not device-related
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Include the smallest reliable sequence that triggers the problem.
+      placeholder: |
+        1. Open BarKeep
+        2. Select…
+        3. Observe…
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add sanitized logs or screenshots if they help explain the issue.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/unipheas/barkeep/security/advisories/new
+    about: Send sensitive security reports privately instead of opening an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,45 @@
+name: Feature request
+description: Suggest a focused improvement to BarKeep
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or opportunity
+      description: What workflow would this improve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe what you would like BarKeep to do.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Share any workarounds or different approaches you considered.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Menu-bar app
+        - Busy Bar Arcade
+        - CLI
+        - MCP / AI integrations
+        - Homebrew packaging
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution
+      options:
+        - label: I may be willing to implement this in a pull request.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,25 @@
+## Summary
+
+Describe what changed and why.
+
+## Verification
+
+- [ ] `swift test`
+- [ ] `swift build -c release`
+- [ ] Tested on a physical Busy Bar when the change affects device behavior
+
+## Device details
+
+- BarKeep version or branch:
+- macOS version:
+- Busy Bar firmware:
+- Connection: USB / Wi-Fi / not applicable
+
+## Checklist
+
+- [ ] The change is focused and does not include unrelated files.
+- [ ] Tests cover new or changed behavior.
+- [ ] Public documentation is updated when setup or behavior changed.
+- [ ] No passwords, tokens, private messages, signing credentials, or personal
+      data are included.
+- [ ] UI changes include a screenshot or short recording.

.gitignore

@@ -6,3 +6,11 @@ dist/
 assets/AppIcon.iconset/
 assets/preview.png
 PUBLISHING.md
+.gstack/
+.env
+.env.*
+!.env.example
+*.key
+*.p12
+*.pem
+*.mobileprovision

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to BarKeep
+
+Thanks for helping improve BarKeep. Bug reports, feature ideas, documentation
+fixes, code contributions, and experimental forks are all welcome.
+
+## Ways to contribute
+
+- Open an issue for a reproducible bug or focused feature request.
+- Improve documentation, setup instructions, or troubleshooting guidance.
+- Add tests for device behavior and firmware edge cases.
+- Submit a pull request for fixes or new features.
+- Fork the project and adapt it for your own hardware or workflow.
+
+For a potential security vulnerability, do not open a public issue. Follow
+[SECURITY.md](SECURITY.md) instead.
+
+## Development setup
+
+You need:
+
+- macOS 14 or newer
+- Xcode command-line tools with Swift 5.9 or newer
+- A Busy Bar for physical-device testing; the automated test suite does not
+  require one
+
+Fork the repository on GitHub, then clone your fork:
+
+```bash
+git clone git@github.com:YOUR-USER/barkeep.git
+cd barkeep
+git remote add upstream https://github.com/unipheas/barkeep.git
+git switch -c feature/your-change
+```
+
+Build and test:
+
+```bash
+swift test
+swift build
+```
+
+To assemble and launch the menu-bar app:
+
+```bash
+./make-app.sh
+```
+
+The script uses an available Developer ID or Apple Development identity when
+possible and otherwise falls back to ad-hoc signing. Locally signed builds may
+need macOS privacy permissions granted again.
+
+## Pull requests
+
+Before opening a pull request:
+
+1. Rebase or merge the latest `upstream/main`.
+2. Run `swift test` and `swift build -c release`.
+3. Add or update tests for behavior changes.
+4. Update the README or other public documentation when setup, behavior, or
+   user-facing features change.
+5. Include screenshots for visible UI changes and note the Busy Bar firmware
+   version used for hardware testing.
+6. Keep each pull request focused enough to review and revert independently.
+
+GitHub Actions runs the test suite and release build for every pull request.
+Maintainers may ask for changes before merging.
+
+## Protect credentials and private data
+
+Never commit:
+
+- Busy Bar local HTTP API passwords or cloud API tokens
+- Slack, GitHub, OpenAI, or other service tokens
+- Apple app-specific passwords
+- Signing certificates, private keys, provisioning profiles, or Keychain
+  exports
+- Notification databases, logs, screenshots, or fixtures containing private
+  messages or calendar data
+
+Use placeholders in examples and environment variables for local CLI/MCP
+configuration. If a credential is committed accidentally, revoke it
+immediately and tell a maintainer through a private security report.
+
+## License
+
+By submitting a contribution, you agree that it may be distributed under
+BarKeep's [MIT License](LICENSE). You retain copyright to your contribution.

README.md

@@ -1,9 +1,17 @@
 # BarKeep 👾
 
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-black.svg)](https://www.apple.com/macos/)
+[![Latest release](https://img.shields.io/github/v/release/unipheas/barkeep)](https://github.com/unipheas/barkeep/releases/latest)
+
 A macOS menu bar companion for the [Busy Bar](https://busy.app) — control your bar over USB or Wi-Fi, automate your busy status, and turn the little LED display into a proper developer peripheral.
 
 No cloud, no account, no telemetry: BarKeep talks directly to the bar's local HTTP API, either over USB (`http://10.0.4.20/api`, no authentication) or Wi-Fi (the bar's local IP address and local HTTP API password).
 
+BarKeep is free and open-source software under the
+[MIT License](LICENSE). You are welcome to use it, fork it, modify it,
+redistribute it, or build your own project from it. Contributions are welcome.
+
 ## Features
 
 **Menu bar app** (tabbed popover: Device / Message / Timers / Arcade / Settings)
@@ -224,14 +232,31 @@ Verified against firmware 1.0.2 / API 24.3.0
 ## Development
 
 ```bash
+swift test             # run the test suite
 swift build            # debug build
-./make-app.sh          # release build + launch
+./make-app.sh          # signed release build + launch
 ```
 
 The icon is generated: `cd assets && swift gen_icon.swift 1024 icon.png` (see `gen_icon.swift` for the pixel grid).
 
+## Contributing
+
+Bug reports, feature ideas, documentation improvements, code contributions,
+and personal forks are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development workflow and pull-request checklist.
+
+Please report potential vulnerabilities privately using
+[GitHub's security advisory form](https://github.com/unipheas/barkeep/security/advisories/new);
+see [SECURITY.md](SECURITY.md) for details.
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+BarKeep is released under the [MIT License](LICENSE). In practical terms, you
+may use, copy, modify, merge, publish, distribute, sublicense, and sell copies
+of the software. Keep the copyright and license notice with copies or
+substantial portions of the project.
+
+Contributions submitted to this repository are licensed under the same MIT
+terms.
 
 Not affiliated with Busy Inc. Busy Bar is a product of https://busy.app.

SECURITY.md

@@ -0,0 +1,41 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest published BarKeep release. Upgrade
+to the newest release before reporting a problem that may already be fixed.
+
+## Report a vulnerability privately
+
+Please use
+[GitHub private vulnerability reporting](https://github.com/unipheas/barkeep/security/advisories/new).
+Do not open a public issue for an undisclosed vulnerability.
+
+Include:
+
+- The affected BarKeep version and installation method
+- Your macOS and Busy Bar firmware versions
+- Reproduction steps or a proof of concept
+- The expected security impact
+- Any suggested mitigation
+
+Do not include real API passwords, OAuth tokens, signing credentials, private
+notifications, or other personal data. Replace them with clearly marked test
+values.
+
+You will receive a best-effort acknowledgement and follow-up through the
+private advisory. Please allow time for a fix and coordinated disclosure
+before publishing details.
+
+## Scope
+
+This policy covers code and release artifacts published by the
+`unipheas/barkeep` and `unipheas/homebrew-barkeep` repositories.
+
+Busy Bar firmware, Busy cloud services, Slack, macOS, Homebrew, Claude, Codex,
+and ChatGPT are third-party products. Report vulnerabilities in those products
+to their respective maintainers unless BarKeep's code is the cause.
+
+Ordinary bugs, feature requests, and documentation corrections can be filed
+through the public
+[issue tracker](https://github.com/unipheas/barkeep/issues).