From d5dcb02d59a9b1bfcbd5afdbc757e1d81325e4d2 Mon Sep 17 00:00:00 2001
From: Chad El Kurdi <162061136+Chad-Mufasax@users.noreply.github.com>
Date: Tue, 26 May 2026 19:38:48 +0200
Subject: [PATCH] OSS community hygiene: CONTRIBUTING + SECURITY + CHANGELOG +
 issue templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CONTRIBUTING.md: PR workflow (now mandatory with branch protection), what to
  contribute and what NOT to contribute, where to ask first, maintainer bandwidth
  note (this is a side project).
- SECURITY.md: GitHub Security Advisory channel for vulns, response SLA (one
  maintainer), in-scope vs upstream (gbrain/gstack/ZE/Claude Code), local-trust
  scope of the vault.
- CHANGELOG.md: 0.1.0 initial public release entry — vault skeleton, install.sh,
  --with-gstack, --company, 5 hooks, gbq universal wrapper, nightly + reflection,
  CI, MIT, branch protection.
- .github/ISSUE_TEMPLATE/{bug,feature}.md: structured submission templates.
- README.md: added Contributing + Security pointer sections (1 paragraph each).
---
 .github/ISSUE_TEMPLATE/bug.md     | 33 +++++++++++++++++
 .github/ISSUE_TEMPLATE/feature.md | 30 ++++++++++++++++
 CHANGELOG.md                      | 41 +++++++++++++++++++++
 CONTRIBUTING.md                   | 60 +++++++++++++++++++++++++++++++
 README.md                         |  4 +++
 SECURITY.md                       | 54 ++++++++++++++++++++++++++++
 6 files changed, 222 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature.md
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 SECURITY.md

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
new file mode 100644
index 0000000..1202b3a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Something installed/runs but doesn't behave as expected
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+<!-- 1-2 sentences. What did you do, what did you expect, what did you get? -->
+
+## Steps to reproduce
+1. 
+2. 
+3. 
+
+## Environment
+- macOS version: <!-- `sw_vers -productVersion` -->
+- Claude Code version: <!-- `claude --version` -->
+- brain-in-a-box commit: <!-- `cd ~/DEV/brain-in-a-box && git rev-parse --short HEAD` -->
+- Bun version: <!-- `bun --version` -->
+
+## Logs / output
+<details>
+<summary>Click to expand</summary>
+
+```
+paste relevant output here — install.sh transcript, ~/.gbrain/nightly.log, test-hooks.sh output, etc.
+```
+
+</details>
+
+## What you've already tried
+<!-- e.g. ran ./test-hooks.sh, gbrain doctor, re-installed, ... -->
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
new file mode 100644
index 0000000..2037181
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature.md
@@ -0,0 +1,30 @@
+---
+name: Feature request / idea
+about: Something brain-in-a-box doesn't do yet that you'd want
+title: "[feat] "
+labels: enhancement
+---
+
+## What problem does this solve
+<!-- The pain point, not the solution. 2-3 sentences. -->
+
+## Proposed approach (optional)
+<!-- If you have an idea of how to implement it. Leave blank if you don't — the discussion will figure it out. -->
+
+## Who benefits
+- [ ] Solo users (personal vault)
+- [ ] Team users (company brain mode)
+- [ ] Agent developers (skill authors)
+- [ ] Other:
+
+## Alignment check
+<!-- Brain-in-a-box is opinionated. Quick sanity: -->
+- [ ] Does NOT require a server (local-first)
+- [ ] Does NOT add telemetry/phone-home
+- [ ] Does NOT lock users into a specific provider
+- [ ] Stays compatible with gstack / openclaw / Hermes / plain Claude Code
+
+If any unchecked: explain why it's worth the trade-off.
+
+## Existing alternatives
+<!-- How would you achieve this today, without brain-in-a-box? -->
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..18d7f7f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to brain-in-a-box.
+
+Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+_Nothing yet — open an issue to suggest._
+
+## [0.1.0] — 2026-05-26 — Initial public release
+
+The first public-OSS day. The product was built and dogfooded privately the day before; today it went public after a multi-layer scan (file content + full git history + tier names like personal contacts) confirmed zero personal info leaks.
+
+### Added
+- **Vault skeleton with team-first folders**: `Profile/`, `Team/` (humans), `Agents/` (AI agents as first-class teammates), `Decisions/` (one file per locked-in choice), `Skills/` (gstack SKILL.md format), plus existing `Journal/`, `Projects/`, `Clients/`, `Resources/`.
+- **`./install.sh`** one-command install — vault skeleton + 5 hooks + GBrain (clone + ZE-embedded init) + gbq wrapper + launchd jobs (nightly 04:00 + reflection 12:00/23:00) + Obsidian install + global `CLAUDE.md` merge. Non-destructive: never overwrites an existing vault or settings.
+- **`./install.sh --with-gstack`** option — clones and sets up [garrytan/gstack](https://github.com/garrytan/gstack) alongside (23 AI specialists for Claude Code).
+- **`./install.sh --company <git-url>`** — team mode, joins a shared company brain as a 2nd federated GBrain source.
+- **`./setup-company.sh`** — admin scaffolds the company brain (`~/Documents/BrainCo/`), git inits, prints push + member-join instructions.
+- **5 hooks** in `engine/hooks/`:
+  - `correction-detector.py` (UserPromptSubmit) — captures corrections to `lessons.md`
+  - `session-logger.py` + `session-indexer.py` (Stop) — per-session logs
+  - `session-recap.py` (Stop) — structured journal entry per session (no LLM)
+  - `daily-reflection.py` (cron, called by launchd 12:00 + 23:00) — LLM summary of the day
+- **`gbq`** universal safe wrapper around `gbrain` — force-kill workaround on PGLite reads (`query/search/ask/graph-query`), clean `wait` on writes (`sync/embed/dream/skillify/brainstorm/code-def/code-refs/sources/...`).
+- **Nightly maintenance** (`engine/nightly/gbrain-nightly.sh`) — stale-lock recovery → self-update gbrain → self-update gstack (if installed) → commit vault → sync personal + company → dream cycle.
+- **`test-hooks.sh`** — verifies all 5 hooks (11 checks) + validates YAML frontmatters in `vault-skeleton/*/_template.md` (4 checks), in an isolated temp HOME. 15/15 expected.
+- **CI** (`.github/workflows/test.yml`) — runs `test-hooks.sh` + shell syntax lint on every PR + push to master.
+- **OSS hygiene** — MIT LICENSE, CONTRIBUTING.md, SECURITY.md, issue templates.
+
+### Security
+- Repository history scrubbed of all personal/business identifiers before going public (multi-layer scan: file content + full git log + tier-1 contact names).
+- Branch protection on `master` (1 PR review required, no force-push, no deletion).
+- `~/.gbrain/config.json` written with mode 0600 (the ZeroEntropy API key never leaves the machine).
+- Hooks resolve absolute paths at install time (sed `__HOME__` → `$HOME`) — no runtime path injection surface.
+
+### Known limitations
+- macOS only (launchd for cron). Linux port welcome (issue first).
+- Embeddings via ZeroEntropy (free tier). Ollama-local variant planned, not yet shipped.
+- Auto-skill suggestion from session patterns is intentionally NOT shipped — speculative without real usage data. Will revisit after 2+ weeks of community usage.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..b633041
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,60 @@
+# Contributing to brain-in-a-box
+
+Thanks for wanting to make this better. The project is small, the workflow is straightforward.
+
+## Quick rules
+
+- **macOS only** (the nightly + reflection rely on `launchd`). Linux/Windows ports welcome via discussion first — propose the approach before coding.
+- **One concern per PR.** Schema change in one PR, doc change in another. Easier to review, easier to revert.
+- **No secrets, ever.** Not in the vault, not in tests, not in code. The `file-protection.sh` hook tries to catch them but don't rely on it.
+- **Match the existing style.** Concise English, no corporate fluff. Read what's there before writing.
+
+## Workflow
+
+The `master` branch is protected: no direct push, no force-push, no deletion. Every change goes through a PR.
+
+```bash
+# 1. Branch from master
+git checkout master && git pull --ff-only
+git checkout -b <type>/<short-name>     # e.g. fix/yaml-validation, feat/ollama-variant
+
+# 2. Make your change
+
+# 3. Run tests locally BEFORE pushing
+bash test-hooks.sh                       # 15/15 expected (5 hooks + 4 YAML frontmatters)
+bash -n install.sh                       # syntax check on every shell script you touched
+
+# 4. Push + open PR
+git push -u origin <your-branch>
+gh pr create                             # or use the GitHub UI
+
+# 5. CI runs automatically (.github/workflows/test.yml — macos-latest)
+#    All checks must pass. 1 review approval required before merge.
+```
+
+## What you can contribute
+
+- **Hook fixes** (`engine/hooks/*.py`) — fixes welcome, ping if behavior change
+- **New skills** (`vault-skeleton/Skills/` templates) — gstack-compatible SKILL.md format
+- **Docs** (`README.md`, `CONTRIBUTING.md`, this one) — clarity > completeness
+- **CI improvements** (`.github/workflows/`) — make tests faster, add coverage
+- **Linux port** (open an issue first to discuss approach — launchd needs replacement)
+- **Ollama variant** (`engine/bin/gbq`, install.sh) — opt-in offline embeddings
+- **Translations** (vault-skeleton templates) — keep the structure, swap the prose
+
+## What NOT to contribute
+
+- New folders in `vault-skeleton/` without strong rationale (the schema is meant to stay stable)
+- Heavy dependencies (the install is bash + python3 + bun + git; keep it light)
+- Telemetry, analytics, or any phone-home (the project is 100% local by design)
+
+## Where to ask first
+
+- **Vision / scope questions** → open a Discussion (not an Issue)
+- **Bugs** → open an Issue using the template
+- **Security vulnerabilities** → see [SECURITY.md](SECURITY.md), never an Issue
+- **"Is this aligned with the roadmap?"** → ping in a Discussion before coding
+
+## A note on the maintainer's bandwidth
+
+This is a side project of one person. PRs that are tight, tested, and aligned get merged fast. PRs that need a lot of back-and-forth may sit. If your PR has been quiet for >2 weeks, ping it.
diff --git a/README.md b/README.md
index 6fdb511..275ddbe 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,10 @@ Each member's nightly pulls the team's contributions + re-indexes. The dream cyc
 ## Security / privacy
 - Everything is **local**: your vault, your index, your key. Nothing goes to a third party (except the text embedding sent to ZeroEntropy at indexing time — see their policy).
 - Never a secret in the vault (the `file-protection` hook + the directives remind you).
+- **Found a security issue?** See [SECURITY.md](SECURITY.md) — please use GitHub Security Advisories, not public Issues.
+
+## Contributing
+PRs welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow (the `master` branch is protected — every change goes through a PR). MIT licensed (see [LICENSE](LICENSE)). Changelog tracked in [CHANGELOG.md](CHANGELOG.md).
 
 ## Updating
 ```bash
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..1a7818f
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,54 @@
+# Security policy
+
+## Reporting a vulnerability
+
+**Do NOT open a public GitHub Issue for security bugs.**
+
+Use one of these instead:
+1. **GitHub Security Advisories** (preferred): https://github.com/BrainInBox/brain-in-a-box/security/advisories/new
+2. **Direct contact** via the maintainer's profile: https://github.com/Chad-Mufasax
+
+Include in the report:
+- Steps to reproduce
+- Impact (what an attacker could do)
+- Suggested mitigation if you have one
+- Whether you'd like credit in the fix announcement
+
+## Response
+
+The maintainer is one person. Reasonable response targets:
+- **Acknowledgment**: within 72h
+- **Triage + severity**: within 1 week
+- **Fix or mitigation**: depends on severity (critical = days, low = weeks)
+
+## What's in scope
+
+- The `install.sh` script (running it on a clean Mac shouldn't be exploitable)
+- The hooks (`engine/hooks/*.py`) — they execute on every Claude Code session
+- The nightly script (`engine/nightly/gbrain-nightly.sh`) — runs as launchd
+- The `gbq` wrapper — runs against your local gbrain
+- Path-traversal / injection in any of the above
+
+## What's NOT in scope (upstream projects)
+
+- **GBrain** (garrytan/gbrain) — report to the gbrain project directly
+- **gstack** (garrytan/gstack) — report to gstack project
+- **ZeroEntropy** (the embedding API) — report to zeroentropy.dev
+- **Claude Code** itself — report to Anthropic
+
+## What's NOT a vulnerability
+
+- A friend you added as collaborator can push code (that's collaboration, not a vuln — see the README discussion on trust models)
+- The brain content is readable to whoever has access to your machine (it's plaintext markdown, by design)
+- An attacker with shell access on your machine can read `~/.gbrain/config.json` (file is `0600`, but root or your own user can still read it — that's local-trust scope)
+
+## Hardening recommendations (for users)
+
+- Enable FileVault on your Mac (encrypts the vault at rest)
+- Don't share your `~/Documents/Brain` over insecure channels
+- If you set up team mode (BrainCo), use a private GitHub repo and audit who has access
+- Never put secrets in the vault — references only (Keychain entries, file paths, env var names)
+
+## Credit
+
+Vulnerability reporters who follow this policy get credit in the fix release notes, unless they opt out.